# Go SDK

Connect to ParticleDB from Go, run parameterized queries, handle transactions and errors.

Source: https://particledb.ai/sdks/go/

Use the configured address for your client. See [connection addresses](/installation/ports/) and [security](/guides/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

The [`github.com/particledb-ai/particledb-go`](https://github.com/particledb-ai/particledb-go/tree/v0.2.2)
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.

```bash
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](/getting-started/quickstart/#2-start-locally), 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.

```go
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.

## SQL client interface with pgx

Use [pgx](https://github.com/jackc/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

```bash
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](/connectivity/tls/#authentication).

### Quick start

```go
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 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](/sql/vector-search/).

## Next steps

- [SQL Reference](/sql/overview/). SQL syntax and examples
- [ORM compatibility](/connectivity/orm-compatibility/). GORM and other ORMs
- [SQL client connections](/connectivity/pg-wire/). connection settings and compatibility
