adbcduck-go - alternative DuckDB Go driver

adbcduck-go is a Go database/sql driver for DuckDB ADBC API. It is an alternative to the official Go driver github.com/marcboeker/go-duckdb. adbcduck-go is a fork of the generic database/sql adapter for ADBC drivers, maintained by the Apache Arrow project.

adbcduck-go is great for:

• libraries that value their dependency footprint - go get github.com/sclgo/adbcduck-go downloads up to 310 MB in Go modules, while go get github.com/marcboeker/go-duckdb downloads up to 824 MB - 500 MB more. Even when using GOPROXY, this quickly adds up especially in CI builds. Remember, projects that import your Go library must download all your transitive dependencies, even you use them only in tests.
• developers that hit issues in the official library - while the approach is this library is not inherently better (or worse) than the approach in the official Go client, it is unlikely that the two different codebases will have the same bugs. This fork and the upstream Arrow ADBC Go library are actively developed and supported.
  • For example, adbcduck-go doesn't suffer from go-duckdb#305
• apps that need to work with a specific DuckDB version or even multiple version at the same time - This driver loads the DuckDB dynamic library at runtime. Multiple DuckDB dynamic libraries can be used at the same time in the same app. In contrast, the official DuckDB Go client either works with the fixed bundled DuckDB release or with a single specific dynamic library, specified both at compile time and at runtime.
  • As a result, the latest version of DuckDB is usable with adbcduck-go immediately after it is released, while it takes 2-4 weeks for a DuckDB release to be embedded in the official Go client.
  • DuckDB guarantees backward compatibility of database files but forward compatibility depends on configuration. Developers should carefully choose client library and DuckDB versions when using shared DBs.

Quickstart

To get started quickly, use:

• blank import path - github.com/sclgo/adbcduck-go/quickstart
• driver name - adbcduck
• data source name - path to DB as specified in https://duckdb.org/docs/stable/connect/overview, optionally followed by key=value options separated by ;
  • example: test.db;threads=4
  • use either empty path or :memory: to specify an in-memory database

import (
	"database/sql"
	_ "github.com/sclgo/adbcduck-go/quickstart"
)

...

sql.Open("adbcduck", "") // Opens an in-memory database

Configuration

Review the API documentation and the minimal code of the quickstart package to see how to configure the library name, location, and, optionally, automatic download.

Registration with blank import is optional. Importing only github.com/sclgo/adbcduck-go gives access to the entire driver API without side effects. Only the github.com/sclgo/adbcduck-go/register and github.com/sclgo/adbcduck-go/quickstart packages have init() functions that call sql.Register .

CLI

adbcduck-go is compatible with usql - the universal SQL CLI - a fully featured, single-binary, CLI for over 50 databases. Check out this example.

Limitations

This library requires CGO, because it depends on the CGO wrapper for the ADBC Driver Manager. In the future, the CGO wrapper may be replaced with one using https://github.com/ebitengine/purego.