CONCEPT Cited by 1 source

Table-group ACL

Definition

Table-group ACL is a database-authorization model where tables are bucketed into named groups (by exact name or name-prefix pattern) and each group carries three user-list roles: readers, writers, and admins. A query is permitted if the connection's authenticated principal is listed in the role-appropriate bucket of the group that matches the table it touches.

The canonical reference case on this wiki is Vitess's table-ACL mechanism, whose JSON configuration file is disclosed in the PlanetScale Password Roles post:

{
  "table_groups": [
    {
      "name": "planetscale user groups",
      "table_names_or_prefixes": ["%"],
      "readers": [...],
      "writers": [...],
      "admins": [...]
    }
  ]
}

The three roles are coarse-grained and partially overlapping — writers typically includes all readers, admins typically includes all writers — but the model is defined by union of user-list membership, not by role inheritance. Each user-list is independent; the post's example puts planetscale-writer in both readers and writers explicitly rather than deriving it.

Properties

• Static by default. The role-user mapping lives in a configuration file evaluated at query-check time; updates require re-reading the file.
• Coarse-grained three-role set. Reader / writer / admin, not fine-grained RBAC. Sufficient for table-level access control; too blunt for row-level or column-level authorization.
• Union-based membership. Adding a user to a role is a simple list-append; no hierarchy to reason about.
• Principal-centric. The ACL check evaluates the connection's wire-protocol principal, making the model composable with ingress-layer principal rewrites — the downstream ACL evaluates against whichever principal the ingress produced.

Why it shows up on this wiki

Table-group ACL is worth its own wiki concept because it is the authorization substrate PlanetScale builds their per-password roles on top of — and, more importantly, the shape of static, file-based authorization that breaks under multi-tenancy. The four failure modes the Password Roles post enumerates (refresh- interval latency, per-pod race conditions, restart-state loss, per-customer state explosion) are not specific to Vitess; they apply to any system whose authorization is a static file loaded at boot. The fix — store per-tenant credentials in an external credential store and keep the table-group ACL file invariant — generalises accordingly, and is canonicalised as the external-credential-store-with-principal-rewrite pattern.

Seen in

• sources/2026-04-21-planetscale-behind-the-scenes-how-we-built-password-roles — canonical wiki disclosure: the Vitess JSON schema, the three-role model, and the static-refresh semantics that drove PlanetScale's architectural workaround.

Related

• systems/vitess-table-acl — canonical working implementation.
• systems/vitess — host platform.
• systems/planetscale — managed-DB consumer that consumes + sidesteps it.
• systems/mysql — wire protocol for the authenticated principal being ACL-checked.
• concepts/external-credential-store — design primitive that lifts dynamic per-tenant credential state out of the static-ACL file.
• concepts/on-the-fly-security-principal-rewrite — the ingress-level primitive that makes a static table-group ACL compatible with dynamic per-tenant credentials.
• patterns/external-credential-store-with-principal-rewrite — full pattern that composes this concept with the other two.