Skip to content
ParticleDB
Release candidateParticleDB 1.1.19-rc.17 is not yet GA or ready for production data.Release status →

Go SDK

Use the configured address for your client. See connection addresses and security. The ParticleDB SDK examples use the database port, 7173; the other examples use the SQL client address.

Go applications can use the ParticleDB SDK over the native client protocol (port 7173) or pgx over the SQL client interface (port 5432).

The github.com/particledb-ai/particledb-go module, version v0.2.2, MIT licensed from v0.2.0. It requires Go 1.26.10 or newer and server 1.1.19-rc.13 or later.

Terminal window
go get github.com/particledb-ai/particledb-go@v0.2.2

The example connects as app, with the password in PARTICLEDB_PASSWORD. Start the server with the local start command, replacing --no-auth with --auth-method scram-sha-256 --pg-username app --pg-password-file ./pdb-password. The password file holds only the password. The SDK connects to localhost:7173 by default.

package main
import (
"context"
"fmt"
"log"
"os"
"time"
"github.com/particledb-ai/particledb-go"
)
func main() {
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
cfg, err := particledb.ParseConfig("")
if err != nil { log.Fatal(err) }
cfg.User = "app"
cfg.Password = os.Getenv("PARTICLEDB_PASSWORD")
pool, err := particledb.NewPoolConfig(ctx, cfg)
if err != nil { log.Fatal(err) }
defer pool.Close()
if _, err := pool.Exec(ctx, "CREATE TABLE tasks (id BIGINT PRIMARY KEY, title TEXT)"); err != nil { log.Fatal(err) }
if _, err := pool.Exec(ctx, "INSERT INTO tasks VALUES ($1, $2)", 1, "first"); err != nil { log.Fatal(err) }
err = particledb.BeginFunc(ctx, pool, particledb.TxOptions{}, func(tx *particledb.Tx) error {
_, err := tx.Exec(ctx, "UPDATE tasks SET title = $1 WHERE id = $2", "updated", 1)
return err
})
if err != nil { log.Fatal(err) }
var title string
if err := pool.QueryRow(ctx, "SELECT title FROM tasks WHERE id = $1", 1).Scan(&title); err != nil { log.Fatal(err) }
fmt.Println(title)
if err := pool.KVSet(ctx, []byte("session:123"), []byte("active")); err != nil { log.Fatal(err) }
value, err := pool.KVGet(ctx, []byte("session:123"))
if err != nil { log.Fatal(err) }
fmt.Println(string(value))
}

Output:

updated
active

Keep the pool for the application’s lifetime and pass a context to each call. BeginFunc commits when the function returns nil and rolls back on an error.

Use pgx over the SQL client interface (port 5432): pooling, bind parameters and transactions are shown below. database/sql with the pgx stdlib adapter or lib/pq also works.

Terminal window
go get github.com/jackc/pgx/v5

The example connects as postgres with the password secret, for a server started with particledb start --auth-method scram-sha-256 --pg-password secret. With the server’s default --auth-method password, use sslmode=require; see TLS and authentication.

package main
import (
"context"
"fmt"
"log"
"github.com/jackc/pgx/v5"
"github.com/jackc/pgx/v5/pgxpool"
)
func main() {
ctx := context.Background()
pool, err := pgxpool.New(ctx,
"postgres://postgres:secret@localhost:5432/particledb?sslmode=disable")
if err != nil {
log.Fatal(err)
}
defer pool.Close()
if _, err := pool.Exec(ctx,
"CREATE TABLE users (id BIGINT PRIMARY KEY, name TEXT)"); err != nil {
log.Fatal(err)
}
tag, err := pool.Exec(ctx, "INSERT INTO users (id, name) VALUES ($1, $2), ($3, $4)",
1, "alice", 2, "bob")
if err != nil {
log.Fatal(err)
}
fmt.Println(tag.RowsAffected()) // 2
var name string
if err := pool.QueryRow(ctx, "SELECT name FROM users WHERE id = $1", 1).Scan(&name); err != nil {
log.Fatal(err)
}
fmt.Println(name) // alice
// Transaction: commits if the function returns nil, rolls back otherwise
err = pgx.BeginFunc(ctx, pool, func(tx pgx.Tx) error {
if _, err := tx.Exec(ctx, "INSERT INTO users (id, name) VALUES ($1, $2)", 3, "carol"); err != nil {
return err
}
_, err := tx.Exec(ctx, "UPDATE users SET name = $1 WHERE id = $2", "alicia", 1)
return err
})
if err != nil {
log.Fatal(err)
}
rows, err := pool.Query(ctx, "SELECT id, name FROM users ORDER BY id")
if err != nil {
log.Fatal(err)
}
for rows.Next() {
var id int64
var n string
if err := rows.Scan(&id, &n); err != nil {
log.Fatal(err)
}
fmt.Println(id, n)
}
if err := rows.Err(); err != nil {
log.Fatal(err)
}
}

Output:

2
alice
1 alicia
2 bob
3 carol

Key-value operations and vector search are SQL, so you call them like any other statement, for example pool.QueryRow(ctx, "SELECT KV_GET($1)", "user:1") or ORDER BY embedding <-> '[0.1,0.2,0.3]' LIMIT 5. See Vector Search.