|
1 | 1 | --- |
2 | | -title: 'Installing chDB for Bun' |
| 2 | +title: 'chDB for Bun' |
3 | 3 | sidebar_label: 'Bun' |
4 | 4 | slug: /chdb/install/bun |
5 | | -description: 'How to install chDB for Bun' |
6 | | -keywords: ['chdb', 'embedded', 'clickhouse-lite', 'bun', 'install'] |
| 5 | +description: 'How to install and use chDB with Bun runtime' |
| 6 | +keywords: ['chdb', 'bun', 'javascript', 'typescript', 'embedded', 'clickhouse', 'sql', 'olap'] |
7 | 7 | --- |
8 | 8 |
|
9 | | -# Installing chDB for Bun |
| 9 | +# chDB for Bun |
10 | 10 |
|
11 | | -## Requirements {#requirements} |
| 11 | +chDB-bun provides experimental FFI (Foreign Function Interface) bindings for chDB, enabling you to run ClickHouse queries directly in your Bun applications with zero external dependencies. |
12 | 12 |
|
13 | | -Install [libchdb](https://github.com/chdb-io/chdb): |
| 13 | +## Installation {#installation} |
| 14 | + |
| 15 | +### Step 1: Install system dependencies {#install-system-dependencies} |
| 16 | + |
| 17 | +First, install the required system dependencies: |
| 18 | + |
| 19 | +#### Install libchdb {#install-libchdb} |
14 | 20 |
|
15 | 21 | ```bash |
16 | 22 | curl -sL https://lib.chdb.io | bash |
17 | 23 | ``` |
18 | 24 |
|
19 | | -## Install {#install} |
| 25 | +#### Install build tools {#install-build-tools} |
20 | 26 |
|
21 | | -See: [chdb-bun](https://github.com/chdb-io/chdb-bun) |
| 27 | +You'll need either `gcc` or `clang` installed on your system: |
22 | 28 |
|
23 | | -## GitHub repository {#github-repository} |
| 29 | +### Step 2: Install chDB-bun {#install-chdb-bun} |
24 | 30 |
|
25 | | -You can find the GitHub repository for the project at [chdb-io/chdb-bun](https://github.com/chdb-io/chdb-bun). |
| 31 | +```bash |
| 32 | +# Install from the GitHub repository |
| 33 | +bun add github:chdb-io/chdb-bun |
| 34 | + |
| 35 | +# Or clone and build locally |
| 36 | +git clone https://github.com/chdb-io/chdb-bun.git |
| 37 | +cd chdb-bun |
| 38 | +bun install |
| 39 | +bun run build |
| 40 | +``` |
26 | 41 |
|
27 | 42 | ## Usage {#usage} |
28 | 43 |
|
29 | | -### Query(query, *format) (ephemeral) {#queryquery-format-ephemeral} |
| 44 | +chDB-bun supports two query modes: ephemeral queries for one-time operations and persistent sessions for maintaining database state. |
| 45 | + |
| 46 | +### Ephemeral queries {#ephemeral-queries} |
| 47 | + |
| 48 | +For simple, one-off queries that don't require persistent state: |
30 | 49 |
|
31 | | -```javascript |
| 50 | +```typescript |
32 | 51 | import { query } from 'chdb-bun'; |
33 | 52 |
|
34 | | -// Query (ephemeral) |
35 | | -var result = query("SELECT version()", "CSV"); |
36 | | -console.log(result); // 23.10.1.1 |
| 53 | +// Basic query |
| 54 | +const result = query("SELECT version()", "CSV"); |
| 55 | +console.log(result); // "23.10.1.1" |
| 56 | + |
| 57 | +// Query with different output formats |
| 58 | +const jsonResult = query("SELECT 1 as id, 'Hello' as message", "JSON"); |
| 59 | +console.log(jsonResult); |
| 60 | + |
| 61 | +// Query with calculations |
| 62 | +const mathResult = query("SELECT 2 + 2 as sum, pi() as pi_value", "Pretty"); |
| 63 | +console.log(mathResult); |
| 64 | + |
| 65 | +// Query system information |
| 66 | +const systemInfo = query("SELECT * FROM system.functions LIMIT 5", "CSV"); |
| 67 | +console.log(systemInfo); |
37 | 68 | ``` |
38 | 69 |
|
39 | | -<!-- vale ClickHouse.Headings = NO --> |
40 | | -### Session.Query(query, *format) {#sessionqueryquery-format} |
41 | | -<!-- vale ClickHouse.Headings = YES --> |
| 70 | +### Persistent sessions {#persistent-sessions} |
42 | 71 |
|
43 | | -```javascript |
44 | | -import { Session } from 'chdb-bun'; |
45 | | -const sess = new Session('./chdb-bun-tmp'); |
| 72 | +For complex operations that require maintaining state across queries: |
46 | 73 |
|
47 | | -// Query Session (persistent) |
48 | | -sess.query("CREATE FUNCTION IF NOT EXISTS hello AS () -> 'Hello chDB'", "CSV"); |
49 | | -var result = sess.query("SELECT hello()", "CSV"); |
50 | | -console.log(result); |
| 74 | +```typescript |
| 75 | +import { Session } from 'chdb-bun'; |
51 | 76 |
|
52 | | -// Before cleanup, you can find the database files in `./chdb-bun-tmp` |
| 77 | +// Create a session with persistent storage |
| 78 | +const sess = new Session('./chdb-bun-tmp'); |
53 | 79 |
|
54 | | -sess.cleanup(); // cleanup session, this will delete the database |
| 80 | +try { |
| 81 | + // Create a database and table |
| 82 | + sess.query(` |
| 83 | + CREATE DATABASE IF NOT EXISTS mydb; |
| 84 | + CREATE TABLE IF NOT EXISTS mydb.users ( |
| 85 | + id UInt32, |
| 86 | + name String, |
| 87 | + email String |
| 88 | + ) ENGINE = MergeTree() ORDER BY id |
| 89 | + `, "CSV"); |
| 90 | + |
| 91 | + // Insert data |
| 92 | + sess.query(` |
| 93 | + INSERT INTO mydb.users VALUES |
| 94 | + (1, 'Alice', '[email protected]'), |
| 95 | + |
| 96 | + (3, 'Charlie', '[email protected]') |
| 97 | + `, "CSV"); |
| 98 | + |
| 99 | + // Query the data |
| 100 | + const users = sess.query("SELECT * FROM mydb.users ORDER BY id", "JSON"); |
| 101 | + console.log("Users:", users); |
| 102 | + |
| 103 | + // Create and use custom functions |
| 104 | + sess.query("CREATE FUNCTION IF NOT EXISTS hello AS () -> 'Hello chDB'", "CSV"); |
| 105 | + const greeting = sess.query("SELECT hello() as message", "Pretty"); |
| 106 | + console.log(greeting); |
| 107 | + |
| 108 | + // Aggregate queries |
| 109 | + const stats = sess.query(` |
| 110 | + SELECT |
| 111 | + COUNT(*) as total_users, |
| 112 | + MAX(id) as max_id, |
| 113 | + MIN(id) as min_id |
| 114 | + FROM mydb.users |
| 115 | + `, "JSON"); |
| 116 | + console.log("Statistics:", stats); |
| 117 | + |
| 118 | +} finally { |
| 119 | + // Always cleanup the session to free resources |
| 120 | + sess.cleanup(); // This deletes the database files |
| 121 | +} |
55 | 122 | ``` |
0 commit comments