Server
Installation
Section titled “Installation”npm install -g @petradb/serverpetradb-server [OPTIONS] [path]If a path is given, the server opens (or creates) a persistent database at that location. Without a path, an in-memory database is used.
Options
Section titled “Options”| Option | Description |
|---|---|
-m, --memory | Use an in-memory database |
-p, --port | Port number (default: 5480) |
-h, --host | Host address (default: 127.0.0.1) |
-c, --config | Path to a TOML configuration file |
Examples
Section titled “Examples”# In-memory database on the default portpetradb-server
# Persistent database on a custom portpetradb-server -p 8080 mydata.db
# With a config filepetradb-server -c petradb.toml mydata.dbConfiguration
Section titled “Configuration”A TOML file controls authentication, CORS, and session limits.
auth = "basic"
[[users]]username = "admin"password = "$HASHED_PASSWORD"
[[users]]username = "reader"password = "$HASHED_PASSWORD"
[cors]origin = "*" # "*" (default), "none", or a specific origin
[sessions]max_sessions = 100 # 0 = unlimited (default)Authentication Modes
Section titled “Authentication Modes”| Mode | Description |
|---|---|
"none" | No authentication (default when no config file is given) |
"basic" | HTTP Basic authentication against the [[users]] list |
Passwords in the config file are stored as PBKDF2 hashes.
When auth = "basic", every request (except GET /health) must include an Authorization: Basic <credentials> header.
origin value | Behaviour |
|---|---|
"*" (default) | Allow all origins |
"none" | No CORS headers |
A URL (e.g. "https://app.example.com") | Allow only that origin |
HTTP API
Section titled “HTTP API”All SQL requests and responses use the PetraDB binary codec (application/octet-stream). Use the @petradb/client library instead of calling these endpoints directly.
Execute SQL
Section titled “Execute SQL”POST /sqlContent-Type: application/octet-streamX-Session-Id: <session-id> (optional)
<sql text>Returns a binary-encoded Seq[Result]. Without an X-Session-Id header, each request runs in a one-off transient session.
Create Session
Section titled “Create Session”POST /sessionReturns { "sessionId": "<id>" }. Use the returned ID in subsequent X-Session-Id headers to share transaction state across requests.
Close Session
Section titled “Close Session”DELETE /session/<id>Returns { "ok": "true" } on success, or 404 if the session does not exist.
Health Check
Section titled “Health Check”GET /healthReturns { "status": "ok" }. Not subject to authentication.
Error Responses
Section titled “Error Responses”| Status | Meaning |
|---|---|
| 400 | SQL parse error, type error, or undefined reference |
| 401 | Missing or invalid credentials |
| 409 | Schema or constraint violation |
| 503 | Session limit reached |