@specific.dev/spectest 0.114.0 → 0.115.1

package/dist/components/supabase-config.d.ts

@@ -1,3 +1,4 @@
+import { type SupabasePoolerConfig } from "./supabase-pooler.js";
 /**
  * GoTrue's mail template types, as `config.toml` spells them. The container
  * variable is the id upper-cased (`magic_link` -> `GOTRUE_MAILER_TEMPLATES_MAGIC_LINK`).
@@ -13,6 +14,8 @@ export interface MailTemplateSpec {
 }
 /** Everything the component takes from the config file, grouped by the service it lands on. */
 export interface MappedSupabaseConfig {
+    /** Optional Supavisor service, configured by [db.pooler]. */
+    pooler: SupabasePoolerConfig;
     /** GoTrue (`<name>-auth`) environment. */
     auth: Record<string, string>;
     /** GoTrue variables whose values come from the component's env option. */
@@ -78,7 +81,8 @@ export interface ExternalProvider {
 /**
  * Classify and map every leaf of a parsed config document.
  *
- * Never throws on content: a setting this component does not apply is
+ * Unrecognized content is reported; invalid supported pooler settings fail
+ * before any service starts. A setting this component does not apply is
  * *reported* (`unsupported`), not vetoed. The file belongs to the project and
  * describes more than one environment — refusing to start over a key that is
  * meaningless in a hermetic VM would make the whole option unadoptable for the

package/dist/components/supabase-config.js

@@ -34,6 +34,7 @@
 // copy-paste gets silently backwards, which is why they are marked at the def
 // site.
 import { readFileSync } from "node:fs";
+import { DEFAULT_POOLER_CONFIG, setPoolerConfig } from "./supabase-pooler.js";
 /**
  * GoTrue's mail template types, as `config.toml` spells them. The container
  * variable is the id upper-cased (`magic_link` -> `GOTRUE_MAILER_TEMPLATES_MAGIC_LINK`).
@@ -119,6 +120,21 @@ const unsupported = (key, reason) => ({ key, bucket: "unsupported", reason });
 // Order matters: the first matching rule wins, so specific keys precede the
 // `**` prefixes that sweep up the rest of a section.
 const RULES = [
+    {
+        key: "db.pooler.**",
+        bucket: "applied",
+        apply: (value, out) => {
+            if (!isTable(value))
+                throw new Error("supabase(): db.pooler must be a table.");
+            for (const [key, setting] of Object.entries(value)) {
+                if (Object.hasOwn(DEFAULT_POOLER_CONFIG, key))
+                    setPoolerConfig(out.pooler, key, setting);
+                // Do not hide new settings under the broad db.** topology rule.
+                else
+                    out.warnings.push(`db.pooler.${key}`);
+            }
+        },
+    },
     // ── auth: core (cli gotrue.service.ts:440-448) ──────────────────────────
     // NEGATED — `enable_signup = true` means DISABLE_SIGNUP = false.
     auth("auth.enable_signup", "GOTRUE_DISABLE_SIGNUP", not),
@@ -383,7 +399,8 @@ function isOff(v) {
 /**
  * Classify and map every leaf of a parsed config document.
  *
- * Never throws on content: a setting this component does not apply is
+ * Unrecognized content is reported; invalid supported pooler settings fail
+ * before any service starts. A setting this component does not apply is
  * *reported* (`unsupported`), not vetoed. The file belongs to the project and
  * describes more than one environment — refusing to start over a key that is
  * meaningless in a hermetic VM would make the whole option unadoptable for the
@@ -392,6 +409,7 @@ function isOff(v) {
  */
 export function mapSupabaseConfig(doc) {
     const out = {
+        pooler: { ...DEFAULT_POOLER_CONFIG },
         auth: {},
         deferredAuth: {},
         rest: {},

package/dist/components/supabase-pooler.d.ts

@@ -0,0 +1,20 @@
+import type { ServiceDefinition } from "../index.js";
+/** Supabase CLI's [db.pooler] settings. Ports are local to the pooler container. */
+export interface SupabasePoolerConfig {
+    enabled: boolean;
+    port: number;
+    pool_mode: "transaction" | "session";
+    default_pool_size: number;
+    max_client_conn: number;
+}
+export declare const DEFAULT_POOLER_CONFIG: SupabasePoolerConfig;
+export declare function setPoolerConfig(config: SupabasePoolerConfig, key: string, value: unknown): void;
+export declare function supabasePoolerService(opts: {
+    config: SupabasePoolerConfig;
+    dbHost: string;
+    tenantId: string;
+    password: string;
+    jwtSecret: string;
+    tls: boolean;
+    url: string;
+}): ServiceDefinition;

package/dist/components/supabase-pooler.js

@@ -0,0 +1,118 @@
+export const DEFAULT_POOLER_CONFIG = {
+    enabled: false,
+    port: 54329,
+    pool_mode: "transaction",
+    default_pool_size: 20,
+    max_client_conn: 100,
+};
+export function setPoolerConfig(config, key, value) {
+    const invalid = (expected) => {
+        throw new Error(`supabase(): db.pooler.${key} must be ${expected}.`);
+    };
+    switch (key) {
+        case "enabled":
+            if (typeof value !== "boolean")
+                invalid("a boolean");
+            config.enabled = value;
+            break;
+        case "pool_mode":
+            if (value !== "transaction" && value !== "session")
+                invalid('"transaction" or "session"');
+            config.pool_mode = value;
+            break;
+        case "port":
+        case "default_pool_size":
+        case "max_client_conn":
+            if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1 ||
+                (key === "port" && value > 65535))
+                invalid(key === "port" ? "an integer from 1 to 65535" : "a positive integer");
+            config[key] = value;
+            break;
+    }
+}
+// Based on supabase/cli's start/templates/pooler.exs and the self-hosted
+// docker/volumes/pooler/pooler.exs. Values come from env, never Elixir source
+// interpolation (passwords may contain quotes, backslashes or #{...}).
+const TENANT_SCRIPT = `{:ok, _} = Application.ensure_all_started(:supavisor)
+{:ok, version} =
+  case Supavisor.Repo.query!("select version()") do
+    %{rows: [[ver]]} -> Supavisor.Helpers.parse_pg_version(ver)
+  end
+params = %{
+  "external_id" => System.fetch_env!("POOLER_TENANT_ID"),
+  "db_host" => System.fetch_env!("POSTGRES_HOST"),
+  "db_port" => 5432,
+  "db_database" => "postgres",
+  "require_user" => false,
+  "auth_query" => "SELECT * FROM pgbouncer.get_auth($1)",
+  "default_max_clients" => String.to_integer(System.fetch_env!("POOLER_MAX_CLIENT_CONN")),
+  "default_pool_size" => String.to_integer(System.fetch_env!("POOLER_DEFAULT_POOL_SIZE")),
+  "default_parameter_status" => %{"server_version" => version},
+  "users" => [%{
+    "db_user" => "pgbouncer",
+    "db_password" => System.fetch_env!("POSTGRES_PASSWORD"),
+    "mode_type" => System.fetch_env!("POOLER_POOL_MODE"),
+    "pool_size" => String.to_integer(System.fetch_env!("POOLER_DEFAULT_POOL_SIZE")),
+    "is_manager" => true
+  }]
+}
+if !Supavisor.Tenants.get_tenant_by_external_id(params["external_id"]) do
+  {:ok, _} = Supavisor.Tenants.create_tenant(params)
+end
+`;
+export function supabasePoolerService(opts) {
+    const { config, dbHost, tenantId, password, jwtSecret, tls, url } = opts;
+    const quotedUrl = `'${url.replace(/'/g, "'\\''")}'`;
+    return {
+        image: { type: "registry", reference: "supabase/supavisor:2.9.12" },
+        // eval starts the OTP application too. Give that temporary instance
+        // ephemeral SQL ports so readiness only sees the final server process.
+        command: '/app/bin/migrate && PROXY_PORT_SESSION=0 PROXY_PORT_TRANSACTION=0 /app/bin/supavisor eval "$(cat /etc/pooler/pooler.exs)" && exec /app/bin/server',
+        env: {
+            // Bind all auxiliary listeners to ephemeral ports, so any valid pooler
+            // port can be used without colliding with its management/internal ports.
+            PORT: "0",
+            PROXY_PORT: "0",
+            SESSION_PROXY_PORTS: "0",
+            TRANSACTION_PROXY_PORTS: "0",
+            PROXY_PORT_SESSION: config.pool_mode === "session" ? String(config.port) : "0",
+            PROXY_PORT_TRANSACTION: config.pool_mode === "transaction" ? String(config.port) : "0",
+            POSTGRES_HOST: dbHost,
+            POSTGRES_PASSWORD: password,
+            DATABASE_URL: `ecto://supabase_admin:${encodeURIComponent(password)}@${dbHost}:5432/_supabase`,
+            // Metadata connections are separate from the user pool. Keep this small
+            // in a single-node test environment (upstream defaults to 25).
+            DB_POOL_SIZE: "2",
+            SECRET_KEY_BASE: "spectest-supavisor-local-secret-key-base-not-for-production-use-0000",
+            VAULT_ENC_KEY: "spectest".repeat(4),
+            API_JWT_SECRET: jwtSecret,
+            METRICS_JWT_SECRET: jwtSecret,
+            REGION: "local",
+            ERL_AFLAGS: "-proto_dist inet_tcp",
+            POOLER_TENANT_ID: tenantId,
+            POOLER_DEFAULT_POOL_SIZE: String(config.default_pool_size),
+            POOLER_MAX_CLIENT_CONN: String(config.max_client_conn),
+            POOLER_POOL_MODE: config.pool_mode,
+            ...(tls ? {
+                GLOBAL_DOWNSTREAM_CERT_PATH: "/tls/pooler.crt",
+                GLOBAL_DOWNSTREAM_KEY_PATH: "/tls/pooler.key",
+            } : {}),
+        },
+        files: [{ path: "/etc/pooler/pooler.exs", content: TENANT_SCRIPT }],
+        ...(tls ? { certificates: [{
+                    hostnames: ["{{SPECTEST_SERVICE}}", "{{SPECTEST_SERVICE}}.internal"],
+                    certPath: "/tls/pooler.crt",
+                    keyPath: "/tls/pooler.key",
+                    user: "root",
+                }] } : {}),
+        ports: [config.port],
+        dependsOn: ["db"],
+        // The pinned image includes psql. Test real tenant authentication and TLS,
+        // with bounded attempts retried by the normal service readiness loop.
+        readyCheck: {
+            type: "exec",
+            command: `PGCONNECT_TIMEOUT=3 PGOPTIONS='-c statement_timeout=3000' psql -X --dbname ${quotedUrl} -v ON_ERROR_STOP=1 -c 'SELECT 1'`,
+            timeoutSecs: 120,
+        },
+    };
+}

package/dist/components/supabase.d.ts

@@ -294,8 +294,11 @@ export interface SupabaseStack {
     anonKey: string;
     /** `service_role` API key (HS256 JWT). */
     serviceRoleKey: string;
-    /** Direct Postgres URL for the app (`postgres` superuser): `postgresql://postgres:<pw>@<name>-db:5432/postgres`. */
+    /** Direct Postgres URL as `postgres`. Use for migrations and LISTEN/NOTIFY. */
     dbUrl: string;
+    /** Supavisor URL as `postgres.<name>`, present when [db.pooler].enabled is true.
+     * Uses the configured pool_mode and port; dbUrl remains a direct connection. */
+    poolerUrl?: string;
     /** The gateway service key — use in a dependent service's `dependsOn` to wait
      *  for the whole stack (the gateway waits on the services behind it). */
     ready: string;

package/dist/components/supabase.js

@@ -64,6 +64,7 @@ import { google } from "./google.js";
 import { microsoft } from "./microsoft.js";
 import { SUPABASE_WEBHOOKS_SQL } from "./supabase-webhooks.js";
 import { postgresTls } from "./postgres-tls.js";
+import { supabasePoolerService } from "./supabase-pooler.js";
 import { mapSupabaseConfig, parseSupabaseConfigFile, } from "./supabase-config.js";
 // ──────────────────────────────────────────────────────────────────────────
 // Pinned upstream image tags (github.com/supabase/supabase docker-compose.yml,
@@ -1384,6 +1385,11 @@ export function supabase(opts = {}) {
     // `auth`/`storage` schemas — regardless of ownership.
     const adminDbUrl = `postgresql://supabase_admin:${encodeURIComponent(dbPassword)}@${dbKey}:5432/postgres` +
         (dbTls ? "?sslmode=verify-full" : "");
+    const pooler = mapped?.pooler.enabled ? mapped.pooler : undefined;
+    const poolerUrl = pooler
+        ? `postgresql://${encodeURIComponent(`postgres.${name}`)}:${encodeURIComponent(dbPassword)}@${name}-pooler:${pooler.port}/postgres` +
+            (dbTls ? "?sslmode=verify-full" : "")
+        : undefined;
     // ── social sign-in ────────────────────────────────────────────────────
     // Every `[auth.external.<name>]` the config enables: served in-environment
     // where there is an emulator for it, reported where there isn't. The app
@@ -1482,12 +1488,29 @@ export function supabase(opts = {}) {
                     // superuser in modern supabase/postgres; `supabase_admin` is.
                     "supabase_admin");
                     await applySqlFile(ctx, SUPABASE_WEBHOOKS_SQL, "database webhooks", "supabase_admin");
+                    if (pooler) {
+                        // The image supplies pgbouncer.get_auth, but the self-hosted
+                        // compose files normally create the pooler's metadata database.
+                        await applySqlFile(ctx, `ALTER USER pgbouncer WITH PASSWORD ${pgLiteral(dbPassword)};
+SELECT 'CREATE DATABASE _supabase OWNER supabase_admin'
+WHERE NOT EXISTS (SELECT FROM pg_database WHERE datname = '_supabase')
+\\gexec
+\\connect _supabase supabase_admin
+CREATE SCHEMA IF NOT EXISTS _supavisor AUTHORIZATION supabase_admin;
+`, "pooler bootstrap", "supabase_admin");
+                    }
                     const extensions = extensionSql(opts.db?.extensions);
                     if (extensions)
                         await applySqlFile(ctx, extensions, "configured extensions", "postgres");
                 },
             };
             parts.db = dbDef;
+            if (pooler && poolerUrl) {
+                parts.pooler = supabasePoolerService({
+                    config: pooler, dbHost: db, tenantId: name, password: dbPassword,
+                    jwtSecret, tls: !!dbTls, url: poolerUrl,
+                });
+            }
             // ── rest (PostgREST) ────────────────────────────────────────────
             parts.rest = {
                 image: { type: "registry", reference: IMAGES.rest },
@@ -1888,6 +1911,7 @@ export function supabase(opts = {}) {
         anonKey,
         serviceRoleKey,
         dbUrl,
+        ...(poolerUrl ? { poolerUrl } : {}),
         ready: name,
         ...(withMail ? { smtp: { host: mailKey, port: 1025 } } : {}),
     };

package/dist/daemon.js

@@ -5159,6 +5159,7 @@ export function harnessMethods(state) {
             // new method. Check the loaded project, including after warm restore.
             setupInteractive: typeof loaded?.project.interactive?.seed === "function",
             replayEnvironmentMode: true,
+            inFlightTest: state.inFlightTest !== null,
         }),
         // Live bootstrap progress, polled by the control plane during
         // `bootstrap` and streamed into the test-run row. `{}` before the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.114.0",
+  "version": "0.115.1",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/supabase-config.test.ts

@@ -238,8 +238,7 @@ secret = "encrypted:c2hoaA=="
     expect(out.warnings).toEqual(["auth.future_option"]);
   });
 
-  // Sections spectest owns outright never reach the user as noise.
-  test("drops the topology sections in silence", () => {
+  test("applies the pooler while dropping unrelated topology sections", () => {
     const out = mapSupabaseConfig(
       toml(`
 project_id = "test"
@@ -247,6 +246,10 @@ project_id = "test"
 port = 54322
 [db.pooler]
 enabled = true
+port = 6544
+pool_mode = "session"
+default_pool_size = 7
+max_client_conn = 150
 [studio]
 port = 54323
 [inbucket]
@@ -257,5 +260,29 @@ site_url = "https://example.com"
     );
     expect(out.warnings).toEqual([]);
     expect(out.auth).toEqual({});
+    expect(out.pooler).toEqual({ enabled: true, port: 6544, pool_mode: "session", default_pool_size: 7, max_client_conn: 150 });
+  });
+
+  test("pooler defaults are independent and disabled until requested", () => {
+    const defaults = { enabled: false, port: 54329, pool_mode: "transaction", default_pool_size: 20, max_client_conn: 100 };
+    expect(mapSupabaseConfig({}).pooler).toEqual(defaults);
+    expect(mapSupabaseConfig({ db: { pooler: { enabled: true } } }).pooler).toEqual({ ...defaults, enabled: true });
+    expect(mapSupabaseConfig({}).pooler).toEqual(defaults);
+  });
+
+  test.each([
+    ["enabled", "true"], ["enabled", {}], ["pool_mode", "statement"], ["pool_mode", false],
+    ["default_pool_size", 0], ["default_pool_size", 1.5], ["max_client_conn", -1],
+    ["max_client_conn", "100"], ["port", 0], ["port", 65536], ["port", NaN],
+  ])("rejects invalid pooler %s = %p", (key, value) => {
+    expect(() => mapSupabaseConfig({ db: { pooler: { [key as string]: value } } })).toThrow(`db.pooler.${key}`);
+  });
+
+  test("reports unknown pooler settings instead of silently ignoring them", () => {
+    expect(mapSupabaseConfig({ db: { pooler: { future_setting: 1 } } }).warnings).toEqual(["db.pooler.future_setting"]);
+  });
+
+  test("rejects a malformed pooler section", () => {
+    expect(() => mapSupabaseConfig({ db: { pooler: true } })).toThrow("db.pooler must be a table");
   });
 });

package/src/components/supabase-config.ts

@@ -35,6 +35,7 @@
 // site.
 
 import { readFileSync } from "node:fs";
+import { DEFAULT_POOLER_CONFIG, setPoolerConfig, type SupabasePoolerConfig } from "./supabase-pooler.js";
 
 /**
  * GoTrue's mail template types, as `config.toml` spells them. The container
@@ -61,6 +62,8 @@ export interface MailTemplateSpec {
 
 /** Everything the component takes from the config file, grouped by the service it lands on. */
 export interface MappedSupabaseConfig {
+  /** Optional Supavisor service, configured by [db.pooler]. */
+  pooler: SupabasePoolerConfig;
   /** GoTrue (`<name>-auth`) environment. */
   auth: Record<string, string>;
   /** GoTrue variables whose values come from the component's env option. */
@@ -211,6 +214,18 @@ const unsupported = (key: string, reason: string): Rule => ({ key, bucket: "unsu
 // `**` prefixes that sweep up the rest of a section.
 
 const RULES: Rule[] = [
+  {
+    key: "db.pooler.**",
+    bucket: "applied",
+    apply: (value, out) => {
+      if (!isTable(value)) throw new Error("supabase(): db.pooler must be a table.");
+      for (const [key, setting] of Object.entries(value)) {
+        if (Object.hasOwn(DEFAULT_POOLER_CONFIG, key)) setPoolerConfig(out.pooler, key, setting);
+        // Do not hide new settings under the broad db.** topology rule.
+        else out.warnings.push(`db.pooler.${key}`);
+      }
+    },
+  },
   // ── auth: core (cli gotrue.service.ts:440-448) ──────────────────────────
   // NEGATED — `enable_signup = true` means DISABLE_SIGNUP = false.
   auth("auth.enable_signup", "GOTRUE_DISABLE_SIGNUP", not),
@@ -478,7 +493,8 @@ function isOff(v: unknown): boolean {
 /**
  * Classify and map every leaf of a parsed config document.
  *
- * Never throws on content: a setting this component does not apply is
+ * Unrecognized content is reported; invalid supported pooler settings fail
+ * before any service starts. A setting this component does not apply is
  * *reported* (`unsupported`), not vetoed. The file belongs to the project and
  * describes more than one environment — refusing to start over a key that is
  * meaningless in a hermetic VM would make the whole option unadoptable for the
@@ -487,6 +503,7 @@ function isOff(v: unknown): boolean {
  */
 export function mapSupabaseConfig(doc: unknown): MappedSupabaseConfig {
   const out: MappedSupabaseConfig = {
+    pooler: { ...DEFAULT_POOLER_CONFIG },
     auth: {},
     deferredAuth: {},
     rest: {},

package/src/components/supabase-pooler-docker.test.ts

@@ -0,0 +1,129 @@
+// Opt-in real-image regression: creates and removes its own containers/network.
+// SPECTEST_TEST_SUPABASE_POOLER_DOCKER=1 bun test src/components/supabase-pooler-docker.test.ts
+import { expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { supabase } from "./supabase.js";
+import type { ServiceDefinition, ServiceSetupContext, ExecOpts } from "../index.js";
+
+async function run(args: string[], stdin = "") {
+  const child = Bun.spawn(args, { stdin: new Blob([stdin]), stdout: "pipe", stderr: "pipe" });
+  const [exitCode, stdout, stderr] = await Promise.all([
+    child.exited, new Response(child.stdout).text(), new Response(child.stderr).text(),
+  ]);
+  return { exitCode, stdout, stderr };
+}
+async function checked(args: string[], stdin = "") {
+  const result = await run(args, stdin);
+  if (result.exitCode) throw new Error(`${args[0]} failed: ${result.stderr}\n${result.stdout}`);
+  return result.stdout;
+}
+async function until(check: () => Promise<boolean>) {
+  const deadline = Date.now() + 60_000;
+  while (Date.now() < deadline) {
+    if (await check()) return;
+    await Bun.sleep(250);
+  }
+  throw new Error("Container did not become ready within 60s");
+}
+
+test.skipIf(!process.env.SPECTEST_TEST_SUPABASE_POOLER_DOCKER)("Supavisor boots, verifies TLS, pools transactions and preserves sessions", async () => {
+  const root = mkdtempSync(join(tmpdir(), "spectest-pooler-docker-"));
+  const network = `spectest-pooler-${process.pid}-${Date.now()}`;
+  const dbContainer = `${network}-db`;
+  const containers: string[] = [];
+  const password = "p@ss/word:#%";
+  const stack = (name: string, mode: "transaction" | "session") => supabase({
+    name, dbPassword: password,
+    configOverrides: { db: { pooler: { enabled: true, pool_mode: mode,
+      port: mode === "transaction" ? 54329 : 6544, default_pool_size: 2, max_client_conn: 12 } } },
+  });
+  const sb = stack("tx", "transaction");
+  const db = sb.group.services({ name: "tx", key: (p) => `tx-${p}` }).db as ServiceDefinition;
+  const exec = (_service: string, args: string[], opts: ExecOpts = {}) =>
+    run(["docker", "exec", "-i", dbContainer, ...args], typeof opts.stdin === "string" ? opts.stdin : "");
+  const ctx = { name: "tx-db", exec } as unknown as ServiceSetupContext<any>;
+  try {
+    await checked(["openssl", "req", "-x509", "-newkey", "rsa:2048", "-nodes", "-days", "1",
+      "-subj", "/CN=Spectest pooler test CA", "-keyout", `${root}/ca.key`, "-out", `${root}/ca.crt`]);
+    for (const host of ["tx-db", "tx-pooler", "session-pooler"]) {
+      await checked(["openssl", "req", "-new", "-newkey", "rsa:2048", "-nodes", "-subj", `/CN=${host}`,
+        "-keyout", `${root}/${host}.key`, "-out", `${root}/${host}.csr`]);
+      writeFileSync(`${root}/${host}.ext`, `subjectAltName=DNS:${host}\nextendedKeyUsage=serverAuth\n`);
+      await checked(["openssl", "x509", "-req", "-days", "1", "-in", `${root}/${host}.csr`,
+        "-CA", `${root}/ca.crt`, "-CAkey", `${root}/ca.key`, "-CAcreateserial",
+        "-extfile", `${root}/${host}.ext`, "-out", `${root}/${host}.crt`]);
+    }
+    await checked(["docker", "network", "create", network]);
+    containers.push(dbContainer);
+    await checked(["docker", "run", "-d", "--name", dbContainer, "--network", network,
+      "--network-alias", "tx-db", "--network-alias", "session-db", "-v", `${root}:/fixtures:ro`,
+      "-e", `POSTGRES_PASSWORD=${password}`, "-e", "PGSSLROOTCERT=/fixtures/ca.crt",
+      "--entrypoint", "sh", (db.image as { reference: string }).reference, "-c",
+      'mkdir /tls; cp /fixtures/tx-db.crt /tls/postgres.crt; cp /fixtures/tx-db.key /tls/postgres.key; chown postgres:postgres /tls/*; chmod 600 /tls/postgres.key; exec docker-entrypoint.sh "$@"',
+      "sh", ...db.args!]);
+    await until(async () => (await exec("", ["pg_isready", "-h", "127.0.0.1", "-U", "postgres"])).exitCode === 0);
+    await db.setup!(ctx);
+    await db.setup!(ctx); // Metadata bootstrap must be repeatable.
+
+    for (const [name, mode] of [["tx", "transaction"], ["session", "session"]] as const) {
+      const current = stack(name, mode);
+      const pooler = current.group.services({ name, key: (p) => `${name}-${p}` }).pooler as ServiceDefinition;
+      const container = `${network}-${name}`;
+      containers.push(container);
+      writeFileSync(`${root}/${name}.exs`, pooler.files![0]!.content);
+      const env = Object.entries(pooler.env!).flatMap(([key, value]) => ["-e", `${key}=${value}`]);
+      await checked(["docker", "run", "-d", "--name", container, "--network", network,
+        "--network-alias", `${name}-pooler`, ...env,
+        "-e", "PGSSLROOTCERT=/tls/ca.crt", "-v", `${root}/ca.crt:/tls/ca.crt:ro`,
+        "-v", `${root}/${name}.exs:/etc/pooler/pooler.exs:ro`,
+        "-v", `${root}/${name}-pooler.crt:/tls/pooler.crt:ro`,
+        "-v", `${root}/${name}-pooler.key:/tls/pooler.key:ro`,
+        "--entrypoint", "sh", (pooler.image as { reference: string }).reference, "-c", pooler.command!]);
+      const query = (sql: string, url = current.poolerUrl!) => exec("", ["psql", "-XAt", "-v", "ON_ERROR_STOP=1", url, "-f", "-"], { stdin: sql });
+      if (pooler.readyCheck!.type !== "exec") throw new Error("Expected SQL readiness probe");
+      const probeCommand = pooler.readyCheck!.command;
+      const probe = () => run(["docker", "exec", container, "sh", "-c", probeCommand]);
+      await until(async () => (await probe()).exitCode === 0);
+      const auth = await query("SELECT current_user, current_database();");
+      expect(auth.stdout.trim()).toBe("postgres|postgres");
+      const badPassword = new URL(current.poolerUrl!); badPassword.password = "wrong";
+      expect((await query("SELECT 1;", badPassword.toString())).exitCode).not.toBe(0);
+      // A CA-trusted certificate for a different name must still fail verification.
+      const wrongHost = new URL(current.poolerUrl!); wrongHost.hostname = container;
+      expect((await query("SELECT 1;", wrongHost.toString())).exitCode).not.toBe(0);
+      if (mode === "transaction") {
+        const results = await Promise.all(Array.from({ length: 8 }, () => query("SELECT pg_backend_pid(), pg_sleep(0.15);")));
+        for (const result of results) expect(result.exitCode).toBe(0);
+        const backends = new Set(results.map((result) => result.stdout.trim().split("|")[0]));
+        // Supavisor 2.9.12 keeps one warm backend in addition to pool_size
+        // overflow slots (tenant_supervisor.ex). Eight clients share <= 3.
+        expect(backends.size).toBeLessThanOrEqual(3);
+        expect(backends.size).toBeGreaterThan(0);
+      } else {
+        const result = await query("CREATE TEMP TABLE session_probe (n int);\nINSERT INTO session_probe VALUES (42);\nSELECT n FROM session_probe;\n");
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toContain("42");
+      }
+      // Tenant settings survive restart, and provisioning remains idempotent.
+      await checked(["docker", "restart", container]);
+      await until(async () => (await probe()).exitCode === 0);
+      await checked(["docker", "rm", "-f", container]);
+      containers.splice(containers.indexOf(container), 1);
+    }
+    const settings = await exec("", ["psql", "-U", "supabase_admin", "-d", "_supabase", "-Atc",
+      "SELECT external_id, default_pool_size, default_max_clients FROM _supavisor.tenants ORDER BY external_id"]);
+    expect(settings.stdout.trim()).toBe("session|2|12\ntx|2|12");
+  } catch (error) {
+    for (const container of containers) {
+      const logs = await run(["docker", "logs", "--tail", "30", container]);
+      console.error(container, logs.stdout, logs.stderr);
+    }
+    throw error;
+  } finally {
+    for (const container of containers.reverse()) await run(["docker", "rm", "-f", "-v", container]);
+    await run(["docker", "network", "rm", network]);
+    rmSync(root, { recursive: true, force: true });
+  }
+}, 180_000);

package/src/components/supabase-pooler.test.ts

@@ -0,0 +1,83 @@
+import { afterAll, expect, test } from "bun:test";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { supabase } from "./supabase.js";
+import { defineEnvironment, type ServiceDefinition } from "../index.js";
+
+const root = mkdtempSync(join(tmpdir(), "supabase-pooler-"));
+afterAll(() => rmSync(root, { recursive: true, force: true }));
+mkdirSync(join(root, "migrations"));
+writeFileSync(join(root, "config.toml"), `[db.pooler]
+enabled = true
+port = 6544
+pool_mode = "session"
+default_pool_size = 3
+max_client_conn = 40
+`);
+
+test("pooling is opt-in and does not change direct URLs", () => {
+  const direct = supabase();
+  const disabled = supabase({ configOverrides: { db: { pooler: { enabled: false } } } });
+  expect(disabled.dbUrl).toBe(direct.dbUrl);
+  expect(disabled.poolerUrl).toBeUndefined();
+  expect(disabled.group.services({ name: "supabase", key: (p) => `supabase-${p}` })).not.toHaveProperty("pooler");
+});
+
+test("reads the project config and overrides it without redirecting internal clients", () => {
+  const password = "a@b/c'\\#{raise} $()";
+  const sb = supabase({ name: "other", dir: root, dbPassword: password,
+    configOverrides: { db: { pooler: { pool_mode: "transaction", max_client_conn: 80 } } } });
+  const parts = sb.group.services({ name: "other", key: (p) => `other-${p}` });
+  const pooler = parts.pooler as ServiceDefinition;
+  const url = new URL(sb.poolerUrl!);
+  expect(url.hostname).toBe("other-pooler");
+  expect(url.port).toBe("6544");
+  expect(decodeURIComponent(url.username)).toBe("postgres.other");
+  expect(decodeURIComponent(url.password)).toBe(password);
+  expect(url.searchParams.get("sslmode")).toBe("verify-full");
+  expect(new URL(sb.dbUrl).hostname).toBe("other-db");
+  expect(pooler.env).toMatchObject({ POOLER_DEFAULT_POOL_SIZE: "3", POOLER_MAX_CLIENT_CONN: "80",
+    POOLER_POOL_MODE: "transaction", PROXY_PORT_TRANSACTION: "6544", PROXY_PORT_SESSION: "0", POSTGRES_HOST: "other-db" });
+  expect(new URL(pooler.env!.DATABASE_URL!).password).toBe(encodeURIComponent(password));
+  expect(pooler.files![0]!.content).not.toContain(password);
+  expect(pooler.certificates![0]!.user).toBe("root");
+  expect((parts.rest as ServiceDefinition).env!.PGRST_DB_URI).toContain("@other-db:5432");
+  expect((parts.auth as ServiceDefinition).env!.GOTRUE_DB_DATABASE_URL).toContain("@other-db:5432");
+  expect((parts.storage as ServiceDefinition).env!.DATABASE_URL).toContain("@other-db:5432");
+  expect((parts.realtime as ServiceDefinition).env!.DB_HOST).toBe("other-db");
+  expect((parts.migrations as ServiceDefinition).dependsOn).not.toContain("pooler");
+});
+
+test("session mode and disabling TLS apply to the selected endpoint", () => {
+  const sb = supabase({ dir: root, db: { tls: false } });
+  const pooler = sb.group.services({ name: "supabase", key: (p) => `supabase-${p}` }).pooler as ServiceDefinition;
+  expect(pooler.env).toMatchObject({ POOLER_POOL_MODE: "session", PROXY_PORT_SESSION: "6544", PROXY_PORT_TRANSACTION: "0" });
+  expect(pooler.certificates).toBeUndefined();
+  expect(sb.poolerUrl).not.toContain("sslmode");
+});
+
+test("group readiness waits for authenticated pooled SQL, after tenant provisioning", () => {
+  const sb = supabase({ configOverrides: { db: { pooler: { enabled: true } } } });
+  const env = defineEnvironment({ name: "pooler-test", services: { supabase: sb.group } });
+  expect(env.config.services.supabase.dependsOn).toContain("supabase-pooler");
+  const pooler = sb.group.services({ name: "supabase", key: (p) => `supabase-${p}` }).pooler as ServiceDefinition;
+  expect(pooler.readyCheck!.type).toBe("exec");
+  if (pooler.readyCheck!.type !== "exec") throw new Error("Expected SQL probe");
+  expect(pooler.readyCheck!.command).toContain(sb.poolerUrl!);
+  expect(pooler.readyCheck!.command).toContain("ON_ERROR_STOP=1");
+  expect(pooler.command).toContain("PROXY_PORT_SESSION=0 PROXY_PORT_TRANSACTION=0 /app/bin/supavisor eval");
+});
+
+test("SQL readiness passes special credentials literally through the shell", async () => {
+  const sb = supabase({ dbPassword: "p@ss/word:'#{safe}%$()\\tail",
+    configOverrides: { db: { pooler: { enabled: true } } } });
+  const pooler = sb.group.services({ name: "supabase", key: (p) => `supabase-${p}` }).pooler as ServiceDefinition;
+  if (pooler.readyCheck!.type !== "exec") throw new Error("Expected SQL probe");
+  const child = Bun.spawn(["sh", "-c", `psql() { printf '%s\\n' "$@"; }; ${pooler.readyCheck!.command}`], {
+    stdout: "pipe", stderr: "pipe",
+  });
+  expect(await child.exited).toBe(0);
+  const args = (await new Response(child.stdout).text()).trim().split("\n");
+  expect(args[args.indexOf("--dbname") + 1]).toBe(sb.poolerUrl!);
+});

package/src/components/supabase-pooler.ts

@@ -0,0 +1,137 @@
+import type { ServiceDefinition } from "../index.js";
+
+/** Supabase CLI's [db.pooler] settings. Ports are local to the pooler container. */
+export interface SupabasePoolerConfig {
+  enabled: boolean;
+  port: number;
+  pool_mode: "transaction" | "session";
+  default_pool_size: number;
+  max_client_conn: number;
+}
+
+export const DEFAULT_POOLER_CONFIG: SupabasePoolerConfig = {
+  enabled: false,
+  port: 54329,
+  pool_mode: "transaction",
+  default_pool_size: 20,
+  max_client_conn: 100,
+};
+
+export function setPoolerConfig(config: SupabasePoolerConfig, key: string, value: unknown): void {
+  const invalid = (expected: string): never => {
+    throw new Error(`supabase(): db.pooler.${key} must be ${expected}.`);
+  };
+  switch (key) {
+    case "enabled":
+      if (typeof value !== "boolean") invalid("a boolean");
+      config.enabled = value as boolean;
+      break;
+    case "pool_mode":
+      if (value !== "transaction" && value !== "session") invalid('"transaction" or "session"');
+      config.pool_mode = value as SupabasePoolerConfig["pool_mode"];
+      break;
+    case "port":
+    case "default_pool_size":
+    case "max_client_conn":
+      if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1 ||
+          (key === "port" && value > 65535)) invalid(key === "port" ? "an integer from 1 to 65535" : "a positive integer");
+      config[key] = value as number;
+      break;
+  }
+}
+
+// Based on supabase/cli's start/templates/pooler.exs and the self-hosted
+// docker/volumes/pooler/pooler.exs. Values come from env, never Elixir source
+// interpolation (passwords may contain quotes, backslashes or #{...}).
+const TENANT_SCRIPT = `{:ok, _} = Application.ensure_all_started(:supavisor)
+{:ok, version} =
+  case Supavisor.Repo.query!("select version()") do
+    %{rows: [[ver]]} -> Supavisor.Helpers.parse_pg_version(ver)
+  end
+params = %{
+  "external_id" => System.fetch_env!("POOLER_TENANT_ID"),
+  "db_host" => System.fetch_env!("POSTGRES_HOST"),
+  "db_port" => 5432,
+  "db_database" => "postgres",
+  "require_user" => false,
+  "auth_query" => "SELECT * FROM pgbouncer.get_auth($1)",
+  "default_max_clients" => String.to_integer(System.fetch_env!("POOLER_MAX_CLIENT_CONN")),
+  "default_pool_size" => String.to_integer(System.fetch_env!("POOLER_DEFAULT_POOL_SIZE")),
+  "default_parameter_status" => %{"server_version" => version},
+  "users" => [%{
+    "db_user" => "pgbouncer",
+    "db_password" => System.fetch_env!("POSTGRES_PASSWORD"),
+    "mode_type" => System.fetch_env!("POOLER_POOL_MODE"),
+    "pool_size" => String.to_integer(System.fetch_env!("POOLER_DEFAULT_POOL_SIZE")),
+    "is_manager" => true
+  }]
+}
+if !Supavisor.Tenants.get_tenant_by_external_id(params["external_id"]) do
+  {:ok, _} = Supavisor.Tenants.create_tenant(params)
+end
+`;
+
+export function supabasePoolerService(opts: {
+  config: SupabasePoolerConfig;
+  dbHost: string;
+  tenantId: string;
+  password: string;
+  jwtSecret: string;
+  tls: boolean;
+  url: string;
+}): ServiceDefinition {
+  const { config, dbHost, tenantId, password, jwtSecret, tls, url } = opts;
+  const quotedUrl = `'${url.replace(/'/g, "'\\''")}'`;
+  return {
+    image: { type: "registry", reference: "supabase/supavisor:2.9.12" },
+    // eval starts the OTP application too. Give that temporary instance
+    // ephemeral SQL ports so readiness only sees the final server process.
+    command: '/app/bin/migrate && PROXY_PORT_SESSION=0 PROXY_PORT_TRANSACTION=0 /app/bin/supavisor eval "$(cat /etc/pooler/pooler.exs)" && exec /app/bin/server',
+    env: {
+      // Bind all auxiliary listeners to ephemeral ports, so any valid pooler
+      // port can be used without colliding with its management/internal ports.
+      PORT: "0",
+      PROXY_PORT: "0",
+      SESSION_PROXY_PORTS: "0",
+      TRANSACTION_PROXY_PORTS: "0",
+      PROXY_PORT_SESSION: config.pool_mode === "session" ? String(config.port) : "0",
+      PROXY_PORT_TRANSACTION: config.pool_mode === "transaction" ? String(config.port) : "0",
+      POSTGRES_HOST: dbHost,
+      POSTGRES_PASSWORD: password,
+      DATABASE_URL: `ecto://supabase_admin:${encodeURIComponent(password)}@${dbHost}:5432/_supabase`,
+      // Metadata connections are separate from the user pool. Keep this small
+      // in a single-node test environment (upstream defaults to 25).
+      DB_POOL_SIZE: "2",
+      SECRET_KEY_BASE: "spectest-supavisor-local-secret-key-base-not-for-production-use-0000",
+      VAULT_ENC_KEY: "spectest".repeat(4),
+      API_JWT_SECRET: jwtSecret,
+      METRICS_JWT_SECRET: jwtSecret,
+      REGION: "local",
+      ERL_AFLAGS: "-proto_dist inet_tcp",
+      POOLER_TENANT_ID: tenantId,
+      POOLER_DEFAULT_POOL_SIZE: String(config.default_pool_size),
+      POOLER_MAX_CLIENT_CONN: String(config.max_client_conn),
+      POOLER_POOL_MODE: config.pool_mode,
+      ...(tls ? {
+        GLOBAL_DOWNSTREAM_CERT_PATH: "/tls/pooler.crt",
+        GLOBAL_DOWNSTREAM_KEY_PATH: "/tls/pooler.key",
+      } : {}),
+    },
+    files: [{ path: "/etc/pooler/pooler.exs", content: TENANT_SCRIPT }],
+    ...(tls ? { certificates: [{
+      hostnames: ["{{SPECTEST_SERVICE}}", "{{SPECTEST_SERVICE}}.internal"],
+      certPath: "/tls/pooler.crt",
+      keyPath: "/tls/pooler.key",
+      user: "root",
+    }] } : {}),
+    ports: [config.port],
+    dependsOn: ["db"],
+    // The pinned image includes psql. Test real tenant authentication and TLS,
+    // with bounded attempts retried by the normal service readiness loop.
+    readyCheck: {
+      type: "exec",
+      command: `PGCONNECT_TIMEOUT=3 PGOPTIONS='-c statement_timeout=3000' psql -X --dbname ${quotedUrl} -v ON_ERROR_STOP=1 -c 'SELECT 1'`,
+      timeoutSecs: 120,
+    },
+  };
+}

package/src/components/supabase.ts

@@ -74,6 +74,7 @@ import { google } from "./google.js";
 import { microsoft } from "./microsoft.js";
 import { SUPABASE_WEBHOOKS_SQL } from "./supabase-webhooks.js";
 import { postgresTls } from "./postgres-tls.js";
+import { supabasePoolerService } from "./supabase-pooler.js";
 import {
   mapSupabaseConfig,
   parseSupabaseConfigFile,
@@ -519,8 +520,11 @@ export interface SupabaseStack {
   anonKey: string;
   /** `service_role` API key (HS256 JWT). */
   serviceRoleKey: string;
-  /** Direct Postgres URL for the app (`postgres` superuser): `postgresql://postgres:<pw>@<name>-db:5432/postgres`. */
+  /** Direct Postgres URL as `postgres`. Use for migrations and LISTEN/NOTIFY. */
   dbUrl: string;
+  /** Supavisor URL as `postgres.<name>`, present when [db.pooler].enabled is true.
+   * Uses the configured pool_mode and port; dbUrl remains a direct connection. */
+  poolerUrl?: string;
   /** The gateway service key — use in a dependent service's `dependsOn` to wait
    *  for the whole stack (the gateway waits on the services behind it). */
   ready: string;
@@ -1855,6 +1859,11 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
   // `auth`/`storage` schemas — regardless of ownership.
   const adminDbUrl = `postgresql://supabase_admin:${encodeURIComponent(dbPassword)}@${dbKey}:5432/postgres` +
     (dbTls ? "?sslmode=verify-full" : "");
+  const pooler = mapped?.pooler.enabled ? mapped.pooler : undefined;
+  const poolerUrl = pooler
+    ? `postgresql://${encodeURIComponent(`postgres.${name}`)}:${encodeURIComponent(dbPassword)}@${name}-pooler:${pooler.port}/postgres` +
+      (dbTls ? "?sslmode=verify-full" : "")
+    : undefined;
 
   // ── social sign-in ────────────────────────────────────────────────────
   // Every `[auth.external.<name>]` the config enables: served in-environment
@@ -1966,12 +1975,30 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
             "supabase_admin",
           );
           await applySqlFile(ctx, SUPABASE_WEBHOOKS_SQL, "database webhooks", "supabase_admin");
+          if (pooler) {
+            // The image supplies pgbouncer.get_auth, but the self-hosted
+            // compose files normally create the pooler's metadata database.
+            await applySqlFile(ctx, `ALTER USER pgbouncer WITH PASSWORD ${pgLiteral(dbPassword)};
+SELECT 'CREATE DATABASE _supabase OWNER supabase_admin'
+WHERE NOT EXISTS (SELECT FROM pg_database WHERE datname = '_supabase')
+\\gexec
+\\connect _supabase supabase_admin
+CREATE SCHEMA IF NOT EXISTS _supavisor AUTHORIZATION supabase_admin;
+`, "pooler bootstrap", "supabase_admin");
+          }
           const extensions = extensionSql(opts.db?.extensions);
           if (extensions) await applySqlFile(ctx, extensions, "configured extensions", "postgres");
         },
       };
       parts.db = dbDef;
 
+      if (pooler && poolerUrl) {
+        parts.pooler = supabasePoolerService({
+          config: pooler, dbHost: db, tenantId: name, password: dbPassword,
+          jwtSecret, tls: !!dbTls, url: poolerUrl,
+        });
+      }
+
       // ── rest (PostgREST) ────────────────────────────────────────────
       parts.rest = {
         image: { type: "registry", reference: IMAGES.rest },
@@ -2395,6 +2422,7 @@ export function supabase(opts: SupabaseOptions = {}): SupabaseStack {
     anonKey,
     serviceRoleKey,
     dbUrl,
+    ...(poolerUrl ? { poolerUrl } : {}),
     ready: name,
     ...(withMail ? { smtp: { host: mailKey, port: 1025 } } : {}),
   };

package/src/daemon.ts

@@ -6177,6 +6177,7 @@ export function harnessMethods(state: RouteState): MethodTable {
       // new method. Check the loaded project, including after warm restore.
       setupInteractive: typeof loaded?.project.interactive?.seed === "function",
       replayEnvironmentMode: true,
+      inFlightTest: state.inFlightTest !== null,
     }),
 
     // Live bootstrap progress, polled by the control plane during

package/src/harness/activity.test.ts

@@ -0,0 +1,20 @@
+import { expect, test } from "bun:test";
+import { harnessMethods } from "../daemon";
+
+test("health reports pending work without acquiring its execution slot", async () => {
+  const state = {
+    inFlightTest: null as Promise<unknown> | null,
+    inFlightBootstrap: null,
+    inFlightProjectSetup: null,
+  };
+  const methods = harnessMethods(state);
+  expect((await methods.health({}) as any).inFlightTest).toBe(false);
+  let finish!: () => void;
+  state.inFlightTest = new Promise<void>((resolve) => { finish = resolve; });
+  expect((await methods.health({}) as any).inFlightTest).toBe(true);
+  finish();
+  await state.inFlightTest;
+  // Completion is acknowledged by the execution-slot owner, not just a request timeout.
+  state.inFlightTest = null;
+  expect((await methods.health({}) as any).inFlightTest).toBe(false);
+});