feat(middleware): ship withPostgresClient and withPostgresAdminClient (#115)

* refactor(middleware): rename withPostgres to withPostgresClient and harden it

Renames the export to sit alongside withSupabaseClient /
withSupabaseAdminClient, and extracts the pool into a shared core module so
the service-role companion can reuse it. Safe to rename now: the old name
exists only on 1.5.0-rc.* / beta, never on a stable release.

Three correctness fixes alongside it:

- The pool cache was keyed on nothing, so a second connectionString in the
  same process silently queried the first database. Now keyed per string.
- The missing-connection-string 500 returned { error }, not the package's
  standard { message, code }.
- An unguarded rollback in the catch could replace the caller's real error
  with a connection error.

Adds unit coverage for each, plus a type-level check that composing without
an upstream jwtClaims stays a compile-time error.

* feat(middleware): add withPostgresAdminClient

Contributes ctx.postgresAdmin — a pg client that bypasses RLS, exported from
./middleware/postgres-admin. Queries run as-is under the connection-string
role: no claim injection, no role switch, no wrapping transaction.

Declares no upstream prerequisite, so unlike withPostgresClient it composes
under auth: 'secret' and auth: 'none'. Shares the pool cache with the scoped
half — same connection string, one pool. That is safe because everything the
scoped half sets is transaction-local, so a connection always returns clean.

Kept as a second middleware rather than a property on ctx.postgres:
defineMiddleware contributes exactly one ctx key, and the split keeps the RLS
bypass visible at the composition site.

* test(e2e): cover both postgres middleware against a real database

Adds /my-notes-pg and /all-notes-pg to the core Node app and the Deno edge
function, both running the identical unfiltered SELECT — one through
ctx.postgres, one through ctx.postgresAdmin. user2 sees none of user1's rows
through the scoped client and sees them through the admin one, which proves
claim injection, the role drop, and the bypass in a single contrast.

The edge function passes connectionString explicitly from E2E_DB_URL: the CLI
injects a SUPABASE_DB_URL addressing the database by container name, and
Deno's DNS resolver rejects the underscores in it. The Node app still covers
the SUPABASE_DB_URL default path.

* docs: document the postgres middleware pair

Adds docs/postgres.md covering both halves, the SQL each query runs, the two
composition paths, table grants, the RLS bypass and why it is a separate
middleware, and guidance to write policies with the auth.* helpers rather
than reading request.jwt.claim.* directly.

Wires both subpaths into typedoc entryPoints — without which neither export
reached api-docs/ — and adds README sections, Exports and env-var rows, and
api-reference entries.

* fix(middleware): discard the connection when a rollback fails

pg-pool only removes a client when release() is given a truthy argument, so
the previous release() returned a connection whose transaction could not be
unwound straight back to the pool — potentially still inside the caller's
transaction with their role set.

That was survivable while the pool served one middleware. It is not now that
withPostgresAdminClient shares it: that middleware begins no transaction and
sets up no session state, so it would silently inherit the leftover role on
the next checkout.

* fix(middleware): refuse unsupported roles instead of downgrading to anon

withPostgresClient silently mapped every role that was not 'authenticated'
to 'anon'. For a forged service_role that was the intent, but Supabase also
supports custom roles via the role claim, and RLS applies to those normally —
so a legitimate `role: manager` token was being answered with zero rows and
no indication that the role was the reason.

Now only 'authenticated' and 'anon' are assumed, and anything else
short-circuits with a 500 and code UNSUPPORTED_ROLE before the handler runs
or a connection is checked out. service_role gets a message pointing at
withPostgresAdminClient; other roles are named in the error.

Custom roles remain unsupported — the reason is that PostgREST connects as the
unprivileged authenticator, where `grant <role> to authenticator` is itself the
authorization, while we connect as postgres and have no such boundary to lean
on. Documented, and tracked separately.

Also hoists the per-request claims serialization out of the per-query path.

* docs: list every subpath in the README exports table

The table covered 8 of 13 entry points. Adding the postgres pair made the
omission look deliberate rather than incidental — a reader could reasonably
conclude withClaims has no subpath, which matters because it is the documented
prerequisite for composing withPostgresClient standalone.

* feat(middleware): make query a tagged template, add queryRaw and ident

`query` now takes a tagged template only, so every interpolation becomes a
bind parameter and can never alter the shape of the statement. `queryRaw(text,
params)` keeps the string form — it is fully safe with params, and it is the
only path that works for query builders and codegen emitting `{ sql,
parameters }`, or for SQL that has to interpolate an identifier.

Passing a plain string to `query` throws, naming `queryRaw`. The two calls
differ only in their brackets, so refusing beats reinterpreting: the string's
first character would otherwise be read as the whole template and a
one-character query would be sent.

`ident()` quotes identifiers, which can never be bind parameters — `select $1
from notes` selects a literal, not a column. It is implemented directly rather
than wrapping `pg.escapeIdentifier`: that top-level export only exists from
pg 8.11, while the peer range is `^8.0.0`, so a wrapper would be a runtime
TypeError on 8.0-8.5. It also rejects empty names and NUL bytes, which pg
passes straight through to a confusing server-side error.

`set local role` now quotes the role via `ident()`. The role is already
constrained to the SUPPORTED_ROLES allowlist, so this changes nothing today —
it keeps the interpolation safe if that list widens to the custom roles the
docstring promises.

Follows the prior art: Prisma shipped the dual overload and reversed it,
Slonik refuses plain strings outright, and postgres.js requires the tag with
`sql.unsafe` as the named escape hatch.

The e2e edge function built its query by interpolating a column list. As a
`query` tag that would have compiled to `select $1 from notes` and returned
the literal string for every row — valid SQL, wrong rows, no error. It now
uses `queryRaw`, with a comment explaining why.

* fix: refuse non-string role claims instead of downgrading to anon

* chore: keep prettier off the release-please changelog

---------

Co-authored-by: Katerina Skroumpelou <sk.katherine@gmail.com>

Author: tomaspozo

.prettierignore

@@ -1,3 +1,5 @@
 node_modules
 dist
 pnpm-lock.yaml
+# generated by release-please; prettier restyles its bullets, causing churn
+CHANGELOG.md

README.md

@@ -438,6 +438,45 @@ export default {
 }
 ```
 
+## Postgres (RLS-scoped queries)
+
+When PostgREST isn't the right tool — joins, CTEs, window functions — `withPostgresClient` puts a direct Postgres connection on `ctx.postgres`, scoped to the caller by RLS:
+
+```ts
+import { withSupabase } from '@supabase/server'
+import { withPostgresClient } from '@supabase/server/middleware/postgres'
+
+export default {
+  fetch: withSupabase(
+    { auth: 'user', middleware: [withPostgresClient()] },
+    async (_req, ctx) => {
+      // No WHERE clause — RLS scopes the rows to the caller.
+      const notes = await ctx.postgres.query`select id, body from notes`
+      return Response.json(notes)
+    },
+  ),
+}
+```
+
+Each query runs in its own transaction that injects the caller's claims and drops to their role, exactly like PostgREST — so `auth.uid()` resolves and your policies enforce. Only `authenticated` and `anon` are assumed; a token naming any other role (including `service_role`, and custom roles) is refused with `code: 'UNSUPPORTED_ROLE'` rather than silently downgraded to `anon`.
+
+When a handler legitimately needs to cross user boundaries, `withPostgresAdminClient` is the explicit opt-out — it contributes `ctx.postgresAdmin`, which bypasses RLS and needs no caller identity, so it works under `auth: 'secret'` and `auth: 'none'` too:
+
+```ts
+import { withPostgresAdminClient } from '@supabase/server/middleware/postgres-admin'
+
+withSupabase(
+  { auth: 'secret', middleware: [withPostgresAdminClient()] },
+  handler,
+)
+```
+
+The pair mirrors `ctx.supabase` / `ctx.supabaseAdmin`, and they share one connection pool. Keeping them as two middleware is deliberate: bypassing RLS stays visible at the composition site, so you can grep for every handler that can do it.
+
+Needs `pg` installed (optional peer dependency) and a raw TCP socket: Node, Deno, Bun, and the Supabase Edge runtime — **not** Workers-style isolates. Reads `SUPABASE_DB_URL` by default. Remember that `authenticated` also needs table grants, not just policies.
+
+See [`docs/postgres.md`](docs/postgres.md) for standalone composition with `withClaims`, the grants requirement, and current limits.
+
 ## Environment Variables
 
 Automatically available in Supabase Edge Functions:
@@ -456,6 +495,7 @@ Also supported (for local dev, self-hosted, or other runtimes):
 | `SUPABASE_PUBLISHABLE_KEY` | `sb_publishable_...` | Single publishable key                                    |
 | `SUPABASE_SECRET_KEY`      | `sb_secret_...`      | Single secret key                                         |
 | `SUPABASE_JWKS_URL`        | `https://...`        | Remote JWKS endpoint (used when `SUPABASE_JWKS` is unset) |
+| `SUPABASE_DB_URL`          | `postgresql://...`   | Postgres connection string, read by `withPostgresClient`  |
 
 When both singular and plural forms are set, plural takes priority.
 
@@ -481,14 +521,21 @@ No. `@supabase/ssr` handles cookie-based session management for frameworks like
 
 ## Exports
 
-| Export                             | What's in it                                                                                                      |
-| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `@supabase/server`                 | `withSupabase`, `createSupabaseContext`                                                                           |
-| `@supabase/server/core`            | `verifyAuth`, `verifyCredentials`, `extractCredentials`, `createContextClient`, `createAdminClient`, `resolveEnv` |
-| `@supabase/server/adapters/hono`   | `withSupabase` (Hono middleware)                                                                                  |
-| `@supabase/server/adapters/h3`     | `withSupabase` (H3 / Nuxt middleware)                                                                             |
-| `@supabase/server/adapters/elysia` | `withSupabase` (Elysia plugin)                                                                                    |
-| `@supabase/server/adapters/nestjs` | `withSupabase` (NestJS guard), `SupabaseCtx` (param decorator)                                                    |
+| Export                                       | What's in it                                                                                                      |
+| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `@supabase/server`                           | `withSupabase`, `createSupabaseContext`                                                                           |
+| `@supabase/server/core`                      | `verifyAuth`, `verifyCredentials`, `extractCredentials`, `createContextClient`, `createAdminClient`, `resolveEnv` |
+| `@supabase/server/adapters/hono`             | `withSupabase` (Hono middleware)                                                                                  |
+| `@supabase/server/adapters/h3`               | `withSupabase` (H3 / Nuxt middleware)                                                                             |
+| `@supabase/server/adapters/elysia`           | `withSupabase` (Elysia plugin)                                                                                    |
+| `@supabase/server/adapters/nestjs`           | `withSupabase` (NestJS guard), `SupabaseCtx` (param decorator)                                                    |
+| `@supabase/server/middleware/client`         | `withSupabaseClient` (RLS-scoped `ctx.supabase` client)                                                           |
+| `@supabase/server/middleware/admin-client`   | `withSupabaseAdminClient` (`ctx.supabaseAdmin`, bypasses RLS)                                                     |
+| `@supabase/server/middleware/claims`         | `withClaims` (JWKS-verified `ctx.jwtClaims`)                                                                      |
+| `@supabase/server/middleware/postgres`       | `withPostgresClient` (RLS-scoped `ctx.postgres` client)                                                           |
+| `@supabase/server/middleware/postgres-admin` | `withPostgresAdminClient` (`ctx.postgresAdmin`, bypasses RLS)                                                     |
+| `@supabase/server/oauth-protected-resource`  | `withOAuthProtectedResource`, `resourceMetadataResponse`, `unauthorizedResponse`                                  |
+| `@supabase/server/peer/supabase-js`          | Re-exported `supabase-js` types (`SupabaseClient`, `PostgrestError`, …)                                           |
 
 ## Documentation
 
@@ -505,6 +552,7 @@ No. `@supabase/ssr` handles cookie-based session management for frameworks like
 | How do environment variables work across runtimes?                  | [`docs/environment-variables.md`](docs/environment-variables.md) |
 | How do I handle errors? What codes exist?                           | [`docs/error-handling.md`](docs/error-handling.md)               |
 | How do I get typed database queries?                                | [`docs/typescript-generics.md`](docs/typescript-generics.md)     |
+| How do I run raw SQL scoped to the caller by RLS?                   | [`docs/postgres.md`](docs/postgres.md)                           |
 | How do I use this with `@supabase/ssr` (Next.js, SvelteKit, Remix)? | [`docs/ssr-frameworks.md`](docs/ssr-frameworks.md)               |
 | What's the complete API surface?                                    | [`docs/api-reference.md`](docs/api-reference.md)                 |
 

docs/api-reference.md

@@ -166,6 +166,135 @@ Defaults to `auth: 'user'` when config is omitted.
 
 ---
 
+## @supabase/server/middleware/postgres
+
+### withPostgresClient
+
+```ts
+const withPostgresClient: Middleware<
+  'postgres',
+  WithPostgresClientConfig | void,
+  { jwtClaims: RequestClaims | null },
+  PostgresApi
+>
+```
+
+Contributes `ctx.postgres` — a `pg` client scoped to the caller by RLS. Each query runs in its own transaction that sets `request.jwt.claims` and drops to the caller's role before the statement, so `auth.uid()` resolves and policies enforce.
+
+Only `authenticated` and `anon` are assumed. A verified token naming any other role — `service_role` or a custom role — short-circuits with a 500 and `{ message, code: 'UNSUPPORTED_ROLE' }` naming the role, rather than being downgraded to `anon`. A missing or absent `role` claim is `anon`.
+
+Requires `ctx.jwtClaims` upstream — supplied by `withSupabase` or by `withClaims` in a standalone `pipeline`. Composing it without one is a compile-time error.
+
+Short-circuits with a 500 and `{ message, code: 'ENV_ERROR' }` when no connection string is available.
+
+Needs raw TCP: Node, Deno, Bun, and the Supabase Edge runtime, not Workers-style isolates. `pg` is an optional peer dependency.
+
+See [`docs/postgres.md`](postgres.md).
+
+### PostgresApi
+
+```ts
+interface PostgresApi {
+  query<T = Record<string, unknown>>(
+    strings: TemplateStringsArray,
+    ...values: unknown[]
+  ): Promise<T[]>
+
+  queryRaw<T = Record<string, unknown>>(
+    text: string,
+    params?: unknown[],
+  ): Promise<T[]>
+}
+```
+
+The value at `ctx.postgres`. Both methods return the result rows directly (not a `pg` `Result`).
+
+`query` is a **tagged template**, so every interpolation becomes a bind parameter and can never alter the statement:
+
+```ts
+const rows = await ctx.postgres
+  .query`select id, body from notes where id = ${id}`
+// -> select id, body from notes where id = $1   with values [id]
+```
+
+Tagged templates cannot carry type arguments, so annotate the binding instead of writing `query<NoteRow>`:
+
+```ts
+const rows: NoteRow[] = await ctx.postgres.query`select id, body from notes`
+```
+
+Passing a plain string to `query` throws — the two calls differ only in their brackets, so it refuses rather than silently reinterpreting.
+
+`queryRaw` takes SQL text plus `params`, for text that cannot be a literal: a query builder emitting `{ sql, parameters }`, or SQL that must interpolate an identifier. Identifiers can never be bind parameters, so check them against a set you control and quote them with `ident`:
+
+```ts
+import { ident } from '@supabase/server/middleware/postgres'
+
+const SORTABLE = new Set(['created_at', 'title'])
+if (!SORTABLE.has(column)) throw new Error('unsupported sort column')
+const rows = await ctx.postgres.queryRaw(
+  `select id, title from posts order by ${ident(column)} desc`,
+)
+```
+
+`ident` quotes and escapes, but does not authorize — it stops injection, not a caller reading a column they should not see. The allowlist is what does that.
+
+### WithPostgresClientConfig
+
+```ts
+interface WithPostgresClientConfig {
+  connectionString?: string
+}
+```
+
+Defaults to the `SUPABASE_DB_URL` environment variable. Pools are created lazily, one per connection string per process.
+
+### RequestClaims
+
+```ts
+interface RequestClaims {
+  role?: string
+  [key: string]: unknown
+}
+```
+
+The minimal claims shape `withPostgresClient` requires upstream at `ctx.jwtClaims`. Satisfied by `withSupabase`'s JWKS-verified claims and by `withClaims`. Only `role` is read; the whole object is serialized into `request.jwt.claims`.
+
+---
+
+## @supabase/server/middleware/postgres-admin
+
+### withPostgresAdminClient
+
+```ts
+const withPostgresAdminClient: Middleware<
+  'postgresAdmin',
+  WithPostgresAdminClientConfig | void,
+  Record<never, never>,
+  PostgresApi
+>
+```
+
+Contributes `ctx.postgresAdmin` — a `pg` client that **bypasses RLS**. Queries run as-is, as the role in the connection string: no claim injection, no role switching, no wrapping transaction.
+
+Declares no upstream prerequisite, so it composes in any auth mode including `'secret'` and `'none'`. Shares the pool cache with `withPostgresClient` — same connection string, one pool.
+
+Short-circuits with a 500 and `{ message, code: 'ENV_ERROR' }` when no connection string is available.
+
+Authorization is the caller's responsibility: RLS is not consulted, so per-user scoping must be an explicit `where` clause.
+
+### WithPostgresAdminClientConfig
+
+```ts
+interface WithPostgresAdminClientConfig {
+  connectionString?: string
+}
+```
+
+Defaults to the `SUPABASE_DB_URL` environment variable.
+
+---
+
 ## Types
 
 ### AuthMode
@@ -353,17 +482,18 @@ class AuthError extends Error {
 
 ## Error Code Constants
 
-| Constant                            | Value                               | Class       | Meaning                                           |
-| ----------------------------------- | ----------------------------------- | ----------- | ------------------------------------------------- |
-| `EnvGenericError`                   | `'ENV_ERROR'`                       | `EnvError`  | Generic environment error                         |
-| `MissingSupabaseURLError`           | `'MISSING_SUPABASE_URL'`            | `EnvError`  | `SUPABASE_URL` not set                            |
-| `MissingPublishableKeyError`        | `'MISSING_PUBLISHABLE_KEY'`         | `EnvError`  | Named publishable key not found                   |
-| `MissingDefaultPublishableKeyError` | `'MISSING_DEFAULT_PUBLISHABLE_KEY'` | `EnvError`  | No default publishable key                        |
-| `MissingSecretKeyError`             | `'MISSING_SECRET_KEY'`              | `EnvError`  | Named secret key not found                        |
-| `MissingDefaultSecretKeyError`      | `'MISSING_DEFAULT_SECRET_KEY'`      | `EnvError`  | No default secret key                             |
-| `AuthGenericError`                  | `'AUTH_ERROR'`                      | `AuthError` | Generic auth error                                |
-| `InvalidCredentialsError`           | `'INVALID_CREDENTIALS'`             | `AuthError` | No credential matched, or JWT failed verification |
-| `CreateSupabaseClientError`         | `'CREATE_SUPABASE_CLIENT_ERROR'`    | `AuthError` | Client creation failed after auth                 |
+| Constant                            | Value                               | Class       | Meaning                                                        |
+| ----------------------------------- | ----------------------------------- | ----------- | -------------------------------------------------------------- |
+| `EnvGenericError`                   | `'ENV_ERROR'`                       | `EnvError`  | Generic environment error                                      |
+| `MissingSupabaseURLError`           | `'MISSING_SUPABASE_URL'`            | `EnvError`  | `SUPABASE_URL` not set                                         |
+| `MissingPublishableKeyError`        | `'MISSING_PUBLISHABLE_KEY'`         | `EnvError`  | Named publishable key not found                                |
+| `MissingDefaultPublishableKeyError` | `'MISSING_DEFAULT_PUBLISHABLE_KEY'` | `EnvError`  | No default publishable key                                     |
+| `MissingSecretKeyError`             | `'MISSING_SECRET_KEY'`              | `EnvError`  | Named secret key not found                                     |
+| `MissingDefaultSecretKeyError`      | `'MISSING_DEFAULT_SECRET_KEY'`      | `EnvError`  | No default secret key                                          |
+| `AuthGenericError`                  | `'AUTH_ERROR'`                      | `AuthError` | Generic auth error                                             |
+| `InvalidCredentialsError`           | `'INVALID_CREDENTIALS'`             | `AuthError` | No credential matched, or JWT failed verification              |
+| `CreateSupabaseClientError`         | `'CREATE_SUPABASE_CLIENT_ERROR'`    | `AuthError` | Client creation failed after auth                              |
+| `UnsupportedRoleError`              | `'UNSUPPORTED_ROLE'`                | —           | `withPostgresClient` will not assume the caller's `role` claim |
 
 ---