Speed and limits
Speed
core/bench/benchmark_results.txt (benchmark.sql): 200,000 files, 10,000 folders, 2,000 users, nested teams, 500 linked folders; JIT off. Measured on 2026-11-09 on one of GitHub's runners (4 CPUs, 128 MB of shared buffers: a shared machine) by core/bench/benchmark.sh, from main at 0.1.0-dev.
The scale benchmark's figures below come from two kinds of machine. main at 0.1.0-dev ran it on GitHub's runners on 2026-11-14 and 15 (4 CPUs and 16 GB, shared by the server and pgbench; gh workflow run nightly.yml -f only=scale): what this build does, given as a range, since one runner was up to three times slower than another half an hour later. The laptop the project was developed on until 2026-10 (16 CPUs, nothing else running) ran it on 2026-10-03, with a build from before the rename (rowfence 0.1.0-dev): the last runs on a machine of its own, which is what the scale gate's limits are for.
| median | ms |
|---|---|
| open one file, prepared statement | 1.2 |
| open a folder (20 files), prepared statement | 1.3 |
authz.can('file', id, 'edit') | 0.4 |
| list every visible file (11k to 53k of 200k) | 42 |
| apply the policy, backfilling 10,000 folders | 1,480 |
| move a folder holding 3,441 subfolders (inside the tree) | 490 |
The scale benchmark (core/bench/scale.sh --large: a million files, 50,000 folders, writes arriving while 400 reads a second are served) moves the folder with the most below it, 16,000 to 19,000 folders, into another root in 0.7 to 1.0 s on a runner, and in 0.56 to 0.62 s on the laptop. Reads through the rules, beside the writes, have a p95 of 4.6 to 13.8 ms on a runner and of 3.2 ms on the laptop (core/bench/README.md).
At twenty times that (scale.sh --full: 20 million files, a million folders, 40,000 users; 22 and 15 million rows of inheritance in a 6 GB database) the laptop, with 8 GB of shared buffers, had reads at a p95 of 4.3 to 4.6 ms and tree writes at 28 to 38 ms. The folder with the most below it, 54,000, moved in 2 to 3.7 s. Applying took three minutes there (the backfill), and authz.verify() two and a half. A runner runs that size to the end too (2026-11-14: no write failed, authz.verify() said true after them, applying took five minutes and verify four), but its 16 GB are too few for 8 GB of shared buffers beside a 6.5 GB database: reads there had a p95 of 38 ms, which says what the machine lacks. A server shared with other work (12 CPUs, 47 GB) ran it to the end as well on 2026-11-15, with this build: no write failed, and authz.verify() said true after them. That server is two to three and a half times slower than a runner at the smaller size with the same build, so its figures at this size are its own: reads alone at a p95 of 17 ms, 44 to 74 tree writes a second, the folder with the most below it moved in 9.4 s. The laptop's figures are still the last from a machine of its own.
JIT is off in signed-in transactions (Signed sessions): with JIT on, Postgres spends about a third of a second compiling each large read through RLS (on the laptop of 2026-10-03, the list above took 290 ms instead of 32), since the rules' lookups are estimated once per row. Applying analyzes the tables the policy reads that were never analyzed: a table never analyzed is planned as ten pages of rows (6 rows as thousands), and a read of it as one JIT compiles. The audit trail and change feed add about 20 µs per changed row (10,000 owner changes: 358 ms instead of 163 ms). The feed also looks up what reads the objects a write changed, a thousand objects of a type at most: on the docs app a member leaving a team or a share on a folder takes about half a millisecond more (0.8 ms instead of 0.3), a folder moved or made to stop inheriting 1.5 to 2 ms more; with 300 folders and 2,000 files below the folder, 4.5 ms more, where the files pass a thousand and the feed says {*} for them. An update of a column no rule reads (a folder's or a user's name) announces nothing and looks nothing up: about 0.1 ms (measured 2026-10-29).
Limits
One database. Everything lives next to the data, so it scales with that Postgres. Across shards, run the same policy in each shard and keep an object's whole tree (and its groups) on one shard; cross-shard inheritance isn't supported.
Nested groups are expanded per query, walking up from the user's own groups: with 20,000 teams in chains ten deep, opening a folder given to the top of one takes 1.9 ms (1.4 ms with chains one deep) and
authz.can0.2 ms (benchmark.sql). A stored closure would only pay off for much deeper or wider nesting, and couldn't honour expiring shares.A read costs what its reader holds. A rule looks the object's ancestors up among the folders where the reader's permission starts (the ones they own, are shared, or reach through a team), and that set is worked out for each query. On GitHub's runners (2026-11-15, with 50,000 and with 250,000 folders) a reader who holds 4,000 folders opened a folder in 2.1 to 3.4 ms where one who holds 100 took 1.3 to 1.9 ms on the same machine: 1.7 to 1.9 times, or 0.2 to 0.4 ms for each thousand folders held (
core/bench/README.md, step 6). How a reader comes to hold them counts for more than how many. An ordinary member of the benchmark, whose folders come through nested teams, ownership and shares at once, opened a folder 2.0 to 2.1 times slower than an org's admin in the same runs: access through one membership of something big costs nothing of the kind, and the admin, who reaches every folder, reads faster than any member. This is the design's cost, and it stays. The other way, testing the object's ancestors one by one against each place a permission can start, was built and measured on 2026-11-15: opening a folder took 1.1 to 3.6 times longer, for every reader. A rule is checked for each row, the 20 files of a folder share their ancestors, and Postgres carries no answer from one row to the next; and one object alone, checked that way, is about 190 lookups, which cost what building 4,000 starting places costs. The set built once for a query is what serves a read of many rows. The earlier figure here (4.5 to 5 ms against 1.3 ms, "about a millisecond per thousand") was one ordinary member of the run of 2026-10-03: it measured how that member's folders reach them, not their count.Reads through the rules run on one CPU. rowstile's functions aren't marked parallel safe: a session's signature is bound to its backend, which a parallel worker isn't. So Postgres never splits a read through the rules between workers: counting 200,000 files took 28 ms through them, 5.5 ms as the owner with two workers. Marking them would not be enough. A rule's lookups sit under an
or, where Postgres plans each one to run row by row for a few rows and hashed for many, and a lookup that may run row by row holds the whole query to one CPU, on 16, 17 and 18 alike. Written asIN, which is only ever hashed, counting 400,000 files on 17 took 2 workers and 87 to 197 ms instead of 149 to 324, but opening one file took 8 to 73 ms instead of 1.5 to 4.4, so the rules keep the lookups that serve opening a file.An app's own search runs after the rules, unless Postgres knows it reveals nothing. Postgres checks a table's rules before any condition of the query that isn't marked leakproof, so that such a condition sees no row the rules hide.
LIKE,ILIKEandlower()aren't: their index goes unused, and worse, Postgres estimates few rows from the search and so checks the rules row by row, over every row. On the docs app with 400,000 files,lower(name) LIKE 'file\_1234%'took 0.07 ms as the owner, through its index, and 2.1 s as an administrator, 8.5 s as a user who sees a quarter of the files;lower(name) = ...and a trigramILIKEdid the same. Equality and ranges on a column itself are leakproof and keep their index:name >= 'file_1234' AND name < 'file_1235'took 2.6 and 6.4 ms. At 20 million files the gap grows:lower(name) LIKEtook 184 s as an administrator and over ten minutes for users who see a few hundred thousand files, the range 13 to 38 ms. So search on a column with=or a range (a generated column holdinglower(name), say), or narrow the search first by such a condition (a folder, an owner).A big policy needs room in Postgres's lock table. Applying it whole (or a first migration) takes a lock on each object it makes, in one transaction, and the table holds
max_locks_per_transactionfor each connection: 6,400 by default. GitLab's thousand tables, drafted byrowstile init, make about 45,000; applying stopped after two and a half minutes with "out of shared memory", and took 163 s withmax_locks_per_transaction = 1024.rowstile applywarns before it starts and names the value to set (a restart; on managed Postgres, a parameter).The sync index (a preview, The sync index) can't take back what a device holds. Revoking stops delivery: rows already on a device stay there while it is offline, and in any copy a client keeps, until the engine tells the client to delete them when it next syncs (Electric's move-out, which its own
Shapeclass doesn't apply: Electric). The window after a change is the engine's replication lag, and for a share that ends, until the nextauthz.sync_tick()too. Conditions on who asks or the clock, conditions that read other rows, caveats, links, scopes and masked columns can't go through: compiling refuses the first three, the others give nothing through it. The engine is trusted: it holds BYPASSRLS and every row, and rowstile can't check what it serves. The index costs writes. Copied in (the default), a move works out again the readers of every row below the moved folder and of their files, a share those of what reads its object, a membership change the member's keys alone. Keyed by folder, a move writes what the folders below it inherit, a share on a folder one row of what it gives itself, and a membership change the member's keys, as copied in. After commit, the writer writes a note, and the worker the rest. On the scale benchmark's dev size (400,000 files in 20,000 folders 20 levels deep, 1,000 users, 100 teams; measured 2026-11-01, one after the other, on a shared machine whose load went from 10 to 60 on 12 cores, Postgres 16, 128 MB of shared buffers, each write and its undoing, after aVACUUM; the earlier layout keyed by folder, in which each principal held the key of every folder it may read, measured beside it):copied in keyed by folder keyed by folder, the earlier layout after commit, keyed: the writer; the worker the index 12.7 million readers rows for the files, 627,000 for the folders, 12,821 keys (13 a user); 1.4 GB 1.2 million for the files, 20,000 for the folders, 12,821 keys (13 a user), 92,000 rows of given and 766,000 of inherits; 0.27 GB 1.2 million for the files, 20,000 for the folders, 10.4 million keys (9,864 a user, 40,021 the most), 1.0 million rows of the groups; 1.6 GB as keyed worked out whole (the first apply) 387 s 67 s 519 s 66 s a move of a folder with 100 folders and 2,000 files below, and back 2.7 s, 1.8 s 0.28 s, 0.36 s 3.0 s, 1.1 s 0.17 s, 0.14 s; 0.16 s, 0.22 s ... with 950 folders and 19,000 files 18.5 s, 12.2 s 1.1 s, 1.6 s 8.5 s, 5.2 s 0.33 s, 0.40 s; 0.84 s, 1.1 s ... with 9,400 folders and 189,000 files 150 to 350 s (measured 2026-10-31) 11.6 s, 11.3 s 40.8 s, 55.2 s a share on a folder with 950 folders below, and its revoke 8.7 s, 8.5 s 0.09 s, 0.09 s 1.5 s, 3.4 s 0.09 s, 0.06 s; 0.07 s, 0.09 s ... with 9,400 folders below 0.11 s, 0.09 s 16.4 s, 32.0 s a member joining a team, and leaving 0.10 s, 0.08 s 0.09 s, 0.07 s 0.19 s, 1.8 s 0.08 s, 0.05 s; 0.05 s, 0.05 s a file made 0.12 s 0.06 s 0.07 s 0.05 s; 0.06 s the engines' filter of the files, as Postgres runs it: a user who reads 211,000, an org admin (all 400,000) 0.84 s, 1.0 s 0.90 s, 3.5 s 0.40 s, 1.3 s 0.46 s, 2.3 s authz.sync_verify()179 s 32 s 266 s 33 s Keyed by folder trades the files' readers for two tables the engines' filter joins through: what a folder's key inherits and what each folder gives itself. A principal holds its own and its groups' keys, as copied in, but its filter reaches the key of every folder it may read through them (the user above, 22,000 rows of inherits), and a key every folder gives, as an org's admins through each folder's org, once for each folder above each one: an org admin's filter reads every row of inherits, 766,000. Right after the first apply, before autovacuum has run, a write that reads many of the index's rows can take forty times as long: run
VACUUMon its tables after it.Identity providers: users and groups come by SCIM, which the database answers (Identity): the FastAPI and the Next.js SDKs have the route, the other SDKs not yet, and it serves no Bulk, no sorting, no ETags and no password change. A JWT's signature is checked in plain SQL: HS256, or RS256 against the provider's stored keys, which takes about 2 ms a sign-in with a 2048-bit key, 4 ms with a 3072-bit one and 7 ms with a 4096-bit one, the first time a connection sees the token; the same token there again takes 0.3 ms, as an HS256 token does. Tokens signed another way (ES256, EdDSA) are refused, since a check of ES256 written in plain SQL took 12 ms: verify those in your backend and sign in from there (Identity), or use an API key.
Writes cost more: each closure table is maintained on every tree write. A tree write locks what it touches: the rows it changes with everything below them, and the rows those hang under. So two writes to different parts of a tree don't wait for each other. Two that meet wait in READ COMMITTED; in REPEATABLE READ and SERIALIZABLE the later one fails with a serialization error, to retry. The locks are a fixed number of rows for each type (1,024, by a hash of the row's id), so now and then two unrelated writes meet on one, and one waits as if they were related. A write of more than 1,000 rows takes its whole type instead, and the other tree writes to that type wait while it runs; so does every tree write to a type that inherits through another type too, or whose inheritance condition reads other rows. The number is a setting the owner writes:
INSERT INTO authz.settings VALUES ('tree_lock_limit', '5000')(0: every tree write takes its whole type). In SERIALIZABLE every tree write takes its whole type, whatever the setting. There Postgres holds on to what each transaction read until every transaction beside it ends, and many tree writes running side by side filled the server's room for that (out of shared memory, an error no app retries). One at a time, sixteen writers held a fifteenth as much and did as many writes. Inheritance conditions that read other tables are re-evaluated for every row of the type when those tables change (and when a statement writes rows of the type's own table, if a condition reads it). A move rewrites one row per folder below it and per ancestor it gains or loses. If a link leads from inside the moved part back to the folder's old or new ancestors, everything below is recomputed instead, which is several times slower.Privileges: what the policy reads (relations, and
{conditions}in permissions, rules and caveats) it reads with the privileges of whoever applied it, wherever it is checked. A condition on the row's own columns is written into the rules as it is; one that may read other rows (a subquery, a function other than a built-in that reads nothing, however its name is written, or an operator Postgres doesn't have for its own types) is called as a function per row the rules check, which costs more on large reads than the same test written as a relation. One exception: a function or operator of the app's that has a built-in's name, in a schema on the search path (an overload oflower, an=for one of the app's types), is read as the built-in: written into the rules as it is, it runs there with the app role's privileges.A write rule sees the tables as the statement found them. Postgres checks each row an
INSERTorUPDATEwrites as it writes it, and a rule's condition, relation or permission reads the tables as they were before the statement: the statement's other rows aren't there for it, those of aWITHquery in the same statement included, and neither are rows another transaction hasn't committed yet. So a rule that holds while rows are missing (not exists (...),count(*) < 2, a permission that holds while a chat has nobody in it) is checked for each row on its own. Withinsert : {(select count(*) from app.seats s where s.room_id = this.room_id) < 2}, a third seat added alone is refused, but oneINSERTof three rows into an empty room writes all three. Two transactions at once, each adding one seat to a room that has one, do the same, unless both are SERIALIZABLE: then one of them fails, to retry. A limit on how many rows there may be (two people in a direct chat, one owner of a group) belongs in the schema, which holds it for every statement and every transaction: a unique index (CREATE UNIQUE INDEX ON app.members (chat_id) WHERE role = 'owner'), or a trigger that counts after the statement and a unique key that two transactions at once can't both write, as the messenger example does.Partitions go through their table: apply turns row-level security on, with no rules of their own, for the partitions of a governed table and the tables that inherit from it, so the app role reads and writes them only through the table (whose rules and triggers are on it). Postgres runs a table's statement triggers only for statements on that table, and it copies the table's row triggers to its partitions, not to a table that inherits from it (
CREATE TABLE ... INHERITS). So apply gives the partitions and the inheriting tables of each table it keeps triggers on (one with rules, a tree's table, a link table, a table a condition reads) the triggers of the table above: a statement on one of them, the owner's too, keeps inheritance, shares and the audit current, and a rule on a column is checked on the rows stored there. A partition made after apply has its table's rules and row triggers from the start, for what is read and written through the table; read directly, it is open until the next apply or migration if the app role was given it, and a statement on it runs none of the table's statement triggers until then. A table that inherits, made after apply, has neither until the next apply or migration.authz.lint()reports both, androwstile applythen applies (it does not answerunchanged). Truncating a partition, or a table that inherits, removes the shares, API keys and pending requests of the rows it empties, and rebuilds the trees they are in. The audit has one line for it, naming the table emptied, and the change feed announces every object of the type. A PowerSync mirror of the sync index follows it (The mirror).authz.lint()reports an app role that may do it. Dropping or detaching a partition runs no trigger at all: until the next apply, the shares of its rows stay, and a row made later with one of their ids gets them. An inheritance table whose table, or link table, has other tables under it than at the last apply (a partition attached, detached, made or dropped, a table that inherits made or dropped) is computed again by the next apply, not kept, androwstile applythen applies: rows that reached it so, or rows written straight into a partition made since, are in it after that apply. The next migrationrowstile migratewrites computes it again too, even where the policy didn't change it.A key handed over inside one update of a partitioned table: a row's shares are forgotten when its key changes, so a row that has the key later starts with none. Where the update also puts the row in another partition, rowstile forgets the shares of every key the update left without a row; if the same update gives that key to another row (two rows swapping keys, which takes a deferrable key), the shares stay with the key. And the audit has no line for a relation column changed by an update that changes the row's key and its partition at once.
A rule on the row after a change, on a table with a generated column: such a rule (
update folder_id after : folder.edit) is checked before the update, so it speaks before Postgres's own checks on the row do (a unique index, a foreign key), whose errors tell of rows the user may not see. Postgres works a generated column out after that. So on a table that has one the rule is checked once the row is written, and those checks speak first:authz.lint()names those tables. A table that inherits goes by its own columns. Where such a table is partitioned and the update puts the row in another partition, Postgres runs no trigger on the row after it: rowstile asks the rule when the statement is done, of each row it left with other values in the rule's columns than the row that had its key. Where the update changes the row's key too (a table partitioned by its key), the row is compared with the one key the update left without a row. Where one update gives several rows new keys, which was which can't be told, and the rule is asked of each of them, whether or not its columns changed. Asked so, the rule answers for a row the user may select, as an explanation does: there, an update that changes the rule's columns and hides the row from who makes it is refused.A key two rows hold, through a table that inherits: a table's primary key doesn't cover the rows of a table that inherits from it (
CREATE TABLE ... INHERITS), so a row there may have the key of a row of the table. rowstile sees one object with that key, and a permission holds on it where it holds on either row:authz.can,perms,explain,whoandauthz.listanswer so, as the rules do. Where two such rows aren't meant to be one object, keep their keys apart (one sequence for both tables).A foreign key's action skips the rules: Postgres runs
ON DELETE CASCADE,ON DELETE SET NULLorSET DEFAULT, andON UPDATE SET NULLorSET DEFAULTwithout row-level security, so deleting a row (or changing its key) can delete or change rows of a governed table that the user may not. Apply warns of each such foreign key on a table with rules: useRESTRICT, or say that it is meant withcascade fromunder the table's rules (the language).ON UPDATE CASCADEis no warning: the row still names the same row, by its new key.Link rows are trusted as they are: a row in a link table (
team_members,folder_teams) grants what it says even when the object it names was deleted. Give link tables foreign keys to their objects withON DELETE CASCADE(andON UPDATE CASCADEfor keys that change), as you would anyway; on a link table with rules of its own, apply warns of the cascade (above) until acascade fromline says it is meant. Shares are removed with their objects by rowstile. (A type with awherelooks its rows up, so a leftover row naming one of its objects counts for nothing; don't rely on it.)A permission named many times over is slow to plan. Each permission is a view, and Postgres writes a view out in full every time a query names it, again for each view it names. A rule that reaches another type's permission (
folder.view), which names others more than once, which do the same, multiplies: the policies in this repository make Postgres write out at most a dozen views for a read, and at around a hundred, planning alone takes a tenth of a second and more for every query, before a row is read, up to a second or two.authz.lint()warns about each permission that makes it write out more than fifty, whether a rule names it or onlyauthz.listandauthz.cancheck it. Tiers that include each other and inherit from the row above don't multiply: withcan edit = owner or editor or parent.editandcan view = edit or viewer or parent.view,viewlooks upparent.viewalone, which includesparent.edit, so each type in a chain adds the same few views. A query that joins tables pays for each of them. Planning is paid by every query that isn't a prepared statement. One that is gets planned in full its first five runs on a connection, and then Postgres usually keeps the plan: a read that took 13 ms to plan took 0.1 ms from its sixth run. The plan Postgres settles on then (a generic one) serves every user as well as the first: the rules read who is signed in when the query runs, not when it is planned, so a plan is made alike for a user who sees a few rows and one who sees them all. A generic plan changes what the app's own parameters change: on the docs app with 400,000 files, and on the scale benchmark's 20 million, a count, a page of a folder and one file took the same time either way, within a run's noise, for an administrator and for users who see a few hundred thousand files. A parameter that hides how many rows match costs more, though. Postgres then guesses many, and may check the rules against the reader's whole set at once rather than row by row. At 20 million files, a search by range (name >= $1 AND name < $1 || '~') found one file in 13 ms for an administrator with a plan made for its value, and in 0.93 s with the generic plan; for users who see 100,000 to 400,000 files, 20 to 28 ms against 98 to 128 ms. The owner's query took 2 ms either way. For such a query,SET LOCAL plan_cache_mode = force_custom_planin its transaction keeps a plan made for each value. Whether queries are prepared is the driver's doing, not the policy's. asyncpg and postgres.js prepare every query, and psycopg one it has run five times. node-postgres prepares only a query given aname, and Prisma'spgadapter only with itsstatementNameGeneratoroption: without them, each query is planned anew. So is every query behind a pooler that keeps no prepared statements, where the drivers are told to make none (Behind a pooler).authz.lint()warns when a table's select rule passes 50 (applying shows it). Name each permission once on the way:can edit = owner or editor,can view = edit or viewer, notviewwritten out again inside three others. The same name twice in oneandororcounts once.Composite keys cost more to check than single-column ones: ids are built as text per row (20,000 folders keyed
(org_id, id): a list of 7,000 takes about 0.4 s). The benchmark gate is measured on single keys. Rows are looked up by each column of such a key, so an index on the columns serves the lookup (rowstile indexesnames it).A
(type, id)pair whose id is one column is found by its type: its id is read through aCASEon the type, which no index serves. An index on(type, id)(whatrowstile indexesasks for) finds the rows of that type, and each of them is read. Where most rows name one type, that is most of the table.prove and the review read text as ICU's root collations do. Two texts a column may hold as one value (the same but for case, accents, spaces or punctuation, numbers written two ways, the same words in another order) are left to the database there. A collation made for a language, or built from rules, may hold more texts as one value: Lithuanian holds
'ylp'and'ilp'alike. For a column under such a collation, the database is the check:authz.check_invariants()on its data, and the review's access part on a review database.
What a 0.x release promises
rowstile 0.1.0 is in beta: complete enough to use before it is released, and it may still change where using it shows a need. Until 1.0, a minor release (0.1 to 0.2) may change the policy language, the authz.* functions, the SDKs, the error codes and the file formats (rowstile.toml, the lock file). What it does keep:
- Each release from 0.1.0-beta.1 on upgrades from the one before it: a database applied by 0.1 is migrated by 0.2, and the suites test it. Skipping releases is tested each night too, from every release on PyPI from the beta on, but it is not promised.
- The beta starts afresh: a database an alpha (0.1.0-alpha.9 or earlier) made is not upgraded. Apply the policy from scratch: on a new database, or on the same one after
rowstile remove --yes, thenrowstile apply(shares and history stay through remove). The upgrade tests start from the beta too. - The changelog says what changed, and its Upgrading says what to do: a policy line to rewrite, a call to rename, a migration to make.
- A patch (0.1.1) only fixes. Nothing to do when upgrading.
- Security fixes go into the newest version only: the next pre-release while no final release exists, a patch after that (SECURITY.md).
What 1.0 promises is decided before 1.0, and this section is replaced by it.