#f4ah6o/duckdb

#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

• List/Struct/Map are represented as string arrays (VARCHAR-only) and rely on DuckDB casting.
• JS (WASM) does not support advanced type bindings; use INSERT statements with type literals instead.
• Appender date/timestamp helpers are only implemented for native targets.

#Arrow Integration

• Arrow query result type
• Schema extraction
• Column-based data access (native also exposes nullable getters)
• Supported types: BOOLEAN, INTEGER, VARCHAR, DOUBLE, BIGINT

#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

npm install @duckdb/node-api@^1.4.3-r.3

#Browser (WASM)

npm install @duckdb/duckdb-wasm@^1.33.1-dev18.0

#JavaScript Limitations

• WASM Appender - Not supported for WASM backend (use INSERT statements instead)
• WASM Advanced Types - Blob, Decimal, Interval, List, Struct, Map are not supported for WASM backend
• 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)

#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

#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(DuckDBError::Message(reason))

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}")
}