# Migrate from Supabase

The [Clerk CLI](https://clerk.com/docs/cli.md) exports your users from the `auth.users` table in your Supabase Postgres database with `clerk migrate export supabase`, then creates them in Clerk with `clerk migrate import`.

The export reads the database, not Supabase's Admin API, because `encrypted_password` exists only in the table. The password digests come across, so your users keep the passwords they already have.

## Migrate with an AI agent

If you work with an AI coding agent, the [`clerk-migrate` skill](https://clerk.com/docs/guides/ai/skills.md) can run your migration for you with the Clerk CLI. Install Clerk's skills:

filename: terminal
```sh
npx skills add clerk/skills
```

Then ask your agent to migrate your users to Clerk. The skill exports your users, runs a dry run against your instance, and shows you what it found. It imports only after you approve.

## What you need

Install the [Clerk CLI](https://clerk.com/docs/cli.md), sign in, and link the project directory you'll run the migration from to the Clerk application you're importing into:

filename: terminal
```sh
npm install -g clerk
clerk auth login
clerk link
```

To skip `clerk auth login` and `clerk link`, set `CLERK_SECRET_KEY` to the Secret Key of the instance you're importing into, or pass it with `--secret-key`.

To skip the global install, replace `clerk` with `npx clerk@latest` in each command. To update an existing install, run `clerk update`.

`import` and `undo` target the linked application's development instance by default. Pass `--instance prod` or a full instance ID to choose another. With a Secret Key, the key picks the instance, so pass the production instance's key to import into production. For other ways to pick the instance and Secret Key, see [choose the destination instance](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#choose-the-destination-instance).

The CLI stores each run in `.clerk/migrate/<run_id>/` and adds `.clerk/` to `.gitignore`. To store runs elsewhere, see [command behavior](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#command-behavior).

> New development instances have a [limit of 100 users](https://clerk.com/docs/guides/development/managing-environments.md). Production instances have no user limit. Before creating users, the import checks a development instance's count against its limit and rejects the users past it. To rehearse with a larger export, import into development with `--allow-partial`, check the result, undo the run, then import everyone into production. See [instance user limits](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#instance-user-limits) for the commands, overrides, and fallback behavior.

### A connection string for your Supabase database

1. In the [Supabase dashboard](https://supabase.com/dashboard), open your project and select **Connect**.
2. Copy the **Session pooler** connection string.
3. Substitute your database password into it.

> Use the pooler string. Supabase's direct connections are IPv6-only unless you've bought the IPv4 add-on, so a direct string typically fails to connect from a laptop or a build server.

Connect as the `postgres` role. An application role usually can't read the `auth` schema, and the export needs to.

## What migrates

- **Supported password hashes:** Supabase hashes with bcrypt by default, and accepts argon2 hashes from its own imports, so the `supabase` source detects the hasher per user: `bcrypt`, `argon2id`, or `argon2i`. The source omits a hash Clerk can't verify, such as one from another hasher or a bcrypt hash with a cost above 15, and the checks warn that the user will import without a password.
- **Unverified emails and phones:** They stay unverified by default. Supabase records verification as a timestamp that stays null until the user confirms. The import attaches an email with no `email_confirmed_at` as unverified and keeps it off the primary fields. The same applies to `phone_confirmed_at`. The checks reject a user whose only email is unverified when your instance requires an email. To reserve those unverified addresses instead, see [unverified emails and phones](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#unverified-emails-and-phones).
- **Names from metadata:** `auth.users` has no name columns. The name lives in `raw_user_meta_data` under whichever key the provider used. The source uses `first_name` and `last_name` as they are. When there's no first name, the `supabase` source splits `display_name`, `full_name`, or `name`, in that order, into first and last name.
- **Discord names:** The source removes a trailing `#` and digits from names such as `name#0` because Clerk interprets that suffix as a URL.
- **Phone numbers:** Supabase stores phone numbers in [E.164](https://www.itu.int/rec/T-REC-E.164/en), the international telephone numbering standard, without the leading `+`. The source adds the `+` Clerk requires.
- **Active bans:** The import bans a user whose `banned_until` is still in the future. Clerk's bans have no end date, so a temporary ban stays until you lift it in Clerk, and the checks warn you about it.
- **Supabase IDs:** Each user's `id` becomes the Clerk user's `external_id`, which is how a re-run recognizes the users it already created. To keep referencing it in your app, see [foreign keys](https://clerk.com/docs/guides/development/migrating/plan-your-migration.md#foreign-keys).
- **User metadata:** `raw_user_meta_data` becomes `unsafeMetadata`. Your users could edit it in Supabase, and they can still edit it in Clerk. Don't trust it on the server.
- **Signup dates:** The import keeps the date from `created_at`.

## What doesn't migrate

- **Multi-factor authentication (MFA) enrollments:** Users must enroll again in Clerk.
- **App metadata:** The import omits `raw_app_meta_data`.
- **Social accounts:** Enable the same providers on the [**SSO connections**](https://dashboard.clerk.com/~/user-authentication/sso-connections) page in the Clerk Dashboard. When a user signs in with one, Clerk links it to their imported account by verified email address. Clerk doesn't link to an address the import attached as unverified, so that sign-in creates a separate user. To link those users, import with `--reserve-unverified`. If you reserve the address and the provider doesn't confirm it, Clerk asks the user to verify it before linking. See [account linking](https://clerk.com/docs/guides/configure/auth-strategies/social-connections/account-linking.md).

1. ## Export your users from Supabase

   Run the export, and enter your connection string, `postgresql://postgres.<project_ref>:<password>@<pooler_host>:5432/postgres`, when the CLI asks:

   filename: terminal

   ```sh
   clerk migrate export supabase
   ```

   Without `--db-url`, the CLI reads `SUPABASE_DB_URL`, then prompts for it. The prompt masks what you type, and a value entered at a prompt stays out of your shell history. If the database rejects the connection string, the prompt explains why and asks again. With `--yes`, `--json`, in an agent run, or without a terminal, the export doesn't prompt, and fails if the connection string is missing or rejected.

   The export saves your users as `export.json` in a new run, and prints the run ID and a field coverage table:

   ```text
   Field coverage
     ✓ 412/412 have an email address
     ! 388/412 have a confirmed email
     ! 341/412 have a password hash
     ✗ 0/412 have a phone number
     ! 260/412 have a first name
     ! 120/412 have a last name
   ```

   Pass `-o <path>` to write the file somewhere else. The path has to end in `.json`.

   If the password hash row is far below the user count, most of your users signed up through a social provider rather than with a password. Before importing, review the [social provider requirements](#users-whose-only-social-provider-is-disabled-in-clerk).
2. ### If the connection fails

   The CLI adds troubleshooting guidance below the database error:

   | What you see                            | What to check                                                                                                   |
   | --------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
   | Could not reach the database            | The host and port. Use the pooler connection string, or enable the IPv4 add-on under **Settings** > **Add-Ons** |
   | The database rejected those credentials | The user and password in the connection string                                                                  |
   | The `auth.users` table was not readable | That Supabase Auth is enabled, and that you're connecting as `postgres` rather than an application role         |

   A password containing characters such as `@`, `#`, or `/` usually doesn't need URL-encoding: the CLI encodes a password it can't otherwise parse. If the connection still fails, URL-encode the password. Connection strings are redacted in every error message, including when the password itself contains an unencoded `@`.
3. ### Import an `auth.users` file you already have

   The `supabase` source also reads a JSON or CSV export of `auth.users` that you made yourself, such as from the SQL editor. A file you wrote doesn't name its source, so pass `--source supabase`:

   filename: terminal

   ```sh
   clerk migrate import <path> --source supabase --dry-run
   ```

   Include `encrypted_password` to keep passwords, and `raw_app_meta_data` for the [social provider check](#users-whose-only-social-provider-is-disabled-in-clerk). Without `raw_app_meta_data`, that check doesn't run.
4. ## Import your users into Clerk
5. ### Soft-deleted and anonymous users

   The source skips soft-deleted (`deleted_at`) and anonymous (`is_anonymous`) users. The import records them as `skipped` and continues without requiring `--allow-partial`.
6. ### Users whose only social provider is disabled in Clerk

   If Discord is disabled in Clerk, a user who signed in only with Discord needs another enabled sign-in method. The checks reject users who have none.

   The checks read each user's `raw_app_meta_data.providers` and compare it against the social providers your destination instance has enabled. A user passes if any of these is true:

   - One of their providers is enabled in Clerk, or is Supabase's own `email` or `phone` provider.
   - They have a verified email and the instance signs in by email code or email link, or a verified phone and the instance signs in by SMS code. An unverified email or phone counts only if you [reserve it](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#unverified-emails-and-phones) with `--reserve-unverified` or answer yes to the reservation prompt. A dry run doesn't ask, so it counts them only when you pass the flag. An email Clerk refuses, such as one with a `.local` domain, doesn't count.
   - Supabase recorded no providers for them.

   The checks reject everyone else, naming each provider as either "not enabled in Clerk" or "not offered by Clerk". Enable the missing [social connections](https://clerk.com/docs/guides/configure/auth-strategies/social-connections/overview.md) in Clerk and run the checks again. Providers Clerk doesn't offer can't be enabled, so to leave those users behind, pass `--allow-partial`. The import records them as `skipped`.

   The CLI still warns about providers that are disabled or unavailable in Clerk, even when their users have another valid sign-in method.

   Check the export against your Clerk instance first. A dry run writes nothing and skips the import's consent, legal acceptance, and reservation questions, so add `--skip-legal-checks` to preview importing users without [legal acceptance](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#legal-acceptance), or `--reserve-unverified` to preview reserving [unverified emails and phones](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#unverified-emails-and-phones):

   filename: terminal

   ```sh
   clerk migrate import <export_run_id> --dry-run
   ```

   The export recorded its source, so the import needs no `--source`. If the checks reject a user, fix the file or instance, or pass `--allow-partial` to import the users that pass. See [check before you import](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#check-before-you-import).

   After the checks pass, rerun the same command with `--yes` instead of `--dry-run`, keeping the input and other flags. Leave off `--yes` to confirm at a prompt.

   Use the import run's ID to check its results or undo it. To [continue an interrupted import](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#continue-an-interrupted-import), run the same command again.
7. ## Verify the migration

   1. Read what the run did. It lists the users that failed or were skipped, and why:

      filename: terminal

      ```sh
      clerk migrate runs <import_run_id>
      ```

   2. Confirm the users exist in Clerk:

      filename: terminal

      ```sh
      clerk users list
      ```

   3. Sign in as one of them with their Supabase password. Only a sign-in confirms the digests came across intact.

## Undo the migration

Preview the users the import created, using the import run's ID:

filename: terminal
```sh
clerk migrate undo <import_run_id> --dry-run
```

Then delete them:

filename: terminal
```sh
clerk migrate undo <import_run_id> --yes
```

`--yes` doesn't delete users who have signed in since the import. Add `--include-signed-in` to authorize those deletions too. Confirming at the interactive prompt also authorizes them.

Pass the same `--instance`, `--app`, or `--secret-key` you gave the import. See [undo an import](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#undo-an-import) for confirmation rules, refusal conditions, and retries.

## Next steps

- [Foreign keys](https://clerk.com/docs/guides/development/migrating/plan-your-migration.md#foreign-keys): Keep referencing your users by the IDs they had before the migration.
- [How the CLI migrates users](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md): Learn how the CLI checks users, continues an interrupted import, and undoes one.
- [Account linking](https://clerk.com/docs/guides/configure/auth-strategies/social-connections/account-linking.md): Learn how Clerk links a social sign-in to an imported user.

---

## Sitemap

[Overview of all docs pages](https://clerk.com/docs/llms.txt)
