Skip to content

Get started

Local development

Tested with:Databasezy API v1 · zb CLI 0.1

zb start runs a whole Databasezy project in Docker on your machine: Postgres plus auth, the Data API, storage, realtime and Functions, behind the same project gateway the hosted platform uses. It needs no account, API key, organization or cloud project, and nothing is sent to the Databasezy API. Each project directory gets its own containers, network, data volume, keys and certificate, so several projects run side by side.

  • Docker Engine 28 or newer (Docker Desktop on macOS and Windows) with the Compose v2 plugin. The Docker context must be local - a Unix socket, a Windows named pipe or a loopback TCP endpoint; remote contexts are refused. If the daemon is not running, zb start stops with exit code 6 and the Docker daemon is not responding after at most 15 seconds, without creating anything.

  • The service images. zb start pulls missing images (--pull never forbids it):

    ContainerImage
    postgresdocker.io/library/postgres:17.6-alpine
    authghcr.io/zerobase/app-auth:<tag>
    postgrest (Data API)docker.io/postgrest/postgrest:v16.4 - the platform’s pinned PostgREST
    storageghcr.io/zerobase/storage:<tag>
    object-storedocker.io/rustfs/rustfs:1.0.3
    realtimeghcr.io/zerobase/realtime:<tag>
    functionsghcr.io/zerobase/functions:<tag>
    functions-runtimeghcr.io/supabase/edge-runtime:v1.77.4 - the platform’s pinned runtime
    gatewayghcr.io/zerobase/gateway:<tag>

    A development build of zb uses the tag dev: build those five images from a checkout of the repository with scripts/build-go-image.sh --tag dev app-auth storage realtime functions gateway. A release build uses main. --image-tag <tag> picks another tag and --image <container>=<reference> replaces one image.

  1. Mark an existing directory as a local project. This writes .databasezy/local.json (an id, nothing secret).

    shell
    zb init --dir ./my-app
    cd my-app
  2. Start it. The first start pulls images, creates the database and bootstraps the auth, storage and realtime schemas and roles, which takes a few minutes; later starts take seconds.

    shell
    zb start
    output
    Local project: 3f9c... (prj_01k...)
    Directory: /home/me/my-app
    State: running
    postgres running
    auth running
    data-api running
    storage running
    realtime running
    functions running
    API URL: https://localhost:52417
    CA certificate: /home/me/.config/databasezy/local-projects/<hash>/platform/tls/ca.crt (trust it in your client; the OS trust store is not changed)
    Database URL: postgresql://app:<redacted>@127.0.0.1:55124/app?sslmode=disable
    Env file: /home/me/.config/databasezy/local-projects/<hash>/local.env (keys and passwords, owner-only; never printed)
    Volume: zb-local-3f9c...-data (retained by stop)
  3. Load the env file into your app or shell and use the API URL with any Supabase client.

    shell
    set -a; . "$(zb status --json | jq -r .env_file)"; set +a
    curl --cacert "$DATABASEZY_CA_FILE" -H "apikey: $DATABASEZY_PUBLISHABLE_KEY" "$DATABASEZY_URL/auth/v1/settings"
  4. Stop it when you are done. Data is kept; the next zb start brings it back.

    shell
    zb stop

Every service except the database is reached through the gateway at https://localhost:<port>, with the same paths as a hosted project:

Service--services namePathRuns
Postgrespostgres127.0.0.1:<port> (DATABASEZY_DB_URL)Postgres 17.6 with logical replication
Authauth/auth/v1the platform’s auth service
Data APIdata-api/rest/v1PostgREST, schema public, roles anon / authenticated / service_role
Storagestorage/storage/v1the platform’s storage service on a local S3 object store
Realtimerealtime/realtime/v1the platform’s realtime service (broadcast, presence, Postgres changes)
Functionsfunctions/functions/v1/<name>the platform’s Functions host and edge-runtime

zb start runs all six. --services picks a subset - a comma-separated list, or all; Postgres is always included and any other service also starts the gateway:

shell
zb start --services data-api,auth # the database, PostgREST, auth and the gateway
zb start # the rest joins; nothing is recreated

zb start --services postgres in a new directory runs only a database: no gateway, no TLS, no keys. That directory keeps the Postgres-only runtime - its database is created without the platform’s logical replication settings and is never recreated - so zb start there keeps starting just Postgres, and asking for other services is refused. Use a new directory for the full stack.

Only two ports are published, both on 127.0.0.1 alone: the gateway’s and the database’s. The gateway port is a free port chosen at the first start (or --port) and stays the project’s port; if another process holds it, zb start refuses before creating or starting anything. The database port is assigned by Docker at each start; the env file is rewritten every time.

Each project generates its own keys at the first start and never rotates them: a publishable and a secret project key, anon and service-role JWTs (valid for a year), an ES256 signing key, database role passwords and a certificate authority for the gateway’s certificate. They live in private state under the OS configuration directory - not in the project directory, so they cannot be committed by accident - and zb start writes the ones your app needs to local.env there (mode 0600):

VariableValue
DATABASEZY_URLhttps://localhost:<port>
DATABASEZY_PUBLISHABLE_KEY / DATABASEZY_SECRET_KEYthe project keys (zbp_... / zbs_...)
DATABASEZY_ANON_KEY / DATABASEZY_SERVICE_ROLE_KEYlegacy JWTs for clients that expect Supabase’s anon and service-role keys
DATABASEZY_DB_URLthe database URL with its password
DATABASEZY_CA_FILE, NODE_EXTRA_CA_CERTSthe project’s CA certificate

Keys are never printed. zb status --show-secrets adds only the database password to the database URL. The URL and key variables are the ones the SDK compatibility suite reads; scripts/sdk-compat/run.py --local <dir> runs it against a local project.

The gateway serves TLS with a certificate for localhost signed by the project’s own CA. Trust that CA in your client - Node reads NODE_EXTRA_CA_CERTS, curl takes --cacert, Deno takes --cert - rather than turning verification off. zb does not add it to your operating system’s trust store.

No email is sent locally, so new users are confirmed when they sign up. Redirects go to --site-url (default http://localhost:3000), which, like the gateway port, is fixed at the first start.

Each directory under supabase/functions (or functions) is a function, as for zb functions deploy: zb start bundles them with the same bundler and serves them at /functions/v1/<name>. verify_jwt comes from supabase/config.toml and is on by default. There is no hot reload: run zb start again after editing a function; unchanged functions keep their version, a deleted directory stops serving its function.

zb stop stops the services first and the database last. Containers, the network, the database volume and the object store are kept, and the CLI never deletes any of them. zb start on a running project changes nothing. zb status shows each service’s state, the URLs and the env file path; --json prints the same as JSON.

Images are pinned by their image ID at the first start. If one is removed, zb start pulls it back only when its tag still points at the same image; a project never silently moves to other images - start a new directory for newer ones.

To delete a project’s data, remove its Docker objects yourself - the containers labelled com.databasezy.local.project=<id>, the volume zb-local-<id>-data and the network zb-local-<id>-network, where <id> is the id in .databasezy/local.json - and then the project’s directory under databasezy/local-projects in your OS configuration directory.

  • One realtime replica with an in-memory bus, and the Free plan’s limits.
  • Stock Postgres 17.6: the hosted extension set and GraphQL (pg_graphql) are not available.
  • No email delivery, and nothing is metered or billed.
  • Functions run without the hosted sandbox (gVisor/Kata) and are invoked over HTTP; triggers (cron, database, storage, auth, queue) are not set up locally.
  • The gateway certificate and the legacy JWTs are valid for a year and are not renewed automatically.
CommandWhat it does
zb init [--dir DIR]Marks an existing directory as a local project.
zb start [--services LIST] [--port N] [--site-url URL] [--image-tag TAG] [--image C=REF] [--pull missing|never] [--timeout 10m]Starts the stack (or a subset) and writes the env file. --timeout accepts 1s to 15m.
zb status [--show-secrets] [--json]Shows each service, the API URL, the CA and env file paths.
zb stop [--timeout 2m]Stops everything and keeps all data.

Every command takes --dir (default .). Full flag reference: CLI reference.