@rip-lang/db 0.9.0 → 1.0.1

package/README.md

@@ -2,320 +2,176 @@
 
 # Rip DB - @rip-lang/db
 
-> **Simple RestFUL HTTP server for concurrent DuckDB read and write queries**
+> **DuckDB server with the official DuckDB UI**
 
-Uses custom Zig-based DuckDB bindings (`lib/`) for fast, type-safe database access.
+High-performance DuckDB HTTP server using native Zig bindings. Includes full
+compatibility with the official DuckDB UI — no WASM, pure native speed.
 
-## Overview
+## Quick Start
 
 ```bash
-# Install globally
+# Install
 bun add -g @rip-lang/db
 
-# Run with in-memory database
+# Run (opens DuckDB UI at http://localhost:4213)
 rip-db
 
-# Run with file-based database
-rip-db mydb.duckdb
+# With a database file
+rip-db mydata.duckdb
 
-# Specify port
-rip-db mydb.duckdb --port=8080
+# Custom port
+rip-db --port=8080
 ```
 
-Or run directly with Rip:
+Open http://localhost:4213 to use the official DuckDB UI.
 
-```bash
-rip db.rip :memory: --port=4000
-```
+## Features
+
+- **Official DuckDB UI** — Beautiful query interface at `/`
+- **Native Zig bindings** — Zero-copy binary protocol, no JS serialization overhead
+- **JSON API** — Simple REST endpoints for programmatic access
+- **Single process** — DuckDB's multi-threaded engine handles concurrency
 
 ## API Endpoints
 
-### POST /sql
+### DuckDB UI (Binary Protocol)
 
-Execute any SQL statement (queries or mutations) with JSON body.
+The official DuckDB UI works out of the box at `http://localhost:4213/`.
 
-**Request:**
-```json
-{
-  "sql": "SELECT * FROM users WHERE id = ?",
-  "params": [1]
-}
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/` | GET | Official DuckDB UI |
+| `/ddb/run` | POST | Execute SQL (binary) |
+| `/ddb/tokenize` | POST | Syntax highlighting |
+| `/ddb/interrupt` | POST | Cancel query |
+
+### JSON API
+
+For programmatic access:
+
+**POST /sql** — Execute SQL with JSON body
+
+```bash
+curl -X POST http://localhost:4213/sql \
+  -H "Content-Type: application/json" \
+  -d '{"sql": "SELECT * FROM users WHERE id = 1"}'
 ```
 
-**Response (JSONCompact format):**
+Response (JSONCompact format):
 ```json
 {
-  "meta": [
-    {"name": "id", "type": "INTEGER"},
-    {"name": "name", "type": "VARCHAR"},
-    {"name": "email", "type": "VARCHAR"}
-  ],
-  "data": [
-    [1, "Alice", "alice@example.com"]
-  ],
+  "meta": [{"name": "id", "type": "INTEGER"}, {"name": "name", "type": "VARCHAR"}],
+  "data": [[1, "Alice"]],
   "rows": 1,
   "time": 0.001
 }
 ```
 
-### POST /
-
-Execute SQL with raw body (duck-ui compatible). Used by [duck-ui](https://demo.duckui.com).
-
-**Request:**
-```
-POST / HTTP/1.1
-Content-Type: application/x-www-form-urlencoded
+**POST /** — Raw SQL in body (duck-ui compatible)
 
-SELECT * FROM users WHERE id = 1
+```bash
+curl -X POST http://localhost:4213/ -d "SELECT 42 as answer"
 ```
 
-**Response:** Same JSONCompact format as `/sql`.
-
-### GET /health
-
-Simple health check (no database query).
+**GET /health** — Health check
 
 ```json
-{ "ok": true }
+{"ok": true}
 ```
 
-### GET /status
-
-Database info including table list.
+**GET /status** — Database info
 
 ```json
-{
-  "ok": true,
-  "database": "mydb.duckdb",
-  "tables": ["users", "orders", "products"],
-  "time": "2026-02-02T14:30:00.000Z"
-}
+{"ok": true, "database": "mydata.duckdb", "tables": ["users", "orders"]}
 ```
 
-### GET /tables
-
-List all tables in the database.
+**GET /tables** — List tables
 
 ```json
-{
-  "ok": true,
-  "tables": ["users", "orders", "products"]
-}
+{"ok": true, "tables": ["users", "orders"]}
 ```
 
-### GET /schema/:table
-
-Get schema for a specific table.
+**GET /schema/:table** — Table schema
 
 ```json
-{
-  "ok": true,
-  "table": "users",
-  "columns": [
-    { "column_name": "id", "data_type": "INTEGER", "is_nullable": "NO" },
-    { "column_name": "name", "data_type": "VARCHAR", "is_nullable": "YES" },
-    { "column_name": "email", "data_type": "VARCHAR", "is_nullable": "YES" }
-  ]
-}
-```
-
-### GET /ui
-
-Built-in SQL console. Open in browser:
-
-```
-http://localhost:4000/ui
-```
-
-## DuckDB UI Compatibility
-
-rip-db implements the official DuckDB UI binary protocol, making it compatible with
-DuckDB's built-in UI. This means you can use the beautiful DuckDB UI with rip-db!
-
-### Binary Protocol Endpoints
-
-| Endpoint          | Method | Purpose                    |
-|-------------------|--------|----------------------------|
-| `/ddb/run`        | POST   | Execute SQL (binary result)|
-| `/ddb/interrupt`  | POST   | Cancel running query       |
-| `/ddb/tokenize`   | POST   | Syntax highlighting        |
-| `/info`           | GET    | Version info               |
-
-### How It Works
-
-```
-┌─────────────┐     Binary Protocol    ┌─────────────┐
-│  DuckDB UI  │ ◀─────────────────────▶│   rip-db    │
-│  (Browser)  │                        │   Server    │
-└─────────────┘                        └─────────────┘
+{"ok": true, "table": "users", "columns": [{"column_name": "id", "data_type": "INTEGER"}]}
 ```
 
-The UI sends SQL to `/ddb/run`, rip-db executes it and returns results in DuckDB's
-binary format. The UI has no idea it's talking to rip-db instead of native DuckDB!
-
-For protocol details, see [PROTOCOL.md](./PROTOCOL.md).
-
-## Examples
+## Building from Source
 
-### Create a table
+Requires Zig 0.15+ and DuckDB development files.
 
 ```bash
-curl -X POST http://localhost:4000/sql \
-  -H "Content-Type: application/json" \
-  -d '{"sql": "CREATE TABLE users (id INTEGER PRIMARY KEY, name VARCHAR, email VARCHAR)"}'
-```
+cd packages/db
 
-### Insert data
+# Build for current platform (outputs to lib/{os}-{arch}/duckdb.node)
+zig build -Doptimize=ReleaseFast --prefix .
 
-```bash
-curl -X POST http://localhost:4000/sql \
-  -H "Content-Type: application/json" \
-  -d '{"sql": "INSERT INTO users VALUES (?, ?, ?)", "params": [1, "Alice", "alice@example.com"]}'
+# Run tests
+zig build test
 ```
 
-### Query with parameters
+Set `DUCKDB_DIR` if DuckDB is not at `/opt/homebrew`:
 
 ```bash
-curl -X POST http://localhost:4000/sql \
-  -H "Content-Type: application/json" \
-  -d '{"sql": "SELECT * FROM users WHERE name LIKE ?", "params": ["%Ali%"]}'
+DUCKDB_DIR=/path/to/duckdb zig build
 ```
 
-### Aggregations
+### Cross-Compiling
+
+Zig can cross-compile to other platforms:
 
 ```bash
-curl -X POST http://localhost:4000/sql \
-  -H "Content-Type: application/json" \
-  -d '{"sql": "SELECT COUNT(*) as total, AVG(age) as avg_age FROM users"}'
+zig build -Dtarget=x86_64-linux-gnu     # Linux x64
+zig build -Dtarget=aarch64-linux-gnu    # Linux ARM64
+zig build -Dtarget=x86_64-windows       # Windows x64
+zig build -Dtarget=aarch64-macos        # macOS ARM64
+zig build -Dtarget=x86_64-macos         # macOS x64
 ```
 
-## Response Format
+**Note:** Cross-compiling requires DuckDB libraries for each target platform.
+For production, use CI/CD with native builds on each OS (GitHub Actions runners).
 
-All responses use JSONCompact format (compatible with DuckDB HTTP Server and duck-ui):
+## Architecture
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `meta` | object[] | Column metadata: `[{name, type}, ...]` |
-| `data` | any[][] | Row data as arrays |
-| `rows` | number | Number of rows returned |
-| `time` | number | Execution time in seconds |
-| `error` | string | Error message (on failure) |
-
-**Success response:**
-```json
-{
-  "meta": [{"name": "id", "type": "INTEGER"}, {"name": "name", "type": "VARCHAR"}],
-  "data": [[1, "Alice"], [2, "Bob"]],
-  "rows": 2,
-  "time": 0.001
-}
 ```
-
-**Error response:**
-```json
-{"error": "Table 'foo' does not exist"}
+┌─────────────┐          ┌─────────────┐          ┌─────────────┐
+│  DuckDB UI  │  binary  │   rip-db    │   FFI    │   DuckDB    │
+│  (Browser)  │◀────────▶│   (Bun)     │◀────────▶│   (native)  │
+└─────────────┘          └─────────────┘          └─────────────┘
 ```
 
-This format is compatible with [duck-ui](https://demo.duckui.com) and other DuckDB HTTP clients.
-
-## Performance
-
-Our custom Zig-based DuckDB bindings deliver exceptional performance:
+- **Single FFI call** per query (not per-value)
+- **Zero-copy** for numeric columns
+- **Binary serialization in Zig** — no JavaScript overhead
+- **Pre-allocated buffers** — no allocations per query
 
-| Operation | Latency | Throughput |
-|-----------|---------|------------|
-| Point lookup (WHERE id=?) | 0.09ms | 11,000 qps |
-| Range scan (LIMIT 100) | 0.20ms | 5,000 qps |
-| Aggregation (COUNT/AVG/MAX) | 0.12ms | 8,400 qps |
-| JOIN + GROUP BY | 0.25ms | 4,000 qps |
-| INSERT (single row) | 0.13ms | 7,700 qps |
+See [INTERNALS.md](./INTERNALS.md) for protocol details.
 
-### Comparison to MySQL/PostgreSQL
-
-| Operation | Our DuckDB | MySQL/PG (localhost) | Speedup |
-|-----------|------------|----------------------|---------|
-| Point lookup | **0.09ms** | 0.3-1ms | 3-10x faster |
-| Range scan | **0.20ms** | 1-5ms | 5-25x faster |
-| Aggregation | **0.12ms** | 2-20ms | 17-170x faster |
-| JOIN + GROUP BY | **0.25ms** | 5-50ms | 20-200x faster |
-| INSERT | **0.13ms** | 0.5-2ms | 4-15x faster |
-
-**Why so fast?**
-- **Zero network latency** — DuckDB runs in-process
-- **No connection overhead** — No auth, handshake, or protocol parsing
-- **Columnar engine** — DuckDB is optimized for analytical queries
-- **Direct FFI** — Zig bindings call DuckDB's C API directly
-
-## Architecture & Concurrency
-
-### Single Process, High Concurrency
-
-DuckDB only allows **one process** to access a database file at a time (for write access). This means rip-db runs as a **single process** — it does NOT use rip-server's multi-worker model.
-
-However, rip-db handles **high concurrency** through two mechanisms:
+## Files
 
 ```
-┌─────────────────────────────────────────────────────────┐
-│                   rip-db (single process)               │
-├─────────────────────────────────────────────────────────┤
-│   Bun HTTP Server (async I/O)                           │
-│   ├─ Request 1 ──┐                                      │
-│   ├─ Request 2 ──┼── thousands of concurrent            │
-│   ├─ Request 3 ──┤   connections via event loop         │
-│   └─ Request N ──┘                                      │
-├─────────────────────────────────────────────────────────┤
-│   rip-api (routes, middleware)                          │
-├─────────────────────────────────────────────────────────┤
-│   DuckDB (multi-threaded query engine)                  │
-│   └─ Queries parallelized across CPU cores              │
-└─────────────────────────────────────────────────────────┘
+packages/db/
+├── build.zig       # Zig build configuration
+├── src/
+│   └── duckdb.zig  # Native Zig bindings
+├── lib/
+│   ├── duckdb.mjs  # Bun FFI wrapper
+│   └── darwin-arm64/
+│       └── duckdb.node  # Compiled library
+├── bin/
+│   └── rip-db      # CLI entry point
+├── db.rip          # Server implementation
+├── README.md       # This file
+└── INTERNALS.md    # Protocol & architecture details
 ```
 
-**Layer 1: Bun's Async I/O**
-- Single JavaScript thread with event loop
-- Handles thousands of concurrent HTTP connections
-- Non-blocking I/O — while one request waits on DuckDB, others are processed
-- No thread-per-request overhead
-
-**Layer 2: DuckDB's Multi-Threading**
-- Queries are parallelized across all CPU cores internally
-- MVCC for concurrent reads
-- Writes serialized automatically by DuckDB
-
-### Why Not Multi-Process?
-
-| Approach | Works with DuckDB? | Why |
-|----------|-------------------|-----|
-| Multi-process (rip-server) | ❌ No | DuckDB only allows one process with write access |
-| Multi-threaded | ✅ Yes | DuckDB handles this internally |
-| Async I/O | ✅ Yes | Bun's event loop handles concurrent connections |
-
-### The Result
-
-Even as a single process, rip-db can handle:
-- **Thousands of concurrent connections** (Bun async I/O)
-- **Parallel query execution** (DuckDB multi-threading)
-- **High throughput** (11,000+ queries/sec on typical hardware)
-
-This is the correct architecture for DuckDB — single process, high concurrency.
-
 ## Requirements
 
 - Bun 1.0+
 - rip-lang 2.0+
 - @rip-lang/api 0.5+
 
-## Building from Source
-
-To rebuild the native DuckDB bindings (requires Zig 0.15+ and DuckDB):
-
-```bash
-./src/build.sh
-```
-
-This creates `lib/{platform}-{arch}/duckdb.node` for your platform.
-
 ## License
 
 MIT

package/bin/rip-db

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 
@@ -8,10 +8,10 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
 const dbRip = join(__dirname, '..', 'db.rip');
-const args = process.argv.slice(2).join(' ');
+const args = process.argv.slice(2);
 
 try {
-  execSync(`rip ${dbRip} ${args}`, { stdio: 'inherit' });
+  execFileSync('rip', [dbRip, ...args], { stdio: 'inherit' });
 } catch (error) {
   process.exit(error.status || 1);
 }

package/build.zig

@@ -0,0 +1,88 @@
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    // Use native target by default
+    const target = b.standardTargetOptions(.{});
+    // Default to ReleaseFast for plain `zig build`, but allow overrides:
+    // - `-Doptimize=...`
+    // - `--release=fast|safe|small`
+    const optimize = b.option(
+        std.builtin.OptimizeMode,
+        "optimize",
+        "Prioritize performance, safety, or binary size",
+    ) orelse switch (b.release_mode) {
+        .off, .fast => std.builtin.OptimizeMode.ReleaseFast,
+        .safe => std.builtin.OptimizeMode.ReleaseSafe,
+        .small => std.builtin.OptimizeMode.ReleaseSmall,
+        .any => std.builtin.OptimizeMode.ReleaseFast,
+    };
+    // Note: Recommended explicit build for packaging: zig build -Doptimize=ReleaseFast --prefix .
+
+    // Get DuckDB directory (defaults to /opt/homebrew)
+    const duckdb_dir = std.process.getEnvVarOwned(b.allocator, "DUCKDB_DIR") catch "/opt/homebrew";
+
+    // Create the module for the library
+    const module = b.createModule(.{
+        .root_source_file = b.path("src/duckdb.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+
+    // Add DuckDB include path
+    module.addIncludePath(.{ .cwd_relative = b.fmt("{s}/include", .{duckdb_dir}) });
+
+    // Build the shared library
+    const lib = b.addLibrary(.{
+        .linkage = .dynamic,
+        .name = "duckdb",
+        .root_module = module,
+    });
+
+    // Link against DuckDB
+    lib.addLibraryPath(.{ .cwd_relative = b.fmt("{s}/lib", .{duckdb_dir}) });
+    lib.linkSystemLibrary("duckdb");
+
+    // Determine output directory based on target
+    const os_tag = target.result.os.tag;
+    const arch = target.result.cpu.arch;
+
+    const os_name: []const u8 = switch (os_tag) {
+        .macos => "darwin",
+        .linux => "linux",
+        .windows => "windows",
+        else => "unknown",
+    };
+
+    const arch_name: []const u8 = switch (arch) {
+        .aarch64 => "arm64",
+        .x86_64 => "x64",
+        else => "unknown",
+    };
+
+    // Install to lib/{os}-{arch}/duckdb.node
+    const install_dir = b.fmt("lib/{s}-{s}", .{ os_name, arch_name });
+    const install_file = b.addInstallFileWithDir(
+        lib.getEmittedBin(),
+        .{ .custom = install_dir },
+        "duckdb.node",
+    );
+    b.getInstallStep().dependOn(&install_file.step);
+
+    // Tests
+    const test_module = b.createModule(.{
+        .root_source_file = b.path("src/duckdb.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+    test_module.addIncludePath(.{ .cwd_relative = b.fmt("{s}/include", .{duckdb_dir}) });
+
+    const tests = b.addTest(.{
+        .root_module = test_module,
+    });
+    tests.addLibraryPath(.{ .cwd_relative = b.fmt("{s}/lib", .{duckdb_dir}) });
+    tests.linkSystemLibrary("duckdb");
+
+    const run_tests = b.addRunArtifact(tests);
+    const test_step = b.step("test", "Run unit tests");
+    test_step.dependOn(&run_tests.step);
+}