Core concepts

Organizations, workspaces, agents, connections, and managed databases — the nouns used throughout Relay and how they relate.

A handful of nouns appear everywhere in Relay. Learn these once and the rest of the product follows.

Organization

The top-level tenant. Everything — billing, members, roles, workspaces — belongs to an organization. A user can belong to more than one. Your plan and its entitlements are set at the organization level.

Workspace

A scope within an organization for isolating environments or teams (think staging vs production, or per-team boundaries). Databases, connections, agents, and policies live in a workspace. Access is gated per-workspace: holding a role in the organization does not, by itself, grant access inside a workspace — see RBAC.

The organization → workspace hierarchy mirrors the Kubernetes cluster → namespace model. Workspace membership is meaningful: you must be granted a role in a workspace (or be an org admin/owner) to act there.

Managed database

A Relay-operated database cluster — an engine (PostgreSQL today), one or more nodes, provisioned into a provider and region. Relay owns its lifecycle: backups, metrics, users, logical databases, parameters, scaling, and restore. See Managed databases.

Connection

A pointer to a database Relay governs access to — often one you already run. A connection records where the database is and how to reach it. Its password is either stored in Relay, encrypted at rest, or resolved at connect time from your credential source, in which case Relay stores only the reference. Connections can be grouped to share policy and access.

Agent

A lightweight process that brokers the actual database traffic: when a member connects, the agent opens a local proxy, applies masking and policy, and forwards queries to the real database. An agent runs as one or more replicas. Relay runs the replicas of managed agents. You run the replicas of self-hosted agents, for example inside your own network. See Agents.

Tunnel

A live, masked session established through an agent — what you get when you run relay connect. Your database client talks to a local port; the agent applies column-level masking and policy before returning results.

Putting it together

Organization
└─ Workspace (e.g. production)
   ├─ Managed databases        ← Relay operates these
   ├─ Connections              ← your existing databases, governed
   │  └─ resolved via a Credential source
   ├─ Agents                   ← broker every connection
   └─ Policies · Masking · Grants · Audit   ← applied uniformly