User Migration Guide

Complete guide to migrating existing users to your subdomain login system with separate databases.

Overview

This guide covers how to migrate existing WordPress users from your main site to your subdomain when both sites use separate databases.

Key Concept: With separate databases, usernames and passwords must match between sites, but user IDs, roles, and metadata can differ.

Understanding the Setup

What Must Match

  • Username - Must be identical (case-sensitive)
  • Password - Must be the same (password hashes should be copied)

What Can Differ

  • User ID - Can be different (plugin uses usernames, not IDs)
  • Roles - Can have different roles on each site
  • User Meta - Can have different metadata
  • Registration Date - Can differ
Example: User "john" can be ID 5 on the main site and ID 12 on the subdomain. The plugin will correctly authenticate "john" regardless of the ID difference.

Prerequisites

Before You Start
  • Backup both databases
  • Have database access credentials
  • Test on staging environment first
  • Document current user counts
Required Tools
  • phpMyAdmin or MySQL command line
  • FTP/SFTP access to both sites
  • Text editor for scripts
  • Spreadsheet software (for CSV method)

Migration Methods

Method Best For Difficulty Time
SQL Direct Export/Import 100+ users, preserves passwords Medium 15-30 minutes
CSV Export/Import <100 users, manual review needed Easy 30-60 minutes
Custom PHP Script Complex requirements, custom logic Advanced 1-2 hours

Method 1: SQL Direct Export/Import

Recommended for 100+ users. Preserves password hashes and user metadata.

Step 1: Export Users from Main Site

-- Export users (replace wp_ with your prefix)
SELECT * FROM wp_users 
WHERE ID > 1  -- Exclude admin if needed
INTO OUTFILE '/tmp/users_export.csv'
FIELDS TERMINATED BY ','
ENCLOSED BY '"'
LINES TERMINATED BY '\n';

Step 2: Import to Subdomain

Use the provided PHP migration script (available in downloads section below).

Important: The migration script handles user ID conflicts automatically by mapping usernames instead of IDs.

Step 3: Verify Migration

-- Check user counts match
SELECT COUNT(*) FROM wp_users;

-- Verify specific user exists
SELECT user_login, user_email FROM wp_users WHERE user_login = 'john';

Method 2: CSV Export/Import

Best for smaller sites (<100 users) or when you need to review data before import.

Step 1: Export Users

  1. Install "Import and export users and customers" plugin on main site
  2. Go to Tools → Export Users
  3. Select all user roles
  4. Include password hashes in export
  5. Download CSV file

Step 2: Review and Clean Data

  • Open CSV in spreadsheet software
  • Remove users you don't want to migrate
  • Verify email addresses are unique
  • Check for any data issues

Step 3: Import to Subdomain

  1. Install same plugin on subdomain
  2. Go to Tools → Import Users
  3. Upload your CSV file
  4. Map columns correctly
  5. Enable "Update existing users"
  6. Click Import

Password Synchronization

Why This Matters: After initial migration, if users change passwords on one site, they won't automatically update on the other site.

Option 1: Copy Password Hashes (Recommended)

During migration, copy the user_pass field from the main site to the subdomain. This preserves existing passwords without requiring users to reset them.

-- Copy password hash for specific user
UPDATE subdomain_wp_users 
SET user_pass = (
    SELECT user_pass FROM main_wp_users 
    WHERE user_login = 'john'
)
WHERE user_login = 'john';

Option 2: Force Password Reset

If you can't copy password hashes, require users to reset passwords on first login.

Option 3: Ongoing Synchronization

For ongoing password sync, consider implementing a custom solution using WordPress hooks to sync password changes between sites via REST API.

Testing & Verification

Pre-Migration Checklist

Post-Migration Testing

  1. Test with 3-5 sample users - Try logging in with different user accounts
  2. Verify user counts - Run SQL query to confirm all users migrated
  3. Check user roles - Ensure roles are assigned correctly
  4. Test password authentication - Confirm passwords work
  5. Test redirect functionality - Verify users land on correct page after login

Verification SQL Queries

-- Count users on main site
SELECT COUNT(*) as main_site_users FROM main_wp_users;

-- Count users on subdomain
SELECT COUNT(*) as subdomain_users FROM subdomain_wp_users;

-- Find users that exist on main but not subdomain
SELECT user_login FROM main_wp_users 
WHERE user_login NOT IN (SELECT user_login FROM subdomain_wp_users);

Troubleshooting Migration Issues

Cause: User already exists on subdomain with same username.

Solutions:
  • Use "Update existing users" option during import
  • Manually delete conflicting users on subdomain first
  • Modify migration script to handle conflicts

Causes:
  • Some users failed to import due to errors
  • Export didn't include all users
  • Import was interrupted
Solutions:
  • Check import logs for error messages
  • Re-run migration for missing users only
  • Use SQL query to find missing users

Causes:
  • Password hashes weren't copied correctly
  • User doesn't exist on subdomain
  • Username mismatch (case sensitivity)
Solutions:
  • Verify user exists with correct username
  • Check password hash was copied
  • Use password reset if needed

Cause: Role metadata wasn't migrated or subdomain uses different role names.

Solutions:
  • Manually assign roles after migration
  • Use bulk role assignment plugin
  • Update wp_usermeta table with correct role data

Migration FAQ

SQL Method: 15-30 minutes for 1000+ users
CSV Method: 30-60 minutes for 100 users
Custom Script: 1-2 hours including setup and testing

Yes! Add a WHERE clause to your SQL export to filter users by role, registration date, or other criteria. For CSV method, simply remove unwanted users from the spreadsheet before import.

Not if you copy password hashes during migration. The SQL and CSV methods both preserve password hashes, so users can log in with their existing passwords immediately.

User metadata (stored in wp_usermeta) can be migrated along with users. The SQL method automatically includes metadata. For CSV method, you'll need to export and import usermeta separately or use a plugin that supports it.

Yes, but use "update existing users" mode to avoid creating duplicates. This is useful for syncing new users or updating existing user data after the initial migration.

It's safer to test on staging first, but yes, you can migrate on a live site. The migration only adds/updates users on the subdomain - it doesn't modify the main site. Always backup both databases before starting.

WordPress requires unique email addresses. If you have duplicate emails, you'll need to either update them before migration or handle the conflict during import by skipping or updating existing users.

Yes, but you'll need to export users from the specific site in your multisite network. Use a plugin or custom SQL query that targets the correct site_id. User roles will need to be mapped from multisite format to single-site format.

Custom fields stored in wp_usermeta will be migrated with the SQL method. For CSV method, you'll need a plugin that supports custom fields or migrate them separately. Make sure both sites have the same custom field definitions.

WooCommerce customer data is stored in wp_usermeta. The SQL method will migrate this automatically. For CSV, use a WooCommerce-specific export/import plugin to preserve customer addresses, order history references, and other WooCommerce metadata.

Downloads

Complete Migration Guide

Full PDF documentation with all methods and examples

Download PDF
Migration Checklist

Printable checklist to track your migration progress

Download Checklist
PHP Migration Script

Production-ready script for SQL direct migration

Download Script

Need Help with Migration?

Contact our support team for assistance with your user migration.

Contact Support
← Back to Documentation