{"id":47693501,"url":"https://github.com/fanduzi/deltascope","last_synced_at":"2026-05-31T07:01:34.922Z","repository":{"id":346813555,"uuid":"1186456839","full_name":"Fanduzi/DeltaScope","owner":"Fanduzi","description":"Offline-first SQL audit engine and MCP SQL audit server for MySQL, TiDB, and PostgreSQL DDL/DML changes.","archived":false,"fork":false,"pushed_at":"2026-05-24T08:43:31.000Z","size":5103,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T10:27:00.353Z","etag":null,"topics":["ai-sql-review","ci-cd","cli","database","database-tools","ddl-review","devops","dml-safety","mcp","mcp-server","migration-safety","mysql","mysql-tools","postgresql","postgresql-tools","sql-audit","sql-lint","sql-review","tidb"],"latest_commit_sha":null,"homepage":"https://deltascope.pages.dev/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Fanduzi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-19T16:37:55.000Z","updated_at":"2026-05-24T08:43:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Fanduzi/DeltaScope","commit_stats":null,"previous_names":["fanduzi/deltascope"],"tags_count":83,"template":false,"template_full_name":null,"purl":"pkg:github/Fanduzi/DeltaScope","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fanduzi%2FDeltaScope","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fanduzi%2FDeltaScope/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fanduzi%2FDeltaScope/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fanduzi%2FDeltaScope/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Fanduzi","download_url":"https://codeload.github.com/Fanduzi/DeltaScope/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fanduzi%2FDeltaScope/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33722156,"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-05-31T02:00:06.040Z","response_time":95,"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":["ai-sql-review","ci-cd","cli","database","database-tools","ddl-review","devops","dml-safety","mcp","mcp-server","migration-safety","mysql","mysql-tools","postgresql","postgresql-tools","sql-audit","sql-lint","sql-review","tidb"],"created_at":"2026-04-02T16:05:27.688Z","updated_at":"2026-05-31T07:01:34.916Z","avatar_url":"https://github.com/Fanduzi.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# DeltaScope\n\n[![Release](https://img.shields.io/github/v/release/Fanduzi/DeltaScope?display_name=tag)](https://github.com/Fanduzi/DeltaScope/releases)\n![Platform](https://img.shields.io/badge/platform-darwin%20%7C%20linux-blue)\n![Go Version](https://img.shields.io/badge/go-1.26.1-00ADD8?logo=go)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n\n[![English](https://img.shields.io/badge/docs-English-blue)](README.md) [![简体中文](https://img.shields.io/badge/docs-简体中文-yellow)](README_ZH.md)\n\n[![Changelog](https://img.shields.io/badge/Changelog-informational)](CHANGELOG.md) [![Security](https://img.shields.io/badge/Security-important)](SECURITY.md) [![License](https://img.shields.io/badge/License-blue)](LICENSE) [![Release Notes](https://img.shields.io/badge/Release_Notes-success)](docs/releases/README.md)\n\u003c/div\u003e\n\nDeltaScope is an offline-first SQL audit and migration risk checker for MySQL, TiDB, and PostgreSQL DDL/DML changes. The main product surfaces are `deltascope`, `deltascope-server`, and `deltascope-mcp`; PostgreSQL offline support is converged on the main archives for supported macOS and Linux platforms. It gives DBAs, application engineers, CI pipelines, and AI agents one consistent way to review DDL and DML before they reach a database.\n\n**Search-focused pages:**\n- [MySQL DDL audit tool](https://deltascope.pages.dev/en/mysql-ddl-audit-tool) — catch risky MySQL schema changes\n- [PostgreSQL DDL audit tool](https://deltascope.pages.dev/en/postgresql-ddl-audit-tool) — review PostgreSQL schema changes and DCL\n- [SQL migration risk checker](https://deltascope.pages.dev/en/sql-migration-risk-checker) — CI and AI workflow integration\n\n## Install\n\nFor macOS, prefer Homebrew. The repository installer script remains available as the generic portable installer for environments where Homebrew is not the right fit.\n\n**macOS (recommended):**\n\n```bash\nbrew tap Fanduzi/deltascope\nbrew install --cask deltascope\n```\n\n**Generic installer:**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/Fanduzi/DeltaScope/main/install.sh | sh\n```\n\nPin a specific release:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/Fanduzi/DeltaScope/v0.240.0/install.sh | \\\n  DELTASCOPE_VERSION=v0.240.0 sh\n```\n\n### Dialects \u0026 Release Archives\n\nEvery tag publishes archives named `deltascope_\u003cversion\u003e_\u003cos\u003e_\u003carch\u003e.tar.gz` containing `deltascope`, `deltascope-server`, and `deltascope-mcp`. All archives support MySQL, TiDB, and PostgreSQL offline audit via `--dialect mysql|tidb|postgresql`. The installer script, Homebrew Cask, and npm MCP launcher all resolve platform-specific archives from GitHub Release assets. See the [audit capability matrix](docs/reference/audit-capability-matrix.md) for per-dialect coverage and [release notes](docs/releases/README.md) for version-by-version changes.\n\n## Quick Start\n\nAudit a risky DML statement:\n\n```bash\ndeltascope audit --sql \"delete from users\"\n```\n\nExample excerpt:\n\n```text\nVerdict: reject\nStatements: 1\nBlockers: 1\nWarnings: 0\nNotices: 0\n\nStatement 1: DELETE\n- [blocker] dml.where.require: UPDATE and DELETE statements must include a WHERE clause\n```\n\nAudit a `CREATE TABLE` statement:\n\n```bash\ndeltascope audit --sql \"create table tbl_users (id bigint unsigned not null auto_increment comment 'id', created_at datetime not null default current_timestamp comment 'created', updated_at datetime not null default current_timestamp on update current_timestamp comment 'updated', primary key (id)) comment='users' engine=InnoDB default charset=utf8mb4\"\n```\n\nExample excerpt:\n\n```text\nVerdict: review\nStatements: 1\nBlockers: 0\nWarnings: 1\nNotices: 0\n\nStatement 1: CREATE TABLE\n- [warning] ddl.column.default.require: column \"id\" should define a default value\n```\n\nAudit a file:\n\n```bash\ndeltascope audit --file ./migrations/20260328_add_column.sql\n```\n\nUse JSON output for CI or agents:\n\n```bash\ndeltascope audit \\\n  --sql \"create table tbl_users (id bigint unsigned not null auto_increment comment 'id', created_at datetime not null default current_timestamp comment 'created', updated_at datetime not null default current_timestamp on update current_timestamp comment 'updated', primary key (id)) comment='users' engine=InnoDB default charset=utf8mb4\" \\\n  --format json \\\n  --fail-on warning\n```\n\nExample JSON shape:\n\n```json\n{\n  \"verdict\": \"review\",\n  \"summary\": {\n    \"statements\": 1,\n    \"blockers\": 0,\n    \"warnings\": 1,\n    \"notices\": 0\n  },\n  \"statements\": [ ... ],\n  \"context\": {\n    \"mode\": \"offline\",\n    \"dialect\": \"mysql\",\n    \"dialect_source\": \"default\"\n  }\n}\n```\n\nAudit a TiDB statement:\n\n```bash\ndeltascope audit --dialect tidb --sql \"alter table users add column email varchar(255) not null\"\n```\n\nAudit a PostgreSQL `CREATE TABLE` with constraints:\n\n```bash\ndeltascope audit \\\n  --dialect postgresql \\\n  --sql \"create table orders (id bigint primary key, user_id bigint references users(id), amount numeric not null check (amount \u003e= 0))\"\n```\n\nWhen SQL looks like PostgreSQL but the dialect is set to MySQL, DeltaScope emits an advisory notice without auto-switching:\n\n```bash\ndeltascope audit --sql \"insert into users(id) values (1) returning id;\"\n```\n\nTo audit PostgreSQL SQL explicitly:\n\n```bash\ndeltascope audit --dialect postgresql --sql \"insert into users(id) values (1) returning id;\"\n```\n\nGenerate SARIF output for GitHub Code Scanning:\n\n```bash\ndeltascope audit --file ./migrations.sql --format sarif \u003e deltascope.sarif\n```\n\nUse CI-native output with any dialect:\n\n```bash\ndeltascope audit --dialect postgresql --file ./migrations/20260409_add_index.sql --format github-actions\n```\n\nFor GitLab CI, use `--format gitlab-codequality` and publish `gl-code-quality-report.json` as a Code Quality artifact; see [use-deltascope-in-gitlab-ci.md](docs/recipe/use-deltascope-in-gitlab-ci.md).\n\n## DML Impact Estimation\n\nFor a selective DML such as `DELETE FROM users WHERE id = 42`, DeltaScope may add an `impact` object to the statement result. The object is conservative by design and reports `estimated_rows`, `estimated_ratio`, `risk_level`, `confidence`, `source`, `reason_codes`, and optional `notes`.\n\n```json\n{\n  \"raw_sql\": \"DELETE FROM users WHERE id = 42\",\n  \"impact\": {\n    \"estimated_rows\": 1,\n    \"estimated_ratio\": 0.0001,\n    \"risk_level\": \"low\",\n    \"confidence\": \"high\",\n    \"source\": \"metadata\",\n    \"reason_codes\": [\"pk_equality\"],\n    \"notes\": [\"refined with table statistics\"]\n  }\n}\n```\n\nOffline mode uses SQL shape only. Metadata-aware mode may refine the estimate with read-only table statistics. DeltaScope does not execute the DML and does not run `EXPLAIN ANALYZE`.\n\nAudit with live metadata (instance-aware rules):\n\n```bash\ndeltascope audit \\\n  --sql \"alter table orders add index idx_status (status)\" \\\n  --host 127.0.0.1 --port 3306 --user root --ask-password --schema app\n```\n\nMetadata-aware audit with an explicit connect timeout (MySQL):\n\n```bash\ndeltascope audit \\\n  --sql \"alter table users add column email varchar(255)\" \\\n  --dialect mysql \\\n  --host 127.0.0.1 --port 3306 --user root --ask-password --schema app \\\n  --metadata-connect-timeout 5s\n```\n\nMetadata-aware audit with PostgreSQL:\n\n```bash\ndeltascope audit \\\n  --sql \"alter table orders add column status text not null\" \\\n  --dialect postgresql \\\n  --host 127.0.0.1 --port 5432 --user root --ask-password --schema app \\\n  --metadata-connect-timeout 5s\n```\n\nSee all shipped rules:\n\n```bash\ndeltascope rules\n```\n\n## Why DeltaScope\n\nSQL mistakes are cheap to catch before they run and expensive after. DeltaScope gives you one consistent engine across local dev, CI, HTTP service, and MCP so the same policy applies everywhere — no per-tool rule duplication, no dialect surprises.\n\n## Key Features\n\n- Create-table governance across identifiers, comments, primary keys, audit columns, charset/collation, indexes, and table options.\n- Alter-table governance for destructive actions, compatibility checks, existence validation, and merge guidance.\n- Object-lifecycle checks for `CREATE VIEW`, `DROP TABLE`, `TRUNCATE TABLE`, and database/schema lifecycle DDL across MySQL, TiDB, and PostgreSQL.\n- DML protections for `WHERE`, `LIMIT`, `ORDER BY`, subqueries, join conditions, bulk insert patterns, denylisted objects, and conservative affected-row impact estimation.\n- Stable product surfaces: `deltascope` CLI, `deltascope-server`, `deltascope-mcp`, and `pkg/deltascope`.\n- `deltascope-mcp` is the official MCP stdio server and exposes `audit_sql`, `describe_rule`, `list_rules`, and `get_capabilities`.\n- CI outputs preserve source file path and statement-start line numbers for GitHub Actions, SARIF, and GitLab Code Quality formats.\n\n## MCP Quick Start\n\n\u003e **No install required.** The npm launcher fetches and runs the correct `deltascope-mcp` binary for your platform automatically.\n\nLauncher requirements:\n\n- Node.js 24 or newer\n- supported native targets: `darwin` or `linux`, `amd64` or `arm64`\n\nRecommended launcher:\n\n```bash\nclaude mcp add --scope user deltascope -- npx -y @fanduzi/deltascope-mcp\ncodex mcp add deltascope -- npx -y @fanduzi/deltascope-mcp\n```\n\nFor raw stdio TOML, native `deltascope-mcp`, direct connection, `connection_ref`, proxy setup, and common errors, see [Use DeltaScope MCP](docs/recipe/use-deltascope-mcp.md).\n\n### MCP with runtime config\n\nRun `deltascope-mcp` with runtime config for logging and metadata defaults:\n\n```bash\ndeltascope-mcp -runtime-config /etc/deltascope/runtime.yaml\n```\n\nMCP stdout logging is forbidden to protect the stdio protocol. Runtime config can set `output: file` or `output: stderr`, but not `stdout`.\n\n### MCP named connection with connect timeout\n\n```yaml\n# ~/.config/deltascope/connections.yaml\nconnections:\n  local_mysql:\n    host: 127.0.0.1\n    port: 3306\n    user: root\n    password_env: MYSQL_PASSWORD\n    schema: app\n    dialect: mysql\n    connect_timeout: 5s\n```\n\nBoth named connections and direct connection inputs accept `connect_timeout`. Empty or `0s` falls back to the runtime config default. MySQL, TiDB, and PostgreSQL all support metadata connect timeout.\n\n## AI Agent Skill\n\n\u003e **Works in Claude Code, Codex, Cursor, and 40+ AI coding agents.**\n\u003e Install once, get inline SQL review in every session.\n\nDeltaScope ships a universal AI agent skill for inline SQL review during AI coding sessions. The skill detects whether DeltaScope is installed locally, calls it to audit your SQL, and surfaces findings with fix suggestions — without leaving your AI coding session.\n\n```bash\n# Install via npx skills (Claude Code, Codex, Cursor and 40+ AI agents)\nnpx skills add Fanduzi/DeltaScope --skill deltascope-review -a claude-code\n```\n\nInstall globally (available across all projects):\n\n```bash\nnpx skills add Fanduzi/DeltaScope --skill deltascope-review -a claude-code -g\n```\n\nKeep the skill up to date:\n\n```bash\nnpx skills update\n```\n\nThen invoke in any supported AI session:\n\n```\n/deltascope-review\n```\n\nPaste a SQL snippet or point to a file — the agent audits it with DeltaScope and suggests fixes. See [skills/README.md](skills/README.md) for full setup and usage.\n\n## More Docs\n\n- [Recipes](docs/recipe/README.md)\n- [Dev docs](docs/dev/README.md)\n- [Reference docs](docs/reference/README.md)\n- [Audit SQL with metadata](docs/recipe/audit-sql-with-metadata.md)\n- [Review DDL before migration](docs/recipe/review-ddl-before-migration.md)\n- [Guard DML in CI](docs/recipe/guard-dml-in-ci.md)\n- [Use with AI agents](docs/recipe/use-with-ai-agents.md)\n- [Inspect rules and config](docs/recipe/inspect-rules-and-config.md)\n- [Troubleshoot metadata-aware audit](docs/recipe/troubleshoot-metadata-aware-audit.md)\n\n## Documentation\n\n- [Admin docs](docs/admin/README.md)\n- [Concept docs](docs/concept/README.md)\n- [Dev docs](docs/dev/README.md)\n- [Reference docs](docs/reference/README.md)\n- [Audit capability matrix](docs/reference/audit-capability-matrix.md)\n\n## Developer Workflows\n\n- `make test` runs `go test ./...`\n- `make build` produces all local binaries under `bin/`\n- `make build-linux` produces Linux amd64 binaries under `bin/`\n- `make test-e2e-cli` runs the Docker-backed metadata CLI smoke suite\n- `make pg-unit-test-gates` runs the PostgreSQL-tagged unit gate set\n- `make pg-e2e-gates` runs the Docker-backed PostgreSQL CLI, HTTP, and MCP suites\n- `make pg-confidence-gates` runs the canonical PostgreSQL confidence closure\n- [docs/dev/testing.md](docs/dev/testing.md) covers the full target set\n\n## HTTP Service\n\nRun the HTTP adapter over the same audit engine:\n\n```bash\ndeltascope-server -listen 127.0.0.1:8083\n```\n\nRun with runtime config for logging and metadata defaults:\n\n```bash\ndeltascope-server -listen 127.0.0.1:8083 -runtime-config /etc/deltascope/runtime.yaml\n```\n\nSee [docs/examples/runtime-config.yaml](docs/examples/runtime-config.yaml) for a complete runtime config example.\n\nEndpoints:\n\n- `GET /healthz`\n- `GET /version`\n- `POST /v1/audit`\n\n`POST /v1/audit` supports both offline JSON audit requests and metadata-aware requests with an optional `connection` block. The HTTP response keeps the public audit result body and adds a `context` block. See the full contract in [HTTP API reference](docs/reference/http-api.md).\n\n### HTTP metadata-aware request with connect timeout\n\n```json\n{\n  \"sql\": \"alter table users add column email varchar(255)\",\n  \"dialect\": \"mysql\",\n  \"connection\": {\n    \"host\": \"127.0.0.1\",\n    \"port\": 3306,\n    \"user\": \"root\",\n    \"password_env\": \"MYSQL_PASSWORD\",\n    \"schema\": \"app\",\n    \"connect_timeout\": \"5s\"\n  }\n}\n```\n\nThe `connection.connect_timeout` field accepts Go duration strings (`500ms`, `5s`, `1m`). It overrides the runtime config default. Empty or `0s` falls back to the runtime config default. Invalid or negative values return a `400` error. MySQL, TiDB, and PostgreSQL all support metadata connect timeout.\n\n## Library Usage\n\n```go\nresult, err := deltascope.Audit(ctx, deltascope.Request{\n    SQL:     \"delete from users\",\n    Dialect: deltascope.DialectMySQL,\n})\n```\n\nThe stable public API lives in [pkg/deltascope](pkg/deltascope/README.md).\n\n## Architecture\n\nDeltaScope keeps one audit path and exposes it through multiple entrypoints. Product-level and implementation-level diagrams live in [docs/concept/architecture.md](docs/concept/architecture.md) and [docs/dev/architecture.md](docs/dev/architecture.md).\n\n### Modules\n\n| Module | Description | Doc |\n|--------|-------------|-----|\n| `cmd/deltascope` | CLI process entrypoint | [README](cmd/deltascope/README.md) |\n| `cmd/deltascope-server` | HTTP service entrypoint | [README](cmd/deltascope-server/README.md) |\n| `cmd/deltascope-mcp` | MCP service entrypoint | [README](cmd/deltascope-mcp/README.md) |\n| `internal/interfaces` | Transport adapter namespace | [README](internal/interfaces/README.md) |\n| `internal/interfaces/cli` | CLI adapter layer | [README](internal/interfaces/cli/README.md) |\n| `internal/interfaces/http` | HTTP adapter layer | [README](internal/interfaces/http/README.md) |\n| `internal/interfaces/mcp` | MCP adapter layer | [README](internal/interfaces/mcp/README.md) |\n| `internal/application` | Use-case orchestration layer | [README](internal/application/README.md) |\n| `internal/application/audit` | Application parse/audit orchestration | [README](internal/application/audit/README.md) |\n| `internal/application/auditmeta` | Shared metadata-aware audit preparation | [README](internal/application/auditmeta/README.md) |\n| `internal/application/policy` | Application policy loader | [README](internal/application/policy/README.md) |\n| `internal/domain` | Core domain types and rules | [README](internal/domain/README.md) |\n| `internal/domain/spec` | Normalized statement specifications | [README](internal/domain/spec/README.md) |\n| `internal/domain/rule` | Rule findings and severity model | [README](internal/domain/rule/README.md) |\n| `internal/domain/rule/catalog` | Explanation-oriented shipped rule catalog | [README](internal/domain/rule/catalog/README.md) |\n| `internal/domain/rule/ddl` | DDL rule catalog | [README](internal/domain/rule/ddl/README.md) |\n| `internal/domain/rule/dml` | DML rule catalog | [README](internal/domain/rule/dml/README.md) |\n| `internal/domain/policy` | Policy configuration model | [README](internal/domain/policy/README.md) |\n| `internal/domain/report` | Audit result aggregation and verdicts | [README](internal/domain/report/README.md) |\n| `internal/infrastructure` | Infrastructure adapter layer | [README](internal/infrastructure/README.md) |\n| `internal/infrastructure/parser` | Parser adapter namespace | [README](internal/infrastructure/parser/README.md) |\n| `internal/infrastructure/parser/tidb` | TiDB parser adapter | [README](internal/infrastructure/parser/tidb/README.md) |\n| `internal/infrastructure/config/viper` | YAML config adapter | [README](internal/infrastructure/config/viper/README.md) |\n| `internal/infrastructure/metadata/mysql` | Metadata provider for MySQL/TiDB-compatible engines | [README](internal/infrastructure/metadata/mysql/README.md) |\n| `internal/infrastructure/output` | Output renderer namespace | [README](internal/infrastructure/output/README.md) |\n| `internal/infrastructure/output/markdown` | Markdown renderer | [README](internal/infrastructure/output/markdown/README.md) |\n| `internal/infrastructure/output/json` | JSON renderer | [README](internal/infrastructure/output/json/README.md) |\n| `configs` | Example configuration files | [README](configs/README.md) |\n| `pkg/deltascope` | Stable public package surface | [README](pkg/deltascope/README.md) |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffanduzi%2Fdeltascope","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffanduzi%2Fdeltascope","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffanduzi%2Fdeltascope/lists"}