chdb-go

At runtime, chdb-go searches for libchdb using the following priority order:

1. CHDB_LIB_PATH: If this environment variable is set, it points directly to the library file. This disables all other search methods. If the file at this path is invalid, it results in an error.
2. Embedded Engine: If the build imports an engine module (e.g., lib/embedded), the engine inside the binary is used. No further searching occurs.
3. Executable Directory: The directory containing the running executable.
4. PATH: Standard system path search.
5. System Library Paths: /usr/local/lib, /opt/homebrew/lib, and /usr/lib.
6. Dynamic Loader Paths: Directories in LD_LIBRARY_PATH, DYLD_LIBRARY_PATH, and DYLD_FALLBACK_LIBRARY_PATH.
7. Dynamic Loader: Search by name (e.g., ldconfig-registered installs or RUNPATH).

Tip: Use chdbpurego.LoadedLibraryPath() to log the absolute path of the library actually being used by your process.

The chdb/durable package allows you to store a chDB database's authoritative state in object storage (S3, R2, MinIO, or a local directory). It uses a checkpoint + write-ahead-log (WAL) protocol.

Key Concepts:

• Namespace: Represents the storage location (e.g., s3://my-bucket/path).
• Object: Represents a specific tenant/database within that namespace.
• Durability: Achieved via FlushThrough(ctx, ticket) (for a specific statement) or Checkpoint(ctx) (to fold WAL into a new base).
• Execution: Execute runs the statement locally and joins the WAL buffer. It does not mean the data has left the machine yet.
• Constraints: One process can only hold one open durable object at a time. Access control is managed via your object store's IAM.

Error Handling:

• durable.ErrLeaseHeld: Another writer is currently active.
• Use durable.CategoryOf(err) to distinguish between CategoryCommitAmbiguous and CategoryCorrupt.

import "github.com/chdb-io/chdb-go/v2/chdb/durable"

// Setup namespace
ns, err := durable.NewNamespace("s3://my-bucket/durable?region=eu-west-1",
        durable.NamespaceOptions{Owner: "worker-1"})

// Open an object
obj, existed, err := ns.Open(ctx, "tenant-123", durable.OpenOptions{Database: "mem"})
defer obj.Close(ctx)

if !existed {
        _, err = obj.Execute(ctx, "CREATE TABLE events (id UInt64) ENGINE = MergeTree ORDER BY id")
}

// Execute and ensure durability
ticket, err := obj.Execute(ctx, "INSERT INTO events VALUES (1)")
err = obj.FlushThrough(ctx, ticket) // survives machine loss

// Query and Checkpoint
rows, err := obj.Query(ctx, "SELECT count() FROM events", "JSONEachRow")
_, err = obj.Checkpoint(ctx) // folds base + WAL into a fresh base

The QueryAnalysis type provides metadata about a statement, allowing you to classify its impact on the system state. This is useful for security gating or permission management.

QueryClass levels (from least to most restrictive):

• QueryReadOnly (0): SELECT, SHOW, DESCRIBE, EXPLAIN. Leaves no trace.
• QueryMutating (1): INSERT, CREATE, ALTER, DROP. Changes the database.
• QueryMutatingGlobal (2): Global UDFs, named collections, or writes to system. Persistent and outside standard database checkpoints.
• QueryControl (3): USE, SET, SYSTEM, BACKUP, RESTORE, or writes outside the engine.
• QueryUnknown (4): The statement failed to parse or is unclassifiable. Treat this as a refusal/unsafe.

QueryAnalysis Fields:

• StatementCount: Number of executable statements.
• Class: The QueryClass of the statement.
• HasSecrets: Boolean indicating if the text contains credentials (passwords, keys, etc.).
• WritesOnlyTargetDatabase: True if all persistent writes land in the named target database.
• ChangesDatabaseLifecycle: True if the statement creates, drops, or renames a database.

Call Shutdown once when your program is completely finished with chDB. This stops the engine and joins the background threads started by chDB.

Key Behaviors:

• Terminal Operation: Shutdown is terminal. After calling it, NewSession will fail for the remainder of the process. Do not call it between units of work.
• Prerequisite: All Session instances must be closed before calling Shutdown. If sessions are still open, Shutdown will return an error wrapping ErrSessionsOpen.
• No Engine Running: If no session was ever opened (e.g., you only called EngineVersion), Shutdown returns nil and does nothing.
• Safety: If you don't call Shutdown, the threads will still be reaped by the OS when the process exits.

// Correct lifecycle pattern
sess, err := chdb.NewSession("/path/to/data")
// ... use session ...
sess.Close()

err = chdb.Shutdown()
if err != nil {
    // handle error
}