database.pizza/docs

title: Quickstart

description: Create an organization, a database, and an API key, then run your first query over the PostgreSQL-compatible wire protocol or HTTP.

This guide gets you from a fresh account to a working query in about five minutes. It assumes you've signed up at app.database.pizza.

We'll use a fictional organization acme and a database production. Replace both with your own names throughout.

1. Create an organization

Organizations group your databases, members, and API keys. When you create one, its name becomes a slug — the URL-safe identifier used in every connection path.

Sign in to the dashboard.
Create an organization named acme.
The slug becomes acme (lowercased, spaces turned into -).

Your connection path always starts with the organization slug, then the database slug: acme/production.

2. Create a database

Inside the acme organization, create a database named production.

The database name also becomes a slug: production.
Each database has an isolated PizzaSQL namespace with its own schema and data.
Databases are isolated from one another — a key for one can't touch another unless you grant it access.

3. Create an API key

Every programmatic connection authenticates with an API key, which doubles as your PostgreSQL password.

Open the production database and go to API keys.
Choose Create API key and give it a name like local dev.
Select the scopes you need. For now, enable Read and Write (and Alter table if you'll be creating tables from a client).
Copy the key immediately — it's shown only once.

A live key looks like pz_live_…. The docs use the placeholder pz_live_REPLACE_ME; substitute your real key.

Security: Treat the key like a password. Don't commit it to source control, and prefer environment variables. See API keys & permissions.

4. Run your first query

You have two equivalent options. Pick whichever fits your workflow.

Over HTTP

curl -s https://db.database.pizza/acme/production/query \
  -H "Authorization: Bearer pz_live_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT 1 + 1 AS answer"}'

{
  "columns": [{ "name": "answer", "type": "INTEGER" }],
  "rows": [[2]],
  "rowsReturned": 1,
  "executionTimeMicro": 108,
  "bytesRead": 4
}

The HTTP query API is documented in full at HTTP query API.

Over PostgreSQL

PGPASSWORD='pz_live_REPLACE_ME' psql \
  "postgresql://u@db.database.pizza:5432/acme%2Fproduction?sslmode=disable" \
  -c "SELECT 1 + 1 AS answer;"

Three details matter here:

The database name is acme/production — the slash is part of the name. In a connection URI it must be percent-encoded as acme%2Fproduction.
TLS is currently declined by the proxy, so connect with sslmode=disable; your key and queries travel in cleartext over the wire.
The wire protocol is partially PostgreSQL-compatible — psql works, but the SQL you send is SQLite-style, not PostgreSQL. See PostgreSQL clients and Compatibility.

Full details are in Connect and PostgreSQL clients.

5. Create a table and query it

Now create a table and read it back:

curl -s https://db.database.pizza/acme/production/query \
  -H "Authorization: Bearer pz_live_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{"sql": "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL, email TEXT NOT NULL)"}'

Then insert and select:

curl -s https://db.database.pizza/acme/production/query \
  -H "Authorization: Bearer pz_live_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{"sql": "INSERT INTO users (name, email) VALUES (?, ?)", "params": ["Ada", "ada@acme.example"]}'

curl -s https://db.database.pizza/acme/production/query \
  -H "Authorization: Bearer pz_live_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM users"}'

Note the ? placeholders with a params array — always pass values this way rather than concatenating them into the SQL string.

INTEGER PRIMARY KEY values are assigned automatically when omitted. PizzaSQL accepts UNIQUE, but does not currently enforce it; enforce email uniqueness in your application. See Constraints before relying on schema-level validation.

Next steps

Change history — see what your queries just changed.
Undo & recovery — revert a mistake before it matters.
Connect — every connection parameter, in one place.
Your first schema — a realistic schema with indexes.
SQL reference — the full dialect.

quickstart.md 4.9 KB Előzmények Nyers