Nock

Estate-aware approve/block for Postgres DDL.

Same verdict in CLI, CI, and Cursor MCP. Never applies migrations.

Why Nock

• Checks your proposed DDL against an estate — a snapshot of your table sizes plus catalogue facts (columns, constraints, indexes) — so it approves or blocks based on your data, not generic SQL patterns

• Check-only: never applies migrations and never writes to your database

• Returns the same JSON verdict from the CLI, GitHub Actions, and Cursor MCP

• Exit codes: 0 pass · 1 warnings only · 2 fail (blocking)

Related MCP server: postgres-aiops

Quick start (golden path)

An estate is a small JSON snapshot of your Postgres table sizes and catalogue facts (columns, constraints, indexes)—not a dump of row data—that Nock uses to approve or block DDL for your database. Details: Estate schema.

1. Get an estate (pick one)

• Bring your own estate: commit .nock/estate.json

• Sync estate yourself: npx @nockhq/cli@latest sync-estate --database-url "$DATABASE_URL" --out .nock/estate.json

• Live DATABASE_URL check: omit --estate, pass --database-url

2. Check

npx @nockhq/cli@latest check \
  --sql migrations/001.sql \
  --estate .nock/estate.json \
  --format json

3. Wire the gate — same command in Actions or MCP check_before_apply. Exit: 0 pass · 1 warn · 2 fail.

Example verdict (truncated)

{ "verdict": "fail", "violations": [ { "rule_id": "R001", "severity": "red" } ] }

Add to CI (GitHub Action)

Preferred: use the published Action from this repo’s packages/action subdirectory, pinned to a tag:

name: Nock — Postgres migration safety (Action)
on:
  pull_request:
    paths: ['migrations/**', '.nock/**']
jobs:
  nock:
    runs-on: ubuntu-latest
    permissions: { contents: read, pull-requests: write }
    steps:
      - uses: actions/checkout@v4
      - name: Run Nock check (Action)
        uses: saiyamshah1496/nock/packages/action@v0.1.9
        with:
          migration-path: migrations/
          estate-path: .nock/estate.json
          policy-path: policy.default.yml
          fail-on: red
          github-token: ${{ secrets.GITHUB_TOKEN }}

Notes:

• This Action is intentionally published from a subdirectory; GitHub Marketplace listing requires a dedicated public repo with a root action.yml (follow‑up item).

• You can also test a PR branch by pinning a commit SHA in uses: owner/repo/path@<sha>.

Alternative (CLI): Copy-paste into .github/workflows/nock.yml:

name: Nock — Postgres migration safety (CLI)
on:
  pull_request:
    paths: ['migrations/**', '.nock/**']
jobs:
  nock:
    runs-on: ubuntu-latest
    permissions: { contents: read, pull-requests: write }
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: 'npm' }
      - name: Run Nock check (CLI)
        run: |
          npx @nockhq/cli@latest check \
            --sql "migrations/001.sql" \
            --estate ".nock/estate.json" \
            --policy "policy.default.yml" \
            --fail-on "red" \
            --format "json" | tee nock-verdict.json

See more in examples/workflows/nock.yml and examples/workflows/nock-action.yml.

Add to Cursor (MCP)

• Install server via npx:

  { "mcpServers": { "nock": { "command": "npx", "args": ["-y", "@nockhq/mcp@latest"] } } }

• Call check_before_apply with either:

  • estatePath: ".nock/estate.json" (file)

  • or databaseUrl: "postgres://..." (live DATABASE_URL check)

• Guide: docs/guides/mcp-check-before-apply.md

Not Squawk, not Atlas

Not Squawk, not Atlas. Squawk lints migration shapes without knowing your table sizes. Atlas plans and applies schema changes. Nock does neither: it takes your DDL plus an estate snapshot (or a live read-only DATABASE_URL) and returns approve or block for CI and agents—lock risk on your data—without ever applying SQL.

Free vs Team

Free — one estate, DIY Bring your own estate file, sync estate yourself, or run a live DATABASE_URL check on your runner. Staging + production means two checks or a CI matrix you own. Nock does not host multi-estate packs on Free.

Team — estate packs Hosted staging / production / tenant estates under one org, plus org policy, audit, and export. Same approve/block engine as Free — ops convenience when you outgrow a single estate file in CI.

Docs

• Getting started

• Estate (sync estate yourself)

• Live DATABASE_URL check

• CI

• MCP

• Grants

• Reference: CLI · Rules · Verdict JSON · Estate schema

Security

• No row data is read or processed; only catalogue (columns, constraints, indexes) and table sizes

• Your database URL never leaves your runner in Free mode

• Prefer read‑only roles and replicas for sync-estate or live checks See docs/SECURITY.md.

Contributing

See docs/DEVELOPMENT.md.

License

MIT