Skip to main content

Setting Up Server

The CSDB server is a Docker-deployable HTTP service for .csdb databases. It mounts a data directory, opens server-managed CSDB files from that directory, and exposes JSON commands over HTTP.

Docker Compose​

Use Docker Compose from the server-typescript repository:

cp .env.example .env
mkdir -p data
cp examples/payroll.csdb data/payroll.csdb
docker compose up --build

The default address is:

http://127.0.0.1:3000

The Compose file:

  • builds the server image from the repository Dockerfile
  • runs the Node.js app in a container
  • mounts the host ./data directory at /data
  • binds to localhost by default
  • runs the container read-only except for mounted data and temporary storage

Data Directory​

Each database is addressed by logical name. For example, this request:

{
  "database": "payroll",
  "command": { "kind": "validate" }
}

maps to:

data/payroll.csdb

Clients do not send filesystem paths. The server resolves database names inside its configured data directory and prevents path traversal.

Configuration​

The .env file controls the local Docker Compose deployment:

VariablePurpose
CSDB_BIND_ADDRESSHost interface for the published port. Defaults to 127.0.0.1.
CSDB_PORTHost port mapped to container port 3000.
CSDB_DATA_PATHHost directory mounted into the container as /data.
CSDB_API_KEYOptional bearer token required for requests.
CSDB_MAX_BODY_BYTESMaximum JSON request body size.
CSDB_SHUTDOWN_TIMEOUT_MSGraceful shutdown timeout.
CSDB_UID, CSDB_GIDContainer user and group IDs for mounted data access.

Set a long random CSDB_API_KEY before exposing the service outside localhost.

HTTP Surface​

The main command endpoint is:

POST /v1/commands
Content-Type: application/json

Server commands mirror the TypeScript API as JSON:

  • Database operations map to CSDBDatabase actions.
  • Table operations map to TableQuery and table mutation actions.
  • SQL commands map to db.sql(statement, params).
  • Query-plan commands use the same field names as TypeScript plans.

Command-specific examples live with the related API pages:

Health Check​

Use the health endpoint to verify the container is running:

GET /health
{ "status": "ok" }