naro-cli 0.11.0 → 0.12.0

package/README.md

@@ -91,9 +91,11 @@ naro db dump --output backup.sql   SQL dump, streamed from Cloudflare (stdout wi
 naro db restore --bookmark <id>    Time Travel, last 30 days (or --timestamp <time>);
                                    asks first, prints the command that undoes it
 naro db pull                       Existing database, no migrations yet: writes its schema
-                                   as migrations/0001_remote_schema.sql, recorded as applied
+                                   and policies as migrations/0001_remote_schema.sql,
+                                   recorded as applied
 naro db reset [--dry-run]          Drop every table, view and trigger, clear the ledger and
-                                   apply ./migrations again (asks first; --yes in CI)
+                                   the policies, and apply ./migrations again (asks first;
+                                   --yes in CI; refuses files the server would refuse)
 naro db lint [--strict]            Check the schema for what D1 actually trips on; exits 1
                                    on an error, and on a warning too with --strict
 naro db table create posts --column "id:integer:pk:autoincrement" --column "title:text:notnull" --column "created_at:datetime:notnull:default=current_timestamp" --owner user_id
@@ -191,12 +193,43 @@ reads the bookmark from just before the drops and prints it, so
 `naro db restore --bookmark <that>` puts the data back. `--dry-run` lists what
 it would drop and re-apply without touching anything.
 
+The backend's accounts, sessions, settings and the other `_naro_` tables are
+kept — except its policies: they are cleared with the schema and the migration
+files create them again. Before it reads anything, `db reset` checks the files
+as `naro db push --dry-run` does: when the control plane would refuse one, the
+re-apply would stop there with the schema already dropped, so the reset is
+refused with `VALIDATION_FAILED`, each file as `<file>: Statement <i> of <n>:
+…` (`--dry-run` prints them and exits 1). A policy that exists only in the
+database would be lost — one made with `naro policy create` or
+`naro policy set`, and the owner policy that `naro db table create --owner`,
+MCP's `create_table` and the table editor add, which no migration file holds.
+So before it asks, `db reset` lists the policies your files do not make, each
+with the SQL that makes it again — its `CREATE POLICY` and, for an owner rule,
+the `COMMENT ON POLICY … IS 'naro:owner <column>'` that keeps its column
+(`--json`: `policiesNotInFiles[].sql`); add it to a migration first to keep
+them. The policies of a table your files do not create go with that table and
+are named apart, with no SQL (`--json`: `policiesOfTablesNotInFiles`): a
+migration that made them would stop at a table that is not there. A file the
+re-apply would stop at that the check above does not catch (one whose SQL
+cannot be split) is named instead — `<file> would be refused: <reason>`
+(`--json`: `wouldBeRefused`) — and then no policy is called lost. A policy row
+that cannot be read is listed as a `-- Policy … cannot be read` comment
+instead: copying it keeps nothing, so drop that policy and create it again. A
+backend whose worker predates named policies is refused with
+`409 BACKEND_OUTDATED`: run `naro backend enable` first.
+
 `naro db lint` reads the schema and runs the checks D1 allows. Its rules are
 the ones D1 actually trips on — orphaned rows, a failed `quick_check`, a
 missing or nullable primary key, a foreign key no index starts with, a trigger
 the REST API cannot recreate, a virtual table that makes `db dump` refuse the
-whole database. There is no "unused index" guess: D1 keeps no execution
-statistics to base one on. An error exits 1, a warning exits 0 — `--strict`
+whole database. On a project with a backend it also checks the policies:
+`rls_no_policy` (a table the Data API refuses entirely),
+`rls_policy_text_default` (a number column a policy reads as a boolean whose
+`DEFAULT` is text, such as `BOOLEAN DEFAULT 'true'`) and
+`rls_policy_unindexed` (warnings), and `rls_policy_invalid`, a policy the
+backend cannot apply — one that reads a text column as true or false among
+them (an error). There is no "unused index" guess: D1 keeps
+no execution statistics to base one on. An error exits 1, a warning exits 0 — `--strict`
 makes warnings fail too, so CI can gate on it:
 
 ```bash
@@ -217,7 +250,9 @@ from a fixed list — and applies it as one migration, recorded in
 `d1_migrations` and written to `./migrations` as `NNNN_schema_<op>_<table>.sql`,
 numbered after your local files and the ledger. `naro migration list`,
 `db pull` and `db reset` see it like any other migration; with `--no-write`
-there is no file, so `db reset` will not re-apply it. `--dry-run` prints the
+there is no file, so `db reset` will not re-apply it. The owner policy
+`--owner` adds is not in that file either: `db reset` lists it, with its SQL,
+before it removes it — add that SQL to a migration to keep it. `--dry-run` prints the
 SQL and changes nothing. While a local migration is not in the ledger yet, a
 change is refused — `naro db push` it first, or the change would run before it.
 
@@ -233,15 +268,17 @@ Every primary key but a single `integer` one is `NOT NULL`; a foreign key must
 point at its table's primary key or a unique column. `--owner user_id` adds
 `user_id TEXT NOT NULL` and, when the backend is on and ready, an owner policy for all
 four actions; any other new table is closed to the Data API until you give it
-a policy (`naro policy create` or `naro policy set`; the command says so).
+a policy (`CREATE POLICY` in a migration, or `naro policy create` or
+`naro policy set`; the command says so).
 Policies are kept by table name: a drop removes the table's policies whenever
 the project has a backend, on or off (the command says so). A rename leaves
 them under the old name, where they apply to no table — the command prints
 what to run to move them. Move them then: the next time `naro db table`
 creates a table as that name or renames one to it, renaming the table back
 included, the policies stored under the name are removed first, so a new
-table never inherits an earlier one's (a table made by `naro db push` or
-`naro db query` gets them as they are). Whatever a command removes it prints
+table never inherits an earlier one's (except, on a project without a
+backend, one changed through `naro db table`, the table editor or MCP) — and
+neither does a table made by `naro db push` or `naro db query`. Whatever a command removes it prints
 so it can be made again: as `CREATE POLICY` statements, which
 `naro policy create` takes back, and — for owner rules, whose owner column
 `CREATE POLICY` cannot say — as the `naro policy set <table> … --owner <column>`
@@ -439,8 +476,112 @@ project's backend, then run the command again.
 
 Policies are Postgres's row-level security, as in Supabase. A table without a
 policy refuses every anon and signed-in request; the service key skips
-policies. Write them as `CREATE POLICY`, a change is live within about 10
-seconds, and `naro policy list` prints them back as SQL:
+policies. Write a table's policies in the migration that creates it —
+`CREATE POLICY` after the `CREATE TABLE`, in the same file. `naro db push`,
+`naro migration up`, `naro db query` and the MCP tools `apply_migration` and
+`execute_sql` apply them together with the table, all or nothing. Three shapes
+cover most apps:
+
+```sql
+-- migrations/0002_todos.sql: each signed-in user reads and changes their own rows.
+CREATE TABLE todos (
+  id integer PRIMARY KEY,
+  user_id uuid NOT NULL,
+  title text NOT NULL
+);
+CREATE POLICY "own rows" ON todos FOR ALL TO authenticated
+  USING ((select auth.uid()) = user_id)
+  WITH CHECK ((select auth.uid()) = user_id);
+
+-- migrations/0003_posts.sql: anyone reads, signed in or not.
+CREATE TABLE posts (id integer PRIMARY KEY, title text NOT NULL);
+CREATE POLICY "read" ON posts FOR SELECT TO anon, authenticated USING (true);
+
+-- migrations/0004_reports.sql: an app only its admins sign in to. First run
+-- naro backend auth signups off and create the admin accounts: authenticated
+-- then means exactly those accounts.
+CREATE TABLE reports (id integer PRIMARY KEY, body text NOT NULL);
+CREATE POLICY "admins" ON reports FOR ALL TO authenticated USING (true) WITH CHECK (true);
+```
+
+A migration or a query takes `CREATE POLICY`; `DROP POLICY [IF EXISTS]` (`IF
+EXISTS` skips a missing table too, as in Postgres); `COMMENT ON POLICY p ON t
+IS 'naro:owner <column>'`, which makes `p` the owner rule `naro policy set
+--owner` writes (any other comment is ignored); and `ALTER TABLE t ENABLE |
+FORCE | NO FORCE ROW LEVEL SECURITY`, which changes nothing because
+row-level security is always on. Before anything runs, naro refuses these with
+`400 VALIDATION_FAILED` "Statement <i> of <n>: …":
+
+- `ALTER TABLE … DISABLE ROW LEVEL SECURITY` — it is always on; to let
+  everyone through, create a policy: `CREATE POLICY "open" ON t USING (true)
+WITH CHECK (true);`
+- `GRANT` and `REVOKE` — every table is behind row-level security, so write a
+  policy instead;
+- `ALTER POLICY` — `DROP POLICY` and `CREATE POLICY` again;
+- a table named `public.x` in `CREATE TABLE`, `DROP TABLE` or a rename: `SQLite
+has no schema "public": write the table name without "public."`
+- a `CREATE POLICY` that reads a column inside a subquery with no table in
+  front of it, when a later statement of the same file creates, drops, renames
+  or alters the policy's table or a table its subqueries read: `a later
+statement changes a table, so name the table of every column inside this
+policy's subqueries (for example members.user_id).` Postgres decides whose
+  column it is when the policy is created; naro binds it once the file is in,
+  when the later statement may have added that name to the subquery's table.
+  A later statement that changes only other tables — the next table of a file
+  grouped table by table — leaves the policy alone.
+
+The statements of one request apply all-or-nothing, the policies with the
+tables: a policy on a table that does not exist
+(`relation "nope" does not exist`), a name already taken, or a 33rd policy on
+one table fails the whole request with `400 DATABASE_QUERY_FAILED`, names the
+statement, and applies nothing — not even the `CREATE TABLE` before it. Policy
+statements, and statements that create, drop or rename a table, take no
+`params` (`400 VALIDATION_FAILED`): write the values into the SQL.
+
+Policies go with their table, as in Postgres: `DROP TABLE` drops them, and a
+new table never inherits the leftovers of an earlier one with the same name
+(except tables changed through the table editor on a project without a backend).
+SQLite changes a column by building the table again — `CREATE TABLE
+__new_x`, copy the rows, `DROP TABLE x`, `ALTER TABLE __new_x RENAME TO x` — so
+the drop removes `x`'s policies and the rename does not bring them back. Write
+the `CREATE POLICY` statements again after the rename, in the same migration.
+A plain `ALTER TABLE a RENAME TO b` does not move them either: they stay under
+`a`, and `b` has none until you create them again.
+The answer's `warnings` lists the policies a migration removed, with SQL you
+can paste; it also says when the project has no backend yet (the policies are
+saved and apply once `naro backend enable` turns it on) and when a policy was
+applied that the Data API refuses, with the reason. `naro db push` and
+`naro db query` print each warning as `⚠ …` on stderr (`--json` has it whole
+in `warnings`, a query's in `result.warnings`).
+
+`naro db push --dry-run` parses the policy statements of the pending files on
+your machine and prints what it would refuse as `<file>: Statement <i> of <n>:
+…` (exit 1); whether a table or a policy exists is known only when the file is
+applied. `naro db pull` writes the policies that exist at the end of the
+baseline file — `ALTER TABLE … ENABLE ROW LEVEL SECURITY;` for each table,
+then each `CREATE POLICY …;`, an owner rule's column as `COMMENT ON POLICY …
+IS 'naro:owner <column>';` (a database without policies pulls as plain
+SQLite). `naro db reset` clears the policies with the schema and creates them
+again from the migration files, so a policy that exists only in the database
+is lost; it lists those before it asks, each with the SQL to add to a
+migration to keep it (an owner rule's column as its `COMMENT ON POLICY`; a
+row that cannot be read is only a comment — drop it and create it again), and
+names apart, without SQL, the policies of tables your files do not create. It
+refuses to start when the control plane would refuse one of the files.
+`naro db lint`, on a
+project with a backend, reports `rls_no_policy` (a table the Data API refuses
+entirely), `rls_policy_text_default` and `rls_policy_unindexed` as warnings,
+and `rls_policy_invalid` — a
+policy the backend cannot apply, such as one that reads a text column as true
+or false — as an error.
+
+`naro policy create` sends the same statements to the database directly: one
+in quotes, or `--file` with several, `DROP POLICY` included. Nothing records
+them in `./migrations`, so `naro db reset` removes what your files do not
+make; use it for a table that already exists. A change is live within about 10
+seconds, and `naro policy list` prints the policies back as SQL. More complete
+policies — they give each user their own todos, everyone the published posts
+and team members their team's docs, and hide deleted docs from all of them:
 
 ```sql
 -- Each signed-in user reads and changes their own todos.
@@ -560,7 +701,9 @@ policy — `naro policy create`, `naro policy drop` and `naro policy set` — wi
 `naro backend enable` uploads the current backend and turns the stored rules
 into named policies; it also turns a backend that is off back on, so run
 `naro backend disable` again afterwards if it should stay off. `naro policy
-list` and `naro policy remove` work in the meantime.
+list` and `naro policy remove` work in the meantime. A migration or a query
+that holds a `CREATE POLICY` or `DROP POLICY` gets the same answer before
+anything runs; SQL without one runs as before.
 
 `naro policy set` refuses with `409 POLICY_EXISTS` when the table's `naro_<action>` policy is not one it wrote (for example one made with `naro policy create`): `Policy <name> on <table> is not one naro policy set wrote. Change it with naro policy create, or drop it first: naro policy drop <name> --table <table>.` A `naro_<action>` policy that cannot be read as stored (the table answers `500 POLICY_INVALID`) is not refused: setting a rule replaces it, and `none` drops it.
 
@@ -584,7 +727,21 @@ pass — reads a row as it will be stored and compares it with the column's
 collation (`COLLATE NOCASE`, `RTRIM`). So:
 
 - a number column it reads takes numbers, booleans and null, not strings, and
-  cannot be compared with `like` or `ilike`;
+  cannot be compared with `like` or `ilike` — the Data API refuses a string
+  for a column that any policy of any table reads (an owner rule's own id
+  column excepted) with `400 INVALID_QUERY`. For a column whose declared type
+  has `INT`, `REAL`, `FLOA`, `DOUB`, `NUM`, `DEC`, `BOOL` or `BIT` in it, that
+  is every string — and even when no policy reads it, a string SQLite would
+  keep as text (`'abc'`, `'true'`; `'7'` is stored as 7), which Postgres
+  refuses as a type error and a policy written later would read inside out. A
+  column declared another type (`uuid`, `date`, `timestamptz`, `json`) keeps a
+  string as text, so Supabase's `user_id uuid` with `auth.uid() = user_id`
+  works; there the Data API refuses only a string SQLite would store as a
+  number (`'12'`), a string with a NUL character, and any string when a
+  policy reads the column as true or false or compares it with a number. On such a
+  column a `WITH CHECK` that orders it against a number (`<`, `>`, `BETWEEN`)
+  can judge a new text differently from the row it becomes, and `LIKE` or a
+  text function on it is refused as on a number column;
 - a primary key column it reads must be sent, and not as null;
 - any other column it reads may be left out only when it has no default or a
   plain one — `NULL`, `TRUE`, `FALSE`, a number, or a quoted string on a column
@@ -609,6 +766,39 @@ An `--update-check` you give replaces the default: without
 `user_id`. Write
 `--update-when 'user_id.eq.auth.uid()' --update-check 'user_id.eq.auth.uid(),status.eq.draft'`.
 
+## Release notes
+
+### 0.12.0
+
+- Migrations and `naro db query` take Postgres's `CREATE POLICY`,
+  `DROP POLICY` and `COMMENT ON POLICY … IS 'naro:owner <column>'` next to
+  the tables they are for (see Row-level security). `naro db reset` clears
+  the policies with the schema and creates them again from your migration
+  files; before it drops anything it checks the files as
+  `naro db push --dry-run` does, and lists the policies your files do not
+  make, with the SQL to keep them.
+- A failed `db push` keeps the server's `details.warnings` of the file that
+  failed (the policies a table rebuild took, with their SQL) and prints them
+  as `⚠` lines; the warnings of the files before it are
+  `details.appliedWarnings`.
+- **Update the CLI before you run `naro db reset`.** `naro-cli` 0.11.0
+  (published on 2026-10-05 from main `98bf538b`, PR #82) and every older
+  version know nothing of policies in migrations. On a project whose backend
+  has named policies, the control plane now drops a table's policies with
+  the table, so their `db reset` takes every policy along — without listing
+  first the ones your files do not make again, and without reading the
+  warning that names them. A table left without a policy refuses every
+  Data API request until you create one again.
+- **Check your clients before the backend updates.** The Data API now
+  refuses a string that SQLite would keep as text in a column declared with
+  INT, REAL, FLOA, DOUB, NUM, DEC, BOOL or BIT (a form's `"true"` for a
+  BOOLEAN, `"high"` for an INTEGER), even when no policy reads the column.
+  The backend worker takes this on at the project's next deploy or
+  `naro backend enable`, not when naro itself updates. Before that, look for
+  such rows: `naro db query "select count(*) from t where typeof(c) = 'text'"`
+  for each number or boolean column — a count above 0 means a client writes
+  strings there and needs fixing first.
+
 ## Machine-readable output (CI / AI agents)
 
 Every command supports `--json`: stdout carries exactly one JSON object,