8.4k

Migrate from Neon to Xata

Learn how to migrate your Neon PostgreSQL database to Xata using xata clone. Step-by-step instructions for leveraging Neon's branching features.

Prerequisites

  • Neon PostgreSQL project
  • Access to Neon Console
  • Xata account and project setup
  • Network access to your Neon database

About Neon and Xata

Both Neon and Xata offer PostgreSQL branching capabilities, but they serve different purposes:

  • Neon: Serverless PostgreSQL with branching for development
  • Xata: PostgreSQL with branching for production workflows and data operations

Migrating from Neon to Xata allows you to:

  • Use Neon branches as staging data for Xata production
  • Leverage Xata's advanced data operations and branching workflows
  • Take advantage of Xata's deployment flexibility (SaaS or BYOC)

Create Snapshot User

Connect to your Neon database and create a dedicated user for migration:

-- Create snapshot user (no REPLICATION privilege needed)
CREATE USER xata_snapshot WITH LOGIN PASSWORD 'your_secure_password';

-- Grant necessary privileges
GRANT SELECT ON ALL TABLES IN SCHEMA public TO xata_snapshot;
GRANT USAGE ON SCHEMA public TO xata_snapshot;

-- Grant privileges on future tables
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO xata_snapshot;

Get Connection String

Find Your Connection Details

  1. Go to Neon Console → Your Project
  2. Click on your database branch
  3. Copy the connection string from the "Connection Details" section

Connection String Format

Neon connection strings typically look like this:

postgresql://xata_snapshot:your_password@ep-cool-name-123456.us-east-2.aws.neon.tech/neondb?sslmode=require

Branch-Specific Connection

If you want to clone from a specific Neon branch:

  1. Create or select a branch in Neon Console
  2. Use that branch's connection string
  3. The clone will copy that branch's data

Initialize Xata Project

Set up your Xata project configuration:

xata init

Configure the Migration

Set up your clone configuration with optional anonymization:

# Set your source URL
export XATA_CLI_SOURCE_POSTGRES_URL="postgresql://xata_snapshot:your_password@ep-cool-name-123456.us-east-2.aws.neon.tech/neondb?sslmode=require"

# Configure anonymization rules
xata clone config --source-url $XATA_CLI_SOURCE_POSTGRES_URL --mode prompt

Start the Migration

Begin the data transfer:

# Start the migration
xata clone start --source-url $XATA_CLI_SOURCE_POSTGRES_URL

Monitor Progress

Check the migration status:

xata clone status

Verification

After migration, verify your data:

  1. Connect to Xata Branch:

    xata branch url

  2. Check Data Integrity:

    -- Compare row counts
SELECT COUNT(*) FROM your_table;

-- Check sample data
SELECT * FROM your_table LIMIT 10;

  3. Test Relationships: Verify foreign key relationships work correctly

Neon Branching Strategy

Option 1: Clone Production Branch

Clone your Neon production branch to Xata:

# Use production branch connection string
export XATA_CLI_SOURCE_POSTGRES_URL="postgresql://xata_snapshot:password@ep-prod-branch.us-east-2.aws.neon.tech/neondb?sslmode=require"
xata clone start --source-url $XATA_CLI_SOURCE_POSTGRES_URL

Option 2: Clone Development Branch

Clone a Neon development branch for testing:

# Use development branch connection string
export XATA_CLI_SOURCE_POSTGRES_URL="postgresql://xata_snapshot:password@ep-dev-branch.us-east-2.aws.neon.tech/neondb?sslmode=require"
xata clone start --source-url $XATA_CLI_SOURCE_POSTGRES_URL

Option 3: Continuous Sync from Production

Keep Xata in sync with Neon production:

# Set up continuous sync
xata clone start --source-url $XATA_CLI_SOURCE_POSTGRES_URL --continuous

Troubleshooting

Common Issues

  1. Connection Issues:

    • Check that SSL is enabled (sslmode=require)
    • Verify the connection string format
    • Ensure the user has correct privileges

  2. Permission Denied:

    • Verify the snapshot user has correct privileges
    • Check that the user has sufficient permissions

  3. Branch Not Found:

    • Ensure you're using the correct branch connection string
    • Verify the branch exists in Neon Console

SSL Configuration

Neon requires SSL. Always include SSL parameters:

postgresql://user:password@host/database?sslmode=require

Migration Strategies

Strategy 1: One-Time Migration

For complete migration from Neon to Xata:

  1. Clone production data to Xata
  2. Update application to use Xata connection
  3. Verify functionality with Xata
  4. Decommission Neon when ready

Strategy 2: Hybrid Approach

Keep both systems during transition:

  1. Clone Neon to Xata for development
  2. Use Xata for new features
  3. Gradually migrate existing features
  4. Maintain sync during transition

Strategy 3: Staging Workflow

Use Neon for development, Xata for production:

  1. Develop on Neon branches
  2. Clone to Xata for staging
  3. Deploy from Xata to production
  4. Use Xata branching for production workflows

Next Steps