migratex 1.0.0

package/README.md

@@ -0,0 +1,188 @@
+# migratex
+
+a schema diff and migration engine that sits on top of your ORM. it treats database changes like a graph — not a numbered list — enabling deterministic migrations, drift detection, and safe CI/CD workflows.
+
+works with **drizzle**, **prisma**, and **typeorm**. supports **postgres** (mysql coming soon).
+
+## why
+
+every ORM handles migrations the same way: numbered files in a folder. `001_create_users.sql`, `002_add_posts.sql`, and so on. works fine solo. put a team on it and two devs on different branches will both create `004_*.sql`, someone has to manually rename theirs, and you pray the SQL doesn't conflict. at scale this is a constant source of broken deploys, merge pain, and wasted time.
+
+migratex fixes this by replacing linear migrations with a DAG (like git uses for commits) and auto-generating the SQL from your ORM schema.
+
+## features
+
+### auto-generated migrations
+stop writing SQL by hand. migratex reads your ORM schema, introspects the database, diffs them, and generates `up.sql` and `down.sql` automatically. change your schema file, run one command, done.
+
+> **the problem this solves:** hand-written migrations drift from the ORM schema over time. someone forgets to add an index in the migration that they added in the schema. or the migration SQL has a typo that doesn't match what the ORM expects. migratex eliminates this entire class of bugs.
+
+### DAG-based migration graph
+migrations are nodes in a graph with content-addressed IDs (SHA-256 hashes), not numbered files. two branches can create migrations independently and merge cleanly — no renaming, no ordering conflicts.
+
+> **the problem this solves:** on any team with parallel feature branches, linear migrations constantly collide. devs waste time renaming files, resolving fake conflicts, and coordinating who gets the next number. the DAG makes this a non-issue.
+
+### conflict detection
+migratex understands the schema semantically. if two branches add a `status` column to the same table with different types, it tells you. if they touch different tables, it merges cleanly. real conflicts get caught, false positives don't.
+
+> **the problem this solves:** with linear migrations, you only find out about real schema conflicts when the migration runs (or worse, in production). migratex catches them at merge time, before anything touches the database.
+
+### drift detection
+compares your ORM schema against the actual database. catches out-of-band changes — someone ran `ALTER TABLE` directly on prod at 2am, or a migration was applied manually and never committed.
+
+> **the problem this solves:** shadow changes to the database that nobody knows about until something breaks. "it works on my machine" but prod has an extra column nobody added through migrations.
+
+### CI-friendly
+`migratex check` validates the migration graph and detects drift. drop it in your pipeline — it exits non-zero if anything is wrong.
+
+> **the problem this solves:** broken migrations making it to production because there's no automated gate. migratex check catches graph issues, missing parents, cycles, and schema drift before deploy.
+
+### advisory locking
+`migratex apply` uses database advisory locks. safe to run from multiple instances — no double-applying, no race conditions.
+
+### up and down migrations
+every migration automatically gets a reverse. rollbacks are generated, not hand-written.
+
+## install
+
+```bash
+npm install migratex
+```
+
+## quickstart
+
+### init
+
+```bash
+$ migratex init
+
+? ORM: drizzle
+? Dialect: pg
+? Schema path: ./src/schema.ts
+? Connection: postgresql://user:pass@localhost:5432/mydb
+? Migrations dir: ./migrations
+
+Created migratex.config.yaml
+Created migrations/
+```
+
+### generate
+
+change your ORM schema, then:
+
+```bash
+$ migratex generate -m "add users table"
+
+Reading ORM schema...
+Introspecting database...
+Computing diff...
+
+Found 2 change(s):
+  create_table users
+  create_index users_email_idx
+
+Generated migration: a1b2c3d4e5f6
+  migrations/a1b2c3d4e5f6/up.sql
+  migrations/a1b2c3d4e5f6/down.sql
+  Description: add users table
+```
+
+### apply
+
+```bash
+$ migratex apply
+
+Loading migration graph...
+Acquiring lock...
+Applying a1b2c3d4e5f6 — add users table... done
+Releasing lock...
+
+1 migration applied.
+```
+
+### check
+
+```bash
+$ migratex check
+
+Validating migration graph... ok
+Checking for drift... ok
+No issues found.
+```
+
+or when something is wrong:
+
+```bash
+$ migratex check
+
+Validating migration graph... ok
+Checking for drift... DRIFT DETECTED
+
+  Table "users":
+    - Column "phone" exists in database but not in ORM schema
+    - Column "email" has type "text" in database but "varchar(255)" in ORM schema
+
+1 table has drifted from the expected schema.
+```
+
+### status
+
+```bash
+$ migratex status
+
+Migration graph:
+  a1b2c3d4 — create users table        [applied]
+  d4e5f6a7 — add posts table           [applied]
+  g7h8i9j0 — add sessions table        [pending]
+
+Heads: g7h8i9j0
+Applied: 2 | Pending: 1
+```
+
+## how it works
+
+```
+your ORM schema (TypeScript)
+        |
+        v
+  sidecar extracts it as JSON
+        |
+        v
+  go core diffs it against the actual DB
+        |
+        v
+  generates migration SQL (up + down)
+        |
+        v
+  stores it as a DAG node in migrations/
+```
+
+```
+migrations/
+  graph.json                    # lightweight index (heads, metadata)
+  a1b2c3d4e5f6/
+    migration.json              # full node (parents, operations, checksums)
+    up.sql                      # apply
+    down.sql                    # revert
+```
+
+each migration node has:
+- **content-addressed ID** — SHA-256 of (parent IDs + operations), truncated to 12 hex chars
+- **parent pointers** — like git commits, can have multiple parents for merges
+- **checksum** — SHA-256 of the up SQL, detects tampering
+- **operations** — structured diff, so conflicts can be detected semantically
+
+## config
+
+```yaml
+# migratex.config.yaml
+orm: drizzle          # drizzle | prisma | typeorm
+dialect: pg           # pg | mysql
+connection: postgresql://user:pass@localhost:5432/mydb
+schemaPath: ./src/schema.ts
+migrationsDir: ./migrations
+```
+
+## license
+
+MIT

package/bin/migratex.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+const { execFileSync } = require("child_process");
+const path = require("path");
+const os = require("os");
+const fs = require("fs");
+
+function getBinaryPath() {
+  const platform = os.platform();
+  const arch = os.arch();
+
+  const platformMap = {
+    darwin: "darwin",
+    linux: "linux",
+    win32: "windows",
+  };
+
+  const archMap = {
+    x64: "amd64",
+    arm64: "arm64",
+  };
+
+  const goPlatform = platformMap[platform];
+  const goArch = archMap[arch];
+
+  if (!goPlatform || !goArch) {
+    console.error(`Unsupported platform: ${platform}-${arch}`);
+    process.exit(1);
+  }
+
+  const ext = platform === "win32" ? ".exe" : "";
+  const binaryName = `migratex-${goPlatform}-${goArch}${ext}`;
+  const binaryPath = path.join(__dirname, "..", "bin", binaryName);
+
+  if (!fs.existsSync(binaryPath)) {
+    console.error(
+      `Binary not found: ${binaryPath}\nRun "npm run postinstall" or reinstall the package.`
+    );
+    process.exit(1);
+  }
+
+  return binaryPath;
+}
+
+const binary = getBinaryPath();
+
+try {
+  execFileSync(binary, process.argv.slice(2), { stdio: "inherit" });
+} catch (err) {
+  if (err.status !== undefined) {
+    process.exit(err.status);
+  }
+  throw err;
+}

package/install.js

@@ -0,0 +1,88 @@
+const https = require("https");
+const http = require("http");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const platformMap = {
+  darwin: "darwin",
+  linux: "linux",
+  win32: "windows",
+};
+
+const archMap = {
+  x64: "amd64",
+  arm64: "arm64",
+};
+
+const platform = platformMap[os.platform()];
+const arch = archMap[os.arch()];
+
+if (!platform || !arch) {
+  console.error(`Unsupported platform: ${os.platform()}-${os.arch()}`);
+  process.exit(1);
+}
+
+const pkg = require("./package.json");
+const version = pkg.version;
+const ext = os.platform() === "win32" ? ".exe" : "";
+const binaryName = `migratex-${platform}-${arch}${ext}`;
+
+const repo = "Vswaroop04/migrion";
+const url = `https://github.com/${repo}/releases/download/v${version}/${binaryName}`;
+
+const dest = path.join(__dirname, "bin", binaryName);
+
+// Skip download if binary already exists (e.g. CI pre-packed it)
+if (fs.existsSync(dest)) {
+  console.log(`migratex binary already exists at ${dest}`);
+  process.exit(0);
+}
+
+console.log(`Downloading migratex v${version} for ${platform}-${arch}...`);
+console.log(`  ${url}`);
+
+function download(url, dest, redirects = 0) {
+  if (redirects > 5) {
+    console.error("Too many redirects");
+    process.exit(1);
+  }
+
+  const client = url.startsWith("https") ? https : http;
+
+  client
+    .get(url, (res) => {
+      // Follow redirects (GitHub releases redirect to S3)
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        return download(res.headers.location, dest, redirects + 1);
+      }
+
+      if (res.statusCode !== 200) {
+        console.error(`Failed to download: HTTP ${res.statusCode}`);
+        console.error(`URL: ${url}`);
+        console.error(
+          `\nMake sure a GitHub release exists for v${version} with the binary "${binaryName}".`
+        );
+        process.exit(1);
+      }
+
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      const file = fs.createWriteStream(dest);
+      res.pipe(file);
+
+      file.on("finish", () => {
+        file.close();
+        // Make binary executable on unix
+        if (os.platform() !== "win32") {
+          fs.chmodSync(dest, 0o755);
+        }
+        console.log(`migratex installed successfully.`);
+      });
+    })
+    .on("error", (err) => {
+      console.error(`Download failed: ${err.message}`);
+      process.exit(1);
+    });
+}
+
+download(url, dest);

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "migratex",
+  "version": "1.0.0",
+  "description": "Schema diff and migration engine for ORMs (Drizzle, Prisma, TypeORM)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Vswaroop04/migrion"
+  },
+  "bin": {
+    "migratex": "bin/migratex.js"
+  },
+  "scripts": {
+    "postinstall": "node install.js"
+  },
+  "files": [
+    "bin/migratex.js",
+    "install.js"
+  ],
+  "keywords": [
+    "migrations",
+    "schema",
+    "database",
+    "orm",
+    "drizzle",
+    "prisma",
+    "typeorm",
+    "postgresql",
+    "mysql",
+    "dag"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}