Skip to content

CONCEPT Cited by 1 source

Credential / Route / Endpoint triple

Definition

The Credential / Route / Endpoint triple is PlanetScale's canonical data model for separating the three concerns that arise when admitting a database connection at a globally distributed edge:

  1. Authentication (proving the caller is who they say they are) — Credential
  2. Routing (which DB cluster the caller should be sent to) — Route
  3. Naming (which hostname the caller uses to reach the edge) — Endpoint

Each concern has a different physical residence — auth stays local to the origin DB region, routing is replicated globally, naming is DNS-resolved — giving the composite admission flow a clean control/data plane split implemented by where the record lives rather than by control-channel semantics alone.

The three records

Canonical definitions from PlanetScale's 2024-04-17 Global Network launch post (Source: sources/2026-04-21-planetscale-introducing-global-replica-credentials):

Credential

Authoritative auth record. Lives only inside the origin DB cluster's region — never replicated to the edge. Verified against the password the client presents during MySQL handshake.

enum TabletType {
  TABLET_TYPE_UNSPECIFIED = 0;
  TABLET_TYPE_PRIMARY = 1;
  TABLET_TYPE_REPLICA = 2;
  TABLET_TYPE_RDONLY = 3;
}

message Credential {
  string branch = 1;
  bytes password_sha256 = 2;
  psdb.data.v1.Role role = 3;
  fixed64 expiration = 4;
  TabletType tablet_type = 5;
}

The tablet_type enum is Vitess-derived and dictates the intended backend class (primary / replica / read-only). This is how a single credential is tied to read-only workloads without requiring application-side primary/replica routing — the server's admission logic enforces the tablet class.

Route

Username → cluster-list mapping. Replicated to every edge region. Carries no authentication information — it's safe to distribute widely because leaking it gives away no secrets. Verbatim: "this Route contains no authentication information and is not authoritative for auth, it is effectively a mapping of username to a list of clusters. This list of clusters covers where this database branch is running."

message Route {
  string branch = 1;
  repeated string cluster = 2;
  fixed64 expiration = 3;
  ...
}

Example shapes:

  • Primary-only credential: Route(branch="abc123", cluster=["us-east-1"])
  • Multi-region replica credential: Route(branch="abc123", cluster=["us-east-1", "us-west-2"])

The Route is the substrate for per-query next-hop routing: at each edge node, the cluster list is kept sorted by measured latency via mesh latency health-check; the next-hop decision is always clusters[0]. Adding or removing a read-only region is a single-record mutation against the Route in etcd.

Endpoint

The hostname the client connects to. Does not live in etcd — it lives in DNS. Two shapes:

  • Direct: {region}.connect.psdb.cloud — a specific edge region.
  • Optimized: {provider}.connect.psdb.cloud — e.g. aws.connect.psdb.cloud, gcp.connect.psdb.cloud — backed by latency-based DNS routing (Route 53 latency policy on AWS). Resolves to the edge region with the lowest measured latency to the client's resolver.

Why the split matters

  • Credential stays local → security. A compromised edge node cannot leak auth material; it has none. Private keys, password hashes, role grants are all pinned to the origin DB region. The edge is a routing / pooling layer, not a trust boundary for auth.
  • Route goes global → routing performance. Every edge node can resolve username → cluster-list locally without cross-region lookups on every connection. Mutation via etcd watch gives near-realtime propagation (patterns/etcd-watched-route-mutation).
  • Endpoint is DNS-resolved → reduces client configuration burden. The client doesn't need to know which edge region is closest; the DNS layer handles that.
  • All three compose to give per-query lowest-latency routing without reconnection. The edge owns the session, the Route tells the edge which clusters to consider, the sorted cluster list picks clusters[0], the DNS endpoint got the client to the right edge in the first place, and the Credential at the origin gated the initial handshake.

Seen in

  • sources/2026-04-21-planetscale-introducing-global-replica-credentials — canonical wiki disclosure. Matt Robenolt + Iheanyi Ekechukwu describe the data model at protobuf level and walk through how the three records compose to let a single global replica credential route reads to any read-only region without the application observing a reconnection.
Last updated · 378 distilled / 1,213 read