db-guardrails

Database Guardrails Adapter

Prerequisite: guardrails-coding-agent must be installed.

Invocation Sequence

Pre-work gates

1. Detect operationType

• Diff path contains migrations/ or filenames match V\d+__*.sql / *_migration.sql → operationType: migration
• Diff contains CREATE TABLE, DROP TABLE, ALTER TABLE, CREATE INDEX → operationType: ddl
• Diff path contains seeds/ or filenames match *seed*.sql → operationType: seed
• Otherwise → operationType: none

2. Invoke input-validation with:

agentFamily: "db-coding-agent"
allowedActions: ["code", "migration", "seed", "review", "query"]
scopedPaths: ["db/", "migrations/", "schemas/", "seeds/", "repositories/"]
blockedPaths: []

3. Invoke budget-monitor with:

agentFamily: "db-coding-agent"
userStoryId: <from config or prompt>
accumulatedCost: <read from .guardrails-costs.jsonl rollup>

4. Invoke policy-enforcement with:

agentFamily: "db-coding-agent"
resolvedLanguage: <from config-resolver>
resolvedFramework: <from config-resolver>
allowedAgents: <from policy.allowedAgents>
lspStatus: <from LSP startup result>

5. Invoke harm-prevention with:

agentFamily: "db-coding-agent"
languagePatternSet:
  - SQL injection pattern: "(?:EXEC|EXECUTE|sp_executesql)\s*\(\s*@[a-zA-Z]+" (dynamic SQL without parameterization)
  - Connection string pattern: "(?:Server=|Data Source=|mongodb://|postgresql://)[^;\"']*(?:Password=|:[^@]+@)"
patternOverrides: {}

6. If operationType is migration: invoke idempotency-guard with:

operationType: "migration"
phase: "pre"
migrationsDir: <resolved from config or default: "db/migrations/">

7. Invoke artifact-validator (pre-write phase) with:

artifactPath: <path of file about to be written>
artifactContent: <content to be written>
engine: <resolved from config-resolver>
scanDirs: <from artifactValidation.scanDirs config, default: ["db/", "migrations/", "schemas/", "seeds/", "stored-procedures/", "views/", "functions/"]>
phase: "pre-write"

This gate fires BEFORE every Write or Edit to detect duplicate database artifacts. If artifact-validator returns BLOCK: halt and report to human. If artifact-validator returns HUMAN_REVIEW: surface the ambiguity to the human and wait for confirmation before proceeding. If the human denies: abort the write and log the decision in the audit trail.

Agent does its work

Extra DB checks (run after agent writes):

Scan any SQL migration files for:

• DROP TABLE / TRUNCATE TABLE without IF EXISTS / guard → P0 BLOCK — "Destructive DDL operation without idempotency guard. Add IF EXISTS or a transaction guard."
• Migration file exists without a corresponding rollback file (V{N}__rollback_*.sql or down.sql equivalent) → P1 BLOCK — "Migration [name] has no rollback script. Create the rollback before completing."
• Connection string with embedded password in source code → P0 BLOCK — "Connection string with embedded credentials detected. Use environment variables or a secrets manager."

Post-write artifact validation:

After the agent writes all artifacts, invoke artifact-validator (post-work phase) with:

artifactPath: <list of all files created/modified during this session>
engine: <resolved from config-resolver>
scanDirs: <from config>
phase: "post-work"

If any BLOCK-level finding: halt and surface to human before proceeding to post-work gates.

Post-work gates

8. Invoke output-validation with:

agentFamily: "db-coding-agent"
lintTool: "sqlfluff lint --dialect <resolved-dialect>"
coverageTool: null
coverageReportPath: null

9. Invoke idempotency-guard with phase: post if operationType != none.

10. Invoke drift-detection with:

agentFamily: "db-coding-agent"
pinnedVersions: <from drift.pinnedVersions>
driftBaselineRef: <from drift.driftBaselineRef, default: "main">
driftTrigger: "session-start"

11. Invoke cost-tracker with:

userStoryId: <from config or prompt>
sessionTokensUsed: <estimated from session context>
modelRateKey: "claude-sonnet-4-6"

12. Invoke audit-trail with:

gateResults: <all gate outcomes from steps 2-11>
agentFamily: "db-coding-agent"
sessionId: <generate: "db-coding-agent-<timestamp>">
userStoryId: <from config or prompt>

13. Invoke artifact-validator (commit phase) with:

artifactPath: <list of all files staged for commit>
engine: <resolved from config-resolver>
scanDirs: <full repository scan>
phase: "commit"

This final pass re-validates all staged artifacts against the full repo to catch duplicates introduced outside the current session. If any BLOCK: prevent the commit and surface to human.

14. If any gate returned BLOCK or WARN: invoke error-escalation with:

gateResults: <all gate outcomes>
agentFamily: "db-coding-agent"
sessionId: <from step 12>

15. Invoke memory-writer (final post-work step) with:

agentFamily: "db-coding-agent"
sessionId: <from step 12>
userStoryId: <from config or prompt>
ticketSummary: <short title from the story/task, if available>
filesModified: <list of repo-relative paths touched this session>
patternsChosen:
  language: <sqlserver | postgres | mongodb | cosmosdb>
  framework: <migration tool used — e.g. flyway, liquibase, alembic, ef-core>
  languageVersion: <resolved engine version>
  designPatterns: <patterns actually used — e.g. ["idempotent-migration", "backfill", "online-index"]>
teamConventions: <non-obvious conventions observed from guidelines-ingestion>
lessonsLearned: <problems hit this session and how they were resolved — empty list when none>
outcome: <success | partial | blocked | failed>

Memory-writer is best-effort telemetry. Never block the session on a memory-write failure.