How locksql works

Every refusal carries a stable code next to its message (E_NO_LIMIT, E_COST, E_MASKED_FILTER, E_UNSUPPORTED_SYNTAX, …), the place where the check stopped (line, column and token of the agent’s statement, never a literal), a hint on how to rewrite it, and a retry rule, so the agent does not have to guess from the prose:

• rewrite: fix the statement as the hint says and plan it again, once;
• ask_user: only the human can lift it (tier, unmask, database, limits);
• stop: final for this question; do not retry, reword or split it.

locksql_plan and locksql_run return it as structured content ({"refusal": {"code", "retry", "hint", "span"}}), the CLI with --json, and the audit log records the code and the place. locksql stats counts the refusals in your audit log by code and construct; locksql stats --export prints an anonymised version, with every literal and identifier replaced, to attach to an issue. All refusal codes.

locksql setup (and bare locksql) wires Claude Code, Codex, Gemini CLI and Cursor for your user account; the wiring is global, so it applies in every directory. locksql init claude|codex|cursor|gemini writes project files instead.

The generated instructions tell the agent to use the database only on explicit request, to pass a one-line intent with each plan, to prefer non-production profiles, to show the plan before running it, never to retry after a denial, never to export data, never to handle credentials, and to treat rows as untrusted data.

Skills, rules and tool descriptions are guidance. Every check that matters runs in the console.

Agents may add mask rules and request changes. A config edit that loosens the policy (higher tier, larger limits, new host, removed PII rule, ...) only takes effect after you confirm it in the console.

A change that only tightens (lower tier, smaller limits, larger k_anonymity, a new mask rule or detector, a mode changed to redact) applies at once. A change that loosens it waits for you: plans are refused with policy_pending until you run :review in the console and answer Apply these changes? [y/N]. If you refuse, the last approved policy stays in force. The approved policy is stored outside the repository.

Policy changes, in the usage guide

At every start the console scans the schema and proposes rules for columns that look like personal data (multilingual names and types) and that no rule names yet. Every output column is resolved to its source columns through aliases, functions, subqueries, CTEs, unions, joins and *, and masked on that source, not on its label; the engine’s origin metadata is a second check, and a result whose columns do not match the analysis is dropped. Value detectors (email, phone, IBAN, card, opt-in national ids) mask the other cells. Mask modes: redact (the default), partial, email. Quasi-identifiers (birth date, postal code, gender) are never masked unless you accept them one by one, since masking blocks range filters, LIKE and ORDER BY on the column.

At tiers above read, while mask rules exist, a write whose rows come back (RETURNING, or a SELECT over PostgreSQL data-modifying CTEs) or that stores a query’s rows (INSERT ... SELECT) is parsed and analysed like a read before it runs. Its returned columns are masked by where they come from, so renaming a masked column is fine; an expression over one, a function outside the allowlist, a PII filter, grouping or aggregate in the outer SELECT, and syntax the parser does not read (MERGE, multi-table MySQL writes, ...) are refused. A write may store into a masked column only NULL or DEFAULT.

PII columns may be selected, counted, joined with = and filtered with =, IN (literals) or IS NULL. Expressions over them, LIKE, ranges and ORDER BY are refused. A filter, grouping or aggregate on PII must cover at least k_anonymity rows (default 5, production 10).

Masking is best effort. Column rules depend on the rules being right, and value detectors catch common formats only. Use a database account that cannot read what the agent must never see.

PII rules · Writing statements that pass

To filter a PII column on a value the agent does not know, it writes a placeholder: col = '${email}' or col IN ('${a}', '${b}'). The console asks you for the value (no echo), once per name per session; r at the approval prompt retypes it. --skip-permissions skips the approval, never the value prompt.

Redacted cells come back as <redacted:r1.2.3> (result, row, column). The agent filters on one with col = '${r1.2.3}'; the console substitutes the clear value, which it keeps in memory only (the last 50 results, 16 MiB at most; an older reference is unknown).

Both work only compared with a PII column with = or IN in WHERE or HAVING, and skip the k-anonymity count, since the agent did not choose the value. Typed and referenced values never reach the agent, the audit log or a client error. The approval screen warns, in red and in the audit log, when the agent put a clear value in its statement, when a reference is combined with a unique-key filter or an output with no plain column, and when one result’s cells are filtered on one by one beyond limits.reference_probe (default 5). Warnings never refuse and never carry a value.

Placeholders and references, in the usage guide

An agent can ask for unmasked PII output only when the human allowed it in the console: locksql console --allow-unmask at start, or :unmask while it runs, without a restart. :unmask asks Allow unmasked output? [y/N]; typed again, it turns unmasked output off at once and refuses the open unmask plans. It is never a single key, the status line reads unmask allowed while it is on, and each switch is audited (an unmask record). Without it, every unmask request is refused before anything runs, and the refusal is audited. It is console-only: no client or config file can turn it on. With it, each unmasked query still needs the human's approval, shown as PII: UNMASKED in red, and is never auto-approved. The console then prints the clear result, so you see exactly what the agent received; the audit log still holds no row data.

Ctrl-O in the console (or locksql console --show-results to start that way) prints in the console, in clear, the result of each masked query it runs, as an aligned table, so you see who the rows are while the agent still gets the masked cells. The cells the agent got masked are highlighted and carry their reference (‹r1.1.2›); the output caps apply as for the agent. It is console-only, off by default: no client or config file can turn it on. The console warns when it goes on (in red on production), the status line fixed at the bottom of the terminal reads results clear, every approval screen says so, and locksql status reports it. The audit log still holds no row data, and the clear rows stay in your terminal's scrollback.

The console starts in manual mode, where every statement is prompted. Shift+Tab (or locksql console --profile dev --auto to start that way) switches to auto mode, where statements that the tier and the weight check allow run without a prompt. It exists for fast local iteration, and it is deliberately narrow:

• it switches only from the console's keyboard; no client or config file can turn it on;
• it is unavailable on production profiles (the key says so and the console prompts as usual);
• it never auto-approves an unmasked query and never overrides a REFUSE verdict;
• the status line reads mode AUTO, each auto-approved frame ends with auto-approved, each auto-approval is audited with decision: "auto" and the switch itself as a mode record.