duckdb

Kind	ffi-c
Capabilities	ffi file
Categories	database analytics ffi
Keywords	duckdb database sql analytics olap

DuckDB bindings for Kit - in-process analytical database

Files

File	Description
`.editorconfig`	Editor formatting configuration
`.gitignore`	Git ignore rules for build artifacts and dependencies
`.tool-versions`	asdf tool versions (Zig, Kit)
`LICENSE`	MIT license file
`README.md`	This file
`examples/basic.kit`	Basic usage example
`examples/sql-dsl.kit`	Example: sql dsl
`kit.toml`	Package manifest with metadata and dependencies
`src/duckdb.kit`	Main module
`tests/duckdb.test.kit`	Tests for duckdb
`tests/error-types.test.kit`	Tests for error-types

Dependencies

No Kit package dependencies.

Installation

kit add gitlab.com/kit-lang/packages/kit-duckdb.git

Usage

import Kit.Duckdb

License

MIT License - see LICENSE for details.

Exported Functions & Types

`DuckDBError`

DuckDB error type for typed error handling. Variants distinguish between different failure modes.

Variants

DuckDBConnectionError {message}

DuckDBQueryError {message}

DuckDBExecuteError {message}

DuckDBTypeError {message}

`duckdb-success`

Okresult state constant.

`duckdb-error`

Error result state constant.

`duckdb-type-invalid`

Invalid column type constant.

`duckdb-type-boolean`

Boolean column type constant.

`duckdb-type-tinyint`

Tiny integer column type constant.

`duckdb-type-smallint`

Small integer column type constant.

`duckdb-type-integer`

Integer column type constant.

`duckdb-type-bigint`

Big integer column type constant.

`duckdb-type-utinyint`

Unsigned tiny integer column type constant.

`duckdb-type-usmallint`

Unsigned small integer column type constant.

`duckdb-type-uinteger`

Unsigned integer column type constant.

`duckdb-type-ubigint`

Unsigned big integer column type constant.

`duckdb-type-float`

Float column type constant.

`duckdb-type-double`

Double column type constant.

`duckdb-type-timestamp`

Timestamp column type constant.

`duckdb-type-date`

Date column type constant.

`duckdb-type-time`

Time column type constant.

`duckdb-type-interval`

Interval column type constant.

`duckdb-type-hugeint`

Huge integer column type constant.

`duckdb-type-varchar`

Variable character column type constant.

`duckdb-type-blob`

Binary large object column type constant.

`duckdb-type-decimal`

Decimal column type constant.

`connect`

Note: This module uses Kit's standard Result type (Ok a | Err DuckDBError).

Opens a DuckDB database connection.

Creates a connection to a DuckDB database, either in-memory or file-backed. Returns a connection record containing the database handle and methods for query execution. The connection record includes error information if the connection fails.

Parameters:

Returns:

String -> {handle: Ptr, database: Ptr, driver: String, connected: Bool, error: String, query: String -> Result (List (Map String a)) DuckDBError, execute: String -> Result Int DuckDBError}

db = Duckdb.connect ":memory:"    # in-memory database
db = Duckdb.connect "analytics.db" # file-based database
result = db.query "SELECT * FROM users"

`try-connect`

Attempts to connect to DuckDB, returning Result type.

Similar to connect but uses a Result type for functional error handling. Returns Ok with a connection record if successful, or Error with a message string if the connection fails.

Parameters:

Returns:

String -> Result {handle: Ptr, database: Ptr, driver: String, connected: Bool, error: String, query: String -> Result (List (Map String a)) DuckDBError, execute: String -> Result Int DuckDBError} DuckDBError

match Duckdb.try-connect ":memory:"
| Ok db ->
    result = db.query "SELECT 42 as answer"
    Duckdb.close db
| Err e ->
    print "Connection failed: ${e}"

`is-connected?`

Checks if a database connection is valid.

Parameters:

Returns:

{connected: Bool | r} -> Bool

db = Duckdb.connect "test.db"
if Duckdb.is-connected? db then
  print "Connected successfully"

`close`

Closes a database connection and database.

Cleans up resources associated with a database connection. Currently a no-op due to crashes in cleanup functions. Resources are automatically cleaned up when the process exits.

Parameters:

Returns:

a -> Unit

db = Duckdb.connect ":memory:"
# ... use database ...
Duckdb.close db

`query`

Executes a query and returns all rows as a list of records.

Executes a SQL SELECT query and parses all result rows into Kit records. Each row is returned as a record with column names as keys and values wrapped in Option types (Some for non-null, None for null).

Parameters:

Returns:

Ptr -> NonEmptyString -> Result (List (Map String a)) DuckDBError

match query connection "SELECT id, name FROM users WHERE id > 10"
| Ok rows ->
    rows |> List.each fn(row) =>
      match Map.get "name" row
      | Some (Some name) -> print name
      | _ -> print "No name"
| Err e -> print "Query error: ${e}"

`execute`

Executes a statement (INSERT, UPDATE, DELETE, CREATE, etc.) and returns affected row count.

Executes a SQL statement that modifies data or schema and returns the number of rows affected. Use this for INSERT, UPDATE, DELETE, CREATE TABLE, DROP TABLE, and other non-SELECT statements.

Parameters:

Returns:

Ptr -> NonEmptyString -> Result Int DuckDBError

match execute connection "INSERT INTO users (id, name) VALUES (1, 'Alice')"
| Ok count -> print "Inserted ${Int.to-string count} rows"
| Err e -> print "Insert error: ${e}"