Skip to main content

SQLens for Laravel — documentation

Developer and rule-author documentation for SQLens, the database safety toolkit for Laravel. These pages describe the contracts the package guarantees.

SQLens is in development. These pages document what ships today. More suites (lint, audit, security, deploy) are still being built; this index gains a page per area as each one lands.

Pages​

  • The lint suite — sqlens:lint and sqlens:baseline: every flag, the exit-code table, the three-stage suppression order and its #[SqlensIgnore] attribute, the single-file fast path with a runnable pre-commit hook, the roundtrip that tests whether down() really inverts, the report-before-block adoption path, and the CI recipe with the two switches a reproducible run needs.
  • The public contracts — the exit codes a pipeline branches on, the JSON envelope a script parses, and the baseline file a repository commits: what each one promises, and what changes only in a major release.
  • The canonical form — the data structure every rule works on: what it guarantees, what it deliberately does not, and the rules that keep a rule off raw SQL and off the database.
  • Capture modes: pretend and shadow — the two ways SQLens obtains a migration's SQL, what pretend mode structurally cannot see, and when shadow mode is the answer.
  • Shadow mode: setup, privileges, topologies — the one mode that needs more than read-only access: what it requires, the dedicated least-privilege role, the pooler and read/write-split rules, and why it never clones your live data.
  • Understanding undetermined — the three-valued result model, why a flag is not an accusation, and the three ways to resolve one.
  • Rules — the rules/ pages, one per rule id. The capture layer's rules are documented from the first release: the pre-scan findings (side effect, result-dependent, introspection guard, indirect call) and the level-0 capture rules (not capturable, pretend error, migrate error, undetermined capture, down failed, down not invertible).

URL conventions​

See the URL conventions for the rule that shapes every page's canonical address.