Concepts
Workspace
Section titled “Workspace”A workspace is your top-level container and the thing that gets billed — every database, member, token, and endpoint belongs to one. Think of it like a Slack or Notion workspace.
In the API it’s called a
namespace. The console, this site, and the assistant all say “workspace”, but the URL paths and SDK keep the original name. Wherever you see<namespace>in a path like/v1/db/<namespace>/<database>/..., that’s just your workspace’s slug.
Billing is per-workspace, not per-user. One person can belong to many workspaces with a different role in each.
Database
Section titled “Database”A database is a single SQLite file living in its own isolated
instance on Cloudflare’s network. Walled off from every other database —
no shared schema, no shared cache. Addressed as <namespace>/<database>
everywhere (the first part is your workspace slug):
| Where | Format |
|---|---|
| REST | POST /v1/db/acme/orders/query |
| SDK | persql.database("acme/orders") |
| MCP tools | database: "orders" (workspace inferred from token) |
| Public endpoints | /p/acme/orders/<endpoint-slug> |
Member and role
Section titled “Member and role”A member is a user × workspace × 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 workspace. Members are added by invitation — see Members & roles.
API token
Section titled “API token”A token is a psql_live_… secret key scoped to one workspace,
used by the REST API and MCP. Tokens aren’t tied to a user — they
carry workspace-level permissions and outlive whoever created them.
Every request a token makes draws down the workspace’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, five usage meters: per request, per row read, per row written, per GB of storage per month, and per AI token. 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 saved SQL statement exposed as a public web address
at /p/:ns/:db/:slug. Endpoints can check their input, require a
logged-in session, rate-limit, and handle CORS — all set in the spec,
no code. See Endpoints overview.