Understanding Auth Migration

This document explains the technical principles behind authentication migration in LobeHub. It's intended for users with database and development experience who want to understand how migration works under the hood.

<Callout type={'info'}> For step-by-step migration instructions, see NextAuth Migration or Clerk Migration. </Callout>

Core Database Schema

Understanding the database schema is essential for troubleshooting migration issues.

Users Table

The users table is auth-framework agnostic - it's a generic user table that works with any authentication system. Each record represents a unique user identity with associated profile information.

Key fields:

Accounts Table

The accounts table stores authentication provider connections. Different SSO providers and email/password authentication are all treated as separate "accounts" linked to a user.

Examples of accounts:

• Google SSO login
• GitHub SSO login
• Email/password credential
• Auth0 (even if using Google login through Auth0, it's a separate account from direct Google SSO)

Relationship: One user can have multiple accounts (1:N relationship).

┌─────────────────┐         ┌─────────────────┐
│     users       │         │    accounts     │
├─────────────────┤         ├─────────────────┤
│ id (PK)         │◄───────┤│ user_id (FK)    │
│ email (unique)  │         │ provider        │
│ avatar          │         │ provider_id     │
│ ...             │         │ ...             │
└─────────────────┘         └─────────────────┘
                                    │
                            ┌───────┴───────┐
                            │               │
                    ┌───────▼──┐     ┌──────▼───┐
                    │ Google   │     │ GitHub   │
                    │ Account  │     │ Account  │
                    └──────────┘     └──────────┘

Migration Principles

<Callout type={'warning'}> Migration does not preserve login sessions. Users must log in again after migration. </Callout>

Simple Migration

Simple migration only migrates the users table and ignores the accounts table.

How it works:

1. User logs in with email/password or SSO after migration
2. Better Auth checks if the email exists in the users table
3. If found, the user is linked to their existing data
4. A new account record is created in the accounts table

Why it works:

When you reset password or login with SSO, if the email returned by the provider matches an existing email in the users table, the system links you to that existing user.

Limitation:

Without migrating the accounts table, the system doesn't know about previously linked accounts.

Example scenario:

• Before migration: User has Google ([email protected]) and Microsoft ([email protected]) linked to the same user
• users table stores primary email: [email protected]
• After simple migration:
  • Login with [email protected] → ✅ Links to existing user
  • Login with [email protected] → ❌ Creates a new user (no account record linking [email protected] to the original user)

Full Migration

Full migration transfers account data from the previous auth system to Better Auth's accounts table.

Data migrated:

• NextAuth: nextauth_accounts table → Better Auth accounts table
• Clerk: External accounts from Clerk API → Better Auth accounts table

Result:

All previously linked accounts continue to work. Login with [email protected] will correctly link to the existing user.

Troubleshooting

Problem: Login Creates a New User Instead of Linking to Existing Data

This typically happens with simple migration when logging in with a secondary email.

Diagnosis steps:

1. Find your original user record

   Query the users table to find your original user by primary email:

   sqlCopy

   SELECT id, email FROM users WHERE email = '[email protected]';
   

   Note the id value.

2. Check accounts linked to this user

   Query the accounts table using the user ID:

   sqlCopy

   SELECT * FROM accounts WHERE user_id = 'your-user-id';
   

3. Find the incorrectly created account

   If you logged in with a secondary email and it created a new user, find that account:

   sqlCopy

   SELECT * FROM accounts WHERE provider_account_id = '[email protected]';
   -- or for SSO providers, search by the provider's user ID
   

Fix:

1. Delete the incorrectly created account record:

   sqlCopy

   DELETE FROM accounts WHERE id = 'incorrect-account-id';
   

2. If a new user was created, you may also need to delete it:

   sqlCopy

   DELETE FROM users WHERE id = 'new-user-id';
   

3. Log in using your primary email (the one stored in the users table)

4. After logging in, go to Settings → Profile → Linked Accounts to re-link your secondary accounts

Problem: SSO Login Doesn't Work After Migration

Check:

1. Ensure the SSO provider is configured in AUTH_SSO_PROVIDERS

2. Verify the provider credentials (AUTH_<PROVIDER>_ID, AUTH_<PROVIDER>_SECRET)

3. For full migration, verify account records were created correctly:

   sqlCopy

   SELECT * FROM accounts WHERE provider = 'google';  -- or your provider
   

Problem: Can't Find My Original User Data

Check:

1. Verify the email you're using matches the one in the users table

2. Check if you might have used a different email or SSO provider originally

3. Query the database directly to find users matching your criteria:

   sqlCopy

   SELECT * FROM users WHERE email LIKE '%your-domain.com';
   

Related Reading

<Card href={'/docs/self-hosting/migration/v2/auth/clerk-to-betterauth'} title={'Clerk Migration Guide'} />

<Card href={'/docs/self-hosting/auth'} title={'Authentication Configuration'} /> </Cards>