DeltaScope

README

DeltaScope

English | 中文 | Changelog | Security | License | Release Notes

DeltaScope is an offline-first SQL audit engine for MySQL and TiDB. It gives DBAs, application engineers, CI pipelines, and AI agents one consistent way to review DDL and DML before they reach a database.

Install

The primary install path is the repository installer script, which resolves the same release archive contract used by CI publishing.

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.6.1/install.sh | \
  DELTASCOPE_VERSION=v0.6.1 sh

The published archive format is deltascope_0.6.1_<os>_<arch>.tar.gz. Development-oriented commands are documented under Dev docs.

Quick Start

Audit inline SQL:

deltascope audit --sql "delete from users"

Audit a file:

deltascope audit --file ./change.sql

Use JSON output for CI or agents:

deltascope audit \
  --sql "alter table users drop column age" \
  --format json \
  --fail-on warning

Run metadata-aware audit against a live schema:

deltascope audit \
  --sql "alter table users add column email varchar(255)" \
  --host 127.0.0.1 --port 3306 --user root --ask-password --schema app

Why DeltaScope

• Reviews DDL and DML with stable blocker, warning, and notice findings.
• Stays useful offline, which keeps local development, CI, and agent loops lightweight.
• Reuses the same rule engine for CLI, HTTP, and library access instead of splitting behavior across tools.
• Adds metadata-aware enrichment only when live schema or instance facts actually matter.

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, and TRUNCATE TABLE.
• DML protections for WHERE, LIMIT, ORDER BY, subqueries, join conditions, bulk insert patterns, and denylisted objects.
• Stable product surfaces: deltascope CLI, deltascope-server, and pkg/deltascope.

Recipes

• Audit SQL offline
• Audit SQL with metadata
• Review DDL before migration
• Guard DML in CI
• Use with AI agents

Documentation

• Admin docs
• Concept docs
• Dev docs
• Reference docs
• Audit capability matrix

Developer Workflows

• make test runs go test ./...
• make build produces both local binaries under .build/bin
• make test-e2e-cli runs the Docker-backed metadata CLI smoke suite
• 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 /healthz
• GET /version
• POST /v1/audit

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
internal/interfaces	Transport adapter namespace	README
internal/interfaces/cli	CLI adapter layer	README
internal/interfaces/http	HTTP adapter layer	README
internal/application	Use-case orchestration layer	README
internal/application/audit	Application parse/audit orchestration	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