Getting started

Install CobaltDB and run your first SQL query in Go.

01. Add the module

CobaltDB’s embedded engine runs in your Go process. Use the current Go toolchain; the repository currently declares Go 1.26.0 and toolchain go1.26.6. No C compiler is required for the database runtime.

mkdir hello-cobalt
cd hello-cobalt
go mod init example.com/hello-cobalt
go get github.com/cobaltdb/cobaltdb

Import the engine from github.com/cobaltdb/cobaltdb/pkg/engine. The Go module resolves the library’s dependencies automatically.

02. Run your first query

Create a Go module, install CobaltDB, and save this complete program as main.go. It opens an in-memory database, creates a table, inserts a greeting and reads it back.

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/cobaltdb/cobaltdb/pkg/engine"
)

func main() {
    db, err := engine.Open(":memory:", &engine.Options{InMemory: true})
    if err != nil { log.Fatal(err) }
    defer db.Close()

    ctx := context.Background()
    _, err = db.Exec(ctx,
        "CREATE TABLE IF NOT EXISTS greetings (message TEXT)")
    if err != nil { log.Fatal(err) }

    _, err = db.Exec(ctx,
        "INSERT INTO greetings VALUES (?)", "Hello, CobaltDB!")
    if err != nil { log.Fatal(err) }

    rows, err := db.Query(ctx, "SELECT * FROM greetings")
    if err != nil { log.Fatal(err) }
    defer rows.Close()
    for rows.Next() {
        var message string
        if err := rows.Scan(&message); err != nil { log.Fatal(err) }
        fmt.Println(message)
    }
}

go mod tidy
go run .

A clean start, every time. This example needs no files or server. Data is discarded when the program closes. Use persistent mode when your application needs data across restarts.

03. Choose your persistence mode

The example above uses in-memory mode. To persist data, open a file path with the default options. Keep the database and its WAL together, and validate durability and recovery on your deployment filesystem.

db, err := engine.Open("app.db", nil)
if err != nil { log.Fatal(err) }
defer db.Close()

Where to go next

Learn the SQL and JSON workflow, explore the engine architecture, or run the standalone server.

The engine’s current API is available in pkg/engine on GitHub. Check errors returned by every statement and close rows when you are finished.

Source-aligned guide · CobaltDB v0.6.1Suggest an improvement