Deltascope
Launcher package for the DeltaScope MCP stdio server
Ask AI about Deltascope
Powered by Claude ยท Grounded in docs
I know everything about Deltascope. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
DeltaScope is an offline-first SQL audit engine for MySQL, TiDB, and PostgreSQL. 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.
Install
For macOS, prefer Homebrew. The repository installer script remains available as the generic portable installer for environments where Homebrew is not the right fit.
macOS (recommended):
brew tap Fanduzi/deltascope
brew install --cask deltascope
Generic installer:
curl -fsSL https://raw.githubusercontent.com/Fanduzi/DeltaScope/main/install.sh | sh
Pin a specific release:
curl -fsSL https://raw.githubusercontent.com/Fanduzi/DeltaScope/v0.42.0/install.sh | \
DELTASCOPE_VERSION=v0.42.0 sh
PostgreSQL Support
DeltaScope supports PostgreSQL offline audit across CLI, HTTP, MCP, and pkg/deltascope surfaces:
- Primary-key fact support: PostgreSQL
CREATE TABLEinline, table-level, named, and composite primary-key declarations populate DeltaScope's normalized primary-key contract. Existing primary-key rules (ddl.table.primary_key.bigint.require,ddl.table.primary_key.columns.max_count) now audit PostgreSQLCREATE TABLEstatements. - Generated/identity definition forms in
CREATE TABLEandALTER TABLE ... ADD COLUMNare processed through the normal audit path. Shared facts such asgenerated_when,is_identity, andidentity_optionsare preserved where applicable. - Generated/identity state-transition forms โ
ALTER TABLE ... ALTER COLUMN ... DROP EXPRESSION,SET GENERATED ALWAYS,SET GENERATED BY DEFAULT, andDROP IDENTITYโ are processed through the normal audit path and produce explicit PostgreSQL-only rule findings (ddl.alter.drop_expression.forbid,ddl.alter.set_generated.forbid,ddl.alter.drop_identity.forbid). - Unique/index rule coverage for standalone CREATE INDEX โ PostgreSQL
CREATE INDEX,CREATE UNIQUE INDEX, andCREATE INDEX CONCURRENTLYstatements now trigger existing generic index rules (ddl.index.secondary.prefix.require,ddl.index.unique.prefix.require,ddl.index.columns.max_count) for approved btree forms. - ALTER TABLE ADD CONSTRAINT fact support โ PostgreSQL
ALTER TABLE ... ADD PRIMARY KEY,ADD CONSTRAINT ... PRIMARY KEY,ADD UNIQUE, andADD CONSTRAINT ... UNIQUEforms now preserve statement-local constraint metadata. Existing primary-key rules (ddl.table.primary_key.bigint.require,ddl.table.primary_key.columns.max_count) and unique prefix rule (ddl.alter.add_index.unique.prefix.require) produce findings for approved forms. - ALTER TABLE ADD CONSTRAINT FOREIGN KEY fact support โ PostgreSQL
ALTER TABLE ... ADD CONSTRAINT ... FOREIGN KEYforms now preserve statement-local FK facts (local columns, referenced table, referenced columns, referenced schema for schema-qualified references). Existing FK rules (ddl.table.foreign_key.forbid,ddl.pg.table.foreign_key.cross_schema.advisory) produce findings for ALTER TABLE FK additions. - ALTER TABLE constraint validation pairing โ PostgreSQL
ALTER TABLE ... ADD CONSTRAINT ... CHECKfacts remain available for shared naming rules, and DeltaScope now adds the PostgreSQL-only GlobalRuleddl.pg.alter.not_valid_constraint.validate.require(defaultwarning). It warns when a named CHECK or FOREIGN KEYNOT VALIDconstraint is not followed by a later matchingALTER TABLE ... VALIDATE CONSTRAINT ...in the same audited SQL batch, using the same schema + table + constraint name as the matching key. The warning is suppressed by a later match and is visible as a global finding across CLI, HTTP, MCP, andpkg/deltascope. - Generated expression text is not evaluated or preserved, and DeltaScope still does not model full generated/identity lifecycle support or complete PostgreSQL sequence semantics.
See the audit capability matrix for detailed surface contracts and release notes for version-by-version changes.
Need PostgreSQL offline audit support?
- Install the normal DeltaScope main archive on supported macOS and Linux platforms; no separate PG-only installer is required.
The published core archive format is deltascope_<version>_<os>_<arch>.tar.gz. Development-oriented commands are documented under Dev docs.
Release Contract
Every tag produces core archives named deltascope_<version>_<os>_<arch>.tar.gz containing the deltascope, deltascope-server, and deltascope-mcp binaries. The supported darwin/amd64, darwin/arm64, linux/amd64, and linux/arm64 main archives are PG-capable and support PostgreSQL offline across all three binaries. The installer script, Homebrew Cask, and npm MCP launcher all resolve those platform-specific main archives from GitHub Release assets. See the npm package metadata for the current @fanduzi/deltascope-mcp package version.
Quick Start
Audit a risky DML statement:
deltascope audit --sql "delete from users"
Example excerpt:
Verdict: reject
Statements: 1
Blockers: 1
Warnings: 0
Notices: 0
Statement 1: DELETE
- [blocker] dml.where.require: UPDATE and DELETE statements must include a WHERE clause
Audit a CREATE TABLE statement:
deltascope 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"
Example excerpt:
Verdict: review
Statements: 1
Blockers: 0
Warnings: 1
Notices: 0
Statement 1: CREATE TABLE
- [warning] ddl.column.default.require: column "id" should define a default value
Audit a file:
deltascope audit --file ./migrations/20260328_add_column.sql
Use JSON output for CI or agents:
deltascope 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" \
--format json \
--fail-on warning
Example JSON shape:
{
"verdict": "review",
"summary": {
"statements": 1,
"blockers": 0,
"warnings": 1,
"notices": 0
},
"statements": [ ... ],
"context": {
"mode": "offline",
"dialect": "mysql",
"dialect_source": "default"
}
}
Audit a PostgreSQL migration with CI-native output:
deltascope audit --dialect postgresql --file ./migrations/20260409_add_index.sql --format github-actions
Audit a PostgreSQL CREATE TABLE statement with named and inline constraints:
deltascope audit \
--dialect postgresql \
--sql "create table orders (id bigint primary key, user_id bigint references users(id), amount numeric not null check (amount >= 0), constraint uniq_orders_user unique (user_id), constraint chk_orders_amount check (amount >= 0));"
Audit a PostgreSQL CREATE TABLE with a named foreign key referencing another table:
deltascope audit \
--dialect postgresql \
--sql "create table orders (user_id bigint, constraint fk_orders_user foreign key (user_id) references users(id));"
Audit a PostgreSQL phased migration follow-up statement:
deltascope audit \
--dialect postgresql \
--sql "alter table users alter column status set default 'active';"
Audit a PostgreSQL constraint lifecycle statement:
deltascope audit \
--dialect postgresql \
--sql "alter table users validate constraint chk_amount;"
Generate SARIF output for GitHub Code Scanning:
deltascope audit --file ./migrations.sql --dialect postgresql --format sarif > deltascope.sarif
When SQL looks like PostgreSQL but the dialect is set to MySQL, DeltaScope emits an advisory notice without auto-switching:
deltascope audit --sql "insert into users(id) values (1) returning id;" --format markdown
To audit PostgreSQL SQL explicitly:
deltascope audit --dialect postgresql --sql "insert into users(id) values (1) returning id;"
DML Impact Estimation
For 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.
{
"raw_sql": "DELETE FROM users WHERE id = 42",
"impact": {
"estimated_rows": 1,
"estimated_ratio": 0.0001,
"risk_level": "low",
"confidence": "high",
"source": "metadata",
"reason_codes": ["pk_equality"],
"notes": ["refined with table statistics"]
}
}
Offline 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.
Audit with live metadata (instance-aware rules):
deltascope audit \
--sql "alter table orders add index idx_status (status)" \
--host 127.0.0.1 --port 3306 --user root --ask-password --schema app
See all shipped rules:
deltascope rules
Why DeltaScope
SQL 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.
Key Features
- Create-table governance across identifiers, comments, primary keys, audit columns, charset/collation, indexes, and table options.
- Alter-table governance for destructive actions, compatibility checks, existence validation, and merge guidance.
- Object-lifecycle checks for
CREATE VIEW,DROP TABLE, andTRUNCATE TABLE. - DML protections for
WHERE,LIMIT,ORDER BY, subqueries, join conditions, bulk insert patterns, denylisted objects, and conservative affected-row impact estimation. - Stable product surfaces:
deltascopeCLI,deltascope-server,deltascope-mcp, andpkg/deltascope. deltascope-mcpis the official MCP stdio server and exposesaudit_sql,describe_rule,list_rules, andget_capabilities.
MCP Quick Start
No install required. The npm launcher fetches and runs the correct
deltascope-mcpbinary for your platform automatically.
Launcher requirements:
- Node.js 24 or newer
- supported native targets:
darwinorlinux,amd64orarm64
Recommended launcher:
claude mcp add --scope user deltascope -- npx -y @fanduzi/deltascope-mcp
codex mcp add deltascope -- npx -y @fanduzi/deltascope-mcp
For raw stdio TOML, native deltascope-mcp, direct connection, connection_ref, proxy setup, and common errors, see Use DeltaScope MCP.
AI Agent Skill
Works in Claude Code, Codex, Cursor, and 40+ AI coding agents. Install once, get inline SQL review in every session.
DeltaScope 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.
# Install via npx skills (Claude Code, Codex, Cursor and 40+ AI agents)
npx skills add Fanduzi/DeltaScope --skill deltascope-review -a claude-code
Install globally (available across all projects):
npx skills add Fanduzi/DeltaScope --skill deltascope-review -a claude-code -g
Keep the skill up to date:
npx skills update
Then invoke in any supported AI session:
/deltascope-review
Paste a SQL snippet or point to a file โ the agent audits it with DeltaScope and suggests fixes. See skills/README.md for full setup and usage.
More Docs
- Recipes
- Dev docs
- Reference docs
- Audit SQL with metadata
- Review DDL before migration
- Guard DML in CI
- Use with AI agents
- Inspect rules and config
- Troubleshoot metadata-aware audit
Documentation
Developer Workflows
make testrunsgo test ./...make buildproduces all local binaries underbin/make build-linuxproduces Linux amd64 binaries underbin/make test-e2e-cliruns the Docker-backed metadata CLI smoke suitemake pg-unit-test-gatesruns the PostgreSQL-tagged unit gate setmake pg-e2e-gatesruns the Docker-backed PostgreSQL CLI, HTTP, and MCP suitesmake pg-confidence-gatesruns the canonical PostgreSQL confidence closure- docs/dev/testing.md covers the full target set
HTTP Service
Run the HTTP adapter over the same audit engine:
deltascope-server -listen 127.0.0.1:8083
Endpoints:
GET /healthzGET /versionPOST /v1/audit
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.
Library Usage
result, err := deltascope.Audit(ctx, deltascope.Request{
SQL: "delete from users",
Dialect: deltascope.DialectMySQL,
})
The stable public API lives in pkg/deltascope.
Architecture
DeltaScope keeps one audit path and exposes it through multiple entrypoints. Product-level and implementation-level diagrams live in docs/concept/architecture.md and docs/dev/architecture.md.
Modules
| Module | Description | Doc |
|---|---|---|
cmd/deltascope | CLI process entrypoint | README |
cmd/deltascope-server | HTTP service entrypoint | README |
cmd/deltascope-mcp | MCP service entrypoint | README |
internal/interfaces | Transport adapter namespace | README |
internal/interfaces/cli | CLI adapter layer | README |
internal/interfaces/http | HTTP adapter layer | README |
internal/interfaces/mcp | MCP adapter layer | README |
internal/application | Use-case orchestration layer | README |
internal/application/audit | Application parse/audit orchestration | README |
internal/application/auditmeta | Shared metadata-aware audit preparation | README |
internal/application/policy | Application policy loader | README |
internal/domain | Core domain types and rules | README |
internal/domain/spec | Normalized statement specifications | README |
internal/domain/rule | Rule findings and severity model | README |
internal/domain/rule/catalog | Explanation-oriented shipped rule catalog | README |
internal/domain/rule/ddl | DDL rule catalog | README |
internal/domain/rule/dml | DML rule catalog | README |
internal/domain/policy | Policy configuration model | README |
internal/domain/report | Audit result aggregation and verdicts | README |
internal/infrastructure | Infrastructure adapter layer | README |
internal/infrastructure/parser | Parser adapter namespace | README |
internal/infrastructure/parser/tidb | TiDB parser adapter | README |
internal/infrastructure/config/viper | YAML config adapter | README |
internal/infrastructure/metadata/mysql | Metadata provider for MySQL/TiDB-compatible engines | README |
internal/infrastructure/output | Output renderer namespace | README |
internal/infrastructure/output/markdown | Markdown renderer | README |
internal/infrastructure/output/json | JSON renderer | README |
configs | Example configuration files | README |
pkg/deltascope | Stable public package surface | README |
