🛰️ sync-solution

sync-solution is an npm package that synchronizes PostgreSQL schema changes (DDL) across multiple databases using RabbitMQ.

It automatically:

• Listens for schema changes in your master database
• Stores changes as versioned migration files
• Publishes migrations via RabbitMQ
• Applies migrations to your remote databases

This ensures all databases stay in sync — reliably and asynchronously.

✨ Features

• 🔍 Detects DDL changes in PostgreSQL automatically
• 📂 Saves migrations in db/migrations/*.sql
• 📤 Publishes schema changes to RabbitMQ queues
• 📥 Consumes and applies migrations on multiple remote databases
• 🔄 Retry-safe: failed migrations remain in the queue until successful
• 🚀 One command runs everything (listener, producer, consumers)
• 🛠️ Configurable via sync-solution.config.js

📦 Installation

Global install (inside a project):

npm install sync-solution

Run with:

npx sync-solution

⚙️ Configuration

Create a file called sync-solution.config.js in your project root:

// sync-solution.config.js
export default {
  rabbitmqUrl: "amqp://localhost",

  masterDb: {
    nickname: "masterDB",
    user: "postgres",
    host: "127.0.0.1",
    database: "main_db",
    password: "password",
    port: 5432
  },

  remoteDbs: [
    {
      nickname: "replica1",
      user: "postgres",
      host: "127.0.0.1",
      database: "replica_db1",
      password: "password",
      port: 5432
    },
    {
      nickname: "replica2",
      user: "postgres",
      host: "127.0.0.1",
      database: "replica_db2",
      password: "password",
      port: 5432
    }
  ],

  // Base queue name (one queue per remote DB will be created)
  queueName: "ddl_sync"
};

🚀 Usage

Start sync services (listener + producer + consumers):

sync-solution

That’s it! 🎉

• Any schema changes in your master DB will be captured.
• Migration files will be saved under db/migrations/.
• Changes will be queued in RabbitMQ.
• Remote DBs will apply them automatically.

🏗️ How It Works

          ┌───────────────┐
          │   Master DB   │
          │ (LISTEN DDL)  │
          └───────┬───────┘
                  │
        [listener + producer]
                  │
                  ▼
          ┌───────────────┐
          │   RabbitMQ    │
          │ (queues)      │
          └───────┬───────┘
          ┌───────┴───────┐
          ▼               ▼
   [consumer DB1]    [consumer DB2]
   (apply DDL)       (apply DDL)

📂 Project Structure

If you install locally, you’ll see something like this:

bin/
  sync-solution.js   # CLI entry point
src/
  db/                # database connection & setup
  helpers/           # helper functions
  listener.js        # listens for schema changes
  queue/             # producer & consumer
  configLoader.js    # loads sync-solution.config.js
  index.js           # unified runner

Migrations will be generated in your project under:

db/migrations/
  2025-08-05T12-34-56_create_table_users.sql
  2025-08-05T12-35-10_alter_table_orders.sql

🧪 Example

1. Start PostgreSQL and RabbitMQ locally
2. Create sync-solution.config.js
3. Run:

sync-solution

4. In your master DB, run:

CREATE TABLE test_sync (id SERIAL PRIMARY KEY, name TEXT);

5. You’ll see:

[Server] Listening for schema changes...
[DDL] Change detected: CREATE TABLE test_sync ...
[Producer] Enqueued migration → replica1
[Producer] Enqueued migration → replica2
[Consumer:replica1] Applied migration ✔
[Consumer:replica2] Applied migration ✔

6. Both remote DBs now have the new table 🎉

🛠️ Development

Clone and link globally for testing:

git clone https://github.com/your-username/sync-solution.git
cd sync-solution
npm install
npm link

Now you can run:

sync-solution

🐞 Troubleshooting

• Error: Missing sync-solution.config.js → Make sure the config file exists in your project root.

• Consumers stuck, migrations not applied → Check if RabbitMQ is running and reachable.

• Migration fails on remote DB → The migration stays in queue until fixed. Review logs and apply manually if needed.

🤝 Contributing

1. Fork this repo
2. Create a feature branch
3. Commit your changes
4. Open a Pull Request

📜 License

MIT © Yazan I. Alfarra