Skip to content
Aurabase Logo
aurabase

Deployment

Zero-downtime migrations, atomic rollback, CI/CD via GitHub Actions / GitLab / CLI, and database branches: a copy of a project to test a migration or a policy before production.

Explanation8 min readLevel intermediateRevised on Apr 15, 2026

Three deployment surfaces#

An Aurabase project exposes three surfaces to deploy: Postgres schema (versioned SQL migrations), edge functions (WASM + cron + jobs), policies and secrets (RLS, env vars, OAuth apps). Each pushes itself independently via aura CLI.

The CLI (aura) is a single binary, also installable with npm install -g @aurabase/cli, and supports dry-run, confirm prompts and diff preview. Linux / macOS / Windows compatible.

Dev, preview, production#

By default, a project has two environments: dev (local, Kubernetes) and prod (cloud). To try a change on a copy of your data before production, create a database branch.

fluxtext
LOCAL DEV
    $ ./start.sh              → full local stack (k3d)
    $ aura dev                → watch mode + types gen

BRANCH (copy of a project, deleted by its TTL)
    $ aura branch create pr-142 --from my-app --ttl 3d
    $ aura db push            → on the branch project, to try the migration
    $ aura branch delete pr-142

PRODUCTION
    merge to main             → CI run: aura db push
                              → aura deploy functions

Versioned SQL, atomic rollback#

Migrations live in aurabase/migrations. One file per change, timestamp in prefix. The CLI applies the missing migrations to the linked project; regenerate your TypeScript types with npx @aurabase/gen after a change.

terminalbash
# Create a new migration
aura db migration new add_devices_table
# → aurabase/migrations/20260415120000_add_devices_table.sql

# See which migrations are applied or pending, then apply them to the linked project
aura db status
aura db push

# Regenerate TypeScript types
npx @aurabase/gen --out src/aurabase.types.ts

# List applied migrations
aura db migration list
Attention

Zero-downtime migrations. Follow the rules: add nullable column first, separate backfill, constraint NOT NULL last. The CLI does not check backward compatibility for you: review destructive statements (drop column, alter column … type) before aura db push.

Database branches#

A branch is a new project cloned from an existing PostgreSQL project: its schema, row level security policies, functions, triggers, views and (unless you ask for the schema only) its rows. It has its own URL, API keys and database, so you can run a migration, test a policy or point a preview deployment at it without touching the source. Branches are deleted automatically when their time to live ends.

clibash
# From the linked project (aura link), 72 hours by default
aura branch create feat/new-checkout

# From another project, kept 7 days
aura branch create pr-142 --from my-app --ttl 7d

# Schema only: no row is copied, sequences start over
aura branch create schema-test --no-data

aura branch list                    # the branches of the linked project
aura branch list --all              # every branch of the organization
aura branch delete feat/new-checkout

aura branch create waits until the branch is ready, then prints its URL and its API keys, shown only once like those of aura projects create (--json prints them for scripts). Use --no-wait to return at once and follow it with aura branch list. A branch is a project: link a folder to it with aura link --project-id <id> and run aura db push there to try a migration.

What a branch is, exactly

A branch is a copy made at creation time, not a live replica and not a copy-on-write clone: nothing flows back to the source or from it afterwards. The platform reads the source in one consistent snapshot and copies the rows into the branch database, so the time is proportional to the data. On the local test stack, a 333 MB table of 350,000 rows was cloned in 14 seconds. A migration that works on the branch is then applied to production with the usual aura db push.

Limits, in full#

Who can createMembers with the developer role or more, from a PostgreSQL project that is active and not hibernated. A MongoDB project is refused.
Branching a branchRefused: create the branch from its parent project.
NameLetters, digits, ., _, - and /, up to 63 characters, unique per project among the live branches (case insensitive).
Time to live72 hours by default, from 1 hour to 30 days (--ttl 1h to --ttl 30d). The expired branch and its database are deleted automatically, within about a minute of the deadline. You can delete it earlier.
Plan limitA branch does not count against your project limit (max_projects); it has its own limit of active branches per organization (max_branches): 1 on Free, 10 on Pro, 25 on Team. Past it, creation is refused with BRANCH_LIMIT_REACHED. A failed branch does not count. See limits.
Data sizeThe rows are streamed, not held in memory, so there is no 32 MiB ceiling. Cloning is refused, in a few seconds, when the tables hold more than the limit of the deployment (2 GiB by default, BRANCH_CLONE_MAX_BYTES when you host Aurabase): the message gives the size and suggests --no-data. A clone also stops after 30 minutes.

What is not cloned#

  • Cloned: tables and their rows, column types, defaults, identity columns, sequences and their current value, constraints, indexes, row level security (enabled, forced, policies), SQL functions and procedures, triggers, views and materialized views, enum types, and the privileges on all of them.
  • Not cloned: auth users, sessions and auth settings; storage buckets and objects; edge functions, secrets, environment variables and cron jobs; realtime table settings (re-enable them on the branch); table and column comments, including @graphql directives; column-level privileges; the pg_graphql activation (aura projects graphql-enable on the branch). Objects are owned by the branch's admin role.
  • Refused (the branch would be incomplete): partitioned and inherited tables, foreign tables, domains, composite and range types, aggregate functions, rewrite rules, foreign keys that point to another schema, and extensions other than those the platform installs in every project.

A branch is created from the schema as it is read just before the copy. Do not change the schema of the source (aura db push, DDL) while a branch is being created.

When creation fails#

Nothing is left behind. The copy runs in a single transaction on the branch database; on any failure it is rolled back, the branch project is deleted, and aura branch create prints the reason (for example the object that cannot be cloned). The failed branch stays visible in aura branch list for 24 hours with its message, and its name is free again. If the database service restarts in the middle of a copy, the branch is declared failed and deleted after 45 minutes.

Three integrations ready#

The CLI works with any CI. Here are the recipes for the three most common.

.github/workflows/deploy.ymlyaml
name: Deploy to Aurabase
on:
  push: { branches: [main] }

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @aurabase/cli   # or download the binary from the release page
      - run: aura login --token ${{ secrets.AURA_PAT }}   # Personal Access Token aura_pat_*
      - run: aura link ${{ vars.AURA_PROJECT_ID }}
      - run: aura db push
      - run: aura deploy functions

Link one project per environment (a staging project and a production project) and run the same pipeline against each. There is no --env flag: the target is the project the folder is linked to.

Atomic, via down migration#

Each 20260415_xxx.sql migration can have a 20260415_xxx.down.sql file next to it. aura db migration down [n] runs the .down.sql of the last n applied migrations, newest first, and removes them from the history; the command checks the server's answer and fails if nothing was reverted. A migration without a .down.sql is only removed from the history, and the CLI says so.

rollbackbash
# Revert the last applied migration (runs its .down.sql)
aura db migration down

# Revert the last three
aura db migration down 3

# Fix the history without touching the schema (a migration applied by hand, a failed one)
aura db migration repair 20260415120000_add_devices_table.sql --applied

# A failed migration is cancelled in its own transaction: nothing to revert.
# Point-in-time recovery of a whole database goes through backups (aura db backup restore <id> --yes)
Attention

Point-in-time recovery has no self-service command yet. For a restore you drive yourself, use the snapshots of aura db backup create / aura db backup restore <id> --yes; the restore overwrites the database, so take a fresh backup first.

To go further#