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 --help

2. 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 whoami

3. 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_app
berth 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:boolean

5. 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" notes

Filters use the column.op=value form:

berth rows list --app "$APP" notes --where done.eq=false

The 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.

VariableHoldsWhere it comes from
$BERTH_ACCOUNT_KEYaccount key, bak_...berth signup or berth login
$APPapp nameyou choose it
$SECRET_KEYsecret app key, bsk_...berth apps create or berth keys create
$PUBLISHABLE_KEYpublishable app key, bpk_...berth apps create or berth keys create
$ACCESS_TOKENsigned-in user JWT/auth/signup, /auth/login, /auth/verify
$REFRESH_TOKENrefresh tokensame session response
$ROW_ID, $USER_ID, $KEY_ID, $WEBHOOK_IDidsset 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.

CallerSendsCan do
Your laptop or CIaccount keycreate, export, restore, and delete apps
Your server or a functionsecret keyeverything inside one app
Your phone or web apppublishable key and user JWTsign in, then only what policies allow