# Migrate from Better Auth

The [Clerk CLI](https://clerk.com/docs/cli.md) exports your users from your Better Auth database with `clerk migrate export betterauth`, then creates them in Clerk with `clerk migrate import`.

Better Auth has no fixed schema. The columns on the `user` table depend on which plugins you enabled, so the export checks which columns exist before it queries the table.

## 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 Better Auth database

The export reads two tables: `user` and `account`, or `users` and `accounts` if you set Better Auth's `usePlural` option. It detects camelCase and snake\_case column names. The database role needs `SELECT` on both tables.

## What migrates

- **Supported password hashes:** Better Auth hashes with its own scrypt by default, and lets an app swap in bcrypt or argon2, so one database can hold more than one kind. The import detects the hasher per user:

  | Stored value                                                                                    | Imported as                                                       |
  | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
  | `<32 hex>:<128 hex>`, Better Auth's scrypt                                                      | `scrypt_werkzeug`                                                 |
  | A well-formed `$2a$`, `$2b$`, or `$2y$` digest, with a cost from 4 to 15                        | `bcrypt`                                                          |
  | A well-formed `$argon2id$v=19$…` or `$argon2i$v=19$…` digest, within Clerk's argon2 cost limits | `argon2id` or `argon2i`                                           |
  | Anything else                                                                                   | The import omits the hash and creates the user without a password |

  Better Auth normalizes a password to Unicode Normalization Form KC (NFKC) before hashing it, and Clerk doesn't. A password containing characters that NFKC changes, such as some accented or full-width characters, won't verify in Clerk, and that user has to reset it.
- **OAuth-only users:** The import creates these users without credentials.
- **Unverified emails and phones:** They stay unverified by default. `emailVerified` is a boolean here. The import keeps an address Better Auth never confirmed off the primary fields and attaches it as unverified. The checks reject a user whose only email is unverified when your instance requires an email. The same applies to `phoneNumberVerified`. 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).
- **Active bans:** The import applies the admin plugin's `banned` flag when it's `true` and `banExpires` hasn't passed. 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.
- **Names:** The source splits `name` into `firstName` and `lastName` at the first whitespace. It uses a one-word name as the first name, and leaves out a one-word name that matches the user's own email address.
- **Better Auth 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).

## What doesn't migrate

- **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).
- **Plugin columns without Clerk equivalents:** The export reads `displayUsername`, `role`, `banReason`, and `twoFactorEnabled`, but the import omits them, and the checks list them under `Clerk won't store`, with `displayUsername` as `display_username`. If you need them, put them in metadata with a [custom source](https://clerk.com/docs/guides/development/migrating/custom-source.md). A custom source replaces the built-in mapping, so it also has to handle the password hashers, verification, bans, and anonymous users itself.
- **Multi-factor authentication (MFA) enrollments:** Users must enroll again in Clerk.

1. ## Export your users from Better Auth

   **MySQL**

   Run the export, and enter your MySQL connection string, `mysql://<user>:<password>@<host>:3306/<database>`, when the CLI asks:

   filename: terminal

   ```sh
   clerk migrate export betterauth
   ```

   The database role also needs to read `information_schema.columns` so the export can detect plugin columns.

   **Postgres**

   Run the export, and enter your Postgres connection string, `postgres://<user>:<password>@<host>:5432/<database>`, when the CLI asks:

   filename: terminal

   ```sh
   clerk migrate export betterauth
   ```

   **SQLite**

   Pass a SQLite file path. It must start with `file:` or `./`, or end in `.sqlite`, `.sqlite3`, or `.db`. The connection needs `PRAGMA` access so the export can detect plugin columns:

   filename: terminal

   ```sh
   clerk migrate export betterauth --db-url "./db.sqlite"
   ```

   **Turso**

   Pass your Turso database's `libsql://` URL. Supply its token through `TURSO_AUTH_TOKEN` or `LIBSQL_AUTH_TOKEN`, or include it in the URL's `?authToken=` parameter:

   filename: terminal

   ```sh
   clerk migrate export betterauth --db-url "libsql://<database>-<org>.turso.io"
   ```

   Without `--db-url`, the CLI reads `BETTERAUTH_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 run reports which plugin columns it found:

   ```text
   Detected plugin columns: username, displayUsername, phoneNumber, phoneNumberVerified.
   ```

   The columns it looks for are the ones Better Auth plugins add: `username` and `displayUsername` (username plugin), `phoneNumber` and `phoneNumberVerified` (phone-number plugin), `role`, `banned`, `banReason`, and `banExpires` (admin plugin), `twoFactorEnabled` (two-factor plugin), and `isAnonymous` (anonymous plugin). The export leaves absent columns out of the query. With none of them, the run says "No plugin columns detected" and exports the core user fields.

   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 verified email
     ! 341/412 have a password hash
     ! 400/412 have a name
     ! 96/412 have a username
     ✗ 0/412 have a phone number
   ```

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

   Better Auth stores the password digest on the `account` row for the `credential` provider, not on the user, so the export joins the two.

   The export includes users without password accounts, such as users who sign in through OAuth, magic links, or passkeys. They don't count toward password coverage.

   A user can have more than one credential account. When those accounts hold different password hashes, the export can't tell which one is current, so it exports that user without a password and warns you. To bring the password, keep one credential account per user in Better Auth and export again.
3. ## Import your users into Clerk

   The import skips the anonymous plugin's guest accounts and records them as `skipped`. They don't require `--allow-partial`.

   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.
4. ## 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 user who had a password, and one who only ever used OAuth.

## 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)
