chDB for Bun | ClickHouse Docs

chDB-bun proporciona bindings FFI (Foreign Function Interface) experimentales para chDB, lo que te permite ejecutar consultas de ClickHouse directamente en tus aplicaciones de Bun sin dependencias externas.

Instalación

Instalar dependencias del sistema

Primero, instala las dependencias del sistema necesarias:

Instalar libchdb

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

Instalar herramientas de compilación

Necesitarás tener gcc o clang instalados en tu sistema:

Instalar chDB-bun

# Instalar desde el repositorio de GitHub
bun add github:chdb-io/chdb-bun

# O clonar y compilar localmente
git clone https://github.com/chdb-io/chdb-bun.git
cd chdb-bun
bun install
bun run build

Uso

chDB-bun admite dos modos de consulta: consultas efímeras para operaciones puntuales y sesiones persistentes para mantener el estado de la base de datos.

Consultas efímeras

Para consultas sencillas y puntuales que no requieren estado persistente:

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);

Sesiones persistentes

Para operaciones complejas que requieren mantener el estado entre consultas:

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
}