#f4ah6o/duckdb

Upgrading from 0.6.4? See MIGRATION.md for the 0.6.4 → 0.7.0 breaking changes (structured errors, 128-bit Decimal, typed Arrow vectors, the quack package move) with before/after examples.

#Targets

• Native: links against libduckdb via the DuckDB C API.
• JavaScript: compile with the MoonBit JS target and pick a backend at runtime:
  • JsBackend::Node uses @duckdb/node-api.
  • JsBackend::Wasm uses @duckdb/duckdb-wasm in the browser.
• MoonBit wasm/wasm-gc targets are not supported (they use stub implementations).

#Feature Support Matrix

#Advanced Types Detailed Support

• Decimal carries the full DuckDB 128-bit scaled integer as lower : UInt64 and upper : Int64 halves (two's complement). decimal_from_hugeint builds a Decimal from halves, decimal_from_parts/decimal_to_parts convert to/from whole+fractional parts (decimal_to_parts returns BigInt values so whole parts beyond 64 bits are preserved, with a signed fractional remainder so negative sub-unit values like -0.50 round-trip), and decimal_to_double may lose precision above 2^53, matching DuckDB semantics.
• List/Struct/Map are represented as string arrays (VARCHAR-only) and rely on DuckDB casting.
• JS (WASM) uses direct duckdb-wasm prepared parameters only. Verified advanced prepared-statement bind support is limited to Decimal and Interval string parameters with an explicit SQL cast, for example ?::DECIMAL(10,2) or ?::INTERVAL.
• JS (WASM) Blob, List, Struct, and Map direct prepared parameters are explicitly unsupported: the browser smoke test fails for them against @duckdb/duckdb-wasm 1.33.1-dev18.0 through 1.33.1-dev65.0.
• Appender date/timestamp helpers are only implemented for native targets.

#Arrow Integration

• Arrow query result type
• Schema extraction
• Columnar access via canonical typed vectors (ArrowResult::to_chunks + Vector accessors); the legacy get_column_* getters still work as deprecated forwarders — see MIGRATION.md
• Supported types: BOOLEAN, INTEGER, VARCHAR, DOUBLE, BIGINT (plus wider ColumnType coverage through the typed vectors)

#CI Coverage

#Updating DuckDB dependencies

• Verification path. A version bump lands as a PR that updates the pin in package.json (JS) or ci.yml (native) and adds the new version to the CI matrix — the matrix install step is what actually exercises a version. The oldest matrix entry stays as the minimum supported version until intentionally dropped; the newest entry matches the package.json pin. The duckdb-pins CI job (scripts/check_duckdb_pins.mjs, runnable locally via pnpm check:dep-pins) enforces this: it fails when a package.json pin does not equal the newest matrix entry, so a bump that forgets the matrix update cannot look green while the pinned version goes untested.
• Automated bumps. Dependabot opens grouped weekly PRs for @duckdb/* npm packages and GitHub Actions. A Dependabot PR is merged only after the new version is added to the ci.yml matrix (the duckdb-pins job fails otherwise) and the full backend suite is green: moon test --target js + pnpm test:wasm-browser for JS bumps, moon test --target native for native bumps.
• Advanced-type re-check. The browser smoke check exercises direct prepared parameters for Decimal, Interval, Blob, List, Struct, and Map. If a bump flips any of them between supported and unsupported, update the BackendCapabilities table in src/duckdb_capabilities.mbt, regenerate the Advanced Types table with scripts/support_matrix.sh, and update the expected-unsupported set in scripts/wasm_browser_smoke.mjs in the same PR.
• A DuckDB 2.0 lane will be added once a 2.0 libduckdb build is published on the DuckDB releases page.

#Installation

#Native Target

#Install libduckdb

brew install duckdb

# Download a release that matches your platform
wget https://github.com/duckdb/duckdb/releases/download/<version>/libduckdb-linux-amd64.zip
unzip libduckdb-linux-amd64.zip
sudo cp libduckdb.so /usr/local/lib/
sudo ldconfig

git clone https://github.com/duckdb/duckdb.git
cd duckdb
mkdir build && cd build
cmake ..
make -j$(nproc)
sudo make install
sudo ldconfig

#Linker Configuration

moon build --target-native -- -L/usr/local/lib -Wl,-rpath,/usr/local/lib -lduckdb

• Include: /opt/homebrew/include, /usr/local/include, /usr/include
• Library: /opt/homebrew/lib, /usr/local/lib, /usr/lib

#Troubleshooting Native Link Errors

1. duckdb.h exists in one of the include paths above.
2. libduckdb.dylib (macOS) or libduckdb.so (Linux) exists in one of the library paths above.
3. moon test --target native runs in an environment where those paths are visible to the linker.

#JavaScript Targets

#Node.js

pnpm install

#Browser (WASM)

pnpm install

pnpm test:wasm-browser

pnpm test:wasm-browser:install

#JavaScript Limitations

• WASM Appender - Not supported for WASM backend (use INSERT statements instead)
• WASM Advanced Types - Decimal and Interval prepared-statement binds are supported as direct string parameters with explicit SQL casts; Blob, List, Struct, and Map direct prepared parameters are unsupported
• Node.js Advanced Types - Decimal, Interval, Blob are supported for bind/append; List/Struct/Map are VARCHAR-only
• JS Appender Date/Timestamp - Not implemented (native only)

#Quack Remote Protocol

connect(on_ready=fn(result) {
  match result {
    Ok(conn) => {
      @quack.install(conn, on_done=fn(_) { () })
      @quack.load(conn, on_done=fn(_) { () })
      @quack.serve(
        conn,
        "quack:localhost",
        token="super_secret",
        on_done=fn(started) {
          match started {
            Ok(info) => println("quack server: \{info.rows}")
            Err(err) => println("quack serve failed: \{err}")
          }
        },
      )
    }
    Err(err) => println("connect failed: \{err}")
  }
})

@quack.create_secret(
  conn,
  "super_secret",
  scope="quack:localhost",
  on_done=fn(_) { () },
)

@quack.query(
  conn,
  "quack:localhost",
  "SELECT 42 AS answer",
  token="super_secret",
  on_done=fn(result) {
    match result {
      Ok(rows) => println("\{rows.rows}")
      Err(err) => println("quack query failed: \{err}")
    }
  },
)

@quack.attach(
  conn,
  "quack:localhost",
  "remote_db",
  token="super_secret",
  on_done=fn(_) { () },
)

#Usage

connect(on_ready=fn (result) {
  match result {
    Ok(conn) => {
      conn.query(
        "select 1 as a, NULL as b, 'duck' as c",
        on_done=fn (query_result) {
          match query_result {
            Ok(result) => {
              println("columns: \{result.columns}")
              println("rows: \{result.rows}")
              println("nulls: \{result.nulls}")
            }
            Err(err) => println("query failed: \{err}")
          }
        },
      )
      conn.close(on_done=fn (closed) {
        match closed {
          Ok(_) => ()
          Err(err) => println("close failed: \{err}")
        }
      })
    }
    Err(err) => println("connect failed: \{err}")
  }
})

#Typed Results

conn.query("select 1 as a, 2.5 as b, NULL as c", on_done=fn (query_result) {
  match query_result {
    Ok(result) => {
      let value = result.get_int(0, 0) // Some(1)
      let typed = result.to_typed()
      let b0 = typed.get_double(0, 1)
      let c0 = typed.get_string(0, 2) // None
      println("\{value} \{b0} \{c0}")
    }
    Err(err) => println("query failed: \{err}")
  }
})

#Streaming Results

#Basic Streaming (Count Rows)

connect(on_ready=fn (result) {
  match result {
    Ok(conn) => {
      conn.query_stream(
        "SELECT i FROM RANGE(1000000) tbl(i)",
        on_done=fn (stream_result) {
          match stream_result {
            Ok(stream) => {
              let mut total = 0
              let done = Ref::new(false)
              while !done.val {
                stream.next(on_done=fn (chunk_result) {
                  match chunk_result {
                    Ok(Some(chunk)) => total = total + chunk.row_count()
                    Ok(None) => done.val = true
                    Err(err) => {
                      done.val = true
                      println("stream failed: \{err}")
                    }
                  }
                })
              }
              stream.close(on_done=fn (_) { () })
              println("rows: \{total}")
            }
            Err(err) => println("stream failed: \{err}")
          }
        },
      )
    }
    Err(err) => println("connect failed: \{err}")
  }
})

#Aggregation Example

// Aggregate state to track running totals
pub struct Aggregates {
  mut total_rows : Int
  mut sum_values : Int
  mut min_value : Int?
  mut max_value : Int?
}

let agg_ref = Ref::new({ total_rows: 0, sum_values: 0, min_value: None, max_value: None })
let done_ref = Ref::new(false)

conn.query_stream(
  "SELECT value FROM measurements",
  on_done=fn (stream_result) {
    match stream_result {
      Ok(stream) => {
        while !done_ref.val {
          stream.next(on_done=fn (chunk_result) {
            match chunk_result {
              Ok(Some(chunk)) => {
                // Process each row in the chunk
                for row = 0; row < chunk.row_count(); row = row + 1 {
                  match chunk.cell(row, 0) {
                    Some(v) => {
                      let value = parse_int(v)
                      agg_ref.val.total_rows = agg_ref.val.total_rows + 1
                      agg_ref.val.sum_values = agg_ref.val.sum_values + value
                      // Update min/max...
                    }
                    None => ()
                  }
                }
              }
              Ok(None) => done_ref.val = true
              Err(err) => { done_ref.val = true; println("error: \{err}") }
            }
          })
        }
        stream.close(on_done=fn (_) {
          println("Total: \{agg_ref.val.total_rows}")
          println("Sum: \{agg_ref.val.sum_values}")
        })
      }
      Err(err) => println("stream failed: \{err}")
    }
  },
)

#Streaming Limitations

• Streamed DataChunk values are strings plus a null mask, consistent with QueryResult.
• Always call ResultStream::close when finished to release resources.

#JS Backend Selection

connect(
  on_ready=fn (result) { /* ... */ },
  backend=JsBackend::Wasm,
)

• Auto - Detects environment (Node.js uses Node, browser uses WASM)
• Node - Forces @duckdb/node-api
• Wasm - Forces @duckdb/duckdb-wasm

#Backend Capabilities

connect(on_ready=fn (result) {
  match result {
    Ok(conn) => {
      let caps = conn.capabilities()
      if caps.appender {
        // safe to call conn.create_appender(...)
      }
      match caps.require(BackendFeature::BlobBind) {
        Ok(_) => () // bind_blob is available
        Err(err) => println("gated: \{err.message()}")
      }
    }
    Err(err) => println("connect failed: \{err}")
  }
})

#Configuration

let config = Config::create()
match config.set("memory_limit", "1GB") {
  Ok(_) => ()
  Err(err) => println("config set failed: \{err}")
}

connect_with_config(
  on_ready=fn (result) { /* ... */ },
  config=Some(config),
  path=":memory:",
)

#Error Handling

• Success: Returns Ok(())
• Failure: Returns Err(err) where err is a structured DuckDBError variant (Query, Prepare, Bind, Append, Unsupported, Closed, InvalidArgument, Backend, DuckDB); err.message() returns the diagnostic text and err.error_type() the engine classification when one exists. See MIGRATION.md for the 0.6.4 Message migration.

match stmt.bind_int(1, 42) {
  Ok(_) =>
    match stmt.bind_varchar(2, "hello") {
      Ok(_) => ()
      Err(e) => println("bind failed: \{e}")
    }
  Err(e) => println("bind failed: \{e}")
}