universal-db-switcher

A universal database switching and migration tool that supports MongoDB, MySQL, PostgreSQL, and SQLite.

Features

• Switch between MongoDB, MySQL, PostgreSQL, and SQLite
• Extract schema from source database
• Convert schema to target database format
• Migrate data with configurable batch size
• CLI tool for command-line migrations

v2.0 Enterprise Features

• Relationship Detection – Automatically detect foreign keys using field name heuristics (userId → users.id)
• Join Table Generation – Convert arrays of objects into normalized SQL join tables
• Index Migration – Migrate MongoDB indexes to SQL indexes
• Constraint Mapping – Map required fields → NOT NULL, unique → UNIQUE constraints
• Incremental Migration – Migrate only new/updated records since last sync
• Live Sync Mode – Keep source and target databases synchronized in real-time

v1.1 Enhancements

• Nested Object Flattening – MongoDB nested objects → flat SQL columns (profile.age → profile_age)
• Array Handling – Arrays stored as JSON in SQL (JSON type when supported, else TEXT)
• Schema Detection – Scans first 100 documents to detect all possible fields
• Improved Type Mapping – Mongo types mapped to appropriate SQL (BIGINT, DOUBLE, JSON, etc.)
• Data Transformation Pipeline – Flatten + array serialization before insertion
• Report Generator – Migration reports with statistics

Installation

npm install universal-db-switcher

Quick Start

Programmatic API

import { switchDB } from 'universal-db-switcher';

const result = await switchDB(
  {
    type: 'mongodb',
    host: 'localhost',
    port: 27017,
    database: 'mydb',
  },
  {
    type: 'mysql',
    host: 'localhost',
    port: 3306,
    database: 'mydb',
    username: 'root',
    password: 'secret',
  },
  { batchSize: 1000 }
);

console.log(result.success ? 'Migration complete!' : result.error);

CLI

# Migrate from MySQL to MongoDB
npx udb-switch migrate -s mysql -t mongodb \
  --source-uri "mysql://user:pass@localhost/sourcedb" \
  --target-uri "mongodb://localhost:27017/targetdb"

# Extract schema only (no data)
npx udb-switch migrate -s mysql -t mongodb --schema-only \
  --source-uri "mysql://user:pass@localhost/db" \
  --target-uri "mongodb://localhost/db"

# Extract schema to file
npx udb-switch schema -t mysql --uri "mysql://user:pass@localhost/db" -o schema.json

# Migrate from MongoDB to MySQL (with flatten + array→JSON transform)
npx udb-switch migrate -s mongodb -t mysql --report \
  --source-uri "mongodb://localhost:27017/source" \
  --target-uri "mysql://root:pass@localhost/target"

# Incremental migration (only new records)
npx udb-switch migrate -s mongodb -t mysql --incremental \
  --change-field "updatedAt" \
  --last-sync "2024-01-01T00:00:00Z"

Supported Databases

| Database | Status | |-----------|-----------| | MongoDB | ✅ Supported | | MySQL | ✅ Supported | | PostgreSQL| 🔜 Planned | | SQLite | 🔜 Planned |

API Reference

switchDB(sourceConfig, targetConfig, options?)

Migrates data from source to target database.

Options:

• batchSize - Batch size for migration (default: 1000)
• schemaOnly - Only extract schema, don't migrate data
• skipSchemaCreation - Skip table creation
• skipTransformation - Disable flatten/array transform
• detectRelationships - Detect foreign keys (default: true)
• generateJoinTables - Convert arrays to join tables (default: true)
• migrateIndexes - Migrate indexes (default: true)
• applyConstraints - Apply NOT NULL/UNIQUE (default: true)
• incremental - Only migrate new/updated records
• changeField - Field to track for incremental migration
• lastSyncTimestamp - Timestamp for incremental migration
• tables - Filter specific tables/collections

SyncEngine

Keep databases synchronized in real-time:

import { SyncEngine } from 'universal-db-switch';

const sync = new SyncEngine(sourceAdapter, targetAdapter, 'mongodb', 'mysql', {
  interval: 5000, // Poll every 5 seconds
  changeField: 'updatedAt',
});

await sync.start();
// ... later
sync.stop();
const status = sync.getStatus();

detectRelationships(schema, options?)

Detect foreign key relationships using heuristics.

generateJoinTables(parentTable, arrayFields)

Generate join table schemas from array fields.

convertMongoIndexes(mongoIndexes, tableName)

Convert MongoDB indexes to SQL index definitions.

mapConstraints(sourceSchema, targetType)

Map MongoDB constraints to SQL constraints.

extractSchema(config)

Extracts schema from a database. For MongoDB, scans first 100 documents.

transformDocuments(docs, options?)

Transformation pipeline: flatten nested objects, convert arrays to JSON.

detectSchema(documents, options?)

Detect schema from document sample. Options: sampleSize (default 100), separator.

generateReport(result, options?)

Generate migration report from MigrationResult.

createAdapter(config)

Creates a database adapter instance.

License

MIT