chDB for Bun | ClickHouse Docs

chDB-bun fournit des bindings FFI (Foreign Function Interface) expérimentaux pour chDB, ce qui vous permet d'exécuter des requêtes ClickHouse directement dans vos applications Bun, sans dépendance externe.

Installation

Installer les dépendances système

Tout d'abord, installez les dépendances système requises :

Installer libchdb

curl -sL https://lib.chdb.io | bash

Installer les outils de compilation

Vous devez disposer de gcc ou de clang sur votre système :

Installer chDB-bun

# Installer depuis le dépôt GitHub
bun add github:chdb-io/chdb-bun

# Ou cloner et compiler localement
git clone https://github.com/chdb-io/chdb-bun.git
cd chdb-bun
bun install
bun run build

Utilisation

chDB-bun prend en charge deux modes de requête : les requêtes éphémères pour les opérations ponctuelles et les sessions persistantes pour conserver l'état de la base de données.

Requêtes éphémères

Pour des requêtes simples et ponctuelles ne nécessitant pas d’état persistant :

import { query } from 'chdb-bun';

// Basic query
const result = query("SELECT version()", "CSV");
console.log(result); // "23.10.1.1"

// Query with different output formats
const jsonResult = query("SELECT 1 as id, 'Hello' as message", "JSON");
console.log(jsonResult);

// Query with calculations
const mathResult = query("SELECT 2 + 2 as sum, pi() as pi_value", "Pretty");
console.log(mathResult);

// Query system information
const systemInfo = query("SELECT * FROM system.functions LIMIT 5", "CSV");
console.log(systemInfo);

Sessions persistantes

Pour les opérations complexes qui nécessitent de préserver l’état entre les requêtes :

import { Session } from 'chdb-bun';

// Create a session with persistent storage
const sess = new Session('./chdb-bun-tmp');

try {
    // Create a database and table
    sess.query(`
        CREATE DATABASE IF NOT EXISTS mydb;
        CREATE TABLE IF NOT EXISTS mydb.users (
            id UInt32,
            name String,
            email String
        ) ENGINE = MergeTree() ORDER BY id
    `, "CSV");

    // Insert data
    sess.query(`
        INSERT INTO mydb.users VALUES 
        (1, 'Alice', 'alice@example.com'),
        (2, 'Bob', 'bob@example.com'),
        (3, 'Charlie', 'charlie@example.com')
    `, "CSV");

    // Query the data
    const users = sess.query("SELECT * FROM mydb.users ORDER BY id", "JSON");
    console.log("Users:", users);

    // Create and use custom functions
    sess.query("CREATE FUNCTION IF NOT EXISTS hello AS () -> 'Hello chDB'", "CSV");
    const greeting = sess.query("SELECT hello() as message", "Pretty");
    console.log(greeting);

    // Aggregate queries
    const stats = sess.query(`
        SELECT 
            COUNT(*) as total_users,
            MAX(id) as max_id,
            MIN(id) as min_id
        FROM mydb.users
    `, "JSON");
    console.log("Statistics:", stats);

} finally {
    // Always cleanup the session to free resources
    sess.cleanup(); // This deletes the database files
}