Concepts
Namespace
Section titled “Namespace”A namespace is the billing entity and the top-level container for
everything else. Think of it as a workspace or organisation. Every
database, member, token, and endpoint belongs to one. The slug appears
in every URL: /v1/db/<namespace>/<database>/....
Billing is per-namespace, not per-user. One user can belong to many namespaces with different roles in each.
Database
Section titled “Database”A database is a single SQLite file living in a Durable Object on
the edge. Fully isolated from every other tenant — no shared schema,
no shared cache. Addressed as <namespace>/<database> everywhere:
| Where | Format |
|---|---|
| REST | POST /v1/db/acme/orders/query |
| SDK | persql.database("acme/orders") |
| MCP tools | database: "orders" (namespace inferred from token) |
| Public endpoints | /p/acme/orders/<endpoint-slug> |
Member and role
Section titled “Member and role”A member is a user × namespace × role. Three roles:
| Role | Can read | Can write | Can manage members | Can manage billing |
|---|---|---|---|---|
viewer | yes | no | no | no |
editor | yes | yes | no | no |
admin | yes | yes | yes | no |
owner | yes | yes | yes | yes |
Owners are the only role that can manage billing or delete the namespace. Members are added by invitation — see Members & roles.
API token
Section titled “API token”A token is a psql_live_… bearer secret scoped to one namespace,
used by the REST API and MCP. Tokens are not tied to a user — they
inherit namespace-level permissions and outlive the member who minted
them. Every request a token makes debits the namespace’s prepaid
balance.
The first 4 + last 4 characters are visible in the console after creation; the full secret is shown exactly once at creation time.
Pricing
Section titled “Pricing”Prepaid balance, four meters: per request, per row read, per row written, per stored GB-month. No subscription, no seat fees, no per-database fees, no plan-tier feature gates. Branches, snapshots and MCP are features, not tiers. See Pricing & billing.
Endpoint
Section titled “Endpoint”An endpoint is a stored, parameterised SQL statement exposed as
public HTTP at /p/:ns/:db/:slug. Endpoints can validate input,
gate by session JWT, rate-limit, and ship CORS — all configured in the
spec, no code. See Endpoints overview.