SYSTEM Cited by 1 source

Vitess table ACL

What it is

The Vitess table ACL is Vitess's native authorization mechanism: a static JSON configuration file read by each vttablet at boot, declaring which MySQL usernames are permitted to read, write, or administer a given set of tables. Configured via vttablet's authorization documentation.

Schema (from the PlanetScale Password Roles post):

{
  "table_groups": [
    {
      "name": "planetscale user groups",
      "table_names_or_prefixes": ["%"],
      "readers": ["planetscale-reader", "planetscale-writer", "planetscale-admin"],
      "writers": ["planetscale-writer", "planetscale-writer-only", "planetscale-admin"],
      "admins": ["planetscale-admin"]
    }
  ]
}

• table_names_or_prefixes — list of tables the policy applies to; % is all tables.
• readers — users permitted to read data + schema from tables in the group.
• writers — users permitted to write data.
• admins — users permitted to read, update, and alter schema.

The file is consumed at vttablet startup and optionally reloaded from disk at a configurable interval via the --table-acl-config-reload-interval flag. That reload is the only path for ACL state changes to reach a running pod.

Why it shows up on this wiki

The mechanism is static by design — it targets deployments where:

1. The set of MySQL usernames is pre-defined and slow-moving.
2. There is a small number of ACL files (typically one per Vitess cluster, not per tenant).
3. ACL updates can be scheduled into a maintenance window.

Those three assumptions break under managed multi-tenant use: the PlanetScale Password Roles post enumerates four concrete failure modes that pushed PlanetScale to architect around the mechanism rather than extending it:

• Refresh-interval latency vs a "credentials work immediately" user story.
• Per-pod race conditions where the same credential resolves to different roles on different pods during rollout.
• Pod-restart has no authoritative source — the local ACL file is lost with the pod, and there's no cluster-level store to consult before the pod rejoins.
• Per-customer state explosion — a single static file per cluster can't encode per-tenant credentials.

PlanetScale's resolution keeps the ACL file invariant across every customer database — three synthetic usernames (planetscale-reader, planetscale-writer, planetscale-admin) mapped universally — and moves all per-tenant dynamism into an external credential store consulted by the user query frontend, which rewrites the security principal on the fly before the query reaches vttablet. This shape 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 of the table-ACL mechanism's configuration schema + static-refresh model, and the four reasons it's a bad fit for a managed-database product.

Related

• systems/vitess — host platform.
• systems/planetscale — managed-database consumer that works around the static model.
• systems/planetscale-user-query-frontend — the ingress service that rewrites the principal so the ACL file can stay invariant.
• systems/mysql — wire-protocol principal being ACL-checked.
• concepts/table-group-acl — the underlying authz model (table-group + readers/writers/admins).
• concepts/external-credential-store — design primitive PlanetScale layers above the static file.
• patterns/external-credential-store-with-principal-rewrite — the pattern that composes this mechanism with dynamic per-tenant credentials.