Run your first query
1. Install
Section titled “1. Install”curl -fsSL https://get.particledb.ai | bashCheck the installation:
particledb --versionparticledb start --helpSee installation for supported platforms and manual installation.
2. Start locally
Section titled “2. Start locally”particledb start \ --data-dir ./pdb-dev \ --http-addr 127.0.0.1:7173 \ --pg-addr 127.0.0.1:5432 \ --redis-addr 127.0.0.1:6379 \ --mysql-addr 127.0.0.1:3307 \ --metrics-addr 127.0.0.1:7175 \ --no-unix-sockets \ --no-authKeep this process running. --no-auth disables authentication, so use this setup only for development on a trusted local machine. See local development for listener settings and security before exposing a server.
3. Connect from your language
Section titled “3. Connect from your language”In another terminal, install a client and run the example. The clients connect to localhost:7173, the ParticleDB port, by default. The example creates a table, writes a row, reads it back and uses a key on the same connection.
pip install particledbPyPI particledb 0.2.2import particledb
db = particledb.connect() # localhost:7173
db.execute("CREATE TABLE agents (id BIGINT PRIMARY KEY, name TEXT)")
db.execute("INSERT INTO agents VALUES ($1, $2)", [1, "planner"])
print(db.query("SELECT id, name FROM agents WHERE id = $1", [1]))
db.kv_set("agent:1:status", "ready")
print(db.kv_get("agent:1:status").decode())[{'id': 1, 'name': 'planner'}]
readynpm install @particledb/sdknpm @particledb/sdk 0.2.1, ES moduleimport { ParticleDB } from '@particledb/sdk';
const db = await ParticleDB.connect(); // localhost:7173
await db.execute('CREATE TABLE agents (id BIGINT PRIMARY KEY, name TEXT)');
await db.execute('INSERT INTO agents VALUES ($1, $2)', [1, 'planner']);
console.log(await db.queryOne('SELECT id, name FROM agents WHERE id = $1', [1]));
await db.kv.set('agent:1:status', 'ready');
console.log(await db.kv.get('agent:1:status'));
await db.close();{ id: 1, name: 'planner' }
readyimplementation("ai.particledb:particledb-java-sdk:1.1.3")Gradle, from Maven Centralvar db = ParticleDB.connect(); // localhost:7173
db.execute("CREATE TABLE agents (id BIGINT PRIMARY KEY, name TEXT)");
db.execute("INSERT INTO agents VALUES (?, ?)", 1L, "planner");
System.out.println(db.queryOne("SELECT id, name FROM agents WHERE id = ?", 1L));
db.kv().set("agent:1:status", "ready");
System.out.println(db.kv().get("agent:1:status"));Row{id=1, name=planner}
readygo get github.com/particledb-ai/particledb-go@v0.2.2Go 1.26.10+ctx := context.Background()
db, _ := particledb.NewPool(ctx, "") // localhost:7173
db.Exec(ctx, "CREATE TABLE agents (id BIGINT PRIMARY KEY, name TEXT)")
db.Exec(ctx, "INSERT INTO agents VALUES ($1, $2)", 1, "planner")
var name string
db.QueryRow(ctx, "SELECT name FROM agents WHERE id = $1", 1).Scan(&name)
db.KVSet(ctx, []byte("agent:1:status"), []byte("ready"))
status, _ := db.KVGet(ctx, []byte("agent:1:status"))
fmt.Println(name, string(status))planner readycargo add particledb-sdkcrates.io particledb-sdk 0.2.1let db = ParticleDB::connect(Config::default())?; // localhost:7173
db.execute("CREATE TABLE agents (id BIGINT PRIMARY KEY, name TEXT)", &[])?;
db.execute("INSERT INTO agents VALUES ($1, $2)", &[Value::Int64(1), Value::String("planner".into())])?;
let row = db.query_one("SELECT name FROM agents WHERE id = $1", &[Value::Int64(1)])?.unwrap();
println!("{}", row.get_by_name::<String>("name")?);
db.kv().set("agent:1:status", "ready")?;
println!("{:?}", db.kv().get("agent:1:status")?);planner
Some("ready")particledb cliSQL client included with the serverCREATE TABLE agents (id BIGINT PRIMARY KEY, name TEXT);
INSERT INTO agents VALUES (1, 'planner');
SELECT id, name FROM agents WHERE id = 1;
SELECT KV_SET('agent:1:status', 'ready');
SELECT KV_GET('agent:1:status');1|planner
OK
readyThe other pages show each task in the language you pick here. See your language guide for authentication, pooling and error handling.
PostgreSQL-compatible clients
Section titled “PostgreSQL-compatible clients”Tools that speak the PostgreSQL protocol, such as psql and existing drivers, connect to the SQL client address instead, port 5432 in the start command above. This reads the row the example wrote:
psql -h 127.0.0.1 -p 5432 -U postgres -d particledb -c "SELECT id, name FROM agents"See PostgreSQL compatibility for supported drivers and differences.
HTTP API
Section titled “HTTP API”The HTTP API on the same port takes SQL as JSON. This sequence uses its own table:
Create a table
Section titled “Create a table”Send a SQL statement to the database from another terminal:
curl --fail-with-body http://localhost:7173/v1/sql \ -H 'Content-Type: application/json' \ -d '{"sql":"CREATE TABLE tasks (id BIGINT PRIMARY KEY, title TEXT, status TEXT)"}'Write a record
Section titled “Write a record”curl --fail-with-body http://localhost:7173/v1/sql \ -H 'Content-Type: application/json' \ -d "{\"sql\":\"INSERT INTO tasks VALUES (1, 'First task', 'pending')\"}"Read it back
Section titled “Read it back”curl --fail-with-body http://localhost:7173/v1/sql \ -H 'Content-Type: application/json' \ -d '{"sql":"SELECT id, title, status FROM tasks ORDER BY id"}'The response’s rows array contains:
[{"id":1,"title":"First task","status":"pending"}]This guide creates the table once. For a fresh rerun, use a new development data directory or remove the sample table from your development database.
Next steps
Section titled “Next steps”- Choose a language client.
- Learn parameters and transactions.
- Add search and memory or key-value where your application needs them.
- Move reusable logic into Particles.
- Review security and deployment.
For a disposable test setup, follow local development. For an existing database, start with migration.
This site uses Google Analytics cookies to count visits. Privacy · License