dalgo2duckdb

README

dalgo2duckdb

Embedded DuckDB adapter for DALgo, following dalgo2sqlite's composition of dalgo2sql and database/sql.

db, err := dalgo2duckdb.NewDatabase("analytics.duckdb") // "" for in-memory
if err != nil { return err }
defer db.Close()
reader, err := db.ExecuteQueryToRecordsReader(ctx,
    dal.NewTextQuery("SELECT * FROM read_parquet('data.parquet')", nil))

Uses the official github.com/duckdb/duckdb-go/v2 driver and requires CGO_ENABLED=1 and a C/C++ toolchain. DuckDB's Parquet reader is built in; no preview flag or extension installation is required.

NewDatabaseWithOptions accepts DALgo schema and SQL adapter options. SQLDB() exposes the underlying pool for native operations such as COPY. This adapter currently provides DALgo's SQL query/transaction surface; DuckDB-specific schema introspection and DDL interfaces are not implemented.

NewReadOnlyDatabase initializes a read-only SQL transaction on each physical connection. It does not classify statements automatically: callers accepting SQL text must call ValidateReadQuery before execution to require one SELECT. SELECT queries can read external files and URLs, so read-only database access is not a filesystem or network sandbox. Authorize external resource access separately before accepting user queries.

Documentation

Overview

Package dalgo2duckdb adapts embedded DuckDB to DALgo using dalgo2sql, following the composition used by dalgo2sqlite. DuckDB requires cgo.

Index

• type Database
  • func NewDatabase(path string) (*Database, error)
  • func NewDatabaseWithOptions(path string, schema dal.Schema, opts dalgo2sql.DbOptions) (*Database, error)
  • func NewReadOnlyDatabase(dsn string) (*Database, error)
  • func (d *Database) Adapter() dal.Adapter
  • func (d *Database) Close() error
  • func (d *Database) SQLDB() *sql.DB
  • func (d *Database) ValidateReadQuery(ctx context.Context, text string) error

Types

type Database

type Database struct {
	dal.DB
	// contains filtered or unexported fields
}

Database embeds the DALgo SQL adapter and owns its connection pool.

func NewDatabase

func NewDatabase(path string) (*Database, error)

NewDatabase opens a DuckDB file; an empty path creates an in-memory database.

func NewDatabaseWithOptions

func NewDatabaseWithOptions(path string, schema dal.Schema, opts dalgo2sql.DbOptions) (*Database, error)

NewDatabaseWithOptions supplies DALgo schema and SQL adapter options.

func NewReadOnlyDatabase

func NewReadOnlyDatabase(dsn string) (*Database, error)

NewReadOnlyDatabase starts a read-only transaction on every physical connection, including replacements after cancellation. Files must use a DSN containing access_mode=read_only; an empty DSN creates an in-memory session. Read-only transactions prevent database writes, but SELECTs can still read external files and URLs. This constructor does not restrict statements sent through the embedded dal.DB or SQLDB. Call ValidateReadQuery before executing untrusted SQL to require exactly one SELECT; resource access requires a separate operator-level authorization decision.

func (*Database) Adapter

func (d *Database) Adapter() dal.Adapter

Adapter identifies this adapter.

func (*Database) Close

func (d *Database) Close() error

Close releases the connection pool.

func (*Database) SQLDB

func (d *Database) SQLDB() *sql.DB

SQLDB returns the underlying pool, for DuckDB-native operations such as COPY.

func (*Database) ValidateReadQuery

func (d *Database) ValidateReadQuery(ctx context.Context, text string) error

ValidateReadQuery asks DuckDB to parse exactly one SELECT without executing preceding statements. Deliberately use the driver's legacy Prepare method: PrepareContext executes all but the last statement of a multi-statement input.