Get started
Berth docs
Berth is a small backend platform. Each app gets its own Postgres database and Postgres role, API keys, end-user auth, row policies, realtime streams, file storage, Deno functions, webhooks, raw SQL, and a one command export. You drive it with the berth CLI or plain HTTPS.
What you get
Quickstart
Five steps: install the CLI, sign up, create an app, create a table, write and read rows. About five minutes.
1. Install the CLI
The CLI is one Python 3 script with no dependencies. This writes ~/.local/bin/berth and tells you the PATH line to add if that folder is not on your PATH yet.
curl -fsSL https://atberth.com/install.sh | sh
berth --help2. Sign up
Berth emails you a 6 digit code. The CLI asks for it, then saves an account key (bak_...) in ~/.config/berth/config.json with mode 600. Next time, berth login does the same for an existing account.
berth signup --email you@example.com
# Check your email, then type the 6 digit code when asked.Check who you are signed in as:
berth whoami3. Create an app
An app name is lowercase letters, numbers, and underscores, starting with a letter. The examples use $APP for it, so set it once:
export APP=notes_appberth apps create "$APP"Berth creates a Postgres database and a Postgres role for the app, and prints two keys once: a secret key (bsk_...) for your server and a publishable key (bpk_...) for your phone or browser build. The CLI keeps the secret key on this machine, so the next commands just take --app. berth use "$APP" makes it the default.
4. Create a table
Columns are name:type, with optional :notnull and :unique. Every table also gets id (uuid) and created_at.
berth tables create --app "$APP" notes title:text:notnull done:boolean5. Write and read rows
berth rows add --app "$APP" notes title="Buy milk" done=false
berth rows add --app "$APP" notes title="Call the bank" done=true
berth rows list --app "$APP" notesFilters use the column.op=value form:
berth rows list --app "$APP" notes --where done.eq=falseThe same with curl
Everything the CLI does is a plain HTTPS call to https://api.atberth.com/v1. Make a secret key for curl and keep it in $SECRET_KEY:
SECRET_KEY=$(berth keys create --app "$APP" --type secret --name curl --json | jq -er .secret)Insert a row:
curl -sS -X POST https://api.atberth.com/v1/apps/$APP/tables/notes/rows \
-H "Authorization: Bearer $SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"title":"Water the plants","done":false}'List rows that are not done, newest first:
curl -sS "https://api.atberth.com/v1/apps/$APP/tables/notes/rows?done=eq.false&order=created_at.desc" \
-H "Authorization: Bearer $SECRET_KEY"The response is {"rows": [...], "next_cursor": null}. A secret key can do anything in its app, so it belongs on your server only. A phone app uses the publishable key plus a signed-in user token: see Keys and security and End-user auth.
Variables in these docs
Every shell example uses the same names, so you can paste them in order.
| Variable | Holds | Where it comes from |
|---|---|---|
$BERTH_ACCOUNT_KEY | account key, bak_... | berth signup or berth login |
$APP | app name | you choose it |
$SECRET_KEY | secret app key, bsk_... | berth apps create or berth keys create |
$PUBLISHABLE_KEY | publishable app key, bpk_... | berth apps create or berth keys create |
$ACCESS_TOKEN | signed-in user JWT | /auth/signup, /auth/login, /auth/verify |
$REFRESH_TOKEN | refresh token | same session response |
$ROW_ID, $USER_ID, $KEY_ID, $WEBHOOK_ID | ids | set by earlier examples on the same page |
Examples that start a page assume $APP, $SECRET_KEY, and $PUBLISHABLE_KEY are set for a fresh app. The base URL is always https://api.atberth.com/v1, and the full route list is at /v1/openapi.json.
How it fits together
Your server and your laptop hold secret or account keys. Phones and browsers hold only the publishable key and a user token, and every table and bucket they touch has a policy. Each app is its own Postgres database, reached through its own Postgres role, so one app can never read another app's data.
| Caller | Sends | Can do |
|---|---|---|
| Your laptop or CI | account key | create, export, restore, and delete apps |
| Your server or a function | secret key | everything inside one app |
| Your phone or web app | publishable key and user JWT | sign in, then only what policies allow |