@rip-lang/db 1.0.1 → 1.0.2

package/README.md

@@ -2,176 +2,159 @@
 
 # Rip DB - @rip-lang/db
 
-> **DuckDB server with the official DuckDB UI**
+> **A lightweight DuckDB HTTP server with the official DuckDB UI built in**
 
-High-performance DuckDB HTTP server using native Zig bindings. Includes full
-compatibility with the official DuckDB UI — no WASM, pure native speed.
+Rip DB turns any DuckDB database into a full-featured HTTP server — complete
+with the official DuckDB UI for interactive queries, notebooks, and data
+exploration. It connects to DuckDB via pure Bun FFI (no npm packages, no
+native build step) and implements DuckDB's binary serialization protocol
+to power the UI with native-speed data transfer.
 
 ## Quick Start
 
 ```bash
-# Install
-bun add -g @rip-lang/db
-
-# Run (opens DuckDB UI at http://localhost:4213)
-rip-db
+# Install DuckDB and Rip DB
+brew install duckdb            # macOS (or see duckdb.org for Linux)
+bun add -g @rip-lang/db        # Installs rip-db command
+
+# Start the server
+rip-db                          # In-memory database
+rip-db mydata.duckdb            # File-based database
+rip-db mydata.duckdb --port 8080
+```
 
-# With a database file
-rip-db mydata.duckdb
+Open **http://localhost:4213** for the official DuckDB UI.
 
-# Custom port
-rip-db --port=8080
-```
+## What It Does
 
-Open http://localhost:4213 to use the official DuckDB UI.
+Rip DB sits between your clients and DuckDB, providing two interfaces:
 
-## Features
+```
+┌─────────────┐          ┌─────────────┐          ┌─────────────┐
+│  DuckDB UI  │  binary  │   rip-db    │   FFI    │   DuckDB    │
+│  (Browser)  │◀────────▶│   (Bun)     │◀────────▶│  (native)   │
+└─────────────┘          └─────────────┘          └─────────────┘
+                               ▲
+                               │ HTTP/S
+                               │ (JSON)
+                               ▼
+                      ┌─────────────────┐
+                      │  HTTP Clients   │
+                      │  (curl, apps)   │
+                      └─────────────────┘
+```
 
-- **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
+**DuckDB UI** — The official DuckDB notebook interface loads instantly in your
+browser. Rip DB proxies the UI assets from ui.duckdb.org and implements the
+full binary serialization protocol that the UI uses to communicate with DuckDB.
+This includes query execution, SQL tokenization for syntax highlighting, and
+Server-Sent Events for real-time catalog updates.
 
-## API Endpoints
+**JSON API** — Any HTTP client can execute SQL queries and receive JSON
+responses. Use it from curl, your application code, or any language that
+speaks HTTP.
 
-### DuckDB UI (Binary Protocol)
+## Features
 
-The official DuckDB UI works out of the box at `http://localhost:4213/`.
+- **Official DuckDB UI** — Interactive notebooks, syntax highlighting, data exploration
+- **Full binary protocol** — Native DuckDB UI serialization implemented in Rip
+- **Pure Bun FFI** — Direct calls to DuckDB's C API using the modern chunk-based interface
+- **Zero npm dependencies for DuckDB** — Uses the system-installed DuckDB library
+- **Parameterized queries** — Prepared statements with type-safe parameter binding
+- **Complete type support** — All DuckDB types handled natively, including UUID, DECIMAL, TIMESTAMP, LIST, STRUCT, MAP
+- **DECIMAL precision preserved** — Exact string representation, never converted to floating point
+- **Timestamps as UTC** — All timestamps returned as JavaScript Date objects (UTC)
+- **Powered by @rip-lang/api** — Fast, lightweight HTTP server framework
+- **Single binary** — One `rip-db` command, one process, one database
 
-| 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
 
-### JSON API
+For programmatic access from any HTTP client.
 
-For programmatic access:
+### POST /sql
 
-**POST /sql** — Execute SQL with JSON body
+Execute SQL with optional parameters:
 
 ```bash
 curl -X POST http://localhost:4213/sql \
   -H "Content-Type: application/json" \
-  -d '{"sql": "SELECT * FROM users WHERE id = 1"}'
+  -d '{"sql": "SELECT * FROM users WHERE id = $1", "params": [1]}'
 ```
 
-Response (JSONCompact format):
-```json
-{
-  "meta": [{"name": "id", "type": "INTEGER"}, {"name": "name", "type": "VARCHAR"}],
-  "data": [[1, "Alice"]],
-  "rows": 1,
-  "time": 0.001
-}
-```
+### POST /
 
-**POST /** — Raw SQL in body (duck-ui compatible)
+Execute raw SQL (body is the query):
 
 ```bash
 curl -X POST http://localhost:4213/ -d "SELECT 42 as answer"
 ```
 
-**GET /health** — Health check
+Response format:
 
 ```json
-{"ok": true}
+{
+  "meta": [{"name": "answer", "type": "INTEGER"}],
+  "data": [[42]],
+  "rows": 1,
+  "time": 0.001
+}
 ```
 
-**GET /status** — Database info
+### Other Endpoints
 
-```json
-{"ok": true, "database": "mydata.duckdb", "tables": ["users", "orders"]}
-```
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | Health check |
+| `/tables` | GET | List all tables |
+| `/schema/:table` | GET | Table schema |
 
-**GET /tables** — List tables
+## DuckDB UI
 
-```json
-{"ok": true, "tables": ["users", "orders"]}
-```
+The official DuckDB UI is available at the root URL. It provides:
 
-**GET /schema/:table** — Table schema
+- **SQL Notebooks** — Write and execute queries in a notebook interface
+- **Syntax Highlighting** — Real-time SQL tokenization as you type
+- **Data Exploration** — Browse tables, schemas, and query results
+- **Multiple Databases** — Attach and query across databases
 
-```json
-{"ok": true, "table": "users", "columns": [{"column_name": "id", "data_type": "INTEGER"}]}
-```
-
-## Building from Source
+The UI communicates with Rip DB using DuckDB's binary serialization protocol,
+which Rip DB implements in full. This means the UI works exactly as it does
+with the official `duckdb -ui` command — same features, same performance.
 
-Requires Zig 0.15+ and DuckDB development files.
+## How It Works
 
-```bash
-cd packages/db
+Rip DB is built from three files:
 
-# Build for current platform (outputs to lib/{os}-{arch}/duckdb.node)
-zig build -Doptimize=ReleaseFast --prefix .
+| File | Lines | Role |
+|------|-------|------|
+| `db.rip` | ~390 | HTTP server — routes, middleware, UI proxy |
+| `lib/duckdb.mjs` | ~800 | FFI driver — modern chunk-based DuckDB C API |
+| `lib/duckdb-binary.rip` | ~550 | Binary serializer — DuckDB UI protocol |
 
-# Run tests
-zig build test
-```
+The FFI driver uses DuckDB's modern chunk-based API (`duckdb_fetch_chunk`,
+`duckdb_vector_get_data`) to read query results directly from columnar memory.
+No deprecated per-value functions, no intermediate copies. For complex types
+like DECIMAL, ENUM, LIST, and STRUCT, it uses DuckDB's logical type
+introspection to read values with full fidelity.
 
-Set `DUCKDB_DIR` if DuckDB is not at `/opt/homebrew`:
+The binary serializer implements the same wire protocol that DuckDB's official
+UI extension uses. It handles all DuckDB types including native 16-byte UUID
+serialization, uint64-aligned validity bitmaps, and proper timestamp encoding.
 
-```bash
-DUCKDB_DIR=/path/to/duckdb zig build
-```
+## Requirements
 
-### Cross-Compiling
+- **Bun** 1.0+
+- **DuckDB** library installed on the system
+  - macOS: `brew install duckdb`
+  - Linux: Install from [duckdb.org](https://duckdb.org/docs/installation)
+- **rip-lang** 2.8+ (installed automatically as a dependency)
 
-Zig can cross-compile to other platforms:
+Set `DUCKDB_LIB_PATH` if DuckDB is not in a standard location:
 
 ```bash
-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
-```
-
-**Note:** Cross-compiling requires DuckDB libraries for each target platform.
-For production, use CI/CD with native builds on each OS (GitHub Actions runners).
-
-## Architecture
-
-```
-┌─────────────┐          ┌─────────────┐          ┌─────────────┐
-│  DuckDB UI  │  binary  │   rip-db    │   FFI    │   DuckDB    │
-│  (Browser)  │◀────────▶│   (Bun)     │◀────────▶│   (native)  │
-└─────────────┘          └─────────────┘          └─────────────┘
-```
-
-- **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
-
-See [INTERNALS.md](./INTERNALS.md) for protocol details.
-
-## Files
-
-```
-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
+DUCKDB_LIB_PATH=/path/to/libduckdb.dylib rip-db
 ```
 
-## Requirements
-
-- Bun 1.0+
-- rip-lang 2.0+
-- @rip-lang/api 0.5+
-
 ## License
 
 MIT

package/bin/rip-db

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