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).
ParticleDB SDK
Section titled “ParticleDB SDK”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.
go get github.com/particledb-ai/particledb-go@v0.2.2The 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:
updatedactiveKeep 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.
SQL client interface with pgx
Section titled “SQL client interface with pgx”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.
Install
Section titled “Install”go get github.com/jackc/pgx/v5The 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.
Quick start
Section titled “Quick start”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:
2alice1 alicia2 bob3 carolKey-value and vector search
Section titled “Key-value and vector search”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.
Next steps
Section titled “Next steps”- SQL Reference. SQL syntax and examples
- ORM compatibility. GORM and other ORMs
- SQL client connections. connection settings and compatibility
This site uses Google Analytics cookies to count visits. Privacy · License