Skip to content
Aurabase Logo
aurabase

Migrate from Supabase

The client API, the RLS policies and the Edge Functions carry over. The CLI exports your Supabase users with their bcrypt password hashes, restores a plain pg_dump (statements, function bodies, COPY data) and imports the users: this page says exactly what each step carries over and where it stops.

How-to guide10 min readLevel intermediateRevised on Nov 10, 2026

95% same as Supabase#

The client API, the RLS policies, the auth model and the storage follow Supabase's conventions, so the application code changes very little. The table below states what is the same and what is not.

FeatureCompatibilityNote
createClient()SameImport @aurabase/aurabase-js instead of @supabase/supabase-js
.from().select()SameSame chainable PostgREST API
RLS policiesSamePostgres SQL policies. to authenticated, to anon and to service_role are accepted as aliases of aura_authenticated, aura_anon and aura_service_role. These roles are created with the project's database cluster; on a cluster created before that change, write the aura_* role names.
auth.uid() and auth.role()SameHelpers compatible claim by claim
auth.getUser()Minor differencedata is the user (data.email); Supabase returns { data: { user } }. Code written as const { data: { user } } = await supabase.auth.getUser() gets user === undefined here: write const { data: user } = await aura.auth.getUser()
.rpc()SameSame signature for Postgres functions
.storage.from().upload()SameS3-compatible API with identical paths
.channel().on("postgres_changes")SameSame change data capture surface
Edge Functions (Deno)SameStandard Deno runtime; Deno.serve() works without rewriting
Auth hooksMinor differenceHTTP webhooks and dedicated endpoints
Service role keySameSame role, same scope

Four commands, in order#

  1. Export — aura migrate export-supabase writes users.json (users, password hashes, OAuth identities) and dump.sql (pg_dump of the public schema, structure and data)
  2. Restore — aura db restore dump.sql replays the dump into the linked project
  3. Import users — aura auth import users.json; users keep their id and their password
  4. Cutover — switch the URL and the keys in your app; deploy your Edge Functions unchanged
terminalbash
# 1. Export from Supabase (Settings > Database > connection string, `postgres` role)
aura migrate export-supabase --db-url "$SUPABASE_DB_URL" --output-dir ./supabase-export

# 2. Restore the schema and the data into the linked Aurabase project
aura link <project>
aura db restore ./supabase-export/dump.sql --dry-run   # parse and print the plan only
aura db restore ./supabase-export/dump.sql

# 3. Import the users, with their password hashes
aura auth import ./supabase-export/users.json

Restore the schema and the data#

aura migrate export-supabase runs pg_dump --schema=public --no-owner --no-acl --format=plain with your local pg_dump (install the PostgreSQL client tools; without them, the command prints the exact pg_dump line to run yourself).

aura db restore <file.sql> reads a plain SQL dump the way psql does: statements are split outside strings, quoted identifiers, comments and dollar-quoted bodies ($$ … $$, $fn$ … $fn$), COPY … FROM stdin blocks are read up to their \. line, and psql meta-commands (\connect, \restrict) are skipped. It then:

  • removes the public. qualifier that pg_dump writes, so tables land in the project schema (--source-schema for another schema);
  • skips what has no meaning on Aurabase and says why: session settings (SET, set_config), OWNER TO, GRANT/REVOKE of the Supabase roles, CREATE EXTENSION (extensions are managed by Aurabase), CREATE SCHEMA public;
  • runs everything else in the order of the file, and stops at the first failing step with its number, its dump line and the error. Fix the cause and resume with --from <step>, or pass --continue-on-error to go past failing steps and get the list at the end. --dry-run prints the plan without executing anything.

Two paths, chosen like aura db push:

Linked project, no DATABASE_URLDATABASE_URL set (direct connection string)
TransportOne SQL API call per statement, validated by the serverOne PostgreSQL connection
COPY dataConverted to INSERT batches (500 rows)COPY protocol, data as dumped
Functions, triggers, DO blocksRefused by the SQL API: create them with aura db function create and aura db trigger createCreated
Safety boundaryThe server's isolation policy for the projectThe project's PostgreSQL role (its own database only, no superuser, Row Level Security applies)

On the SQL API path, the server also refuses E'…' strings, references to other schemas and, in a statement, text that looks like a forbidden command, even inside a string literal: a data row containing such text fails with its step number. Use the direct path for those dumps. The direct connection string is in Settings › Connection when your deployment publishes direct PostgreSQL access.

Restore runs sequentially: a plain SQL dump is ordered (tables, then data, then constraints and indexes) and has no dependency graph to parallelize. No throughput figure is published.

Attention

References to auth.users do not restore as is. Aurabase Auth does not keep its users in an auth.users table, so a foreign key such as REFERENCES auth.users(id) fails. Restore with --continue-on-error and keep the user_id columns without that constraint: the user ids are preserved by the import below, so the values still match.

Users and passwords#

aura migrate export-supabase reads auth.users and auth.identities and writes, for each user: the original id, the email, email_verified, the bcrypt hash of encrypted_password, the name and the metadata (raw_user_meta_data, and raw_app_meta_data without Supabase's own provider/providers keys), and the linked OAuth identities (Google, GitHub…). The file is written readable by you only: it holds password hashes, delete it after the import.

aura auth import users.json sends the users in batches of 1,000 to the admin import API and prints every line that is not created (skipped when the email or the id already exists, error with the reason). Running it again is safe: existing users are never overwritten.

At sign-in, Aurabase Auth verifies the bcrypt hash, then replaces it with an Argon2id hash: your users keep their password and do nothing. The import accepts bcrypt hashes $2a$, $2b$ and $2y$ with a cost from 4 to 12 (Supabase uses 10), and Argon2id hashes with bounded parameters; any other format is refused line by line. OAuth users sign in again with the same provider and land on the same account.

Attention

Not carried over: MFA factors (TOTP, phone), active sessions and refresh tokens (every user signs in once again), bans, phone-only, anonymous and deleted users (counted and reported by the export). Users with MFA must enroll again.

Native Deno — zero rewrites#

Aurabase runs a standard Deno runtime. Your functions using Deno.serve() are 100% compatible without modification:

functions/hello.tstypescript
// Standard Deno function — works as is on Aurabase
Deno.serve(async (req) => {
  const { name } = await req.json()
  return new Response(
    JSON.stringify({ message: `Hello ${name}!` }),
    { headers: { 'content-type': 'application/json' } }
  )
})

To go further#