> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# chDB for Bun

> كيفية تثبيت chDB واستخدامه مع بيئة تشغيل Bun

يوفّر chDB-bun واجهات ربط FFI (Foreign Function Interface) تجريبية لـ chDB، ما يتيح لك تشغيل استعلامات ClickHouse مباشرةً داخل تطبيقات Bun من دون أي تبعيات خارجية.

<div id="installation">
  ## التثبيت
</div>

<Steps>
  <Step title="تثبيت تبعيات النظام" id="install-system-dependencies">
    أولًا، ثبّت تبعيات النظام المطلوبة:

    #### تثبيت libchdb

    ```bash theme={null}
    curl -sL https://lib.chdb.io | bash
    ```

    #### تثبيت أدوات البناء

    ستحتاج إلى تثبيت `gcc` أو `clang` على نظامك:
  </Step>

  <Step title="تثبيت chDB-bun" id="install-chdb-bun">
    ```bash theme={null}
    # التثبيت من مستودع GitHub
    bun add github:chdb-io/chdb-bun

    # أو استنساخه وبناءه محليًا
    git clone https://github.com/chdb-io/chdb-bun.git
    cd chdb-bun
    bun install
    bun run build
    ```
  </Step>
</Steps>

<div id="usage">
  ## الاستخدام
</div>

يدعم chDB-bun وضعَي استعلام: الاستعلامات المؤقتة للعمليات التي تُنفَّذ لمرة واحدة، والجلسات المستمرة للحفاظ على حالة قاعدة البيانات.

<div id="ephemeral-queries">
  ### الاستعلامات المؤقتة
</div>

للاستعلامات البسيطة التي تُنفَّذ لمرة واحدة ولا تتطلب حالة محفوظة:

```typescript theme={null}
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);
```

<div id="persistent-sessions">
  ### الجلسات المستمرة
</div>

للعمليات المعقدة التي تتطلب الحفاظ على الحالة عبر الاستعلامات:

```typescript theme={null}
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
}
```