README
¶
Application Audit Module
Application orchestration for parsing and, later, evaluating SQL audit requests.
Files
| File | Responsibility |
|---|---|
| parse.go | Dispatches by dialect, builds application-owned parsed statements from infrastructure-backed parser adapters via parser-neutral extractors, and leaves PostgreSQL build-tagged support behind the Phase 3 adapter seam |
| parse_pg.go | Implements PostgreSQL parsing when built with the postgresql tag |
| parse_pg_stub.go | Returns the PG-capable build guidance error when PostgreSQL support is not compiled in |
| parse_test.go | Verifies that application parsing hides parser-specific AST details |
| extract.go | Converts parsed statements into first-pass domain Statement values by invoking parser-neutral extractors and attaching shape-only DML impact facts |
| extract_test.go | Verifies representative DDL and DML extraction behavior, including create-like/create-as/partition flags plus enriched create-table facts, preserved backticked-keyword and unnamed-index names, extracted column charset/collation facts, normalized row-format and auto-increment-init options, explicit DDL lifecycle operations, richer alter-table detail including explicit statement-local change facts, multi-column add expansion, non-index constraint handling, and extracted DML target-table plus predicate-shape facts |
| impact.go | Maps extracted DML predicate shapes to conservative offline impact estimates, populates statement impact objects with estimated_rows, estimated_ratio, risk_level, confidence, source, reason_codes, and optional notes, upgrades shape-derived sources to metadata after enrichment, and refines the narrow primary-key-on-id case when metadata snapshots confirm PRIMARY(id) plus optional table_rows facts |
| impact_test.go | Verifies shape-only impact estimation plus post-enrichment metadata source upgrades, unique-equality refinement, and offline preservation behavior for representative UPDATE and DELETE shapes and their additive impact payloads |
| evaluate.go | Applies registered rules, enriches findings with explanation metadata, and aggregates statement/global findings into report output while preserving statement-level DML impact estimates |
| evaluate_test.go | Verifies application-owned report-flow integration and explanation enrichment over the rule registry |
| explain.go | Joins evaluated findings with shipped catalog metadata and statement metadata availability notes |
| service.go | Orchestrates the full audit flow across policy loading, parsing, extraction, top-level request metadata plumbing, optional metadata enrichment, post-enrichment DML impact attachment/refinement, rule registration, evaluation, and partial-support error propagation for unsupported statements |
| service_test.go | Verifies the end-to-end application audit use case with defaults, config overrides, multi-statement SQL, PostgreSQL validation-boundary acceptance, mixed supported/unsupported partial results, metadata enrichment behavior, metadata-backed DML impact surfacing, and schema-only context/top-level request plumbing |
| metadata.go | Defines the optional metadata-provider and index-owner resolver seams, then attaches schema, instance, and target-table facts to statements before evaluation |
Exports
Parse(sql string, dialect spec.Dialect)Extract(parsed ParsedSQL)EvaluateStatements(registry, statements)AuditSQL(ctx, request)RequestMetadataRequestMetadataProviderIndexOwnerResolverServiceNewService()Service.Audit(ctx, request)ParsedStatementParsedSQLPostgreSQLCapabilityBoundaryError
Dependencies
- Upstream: future CLI and public audit entrypoints
- Downstream:
context,fmt,internal/application/policy,internal/domain/report,internal/domain/rule,internal/domain/rule/ddl,internal/domain/rule/dml,internal/domain/spec,internal/infrastructure/parser/postgresql,internal/infrastructure/parser/tidb
Update Rule
- If members/interfaces/dependencies change, update this file in same change.
Documentation
¶
Overview ¶
Package audit orchestrates audit use cases at the application layer. input: extracted domain statements and the registered rule engine output: aggregated report results with statement/global findings and preserved statement-level impact estimates pos: application evaluation step between extraction/metadata refinement and reporting note: if this file changes, update this header and module README.md.
Package audit enriches evaluated findings with shared explanation metadata. input: rule findings, shipped catalog entries, and optional statement metadata context output: additive per-finding explanation data without changing verdict semantics pos: application explanation enrichment between evaluation and report aggregation note: if this file changes, update this header and module README.md.
Package audit orchestrates audit use cases at the application layer. input: application-owned parsed SQL statements and parser-neutral extractors output: first-pass StatementSpec values plus attached shape-only impact facts for later rule evaluation pos: application extraction step between parsing and rule execution note: if this file changes, update this header and module README.md.
Package audit orchestrates audit use cases at the application layer. input: extracted statement-local DML shape facts plus optional metadata snapshots for refinement output: conservative DML impact estimates attached during extraction and upgraded after metadata enrichment pos: application impact estimation step between extraction, metadata enrichment, and rule evaluation note: if this file changes, update this header and module README.md.
Package audit orchestrates audit use cases at the application layer. input: optional metadata providers plus parsed statement targets for enrichment output: metadata-enriched statements for rules that can use live instance or schema facts pos: application-layer bridge between provider-backed metadata and domain statements note: if this file changes, update this header and module README.md.
Package audit provides application-layer parser mismatch hints.
Package audit orchestrates audit use cases at the application layer. input: SQL text, selected dialect, and infrastructure-backed parser adapters output: application-owned parsed statements for later extraction and rule evaluation pos: application parsing entrypoint between interfaces and parser infrastructure note: if this file changes, update this header and module README.md.
Package audit orchestrates audit use cases at the application layer. input: audit requests carrying SQL text, dialect, optional policy override paths, and optional metadata providers output: end-to-end audit results assembled from policy loading, parsing, extraction, metadata enrichment, post-enrichment impact refinement, and rule evaluation pos: application service entrypoint for the unified offline/metadata-aware SQL audit use case with preserved statement impact estimates note: if this file changes, update this header and module README.md.
Index ¶
- Variables
- func AuditSQL(ctx context.Context, request Request) (report.Result, error)
- func EvaluateStatements(registry *rule.Registry, statements []spec.Statement) (report.Result, error)
- func Extract(parsed ParsedSQL) ([]spec.Statement, error)
- type IndexOwnerResolver
- type MetadataProvider
- type MetadataRequest
- type ParsedSQL
- type ParsedStatement
- type PlanEstimator
- type PostgreSQLCapabilityBoundaryError
- type Request
- type Service
Constants ¶
This section is empty.
Variables ¶
var ( // ErrEmptySQL indicates the request did not include auditable SQL text. ErrEmptySQL = errors.New("audit SQL must not be empty") // ErrUnknownDialect indicates the request did not specify a supported dialect. ErrUnknownDialect = errors.New("audit dialect must be mysql, tidb, or postgresql") // ErrUnsupportedStatement indicates at least one parsed statement is recognized but unsupported. ErrUnsupportedStatement = errors.New("audit includes unsupported statements") )
Functions ¶
Types ¶
type IndexOwnerResolver ¶ added in v0.18.0
type IndexOwnerResolver interface {
ResolveTableForIndex(ctx context.Context, dialect spec.Dialect, schema string, index string) (string, error)
}
IndexOwnerResolver optionally resolves standalone index statements back to owning tables.
type MetadataProvider ¶
type MetadataProvider interface {
LoadInstanceFacts(ctx context.Context, dialect spec.Dialect, schema string) (*spec.InstanceFacts, error)
LoadTableSnapshot(ctx context.Context, dialect spec.Dialect, schema string, table string) (*spec.TableSnapshot, error)
}
MetadataProvider supplies optional instance and schema facts for one audit run.
type MetadataRequest ¶
type MetadataRequest struct {
Schema string
Provider MetadataProvider
}
MetadataRequest describes one optional metadata-aware audit invocation.
type ParsedSQL ¶
type ParsedSQL struct {
Dialect spec.Dialect `json:"dialect"`
Statements []ParsedStatement `json:"statements"`
Warnings []string `json:"warnings,omitempty"`
}
ParsedSQL is the application-owned parsing result used by later extraction steps.
type ParsedStatement ¶
type ParsedStatement struct {
Kind spec.Kind `json:"kind"`
RawSQL string `json:"raw_sql"`
Extractor spec.StatementExtractor `json:"-"`
}
ParsedStatement keeps application-facing statement metadata while hiding parser nodes.
type PlanEstimator ¶ added in v0.18.0
type PlanEstimator interface {
LoadPlanEstimate(ctx context.Context, statement spec.Statement) (*spec.ImpactEstimate, error)
}
PlanEstimator optionally loads planner-backed DML impact estimates.
type PostgreSQLCapabilityBoundaryError ¶ added in v0.20.0
type PostgreSQLCapabilityBoundaryError struct {
Message string
}
PostgreSQLCapabilityBoundaryError reports that PostgreSQL parsing needs a PostgreSQL-capable build.
func (*PostgreSQLCapabilityBoundaryError) Error ¶ added in v0.20.0
func (e *PostgreSQLCapabilityBoundaryError) Error() string
type Request ¶
type Request struct {
SQL string
Dialect spec.Dialect
ConfigPath string
Schema string
MetadataProvider MetadataProvider
Metadata *MetadataRequest
}
Request describes one application-level audit invocation.
Source Files