Supabase Made Crystal Clear · chapter 2: Architecture: One Postgres
One request, end to end
2026-10-02
Lane A is the browser with a publishable key and a user JWT: key check, role switch, grants, RLS, one SQL statement. Lane B is your server with the secret key: same path, but the role becomes service_role and the RLS gate is skipped.
Below: the paragraph from the book that builds this idea, then the diagram itself (Figure 2.2), and a recap. About a minute of reading.
PostgREST connects to the database as a single, deliberately weak role called authenticator. The PostgREST docs describe it as "a chameleon whose job is to 'become' other users to service authenticated HTTP requests." For each request it runs SET LOCAL ROLE to the role named in the JWT (authenticated here, anon when there is no user) and translates the URL into exactly one SQL statement. "The REST API resolves all requests to a single SQL statement." Postgres then applies two gates in a fixed order: "Postgres evaluates table grants first, and only then applies Row Level Security." A missing grant fails loudly with error 42501; a policy that matches no rows fails silently with an empty array. Figure 2.2 lays the whole path out, with a second lane for a server holding the secret key.
Recap
- The idea: Lane A is the browser with a publishable key and a user JWT: key check, role switch, grants, RLS, one SQL statement.
- The picture: Figure 2.2, from chapter 2 ("Architecture: One Postgres") of Supabase Made Crystal Clear.
- Go deeper: the chapter builds this step by step, with recipes and sources at the end.
This diagram is one of many in Supabase Made Crystal Clear.
Every chapter opens with the gist, draws the hard ideas, and ends with recipes and sources.
Get the book
