{"id":50470424,"url":"https://github.com/adepanges/schema-diff","last_synced_at":"2026-06-01T10:02:21.880Z","repository":{"id":341411852,"uuid":"1037519549","full_name":"adepanges/schema-diff","owner":"adepanges","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-16T17:06:07.000Z","size":419,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-17T01:53:25.190Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adepanges.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-13T17:39:44.000Z","updated_at":"2026-03-16T17:06:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/adepanges/schema-diff","commit_stats":null,"previous_names":["adepanges/schema-diff"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/adepanges/schema-diff","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adepanges%2Fschema-diff","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adepanges%2Fschema-diff/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adepanges%2Fschema-diff/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adepanges%2Fschema-diff/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adepanges","download_url":"https://codeload.github.com/adepanges/schema-diff/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adepanges%2Fschema-diff/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33769492,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-01T10:02:20.779Z","updated_at":"2026-06-01T10:02:21.871Z","avatar_url":"https://github.com/adepanges.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# schema-diff \n\n**`schema-diff `** is a GitHub Action (and CLI) that detects database schema changes across any migration tool, spins up a local database, and produces a **comprehensive, human-readable diff report**.\n\n\u003e 🔍 Stop guessing what your migration does. See exactly what changed, in every PR.\n\n---\n\n## ✨ Features\n\n- 🔌 **Migration-tool agnostic** — works with any tool (Flyway, Liquibase, db-migrate, Alembic, raw SQL, custom scripts, etc.)\n- 🗄️ **Multi-database support** — PostgreSQL, MySQL, SQLite, and more\n- 📐 **DBML-powered diffing** — schema is parsed into DBML for clean, structured comparison\n- 📊 **Rich diff reports** — added/removed/modified tables, columns, indexes, constraints, and foreign keys\n- 🐳 **Ephemeral local DB** — launches a temporary containerized database, runs your migrations, then dumps the schema\n- 💬 **PR-ready comments** — automatically posts a formatted diff summary as a GitHub PR comment\n- 🗂️ **Schema snapshots** — saves DBML and SQL dumps so you can track schema history over time\n\n---\n\n## 🔄 How It Works\n\n```\nMigration Files\n      │\n      ▼\n Local DB (Docker)   ← spun up automatically\n      │\n      ▼ (run migrations)\n  Schema Dump\n      │\n      ├──► SQL Dump       (for archiving / version control)\n      ├──► DBML Schema    (structured, human-readable)\n      │\n      ▼\n  DBML Diff vs. baseline\n      │\n      ▼\n  Diff Report           → PR Comment / CI Artifact / CLI Output\n```\n\n1. **Launch** — schema-diff  starts a temporary local database using Docker\n2. **Migrate** — runs your migration command (you provide it)\n3. **Dump** — exports the resulting schema as SQL and DBML\n4. **Diff** — compares DBML snapshots between the current branch and the baseline (e.g., `main`)\n5. **Report** — generates a structured, readable change report\n\n---\n\n## 🚀 Quick Start\n\n### GitHub Action\n\n```yaml\n# .github/workflows/schema-check.yml\nname: Schema Drift Check\n\non:\n  pull_request:\n    paths:\n      - 'migrations/**'\n\njobs:\n  schema-diff:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n\n      - name: Run schema-diff \n        uses: your-org/schema-diff @v1\n        with:\n          db-engine: postgres\n          db-version: \"15\"\n          migrate-command: \"npx db-migrate up\"\n          migrations-path: ./migrations\n          baseline-branch: main\n          post-pr-comment: true\n```\n\n### CLI\n\n```bash\n# Install\nnpm install -g schema-diff \n\n# Run against your local migration setup\nschema-diff  diff \\\n  --db-engine postgres \\\n  --migrate-command \"flyway migrate\" \\\n  --migrations-path ./db/migrations \\\n  --baseline ./snapshots/main.dbml\n```\n\n---\n\n## ⚙️ Configuration\n\n### GitHub Action Inputs\n\n| Input | Required | Default | Description |\n|-------|----------|---------|-------------|\n| `db-engine` | ✅ | — | Database engine: `postgres`, `mysql`, `sqlite` |\n| `db-version` | ❌ | `latest` | Version of the DB Docker image |\n| `migrate-command` | ✅ | — | Shell command to run your migrations |\n| `migrations-path` | ❌ | `./migrations` | Path to your migration files |\n| `baseline-branch` | ❌ | `main` | Branch to compare against |\n| `post-pr-comment` | ❌ | `true` | Post diff as a PR comment |\n| `output-dbml` | ❌ | `true` | Save DBML snapshot as artifact |\n| `output-sql-dump` | ❌ | `false` | Save SQL dump as artifact |\n| `fail-on-destructive` | ❌ | `false` | Fail CI if destructive changes are detected |\n\n### CLI Options\n\n```\nschema-diff  diff [options]\n\nOptions:\n  --db-engine \u003cengine\u003e         postgres | mysql | sqlite\n  --db-version \u003cversion\u003e       Docker image version (default: latest)\n  --migrate-command \u003ccmd\u003e      Migration command to run\n  --migrations-path \u003cpath\u003e     Path to migration files\n  --baseline \u003cfile\u003e            Baseline DBML file to diff against\n  --output-dir \u003cpath\u003e          Directory to write outputs (default: .schema-diff )\n  --format \u003cformat\u003e            Report format: text | markdown | json\n  --fail-on-destructive        Exit 1 if destructive changes found\n```\n\n---\n\n## 📋 Example Report\n\nWhen schema-diff  detects changes, it posts a report like this to your PR:\n\n---\n\n### 🔍 Schema Drift Detected — `migrations/V3__add_payments.sql`\n\n| | Summary |\n|--|---------|\n| ✅ Added | 2 tables, 1 index |\n| ✏️ Modified | 1 table (3 columns changed) |\n| ❌ Removed | 0 |\n| ⚠️ Destructive | 1 warning |\n\n#### ✅ New Tables\n\n```dbml\nTable payments {\n  id uuid [pk]\n  user_id uuid [ref: \u003e users.id]\n  amount decimal(10,2) [not null]\n  status varchar(50) [default: 'pending']\n  created_at timestamp [default: `now()`]\n}\n\nTable payment_methods {\n  id uuid [pk]\n  user_id uuid [ref: \u003e users.id]\n  provider varchar(100)\n  token text\n}\n```\n\n#### ✏️ Modified: `users`\n\n```diff\n  Table users {\n    id uuid [pk]\n    email varchar(255)\n+   stripe_customer_id varchar(255)\n+   payment_verified boolean [default: false]\n-   legacy_billing_id int\n  }\n```\n\n\u003e ⚠️ **Destructive change detected:** Column `legacy_billing_id` removed from `users`. Ensure data has been migrated before deploying.\n\n---\n\n## 🗄️ Supported Databases\n\n| Database | Status |\n|----------|--------|\n| PostgreSQL | ✅ Supported |\n| MySQL / MariaDB | ✅ Supported |\n| SQLite | ✅ Supported |\n| MongoDB | 🗓️ Planned |\n| MSSQL | 🗓️ Planned |\n\n---\n\n## 🔌 Migration Tool Compatibility\n\nschema-diff  does **not** depend on any specific migration tool. You provide the command, schema-diff  runs it.\n\n| Tool | Example `migrate-command` |\n|------|--------------------------|\n| Flyway | `flyway migrate` |\n| Liquibase | `liquibase update` |\n| Alembic | `alembic upgrade head` |\n| db-migrate | `npx db-migrate up` |\n| Prisma | `npx prisma migrate deploy` |\n| golang-migrate | `migrate -path ./migrations -database $DB_URL up` |\n| Raw SQL | `psql $DB_URL -f ./schema.sql` |\n| Custom script | `./scripts/run_migrations.sh` |\n\n---\n\n## 📦 Outputs \u0026 Artifacts\n\nAfter each run, schema-diff  produces:\n\n```\n.schema-diff /\n├── current.dbml          # DBML schema of current branch\n├── baseline.dbml         # DBML schema of baseline branch\n├── diff.md               # Human-readable diff report (Markdown)\n├── diff.json             # Machine-readable diff (for automation)\n└── dump.sql              # Full SQL schema dump (optional)\n```\n\nThese are automatically uploaded as GitHub Actions artifacts and can also be committed to your repo for schema version tracking.\n\n---\n\n## 📅 Roadmap\n\n- ✅ PostgreSQL support\n- ✅ MySQL / SQLite support  \n- ✅ DBML-based diffing\n- ✅ Automatic PR comments\n- ✅ Rich diff reports with severity classification (info / warning / danger)\n- ✅ Collapsible per-table sections and adaptive PR comment sizing\n- 🔜 DBML visualization (schema diagram in PR comment)\n- 🔜 MongoDB support\n- 🔜 Slack / Teams notifications\n- 🔜 Schema registry / history dashboard\n- 🔜 Custom diff rules (e.g., allow column additions, block column drops)\n\n### Planned DDL Object Support\n\n- [x] Tables, columns, indexes, foreign keys, constraints\n- [x] Functions \u0026 stored procedures\n- [ ] Views\n- [ ] Triggers\n- [ ] Enums \u0026 custom types\n- [ ] Sequences\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.\n\n```bash\ngit clone https://github.com/your-org/schema-diff \ncd schema-diff \nnpm install\nnpm test\n```\n\n---\n\n## 📄 License\n\nMIT © [Your Name](https://github.com/your-org)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadepanges%2Fschema-diff","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadepanges%2Fschema-diff","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadepanges%2Fschema-diff/lists"}