cowsdb / libcows

Library builder for CowsDB, a non-commercial, community powered chdb/ClickHouse embedded alternative.

libCows

Independent builder generating a stable chdb compatible library binding for C/C++/Go/Rust/Node/Bun/etc

Features

• In-process SQL OLAP Engine, powered by chdb/ClickHouse
• Library only designed for native bindings and integrations
• Compatible with chdb bindings without python obsession.
• Same source code and featureset as chdb/ClickHouse.

📦 Installation

Install libcows manually on x64 or arm64 Linux platforms:

Linux

📦 x86_64

wget https://github.com/cowsdb/libcows/releases/latest/download/libcows.zip
unzip libcows.zip
mv libcows.so /usr/lib/libcows.so

📦 arm64

wget https://github.com/cowsdb/libcows/releases/latest/download/libcows_arm64.zip
unzip libcows_arm64.zip
mv libcows.so /usr/lib/libcows.so

Packages

Install libcows on any deb or rpm based operating system:

📦 Debian Repository (x64/arm64)

wget -q -O - https://cowsdb.github.io/libcows_installer.sh | sudo bash
sudo apt install libcows

📦 RPM Repository (x64/arm64)

wget -q -O - https://cowdb.github.io/libcows_installer.sh | sudo bash
sudo yum install -y libcows

Usage

A basic libcows usage example is included with this repository:

cd example
./run.sh

🚧: Project Status

• patch builder, bypass python bindings
• package library as deb, rpm
• host package repository on github pages/actions
• arm64 library support
• header files and examples
• split from chdb-io after they used us up

libcows's Issues

Add Execute function

Link and export the simplified Execute function used for bindings to avoid code duplication and reduce FFI complexity

• Example: https://github.com/metrico/chdb-bun/tree/main/lib

Static build

Is a static library.a build even possible, and at what cost? Let's f around and find out in this thread.

arm64: cannot allocate memory in static TLS block

The arm64 builds of libchdb.so are succeeding without errors, but library invocations fail

libchdb.so: cannot allocate memory in static TLS block

Not sure if this can/should be solved at build stage or with include changes. Any Help welcome!

UDF Functions

The upcoming releases of ClickHouse allow correct allocation of UDF resources with two new parameters:

• user_scripts_path
• user_defined_executable_functions_config

#!/usr/bin/env bash

set -e

CUR_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
# shellcheck source=../shell_config.sh
. "$CUR_DIR"/../shell_config.sh

SCRIPTS_DIR=$CUR_DIR/scripts_udf

$CLICKHOUSE_LOCAL -q 'select test_function()' -- --user_scripts_path=$SCRIPTS_DIR --user_defined_executable_functions_config=$SCRIPTS_DIR/function.xml

This will finally allow using the execute binary UDF functions in chDB:

SELECT * FROM executable('./some_script.py', TabSeparated, 'name String', (SELECT name));

Todo

• Backport functions chdb chdb-io/chdb#81
• Add support for the new parameters in the chdb session binding to leverage this functionality 😃

Full API

Hi,
I am working on Go bindings for the chdb, and I was wondering where can I find the API definition provided by the shared library. What is in libchdb.h seems to be incomplete.