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

Run your first query

Terminal window
curl -fsSL https://get.particledb.ai | bash

Check the installation:

Terminal window
particledb --version
particledb start --help

See installation for supported platforms and manual installation.

Terminal window
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-auth

Keep 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.

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.2

import 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())
Output
[{'id': 1, 'name': 'planner'}]
ready

The other pages show each task in the language you pick here. See your language guide for authentication, pooling and error handling.

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:

Terminal window
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.

The HTTP API on the same port takes SQL as JSON. This sequence uses its own table:

Send a SQL statement to the database from another terminal:

Terminal window
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)"}'
Terminal window
curl --fail-with-body http://localhost:7173/v1/sql \
-H 'Content-Type: application/json' \
-d "{\"sql\":\"INSERT INTO tasks VALUES (1, 'First task', 'pending')\"}"
Terminal window
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.

  1. Choose a language client.
  2. Learn parameters and transactions.
  3. Add search and memory or key-value where your application needs them.
  4. Move reusable logic into Particles.
  5. Review security and deployment.

For a disposable test setup, follow local development. For an existing database, start with migration.