📖 DigitCave Migration Tool

DigitCave provides a simple and flexible migration runner for managing SQL database schemas across multiple services. This document explains the entry script used to run migrations.

🚀 Entry File: migrate.ts

#!/usr/bin/env ts-node

import dotenv from "dotenv";
dotenv.config();

import { authenticationDB, servicesDB } from "./config/db";
import { Schema } from "./config/migration/Schema";
import { Project } from "./entities/Project";
import { User } from "./entities/User";

export async function migrate() {
  Schema.init({
    dbConnections: {
      default: servicesDB,
      authentication: authenticationDB,
    },
    dialects: {
      default: "mysql",
      authentication: "mysql",
    },
    verbose: true,
    shouldLog: false,
    useBatch: true,
    shouldSyncAll: true,
    schemasWithFlags: [
      { fn: () => User.sync(), shouldSync: true },
      { fn: () => Project.sync(), shouldSync: true },
    ],
  });

  console.log("🚀 Starting schema migrations...");
  await Schema.syncMarkedSchemas();
  console.log("🎉 Migrations finished.");
}

migrate().catch((err) => {
  console.error("❌ Migration failed:", err);
  process.exit(1);
});

⚙️ How it Works

1. Environment Setup Loads database credentials from .env file using dotenv.

2. Database Connections Two connections are configured:

   • servicesDB → The default database
   • authenticationDB → The authentication database

3. Schema Initialization The Schema.init() method configures:

   • Supported connections & dialects
   • Logging preferences (verbose, shouldLog)
   • Migration behavior (useBatch, shouldSyncAll)
   • List of entities/models to sync (schemasWithFlags)

4. Migration Execution

   • Schema.syncMarkedSchemas() runs all models flagged with shouldSync: true.
   • Logs start & finish messages to console.
   • Exits gracefully on error.

📦 Usage

Run Migrations

ts-node migrate.ts

Or, if installed globally / via npx:

digitcave migrate

Example .env file

DB_HOST=localhost
DB_USER=root
DB_PASSWORD=secret
DB_NAME=services
AUTH_DB_NAME=auth

Expected Console Output

🚀 Starting schema migrations...
🎉 Migrations finished.

If something fails:

❌ Migration failed: Error: Connection refused

🏗️ Adding a New Entity

1. Define your entity in ./entities:

export class Product {
  static async sync() {
    console.log("🔄 Syncing Product schema...");
    // schema logic here
  }
}

2. Register it in migrate.ts:

schemasWithFlags: [
  { fn: () => User.sync(), shouldSync: true },
  { fn: () => Project.sync(), shouldSync: true },
  { fn: () => Product.sync(), shouldSync: true },
],

3. Run migration again:

ts-node migrate.ts

🔑 CLI Alias (Optional)

Add a bin entry in package.json to run as a global tool:

"bin": {
  "digitcave": "./migrate.ts"
}

Then:

npm install -g .
digitcave migrate