HTTP API
ParticleDB serves a lightweight HTTP API on port 7173, the ParticleDB port, next to a small HTML index page at /: run SQL and get JSON back, stream results as Server-Sent Events, read and write simple key-value tables, and probe health. Use it from curl, fetch, or any HTTP client.
Base URL
Section titled “Base URL”http://localhost:7173Configure it with:
particledb start --http-addr 0.0.0.0:7173Use the HTTP address for these requests. SQL drivers and other clients have separate connection addresses. See connection addresses.
Endpoints
Section titled “Endpoints”| Path | Method | Purpose |
|---|---|---|
/v1/sql |
POST |
Execute one SQL statement and return JSON rows |
/v1/sql/stream |
POST |
Stream SQL results as Server-Sent Events |
/v1/tables |
GET |
List public tables |
/v1/kv/get |
POST |
Read a single KV row by key |
/v1/kv/set |
POST |
Upsert a KV row |
/v1/kv/delete |
POST |
Delete a KV row |
/v1/version |
GET |
Fixed name/protocol metadata (not the server release) |
/health |
GET |
Plain-text health check (OK) |
/health/live |
GET |
Liveness probe JSON |
/health/ready |
GET |
Readiness probe JSON |
/health/deep |
GET |
Deep health JSON |
/metrics |
GET |
Prometheus text metrics; see Monitoring |
When authentication is enabled, every /v1/* endpoint except /v1/version
requires credentials. See Authentication. The /health*
endpoints never do.
POST /v1/sql
Section titled “POST /v1/sql”curl -X POST http://localhost:7173/v1/sql \ -H "Content-Type: application/json" \ -d '{"sql":"SELECT 1 AS ok"}'Response:
{ "rows": [ { "ok": 1 } ], "row_count": 1, "columns": ["ok"], "notices": []}notices carries any warnings the statement produced. A statement that fails
returns 400 with an error field, for example
{"error":"table not found: nosuch"}.
Each request runs one statement. A body with several statements
(SELECT 1; SELECT 2) is refused with 400.
The server also accepts raw SQL as a plain-text body:
printf 'SELECT 1 AS ok' | curl -X POST http://localhost:7173/v1/sql --data-binary @-DDL / DML examples
Section titled “DDL / DML examples”curl -X POST http://localhost:7173/v1/sql \ -H "Content-Type: application/json" \ -d '{"sql":"CREATE TABLE events (id BIGINT PRIMARY KEY, name TEXT)"}'
curl -X POST http://localhost:7173/v1/sql \ -H "Content-Type: application/json" \ -d "{\"sql\":\"INSERT INTO events (id, name) VALUES (1, 'signup')\"}"
curl -X POST http://localhost:7173/v1/sql \ -H "Content-Type: application/json" \ -d '{"sql":"SELECT id, name FROM events"}'DDL answers with a result row and DML with an affected_rows row:
{"rows":[{"result":"TABLE CREATED"}],"row_count":1,"columns":["result"],"notices":[]}{"rows":[{"affected_rows":1}],"row_count":1,"columns":["affected_rows"],"notices":[]}Parameter handling
Section titled “Parameter handling”POST /v1/sql binds $1-style placeholders from a params array, in order. Values are
JSON numbers, strings, booleans or null, and are never spliced into the SQL text:
curl --fail-with-body http://localhost:7173/v1/sql \ -H 'Content-Type: application/json' \ -d '{"sql":"SELECT id, title FROM tasks WHERE id = $1","params":[1]}'A request whose params count differs from the statement’s placeholders is rejected with
status 400, for example request supplies 0 parameters, but the statement requires 1.
POST /v1/sql/stream binds params the same way. A count mismatch there arrives inside
the stream as an error event (SQLSTATE 08P01) followed by done.
Streaming SQL
Section titled “Streaming SQL”POST /v1/sql/stream
Section titled “POST /v1/sql/stream”Streams results as Server-Sent Events (SSE), one event per row.
curl -N -X POST http://localhost:7173/v1/sql/stream \ -H "Content-Type: application/json" \ -d '{"sql":"SELECT * FROM events"}'The stream emits a columns event with each column’s name and type, one row event
per row, then a metadata event and a done event:
event: columnsdata: {"columns":[{"name":"id","type":"integer"},{"name":"name","type":"text"}]}
event: rowdata: {"columns":["id","name"],"values":[1,"signup"]}
event: metadatadata: {"rows_affected":1,"elapsed_ms":0.309}
event: donedata: {}There is no WebSocket endpoint; use SSE for incremental results in the browser.
Tables
Section titled “Tables”GET /v1/tables
Section titled “GET /v1/tables”curl http://localhost:7173/v1/tablesResponse:
{ "tables": ["events", "kv_store"]}Only table names are returned.
KV Helpers
Section titled “KV Helpers”The KV endpoints read and write a table that has a key column and a value
column. Create the table first:
CREATE TABLE kv_store ( key TEXT PRIMARY KEY, value TEXT);POST /v1/kv/set
Section titled “POST /v1/kv/set”curl -X POST http://localhost:7173/v1/kv/set \ -H "Content-Type: application/json" \ -d '{"table":"kv_store","key":"user:1001","value":"{\"name\":\"Alice\"}"}'{ "ok": true}POST /v1/kv/get
Section titled “POST /v1/kv/get”curl -X POST http://localhost:7173/v1/kv/get \ -H "Content-Type: application/json" \ -d '{"table":"kv_store","key":"user:1001"}'{ "key": "user:1001", "value": "{\"name\":\"Alice\"}"}If the key is missing, the server returns 404 with an error field
({"error":"key not found: user:1001"}).
POST /v1/kv/delete
Section titled “POST /v1/kv/delete”curl -X POST http://localhost:7173/v1/kv/delete \ -H "Content-Type: application/json" \ -d '{"table":"kv_store","key":"user:1001"}'{ "ok": true}Health and Metrics
Section titled “Health and Metrics”GET /health
Section titled “GET /health”curl http://localhost:7173/healthResponse:
OKGET /health/live
Section titled “GET /health/live”{ "status": "alive", "uptime_seconds": 42}GET /health/ready
Section titled “GET /health/ready”{ "status": "ready", "tables_loaded": 3, "connections_active": 1, "connections_max": 2000, "connections_available": 1999}GET /health/deep
Section titled “GET /health/deep”{ "status": "healthy", "ready": true}Metrics
Section titled “Metrics”Prometheus metrics are covered on the Monitoring page.
Version
Section titled “Version”GET /v1/version
Section titled “GET /v1/version”curl http://localhost:7173/v1/version{ "name": "ParticleDB", "version": "0.1.0", "protocol": "pg-wire"}The version field is a fixed value and does not report the server
release. To read the server release, call the gRPC
health method or run SELECT version().
The built-in HTTP server responds with permissive CORS headers:
Access-Control-Allow-Origin: *Access-Control-Allow-Methods: GET, POST, OPTIONSAccess-Control-Allow-Headers: Content-Type, authorization
It also answers generic OPTIONS requests with 204 No Content.
Authentication
Section titled “Authentication”When the server runs with authentication (the default), send a database user’s name and password with HTTP Basic authentication:
curl -u app_user:app_password -X POST http://localhost:7173/v1/sql \ -H "Content-Type: application/json" \ -d '{"sql":"SELECT 1 AS ok"}'A request without credentials gets 401 Unauthorized
({"error":"authentication required: provide an Authorization header"}). On
/v1/sql/stream the rejection arrives inside the stream instead, as an error
event followed by done.
Under --no-auth or --auth-method trust, no credentials are needed.
Security Notes
Section titled “Security Notes”- Basic credentials travel in clear text over plain HTTP. Start the server with
--tls-cert/--tls-keyand port 7173 serves HTTPS only (a dedicated health port stays plain HTTP), or put a TLS-terminating reverse proxy in front of it. Add--require-tls-for-credentialsto refuse Basic credentials sent without TLS. - Restrict who can reach port 7173 (
--http-addr 127.0.0.1:7173binds this HTTP endpoint to loopback only).
Next Steps
Section titled “Next Steps”- SQL client compatibility. Primary SQL interface for applications and ORMs
- gRPC. Typed RPC interface with protobuf messages
- TLS / Security. PG/gRPC/Redis TLS details and HTTP deployment notes
Related
Section titled “Related”This site uses Google Analytics cookies to count visits. Privacy · License