duckdb

README

booba-shim/duckdb

A database/sql driver named "duckdb" plus a native Arrow API, both wrapping DuckDB-Wasm running in a browser Web Worker.

DSN format

<path>?key=val&key=val…

Where <path> is :memory: or a virtual filename pre-registered via the JS bridge. Supported query parameters:

• access_mode=read_only — enable read-only mode.

Example: "my-file.db?access_mode=read_only".

File registration

Before calling sql.Open, the page (or Go-side code via syscall/js) must pre-register files with the bridge.

From JavaScript:

// Register a file from a URL (lazy-loaded on first access)
await boobaShim.duckdb.registerFileURL('my-file.db', '/path/to/file.db');

// Register a file from bytes (immediate)
const bytes = new Uint8Array([/* ... */]);
await boobaShim.duckdb.registerFileBuffer('data.csv', bytes);

From Go (inside a WASM module):

import "syscall/js"

js.Global().Get("boobaShim").Get("duckdb").Call("registerFileURL", "my-file.db", "/path/to/file.db")

Then open the connection:

db, _ := sql.Open("duckdb", "my-file.db")

Supported types (v0.1.0)

Argument types (passed to db.QueryRow, db.Query, db.Exec):

• nil → NULL
• bool → BOOLEAN
• signed integers (int, int8, int16, int32, int64) → BIGINT
• unsigned integers (uint, uint8, uint16, uint32, uint64) up to math.MaxInt64 → BIGINT
• float32, float64 → DOUBLE
• string → VARCHAR
• []byte → BLOB
• time.Time → TIMESTAMP (ISO-8601 format, UTC)

Arrow column types (returned by db.Query / db.QueryRow.Scan):

• Boolean
• Int8, Int16, Int32, Int64
• Uint8, Uint16, Uint32, Uint64
• Float32, Float64
• String, LargeString
• Binary, LargeBinary
• Date32, Date64
• Timestamp

Anything else errors loudly; no silent truncation or zero-value fallback.

Async / goroutine safety

Every method blocks the calling goroutine on a JS Promise. This is safe inside tea.Cmd goroutines (which run off the main thread); it is not safe on Bubble Tea's main Update goroutine.

Single-connection concurrency: callers must serialize all operations on a single *sql.DB. Create a mutex or use a channel if you need true concurrency.

Known limitations (v0.1.0)

• Only one file-path connection per page session. The bridge hardcodes the ATTACH alias attached, so opening a second sql.Open("duckdb", "other.duckdb?...") in the same page session fails with a catalog error. :memory: connections are unaffected. Per-handle aliases are a v0.2 task.
• rowsAffected is always 0; DuckDB-Wasm does not expose row-count data.
• No transactions.
• No streaming send() path; all results are fully materialized via query() before returning.
• context.Context is accepted but cancellation is not implemented.
• --vendored asset-tool mode is a stub; use --cdn for production.
• uint64/UBIGINT values above math.MaxInt64 return an error rather than wrapping silently (driver.Value cannot carry uint64); lossless large-UBIGINT support is a v0.2 task.

Documentation

Overview

Package duckdb is a booba-shim that exposes upstream @duckdb/duckdb-wasm to Go-WASM programs as a database/sql driver named "duckdb" and a native Arrow API.

Under GOOS=js, importing this package for side effects registers the driver:

import _ "github.com/NimbleMarkets/booba-shim/duckdb"
db, err := sql.Open("duckdb", "my-data.duckdb?access_mode=read_only")

On any other GOOS, every public entry point returns ErrNonJSPlatform so host-side test binaries can import the package without panicking.

The page must load web/duckdb/duckdb-shim.js (via go tool booba-shim-assets) before the WASM main runs.

Index

• Variables
• type Client
  • func Open(_ context.Context, _ string) (*Client, error)
  • func (*Client) Close() error
  • func (*Client) Exec(_ context.Context, _ string, _ ...any) (int64, error)
  • func (*Client) QueryArrow(_ context.Context, _ string, _ ...any) (*ipc.Reader, error)
• type Error
  • func (e *Error) Error() string

Variables

var ErrNonJSPlatform = errors.New("booba-shim/duckdb: only usable under GOOS=js")

ErrNonJSPlatform is returned by every entry point when the package is imported under a GOOS other than js. It exists so that consumers can use build-tag patterns like:

//go:build !js
package data
import _ "github.com/duckdb/duckdb-go/v2"

//go:build js
package data
import _ "github.com/NimbleMarkets/booba-shim/duckdb"

and still run host-side `go test ./...` without panicking on missing JS globals.

Types

type Client

type Client struct{}

Client is the native (non-database/sql) handle to a DuckDB-Wasm connection. Under GOOS!=js it is an opaque, non-functional placeholder.

func Open

func Open(_ context.Context, _ string) (*Client, error)

Open returns ErrNonJSPlatform on non-js builds.

func (*Client) Close

func (*Client) Close() error

Close is a no-op on non-js builds.

func (*Client) Exec

func (*Client) Exec(_ context.Context, _ string, _ ...any) (int64, error)

Exec returns ErrNonJSPlatform on non-js builds.

func (*Client) QueryArrow

func (*Client) QueryArrow(_ context.Context, _ string, _ ...any) (*ipc.Reader, error)

QueryArrow returns ErrNonJSPlatform on non-js builds.

type Error

type Error struct {
	// Message is the human-readable error from DuckDB or the bridge.
	Message string
	// Code is set if DuckDB-Wasm exposed a structured code; "" otherwise.
	Code string
}

Error is the typed error returned for failures originating in the JS bridge (DuckDB-Wasm errors, connection issues, etc.).

func (*Error) Error

func (e *Error) Error() string