SQL Contracts

The sql step verifies database invariants directly at the data layer.

Use it to assert:

• Database availability
• Schema invariants
• Migration state
• Critical data guarantees

Stoney currently supports PostgreSQL.

Example

version: 1
feature: users
 
contracts:
  - name: user_invariants
    checks:
      - id: verify_user_creation
        work_item: "USER-42"
        says: "User must be persisted in the active state"
        steps:
          - sql:
              driver: postgres
              url_env: STONEY_DB_URL
              query: "SELECT email, status FROM users WHERE email = 'test@example.com';"
            expect:
              rows: 1
              equals:
                status: "active"

How SQL Checks Work

• The connection string is read from url_env.
• statement_timeout is enforced per connection.
• The first row is evaluated against equals.
• rows asserts the total row count.

Safe-by-Default Behavior

Stoney blocks:

• INSERT / UPDATE / DELETE
• DROP / ALTER / TRUNCATE / CREATE
• Multi-statement queries

Override via (use with caution):

STONEY_ALLOW_WRITE_SQL=true
STONEY_ALLOW_MULTI_SQL=true

Best Practices

• Use least-privileged read-only DB users
• Prefer invariant checks over volatile data-dependent tests
• Keep queries deterministic
• Run against staging unless intentionally validating production

SQL contracts enforce infrastructure guarantees — not migration scripts.