duckdb

package module
v0.0.0-...-5e53a9c Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 3, 2025 License: MIT Imports: 24 Imported by: 0

README

Go SQL driver for DuckDB

The DuckDB driver conforms to the built-in database/sql interface.

Tests status GoDoc

Installation

go get github.com/marcboeker/go-duckdb
Windows

On windows, the correct version of gcc and the neccesary runtime libraries needs to be installed. One method to do this is using msys64. To begin, install msys64 using their installer. Once this is done, open a msys64 shell and run

pacman -S mingw-w64-ucrt-x86_64-gcc

select yes when neccesary, its ok if the shell closes. Then add gcc to the path using whatever method you prefer. In powershell this is $env:PATH = "C:\msys64\ucrt64\bin:$env:PATH". Once this is done, you can compile this package on windows.

Usage

go-duckdb hooks into the database/sql interface provided by the Go stdlib. To open a connection, simply specify the driver type as duckdb.

db, err := sql.Open("duckdb", "")
check(err)
defer db.Close()

This creates an in-memory instance of DuckDB. To open a persistent database, you need to specify a filepath to the database file. If the file does not exist, then DuckDB creates it.

db, err := sql.Open("duckdb", "/path/to/foo.db")
check(err)
defer db.Close()

If you want to set specific config options for DuckDB, you can add them as query style parameters in the form of name=value pairs to the DSN.

db, err := sql.Open("duckdb", "/path/to/foo.db?access_mode=read_only&threads=4")
check(err)
defer db.Close()

Alternatively, you can use sql.OpenDB. That way, you can perform initialization steps in a callback function before opening the database. Here's an example that configures some database parameters when opening a database with sql.OpenDB(connector).

connector, err := duckdb.NewConnector("/path/to/foo.db?access_mode=read_only&threads=4", func(execer driver.ExecerContext) error {
    bootQueries := []string{
        "SET schema=main",
        "SET search_path=main",
    }

    for _, query := range bootQueries {
        _, err = execer.ExecContext(context.Background(), query, nil)
        if err != nil {
			return err
        }
    }
    return nil
})
check(err)

db := sql.OpenDB(connector)
defer db.Close()

Please refer to the database/sql documentation for further usage instructions.

Notes and FAQs

undefined: conn

When building this package, some people run into an undefined: conn error. This is due to the go compiler determining that CGO is not available. This can happen due to a few issues.

The first noted in the comment here is that the buildtools are not installed. To fix this for ubuntu, you can install them using:

sudo apt-get update && sudo apt-get install build-essential

Another issue is when you are cross-compiling, since the go compiler automatically disables CGO when cross-compiling. To enable cgo when cross-compiling use CC={C cross compiler} CGO_ENABLED=1 {command} to force-enable CGO and set the right cross-compiler.

TIMESTAMP vs. TIMESTAMP_TZ

In the C API, DuckDB stores both TIMESTAMP and TIMESTAMP_TZ as duckdb_timestamp, which holds the number of microseconds elapsed since January 1, 1970 UTC (i.e., an instant without offset information). When passing a time.Time to go-duckdb, go-duckdb transforms it to an instant with UnixMicro(), even when using TIMESTAMP_TZ. Later, scanning either type of value returns an instant, as SQL types do not model time zone information for individual values.

Memory Allocation

DuckDB lives in-process. Therefore, all its memory lives in the driver. All allocations live in the host process, which is the Go application. Especially for long-running applications, it is crucial to call the corresponding Close-functions as specified in database/sql. The following is a list of examples.

db, err := sql.Open("duckdb", "")
defer db.Close()

conn, err := db.Conn(context.Background())
defer conn.Close()

rows, err := conn.QueryContext(context.Background(), "SELECT 42")
// Alternatively, rows.Next() has to return false.
rows.Close()

appender, err := NewAppenderFromConn(conn, "", "test")
defer appender.Close()

// If not passed to sql.OpenDB.
connector, err := NewConnector("", nil)
defer connector.Close()

DuckDB Appender API

If you want to use the DuckDB Appender API, you can obtain a new Appender by passing a DuckDB connection to NewAppenderFromConn(). See examples/appender.go for a complete example.

connector, err := duckdb.NewConnector("test.db", nil)
check(err)
defer connector.Close()

conn, err := connector.Connect(context.Background())
check(err)
defer conn.Close()

// Obtain an appender from the connection.
// NOTE: The table 'test_tbl' must exist in test.db.
appender, err := NewAppenderFromConn(conn, "", "test_tbl")
check(err)
defer appender.Close()

err = appender.AppendRow(...)
check(err)

DuckDB Profiling API

This section describes using the DuckDB Profiling API. DuckDB's profiling information is connection-local. The following example walks you through the necessary steps to obtain the ProfilingInfo type, which contains all available metrics. Please refer to the DuckDB documentation on configuring and collecting specific metrics.

  • First, you need to obtain a connection.
  • Then, you enable profiling for the connection.
  • Now, for each subsequent query on this connection, DuckDB will collect profiling information.
    • Optionally, you can turn off profiling at any point.
  • Next, you execute the query for which you want to obtain profiling information.
  • Finally, directly after executing the query, retrieve any available profiling information.

For readability, we omit error handling in this example.

db, err := sql.Open("duckdb", "")
con, err := db.Conn(context.Background())

_, err = con.ExecContext(context.Background(), `PRAGMA enable_profiling = 'no_output'`)
_, err = con.ExecContext(context.Background(), `PRAGMA profiling_mode = 'detailed'`)

res, err := con.QueryContext(context.Background(), `SELECT 42`)
info, err := GetProfilingInfo(con)
err = res.Close()

_, err = con.ExecContext(context.Background(), `PRAGMA disable_profiling`)
err = con.Close()
err = db.Close()

DuckDB Apache Arrow Interface

If you want to use the DuckDB Arrow Interface, you can obtain a new Arrow by passing a DuckDB connection to NewArrowFromConn().

connector, err := duckdb.NewConnector("", nil)
check(err)
defer connector.Close()

conn, err := connector.Connect(context.Background())
check(err)
defer conn.Close()

// Obtain the Arrow from the connection.
arrow, err := duckdb.NewArrowFromConn(conn)
check(err)

rdr, err := arrow.QueryContext(context.Background(), "SELECT * FROM generate_series(1, 10)")
check(err)
defer rdr.Release()

for rdr.Next() {
  // Process each record.
}

The Arrow interface is a heavy dependency. If you do not need it, you can disable it by passing -tags=no_duckdb_arrow to go build. This will be made opt-in in V2.

go build -tags="no_duckdb_arrow"

Vendoring

If you want to vendor a module containing go-duckdb, please use modvendor to include the missing header files and libraries. See issue #174 for more details.

  1. go install github.com/goware/modvendor@latest
  2. go mod vendor
  3. modvendor -copy="**/*.a **/*.h" -v

Now you can build your module as usual.

Linking DuckDB

By default, go-duckdb statically links DuckDB into your binary. Statically linking DuckDB increases your binary size.

go-duckdb bundles pre-compiled static libraries for some OS and architecture combinations.

  • MacOS: amd64, arm64.
  • Linux: amd64, arm64.
  • FreeBSD: amd64.
  • Windows: amd64.

Alternatively, you can dynamically link DuckDB by passing -tags=duckdb_use_lib to go build. You must have a copy of libduckdb available on your system (.so on Linux or .dylib on macOS), which you can download from the DuckDB releases page. For example:

# On Linux.
CGO_ENABLED=1 CGO_LDFLAGS="-L/path/to/libs" go build -tags=duckdb_use_lib main.go
LD_LIBRARY_PATH=/path/to/libs ./main

# On macOS.
CGO_ENABLED=1 CGO_LDFLAGS="-L/path/to/libs" go build -tags=duckdb_use_lib main.go
DYLD_LIBRARY_PATH=/path/to/libs ./main

DuckDB Extensions

go-duckdb statically builds the JSON extension for its pre-compiled libraries. Additionally, automatic extension loading is enabled. The extensions available differ between the pre-compiled libraries. Thus, if you fail to install and load an extension, you might have to link a custom DuckDB.

Specifically, for MingW (Windows), there are no distributed extensions (yet). You can statically include them by extending the BUILD_EXTENSIONS="json" variable in the Makefile.

Documentation

Overview

Package duckdb implements a database/sql driver for the DuckDB database.

Example (SimpleConnection) 
// Connect to DuckDB using '[database/sql.Open]'.
db, err := sql.Open("duckdb", "?access_mode=READ_WRITE")
checkErr(err, "failed to open connection to duckdb: %s")
defer db.Close()

ctx := context.Background()

createStmt := `CREATE table users(name VARCHAR, age INTEGER)`
_, err = db.ExecContext(ctx, createStmt)
checkErr(err, "failed to create table: %s")

insertStmt := `INSERT INTO users(name, age) VALUES (?, ?);`
res, err := db.ExecContext(ctx, insertStmt, "Marc", 30)
checkErr(err, "failed to insert users: %s")

rowsAffected, err := res.RowsAffected()
checkErr(err, "failed to get number of rows affected")
fmt.Printf("Inserted %d row(s) into users table", rowsAffected)

Output:

Inserted 1 row(s) into users table

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetDataChunkCapacity 

func GetDataChunkCapacity() int

GetDataChunkCapacity returns the capacity of a data chunk.

func RegisterReplacementScan 

func RegisterReplacementScan(connector *Connector, cb ReplacementScanCallback)

func RegisterScalarUDF 

func RegisterScalarUDF(c *sql.Conn, name string, f ScalarFunc) error

RegisterScalarUDF registers a user-defined scalar function. *sql.Conn is the SQL connection on which to register the scalar function. name is the function name, and f is the scalar function's interface ScalarFunc. RegisterScalarUDF takes ownership of f, so you must pass it as a pointer.

func RegisterScalarUDFSet 

func RegisterScalarUDFSet(c *sql.Conn, name string, functions ...ScalarFunc) error

RegisterScalarUDFSet registers a set of user-defined scalar functions with the same name. This enables overloading of scalar functions. E.g., the function my_length() can have implementations like my_length(LIST(ANY)) and my_length(VARCHAR). *sql.Conn is the SQL connection on which to register the scalar function set. name is the function name of each function in the set. functions contains all ScalarFunc functions of the scalar function set.

func RegisterTableUDF 

func RegisterTableUDF[TFT TableFunction](c *sql.Conn, name string, f TFT) error

RegisterTableUDF registers a user-defined table function. Projection pushdown is enabled by default.

func SetChunkValue 

func SetChunkValue[T any](chunk DataChunk, colIdx int, rowIdx int, val T) error

SetChunkValue writes a single value to a column in a data chunk. The difference with `chunk.SetValue` is that `SetChunkValue` does not require casting the value to `any` (implicitly). NOTE: Custom ENUM types must be passed as string.

func SetRowValue 

func SetRowValue[T any](row Row, colIdx int, val T) error

SetRowValue sets the value at colIdx to val. Returns an error on failure, and nil for non-projected columns.

Types

type Appender 

type Appender struct {
	// contains filtered or unexported fields
}

Appender holds the DuckDB appender. It allows efficient bulk loading into a DuckDB database.

func NewAppenderFromConn 

func NewAppenderFromConn(driverConn driver.Conn, schema, table string) (*Appender, error)

NewAppenderFromConn returns a new Appender from a DuckDB driver connection.

func (*Appender) AppendRow 

func (a *Appender) AppendRow(args ...driver.Value) error

AppendRow loads a row of values into the appender. The values are provided as separate arguments.

func (*Appender) Close 

func (a *Appender) Close() error

Close the appender. This will flush the appender to the underlying table. It is vital to call this when you are done with the appender to avoid leaking memory.

func (*Appender) Flush 

func (a *Appender) Flush() error

Flush the data chunks to the underlying table and clear the internal cache. Does not close the appender, even if it returns an error. Unless you have a good reason to call this, call Close when you are done with the appender.

type Arrow 

type Arrow struct {
	// contains filtered or unexported fields
}

Arrow exposes DuckDB Apache Arrow interface. https://duckdb.org/docs/api/c/api#arrow-interface

func NewArrowFromConn 

func NewArrowFromConn(driverConn driver.Conn) (*Arrow, error)

NewArrowFromConn returns a new Arrow from a DuckDB driver connection.

func (*Arrow) QueryContext 

func (a *Arrow) QueryContext(ctx context.Context, query string, args ...any) (array.RecordReader, error)

QueryContext prepares statements, executes them, returns Apache Arrow array.RecordReader as a result of the last executed statement. Arguments are bound to the last statement.

func (*Arrow) RegisterView 

func (a *Arrow) RegisterView(reader array.RecordReader, name string) (release func(), err error)

RegisterView registers an Arrow record reader as a view with the given name in DuckDB. The returned release function must be called to release the memory once the view is no longer needed.

type CardinalityInfo 

type CardinalityInfo struct {
	// The absolute Cardinality.
	Cardinality uint
	// IsExact indicates whether the cardinality is exact.
	Exact bool
}

CardinalityInfo contains the cardinality of a (table) function. If it is impossible or difficult to determine the exact cardinality, an approximate cardinality may be used.

type ChunkTableFunction 

type ChunkTableFunction = tableFunction[ChunkTableSource]

A ChunkTableFunction is a type which can be bound to return a ChunkTableSource.

type ChunkTableSource 

type ChunkTableSource interface {

	// FillChunk takes a Chunk and fills it with values.
	// It returns true, if there are more chunks to fill.
	FillChunk(DataChunk) error
	// contains filtered or unexported methods
}

A ChunkTableSource represents anything that produces rows in a vectorised way. The cardinality is requested before function initialization. After initializing the ChunkTableSource, go-duckdb requests the rows. It sequentially calls the FillChunk method with a single thread.

type ColumnInfo 

type ColumnInfo struct {
	// The column Name.
	Name string
	// The column type T.
	T TypeInfo
}

ColumnInfo contains the metadata of a column.

type Composite 

type Composite[T any] struct {
	// contains filtered or unexported fields
}

Use as the `Scanner` type for any composite types (maps, lists, structs)

func (Composite[T]) Get 

func (s Composite[T]) Get() T

func (*Composite[T]) Scan 

func (s *Composite[T]) Scan(v any) error

type Conn 

type Conn struct {
	// contains filtered or unexported fields
}

Conn holds a connection to a DuckDB database. It implements the driver.Conn interface.

func (*Conn) Begin 

func (c *Conn) Begin() (driver.Tx, error)

Begin is deprecated: Use BeginTx instead.

func (*Conn) BeginTx 

func (c *Conn) BeginTx(ctx context.Context, opts driver.TxOptions) (driver.Tx, error)

BeginTx starts and returns a new transaction. It implements the driver.ConnBeginTx interface.

func (*Conn) CheckNamedValue 

func (c *Conn) CheckNamedValue(nv *driver.NamedValue) error

CheckNamedValue implements the driver.NamedValueChecker interface.

func (*Conn) Close 

func (c *Conn) Close() error

Close closes the connection to the database. It implements the driver.Conn interface.

func (*Conn) ExecContext 

func (c *Conn) ExecContext(ctx context.Context, query string, args []driver.NamedValue) (driver.Result, error)

ExecContext executes a query that doesn't return rows, such as an INSERT or UPDATE. It implements the driver.ExecerContext interface.

func (*Conn) Prepare 

func (c *Conn) Prepare(query string) (driver.Stmt, error)

Prepare returns a prepared statement, bound to this connection. It implements the driver.Conn interface.

func (*Conn) PrepareContext 

func (c *Conn) PrepareContext(ctx context.Context, query string) (driver.Stmt, error)

PrepareContext returns a prepared statement, bound to this connection. It implements the driver.ConnPrepareContext interface.

func (*Conn) QueryContext 

func (c *Conn) QueryContext(ctx context.Context, query string, args []driver.NamedValue) (driver.Rows, error)

QueryContext executes a query that may return rows, such as a SELECT. It implements the driver.QueryerContext interface.

type Connector 

type Connector struct {
	// contains filtered or unexported fields
}

func NewConnector 

func NewConnector(dsn string, connInitFn func(execer driver.ExecerContext) error) (*Connector, error)

NewConnector opens a new Connector for a DuckDB database. The user must close the Connector, if it is not passed to the sql.OpenDB function. Otherwise, sql.DB closes the Connector when calling sql.DB.Close().

Example 
c, err := NewConnector("duck.db?access_mode=READ_WRITE", func(execer driver.ExecerContext) error {
	initQueries := []string{
		`SET memory_limit = '10GB';`,
		`SET threads TO 1;`,
	}

	ctx := context.Background()
	for _, query := range initQueries {
		_, err := execer.ExecContext(ctx, query, nil)
		if err != nil {
			return err
		}
	}
	return nil
})
if err != nil {
	log.Fatalf("failed to create new duckdb connector: %s", err)
}

db := sql.OpenDB(c)
var value string
row := db.QueryRow(`SELECT value FROM duckdb_settings() WHERE name = 'memory_limit';`)
if row.Scan(&value) != nil {
	log.Fatalf("failed to scan row: %s", err)
}

if err = c.Close(); err != nil {
	log.Fatalf("failed to close the connector: %s", err)
}
if err = db.Close(); err != nil {
	log.Fatalf("failed to close the database: %s", err)
}
if err = os.Remove("duck.db"); err != nil {
	log.Fatalf("failed to remove the database file: %s", err)
}

fmt.Printf("The memory_limit is %s.", value)

Output:

The memory_limit is 9.3 GiB.

func (*Connector) Close 

func (c *Connector) Close() error

func (*Connector) Connect 

func (c *Connector) Connect(context.Context) (driver.Conn, error)

func (*Connector) Driver 

func (*Connector) Driver() driver.Driver

type DataChunk 

type DataChunk struct {
	// contains filtered or unexported fields
}

DataChunk storage of a DuckDB table.

func (*DataChunk) GetSize 

func (chunk *DataChunk) GetSize() int

GetSize returns the internal size of the data chunk.

func (*DataChunk) GetValue 

func (chunk *DataChunk) GetValue(colIdx int, rowIdx int) (any, error)

GetValue returns a single value of a column.

func (*DataChunk) SetSize 

func (chunk *DataChunk) SetSize(size int) error

SetSize sets the internal size of the data chunk. Cannot exceed GetCapacity().

func (*DataChunk) SetValue 

func (chunk *DataChunk) SetValue(colIdx int, rowIdx int, val any) error

SetValue writes a single value to a column in a data chunk. Note that this requires casting the type for each invocation. NOTE: Custom ENUM types must be passed as string.

type Decimal 

type Decimal struct {
	Width uint8
	Scale uint8
	Value *big.Int
}

func (*Decimal) Float64 

func (d *Decimal) Float64() float64

func (*Decimal) String 

func (d *Decimal) String() string

type Driver 

type Driver struct{}

func (Driver) Open 

func (d Driver) Open(dsn string) (driver.Conn, error)

func (Driver) OpenConnector 

func (Driver) OpenConnector(dsn string) (driver.Connector, error)

type Error 

type Error struct {
	Type ErrorType
	Msg  string
}

func (*Error) Error 

func (e *Error) Error() string

func (*Error) Is 

func (e *Error) Is(err error) bool

type ErrorType 

type ErrorType int
const (
	ErrorTypeInvalid              ErrorType = iota // invalid type
	ErrorTypeOutOfRange                            // value out of range error
	ErrorTypeConversion                            // conversion/casting error
	ErrorTypeUnknownType                           // unknown type error
	ErrorTypeDecimal                               // decimal related
	ErrorTypeMismatchType                          // type mismatch
	ErrorTypeDivideByZero                          // divide by 0
	ErrorTypeObjectSize                            // object size exceeded
	ErrorTypeInvalidType                           // incompatible for operation
	ErrorTypeSerialization                         // serialization
	ErrorTypeTransaction                           // transaction management
	ErrorTypeNotImplemented                        // method not implemented
	ErrorTypeExpression                            // expression parsing
	ErrorTypeCatalog                               // catalog related
	ErrorTypeParser                                // parser related
	ErrorTypePlanner                               // planner related
	ErrorTypeScheduler                             // scheduler related
	ErrorTypeExecutor                              // executor related
	ErrorTypeConstraint                            // constraint related
	ErrorTypeIndex                                 // index related
	ErrorTypeStat                                  // stat related
	ErrorTypeConnection                            // connection related
	ErrorTypeSyntax                                // syntax related
	ErrorTypeSettings                              // settings related
	ErrorTypeBinder                                // binder related
	ErrorTypeNetwork                               // network related
	ErrorTypeOptimizer                             // optimizer related
	ErrorTypeNullPointer                           // nullptr exception
	ErrorTypeIO                                    // IO exception
	ErrorTypeInterrupt                             // interrupt
	ErrorTypeFatal                                 // Fatal exceptions are non-recoverable, and render the entire DB in an unusable state
	ErrorTypeInternal                              // Internal exceptions indicate something went wrong internally (i.e. bug in the code base)
	ErrorTypeInvalidInput                          // Input or arguments error
	ErrorTypeOutOfMemory                           // out of memory
	ErrorTypePermission                            // insufficient permissions
	ErrorTypeParameterNotResolved                  // parameter types could not be resolved
	ErrorTypeParameterNotAllowed                   // parameter types not allowed
	ErrorTypeDependency                            // dependency
	ErrorTypeHTTP
	ErrorTypeMissingExtension // Thrown when an extension is used but not loaded
	ErrorTypeAutoLoad         // Thrown when an extension is used but not loaded
	ErrorTypeSequence
	ErrorTypeInvalidConfiguration // An invalid configuration was detected (e.g. a Secret param was missing, or a required setting not found)
)

type Interval 

type Interval struct {
	Days   int32 `json:"days"`
	Months int32 `json:"months"`
	Micros int64 `json:"micros"`
}

type Map 

type Map map[any]any

func (*Map) Scan 

func (m *Map) Scan(v any) error

type ParallelChunkTableFunction 

type ParallelChunkTableFunction = tableFunction[ParallelChunkTableSource]

A ParallelChunkTableFunction is a type which can be bound to return a ParallelChunkTableSource.

type ParallelChunkTableSource 

type ParallelChunkTableSource interface {

	// FillChunk takes a Chunk and fills it with values.
	// It returns true, if there are more chunks to fill.
	FillChunk(any, DataChunk) error
	// contains filtered or unexported methods
}

A ParallelChunkTableSource represents anything that produces rows in a vectorised way. The cardinality is requested before function initialization. After initializing the ParallelChunkTableSource, go-duckdb requests the rows. It simultaneously calls the FillChunk method with multiple threads. If ParallelTableSourceInfo.MaxThreads is greater than one, FillChunk must use synchronization primitives to avoid race conditions.

type ParallelRowTableFunction 

type ParallelRowTableFunction = tableFunction[ParallelRowTableSource]

A ParallelRowTableFunction is a type which can be bound to return a ParallelRowTableSource.

type ParallelRowTableSource 

type ParallelRowTableSource interface {

	// FillRow takes a Row and fills it with values.
	// It returns true, if there are more rows to fill.
	FillRow(any, Row) (bool, error)
	// contains filtered or unexported methods
}

A ParallelRowTableSource represents anything that produces rows in a non-vectorised way. The cardinality is requested before function initialization. After initializing the ParallelRowTableSource, go-duckdb requests the rows. It simultaneously calls the FillRow method with multiple threads. If ParallelTableSourceInfo.MaxThreads is greater than one, FillRow must use synchronisation primitives to avoid race conditions.

type ParallelTableSourceInfo 

type ParallelTableSourceInfo struct {
	// MaxThreads is the maximum number of threads on which to run the table source function.
	// If set to 0, it uses DuckDB's default thread configuration.
	MaxThreads int
}

ParallelTableSourceInfo contains information for initializing a parallelism-aware table source.

type ProfilingInfo 

type ProfilingInfo struct {
	// Metrics contains all key-value pairs of the current node.
	// The key represents the name and corresponds to the measured value.
	Metrics map[string]string
	// Children contains all children of the node and their respective metrics.
	Children []ProfilingInfo
}

ProfilingInfo is a recursive type containing metrics for each node in DuckDB's query plan. There are two types of nodes: the QUERY_ROOT and OPERATOR nodes. The QUERY_ROOT refers exclusively to the top-level node; its metrics are measured over the entire query. The OPERATOR nodes refer to the individual operators in the query plan.

func GetProfilingInfo 

func GetProfilingInfo(c *sql.Conn) (ProfilingInfo, error)

GetProfilingInfo obtains all available metrics set by the current connection.

type ReplacementScanCallback 

type ReplacementScanCallback func(tableName string) (string, []any, error)

type Row 

type Row struct {
	// contains filtered or unexported fields
}

Row represents one row in duckdb. It references the internal vectors.

func (Row) IsProjected 

func (r Row) IsProjected(colIdx int) bool

IsProjected returns whether the column is projected.

func (Row) SetRowValue 

func (r Row) SetRowValue(colIdx int, val any) error

SetRowValue sets the value at colIdx to val. Returns an error on failure.

type RowTableFunction 

type RowTableFunction = tableFunction[RowTableSource]

A RowTableFunction is a type which can be bound to return a RowTableSource.

type RowTableSource 

type RowTableSource interface {

	// FillRow takes a Row and fills it with values.
	// It returns true, if there are more rows to fill.
	FillRow(Row) (bool, error)
	// contains filtered or unexported methods
}

A RowTableSource represents anything that produces rows in a non-vectorised way. The cardinality is requested before function initialization. After initializing the RowTableSource, go-duckdb requests the rows. It sequentially calls the FillRow method with a single thread.

type ScalarFunc 

type ScalarFunc interface {
	// Config returns ScalarFuncConfig to configure the scalar function.
	Config() ScalarFuncConfig
	// Executor returns ScalarFuncExecutor to execute the scalar function.
	Executor() ScalarFuncExecutor
}

ScalarFunc is the user-defined scalar function interface. Any scalar function must implement a Config function, and an Executor function.

type ScalarFuncConfig 

type ScalarFuncConfig struct {
	// InputTypeInfos contains Type information for each input parameter of the scalar function.
	InputTypeInfos []TypeInfo
	// ResultTypeInfo holds the Type information of the scalar function's result type.
	ResultTypeInfo TypeInfo

	// VariadicTypeInfo configures the number of input parameters.
	// If this field is nil, then the input parameters match InputTypeInfos.
	// Otherwise, the scalar function's input parameters are set to variadic, allowing any number of input parameters.
	// The Type of the first len(InputTypeInfos) parameters is configured by InputTypeInfos, and all
	// remaining parameters must match the variadic Type. To configure different variadic parameter types,
	// you must set the VariadicTypeInfo's Type to TYPE_ANY.
	VariadicTypeInfo TypeInfo
	// Volatile sets the stability of the scalar function to volatile, if true.
	// Volatile scalar functions might create a different result per row.
	// E.g., random() is a volatile scalar function.
	Volatile bool
	// SpecialNullHandling disables the default NULL handling of scalar functions, if true.
	// The default NULL handling is: NULL in, NULL out. I.e., if any input parameter is NULL, then the result is NULL.
	SpecialNullHandling bool
}

ScalarFuncConfig contains the fields to configure a user-defined scalar function.

type ScalarFuncExecutor 

type ScalarFuncExecutor struct {
	// RowExecutor accepts a row-based execution function.
	// []driver.Value contains the row values, and it returns the row execution result, or error.
	RowExecutor func(values []driver.Value) (any, error)
}

ScalarFuncExecutor contains the callback function to execute a user-defined scalar function. Currently, its only field is a row-based executor.

type Stmt 

type Stmt struct {
	// contains filtered or unexported fields
}

Stmt implements the driver.Stmt interface.

func (*Stmt) Bind 

func (s *Stmt) Bind(args []driver.NamedValue) error

Bind binds the parameters to the statement. WARNING: This is a low-level API and should be used with caution.

func (*Stmt) Close 

func (s *Stmt) Close() error

Close closes the statement. It implements the driver.Stmt interface.

func (*Stmt) Exec deprecated 

func (s *Stmt) Exec(args []driver.Value) (driver.Result, error)

Deprecated: Use ExecContext instead.

func (*Stmt) ExecBound 

func (s *Stmt) ExecBound(ctx context.Context) (driver.Result, error)

ExecBound executes a bound query that doesn't return rows, such as an INSERT or UPDATE. It can only be used after Bind has been called. WARNING: This is a low-level API and should be used with caution.

func (*Stmt) ExecContext 

func (s *Stmt) ExecContext(ctx context.Context, nargs []driver.NamedValue) (driver.Result, error)

ExecContext executes a query that doesn't return rows, such as an INSERT or UPDATE. It implements the driver.StmtExecContext interface.

func (*Stmt) NumInput 

func (s *Stmt) NumInput() int

NumInput returns the number of placeholder parameters. It implements the driver.Stmt interface.

func (*Stmt) ParamName 

func (s *Stmt) ParamName(n int) (string, error)

ParamName returns the name of the parameter at the given index (1-based).

func (*Stmt) ParamType 

func (s *Stmt) ParamType(n int) (Type, error)

ParamType returns the expected type of the parameter at the given index (1-based).

func (*Stmt) Query deprecated 

func (s *Stmt) Query(args []driver.Value) (driver.Rows, error)

Deprecated: Use QueryContext instead.

func (*Stmt) QueryBound 

func (s *Stmt) QueryBound(ctx context.Context) (driver.Rows, error)

QueryBound executes a bound query that may return rows, such as a SELECT. It can only be used after Bind has been called. WARNING: This is a low-level API and should be used with caution.

func (*Stmt) QueryContext 

func (s *Stmt) QueryContext(ctx context.Context, nargs []driver.NamedValue) (driver.Rows, error)

QueryContext executes a query that may return rows, such as a SELECT. It implements the driver.StmtQueryContext interface.

func (*Stmt) StatementType 

func (s *Stmt) StatementType() (StmtType, error)

StatementType returns the type of the statement.

type StmtType 

type StmtType C.duckdb_statement_type
const (
	STATEMENT_TYPE_INVALID      StmtType = C.DUCKDB_STATEMENT_TYPE_INVALID
	STATEMENT_TYPE_SELECT       StmtType = C.DUCKDB_STATEMENT_TYPE_SELECT
	STATEMENT_TYPE_INSERT       StmtType = C.DUCKDB_STATEMENT_TYPE_INSERT
	STATEMENT_TYPE_UPDATE       StmtType = C.DUCKDB_STATEMENT_TYPE_UPDATE
	STATEMENT_TYPE_EXPLAIN      StmtType = C.DUCKDB_STATEMENT_TYPE_EXPLAIN
	STATEMENT_TYPE_DELETE       StmtType = C.DUCKDB_STATEMENT_TYPE_DELETE
	STATEMENT_TYPE_PREPARE      StmtType = C.DUCKDB_STATEMENT_TYPE_PREPARE
	STATEMENT_TYPE_CREATE       StmtType = C.DUCKDB_STATEMENT_TYPE_CREATE
	STATEMENT_TYPE_EXECUTE      StmtType = C.DUCKDB_STATEMENT_TYPE_EXECUTE
	STATEMENT_TYPE_ALTER        StmtType = C.DUCKDB_STATEMENT_TYPE_ALTER
	STATEMENT_TYPE_TRANSACTION  StmtType = C.DUCKDB_STATEMENT_TYPE_TRANSACTION
	STATEMENT_TYPE_COPY         StmtType = C.DUCKDB_STATEMENT_TYPE_COPY
	STATEMENT_TYPE_ANALYZE      StmtType = C.DUCKDB_STATEMENT_TYPE_ANALYZE
	STATEMENT_TYPE_VARIABLE_SET StmtType = C.DUCKDB_STATEMENT_TYPE_VARIABLE_SET
	STATEMENT_TYPE_CREATE_FUNC  StmtType = C.DUCKDB_STATEMENT_TYPE_CREATE_FUNC
	STATEMENT_TYPE_DROP         StmtType = C.DUCKDB_STATEMENT_TYPE_DROP
	STATEMENT_TYPE_EXPORT       StmtType = C.DUCKDB_STATEMENT_TYPE_EXPORT
	STATEMENT_TYPE_PRAGMA       StmtType = C.DUCKDB_STATEMENT_TYPE_PRAGMA
	STATEMENT_TYPE_VACUUM       StmtType = C.DUCKDB_STATEMENT_TYPE_VACUUM
	STATEMENT_TYPE_CALL         StmtType = C.DUCKDB_STATEMENT_TYPE_CALL
	STATEMENT_TYPE_SET          StmtType = C.DUCKDB_STATEMENT_TYPE_SET
	STATEMENT_TYPE_LOAD         StmtType = C.DUCKDB_STATEMENT_TYPE_LOAD
	STATEMENT_TYPE_RELATION     StmtType = C.DUCKDB_STATEMENT_TYPE_RELATION
	STATEMENT_TYPE_EXTENSION    StmtType = C.DUCKDB_STATEMENT_TYPE_EXTENSION
	STATEMENT_TYPE_LOGICAL_PLAN StmtType = C.DUCKDB_STATEMENT_TYPE_LOGICAL_PLAN
	STATEMENT_TYPE_ATTACH       StmtType = C.DUCKDB_STATEMENT_TYPE_ATTACH
	STATEMENT_TYPE_DETACH       StmtType = C.DUCKDB_STATEMENT_TYPE_DETACH
	STATEMENT_TYPE_MULTI        StmtType = C.DUCKDB_STATEMENT_TYPE_MULTI
)

type StructEntry 

type StructEntry interface {
	// Info returns a STRUCT entry's type information.
	Info() TypeInfo
	// Name returns a STRUCT entry's name.
	Name() string
}

StructEntry is an interface to provide STRUCT entry information.

func NewStructEntry 

func NewStructEntry(info TypeInfo, name string) (StructEntry, error)

NewStructEntry returns a STRUCT entry. info contains information about the entry's type, and name holds the entry's name.

type TableFunction 

type TableFunction interface {
	RowTableFunction | ParallelRowTableFunction | ChunkTableFunction | ParallelChunkTableFunction
}

TableFunction implements different table function types: RowTableFunction, ParallelRowTableFunction, ChunkTableFunction, and ParallelChunkTableFunction.

type TableFunctionConfig 

type TableFunctionConfig struct {
	// The Arguments of the table function.
	Arguments []TypeInfo
	// The NamedArguments of the table function.
	NamedArguments map[string]TypeInfo
}

TableFunctionConfig contains any information passed to DuckDB when registering the table function.

type Type 

type Type C.duckdb_type

Type wraps the corresponding DuckDB type enum. 

const (
	TYPE_INVALID      Type = C.DUCKDB_TYPE_INVALID
	TYPE_BOOLEAN      Type = C.DUCKDB_TYPE_BOOLEAN
	TYPE_TINYINT      Type = C.DUCKDB_TYPE_TINYINT
	TYPE_SMALLINT     Type = C.DUCKDB_TYPE_SMALLINT
	TYPE_INTEGER      Type = C.DUCKDB_TYPE_INTEGER
	TYPE_BIGINT       Type = C.DUCKDB_TYPE_BIGINT
	TYPE_UTINYINT     Type = C.DUCKDB_TYPE_UTINYINT
	TYPE_USMALLINT    Type = C.DUCKDB_TYPE_USMALLINT
	TYPE_UINTEGER     Type = C.DUCKDB_TYPE_UINTEGER
	TYPE_UBIGINT      Type = C.DUCKDB_TYPE_UBIGINT
	TYPE_FLOAT        Type = C.DUCKDB_TYPE_FLOAT
	TYPE_DOUBLE       Type = C.DUCKDB_TYPE_DOUBLE
	TYPE_TIMESTAMP    Type = C.DUCKDB_TYPE_TIMESTAMP
	TYPE_DATE         Type = C.DUCKDB_TYPE_DATE
	TYPE_TIME         Type = C.DUCKDB_TYPE_TIME
	TYPE_INTERVAL     Type = C.DUCKDB_TYPE_INTERVAL
	TYPE_HUGEINT      Type = C.DUCKDB_TYPE_HUGEINT
	TYPE_UHUGEINT     Type = C.DUCKDB_TYPE_UHUGEINT
	TYPE_VARCHAR      Type = C.DUCKDB_TYPE_VARCHAR
	TYPE_BLOB         Type = C.DUCKDB_TYPE_BLOB
	TYPE_DECIMAL      Type = C.DUCKDB_TYPE_DECIMAL
	TYPE_TIMESTAMP_S  Type = C.DUCKDB_TYPE_TIMESTAMP_S
	TYPE_TIMESTAMP_MS Type = C.DUCKDB_TYPE_TIMESTAMP_MS
	TYPE_TIMESTAMP_NS Type = C.DUCKDB_TYPE_TIMESTAMP_NS
	TYPE_ENUM         Type = C.DUCKDB_TYPE_ENUM
	TYPE_LIST         Type = C.DUCKDB_TYPE_LIST
	TYPE_STRUCT       Type = C.DUCKDB_TYPE_STRUCT
	TYPE_MAP          Type = C.DUCKDB_TYPE_MAP
	TYPE_ARRAY        Type = C.DUCKDB_TYPE_ARRAY
	TYPE_UUID         Type = C.DUCKDB_TYPE_UUID
	TYPE_UNION        Type = C.DUCKDB_TYPE_UNION
	TYPE_BIT          Type = C.DUCKDB_TYPE_BIT
	TYPE_TIME_TZ      Type = C.DUCKDB_TYPE_TIME_TZ
	TYPE_TIMESTAMP_TZ Type = C.DUCKDB_TYPE_TIMESTAMP_TZ
	TYPE_ANY          Type = C.DUCKDB_TYPE_ANY
	TYPE_VARINT       Type = C.DUCKDB_TYPE_VARINT
	TYPE_SQLNULL      Type = C.DUCKDB_TYPE_SQLNULL
)

type TypeInfo 

type TypeInfo interface {
	// InternalType returns the Type.
	InternalType() Type
	// contains filtered or unexported methods
}

TypeInfo is an interface for a DuckDB type.

func NewArrayInfo 

func NewArrayInfo(childInfo TypeInfo, size uint64) (TypeInfo, error)

NewArrayInfo returns ARRAY type information. childInfo contains the type information of the ARRAY's elements. size is the ARRAY's fixed size.

func NewDecimalInfo 

func NewDecimalInfo(width uint8, scale uint8) (TypeInfo, error)

NewDecimalInfo returns DECIMAL type information. Its input parameters are the width and scale of the DECIMAL type.

func NewEnumInfo 

func NewEnumInfo(first string, others ...string) (TypeInfo, error)

NewEnumInfo returns ENUM type information. Its input parameters are the dictionary values.

func NewListInfo 

func NewListInfo(childInfo TypeInfo) (TypeInfo, error)

NewListInfo returns LIST type information. childInfo contains the type information of the LIST's elements.

func NewMapInfo 

func NewMapInfo(keyInfo TypeInfo, valueInfo TypeInfo) (TypeInfo, error)

NewMapInfo returns MAP type information. keyInfo contains the type information of the MAP keys. valueInfo contains the type information of the MAP values.

func NewStructInfo 

func NewStructInfo(firstEntry StructEntry, others ...StructEntry) (TypeInfo, error)

NewStructInfo returns STRUCT type information. Its input parameters are the STRUCT entries.

func NewTypeInfo 

func NewTypeInfo(t Type) (TypeInfo, error)

NewTypeInfo returns type information for DuckDB's primitive types. It returns the TypeInfo, if the Type parameter is a valid primitive type. Else, it returns nil, and an error. Valid types are: TYPE_[BOOLEAN, TINYINT, SMALLINT, INTEGER, BIGINT, UTINYINT, USMALLINT, UINTEGER, UBIGINT, FLOAT, DOUBLE, TIMESTAMP, DATE, TIME, INTERVAL, HUGEINT, VARCHAR, BLOB, TIMESTAMP_S, TIMESTAMP_MS, TIMESTAMP_NS, UUID, TIMESTAMP_TZ, ANY].

type UUID 

type UUID [uuid_length]byte

func (*UUID) Scan 

func (u *UUID) Scan(v any) error

func (*UUID) String 

func (u *UUID) String() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.