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.

composer require pushery/sqlens-for-laravel

The public API is documented and is what a 1.0 will commit to, but it is not frozen: a field or a flag may still change in a minor release before then. What is documented below is what ships today — every suite has its pages, and a boundary a suite does not cross is written down beside it rather than left for you to discover.

The package is on Packagist, and the source, the issue tracker and the README live at github.com/pushery/sqlens-for-laravel.

Pages​

Start here​

  • Integration guide — the whole path in the order you walk it: install, the first run and how to read it, publishing the config, adopting on a project that already has migrations, wiring CI, and wiring the deploy gate. If you read one page, read this one.

The suites​

  • 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 audit suite — sqlens:audit against a database that already exists: every flag, and the four statements the command will not make for you — which instance it read, what the ignore list keeps quiet (and why that is not a baseline), which tenant the report is about, and what the reading role was allowed to see.
  • The security suite — sqlens:security: roles, grants, transport, row-level security and unencrypted columns, gated by a severity axis of its own rather than by the strictness level, and why undetermined is the normal answer on a managed database.
  • The analyse suite — the PHPStan extension that reads the code handing SQL to the database, and how it sits beside Larastan and phpstan-dba.
  • Formatting your SQL — sqlens:format, a --check mode a CI step can act on, three backends behind one seam, and the four things the formatter will never do to a statement.
  • Runtime guardrails — what sqlens.guard watches in a running application, why it is off unless you name a profile, why it logs instead of throwing, and what it deliberately cannot see.

Tooling around a project​

  • Checking the environment — sqlens:doctor: which server version each connection really runs, which optional tools were found, and what each absence costs. The first command to run on a new machine.
  • Optional analyzers — the outside tools SQLens will call, what each one adds, and the one it deliberately does not adopt.
  • The Postgres Language Server — what the optional dblint adapter reports, what a run does to your database, and why its version window is one minor wide.
  • Agent context files — sqlens:agent-rules: writing the active rule set into the coding agents' context files, so an agent knows a rule before it writes the migration rather than after the linter rejects it.

Around a deploy​

  • The deploy recipe — wiring the gate so a failure actually stops the migration rather than being reported after it.
  • What sqlens:predeploy needs — the permissions it asks for, and the ones it never does.
  • The deploy readers — what each one needs to see, and what a partial answer means.
  • Post-deploy verification — what sqlens:postdeploy reads after migrate --force, what it is deliberately not, and the exit codes a deploy script acts on.
  • sqlens:drift — what the database holds, against what the migrations describe.
  • Drift detection rollout — bringing a grown production database under drift control in three steps, and why skipping the first one kills the feature.
  • The migration debt account — the two-step patterns this tool recommends, and the account of the second steps.

The contracts​

  • 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 public API, and where it stops — what is promised from 1.0, what is explicitly not, and how a command becomes one or the other.
  • The remediation payload — the machine-readable fix material a finding can carry: every field, what a consumer must check, and the line SQLens does not cross.
  • MCP server — connecting an agent to the same engine the commands use.
  • 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.

What it reads, and what it will not​

  • 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.
  • The catalog reader — what an audit reads, what it never touches, the privileges it needs, and how it degrades on a managed database.
  • The audit role — what SQLens needs to read, and what it deliberately does not.
  • Read/write splits and replicas — why an audit refuses to let the framework pick which server it describes.
  • Scope and limits — what SQLens checks, what it deliberately does not, and how it tells you which of the two you are looking at.
  • Understanding undetermined — the three-valued result model, why a flag is not an accusation, and the three ways to resolve one.

The rules, and the evidence behind them​

Security​

Engines​

URL conventions​

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