@specific.dev/spectest 0.113.0 → 0.115.0

package/README.md

@@ -20,6 +20,34 @@ Pub/Sub integrations are project-owned as of SDK 0.98.0. The former
 Use a local service definition or `serviceGroup()` wrapper; the repository’s
 `examples/google-pubsub` demonstrates this using public SDK APIs.
 
+## Interactive entrypoints (0.114.0)
+
+Choose the links shown in the interactive dashboard and PR preview comment:
+
+```ts
+const env = defineEnvironment({
+  name: "my-app",
+  services: { web, api },
+  interactive: {
+    instructions: "Sign in as demo@example.com and use 000000 as the code",
+    entrypoints: [
+      { name: "App", url: "https://app.test" },
+      { name: "Admin", url: "https://app.test/admin" },
+      { name: "API shell", terminal: "api" },
+    ],
+  },
+});
+```
+
+List order is preserved. URLs must match declared service hostnames and are
+translated to public preview URLs, retaining paths, queries and fragments.
+Terminal targets are typed service names and use dashboard member permissions.
+Entrypoints are display metadata; they do not change exposure or test execution.
+With no entries, the only preview link is **Open environment**. Optional
+`interactive.instructions` is a concise, direct plain-text sign-in description,
+shown in a collapsed **Instructions** section in the dashboard and PR
+comment. Blank instructions are omitted.
+
 
 ## Microphone fixtures and WebSocket fakes (0.103.0)
 

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/index.d.ts

@@ -1,6 +1,8 @@
 export type { Phone, PhoneOptions, CallOptions, SpeechOptions } from "./phone.js";
 import type { Phone, PhoneOptions } from "./phone.js";
 import type { Android, AndroidApp } from "./android.js";
+import { type InteractiveEntrypoint, type InteractiveEntrypoints } from "./interactive.js";
+export type { InteractiveEntrypoint, InteractiveEntrypoints } from "./interactive.js";
 export type { Android, AndroidApp, AndroidElement, AndroidRecordingOptions } from "./android.js";
 import { strict as nodeAssert } from "node:assert";
 export type { Carrier, Wrapped, WrappedObject, WrappedArray, WrappedHeaders, WrappedBuffer, WrappedBinaryView, WrappedBytes, WrappedBlob, WrappedFile, WrappedFormData, WrappedStream, WrappedReader, WrappedBYOBReader, WrappedReadResult, WrappedResponse, Provenanced, SpectestFetch, SpectestRequestInit, Unwrap, } from "./inspect.js";
@@ -69,6 +71,11 @@ export interface EnvironmentConfig<S extends ServicesMap = ServicesMap> {
     services: S;
     /** Sandbox timeout in seconds (default 1h). */
     timeoutSecs?: number;
+    /** Display metadata only; entrypoints retain their author-declared order. */
+    interactive?: {
+        entrypoints: InteractiveEntrypoint[];
+        instructions?: string;
+    };
 }
 /**
  * The shape that ends up in the JSON config the control plane and Rust
@@ -1717,6 +1724,15 @@ export interface EnvironmentInput<SI extends InputServicesMap, F extends FakesMa
     /** Services and/or service groups, keyed by name. See
      *  {@link EnvironmentConfig.services} and {@link ServiceGroup}. */
     services: SI;
+    /** Links highlighted in the dashboard and PR previews, in list order.
+     * URL entries target declared service hostnames; terminal entries name services. */
+    interactive?: {
+        entrypoints?: InteractiveEntrypoints<keyof NoInfer<ExpandServices<SI>> & string>;
+        /** Concise, direct plain-text sign-in instructions shown in the dashboard
+         * and a collapsed PR comment section. Example: "Sign in as demo@example.com
+         * and use 000000 as the code". */
+        instructions?: string;
+    };
     /** Sandbox timeout in seconds (default 1h). */
     timeoutSecs?: number;
     /** Fake servers — see {@link defineFake}. Keyed by stable name; the key

package/dist/index.js

@@ -1,3 +1,4 @@
+import { resolveEntrypoints } from "./interactive.js";
 // Spectest SDK. The user's single `spectest/index.ts` calls
 // `defineEnvironment({ name, services })` once, defines test cases via
 // the returned `env.test(...)`, and default-exports `env.project([...])`.
@@ -422,10 +423,9 @@ export function defineFake(opts) {
  * produces the file's default export.
  */
 export function defineEnvironment(input) {
-    // Split fakes off the wire config and expand service groups; only
-    // { name, services, timeoutSecs } — with plain, fully-expanded services —
-    // is stored as `config` and shipped to the control plane.
-    const { fakes, services: rawServices, ...rest } = input;
+    // Split fakes off the wire config, expand service groups, and validate
+    // interactive destinations against the final service names.
+    const { fakes, interactive, services: rawServices, ...rest } = input;
     const expanded = expandServiceGroups(rawServices);
     for (const [key, svc] of Object.entries(expanded)) {
         for (const build of svc.imageBuilds ?? [])
@@ -440,6 +440,15 @@ export function defineEnvironment(input) {
         services: expanded,
     };
     validateEnvironmentConfig(config);
+    if (interactive?.instructions !== undefined && typeof interactive.instructions !== "string") {
+        throw new Error("interactive.instructions must be a string");
+    }
+    if (interactive?.entrypoints !== undefined || interactive?.instructions !== undefined) {
+        config.interactive = {
+            entrypoints: interactive.entrypoints === undefined ? [] : resolveEntrypoints(interactive.entrypoints, config.services),
+            ...(interactive.instructions === undefined ? {} : { instructions: interactive.instructions }),
+        };
+    }
     if (fakes)
         validateFakes(config, fakes);
     // Every test created via this env's `.test(...)` is registered here. A

package/dist/interactive.d.ts

@@ -0,0 +1,18 @@
+/** One destination highlighted in interactive environments and PR previews. */
+export type InteractiveEntrypoint<Service extends string = string> = {
+    name: string;
+} & ({
+    url: string;
+    terminal?: never;
+} | {
+    terminal: Service;
+    url?: never;
+});
+/** Display order is exactly the order of this list. */
+export type InteractiveEntrypoints<Service extends string = string> = readonly InteractiveEntrypoint<Service>[];
+export declare function resolveEntrypoints(entries: InteractiveEntrypoints, services: Record<string, {
+    hostnames?: readonly string[];
+    tls?: readonly {
+        hostname: string;
+    }[];
+}>): InteractiveEntrypoint[];

package/dist/interactive.js

@@ -0,0 +1,39 @@
+export function resolveEntrypoints(entries, services) {
+    if (!Array.isArray(entries))
+        throw new Error("interactive.entrypoints must be a list");
+    const names = new Set();
+    return entries.map((entry, index) => {
+        const fail = (reason) => { throw new Error(`interactive.entrypoints[${index}]: ${reason}`); };
+        if (!entry || typeof entry.name !== "string" || !entry.name.trim())
+            fail("name must be a non-empty string");
+        const { name } = entry;
+        if (names.has(name))
+            fail(`duplicate name ${JSON.stringify(name)}`);
+        names.add(name);
+        if ((entry.url !== undefined) === (entry.terminal !== undefined))
+            fail("specify exactly one of url or terminal");
+        if (entry.terminal !== undefined) {
+            if (typeof entry.terminal !== "string" || !Object.hasOwn(services, entry.terminal)) {
+                fail("terminal must name a declared service");
+            }
+            return { name, terminal: entry.terminal };
+        }
+        if (typeof entry.url !== "string")
+            return fail("expected an absolute HTTP or HTTPS URL");
+        let url;
+        try {
+            url = new URL(entry.url);
+        }
+        catch {
+            return fail("expected an absolute HTTP or HTTPS URL");
+        }
+        if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.port) {
+            fail("use an HTTP or HTTPS service URL without credentials or a non-default port");
+        }
+        const declared = Object.values(services).some((service) => [...(service.hostnames ?? []), ...(service.tls ?? []).map((tls) => tls.hostname)]
+            .some((host) => !host.startsWith("*.") && host.toLowerCase() === url.hostname));
+        if (!declared)
+            fail(`hostname ${JSON.stringify(url.hostname)} is not a declared service endpoint`);
+        return { name, url: url.href };
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.113.0",
+  "version": "0.115.0",
   "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/index.ts

@@ -1,6 +1,8 @@
 export type { Phone, PhoneOptions, CallOptions, SpeechOptions } from "./phone.js";
 import type { Phone, PhoneOptions } from "./phone.js";
 import type { Android, AndroidApp } from "./android.js";
+import { resolveEntrypoints, type InteractiveEntrypoint, type InteractiveEntrypoints } from "./interactive.js";
+export type { InteractiveEntrypoint, InteractiveEntrypoints } from "./interactive.js";
 export type { Android, AndroidApp, AndroidElement, AndroidRecordingOptions } from "./android.js";
 // Spectest SDK. The user's single `spectest/index.ts` calls
 // `defineEnvironment({ name, services })` once, defines test cases via
@@ -245,6 +247,8 @@ export interface EnvironmentConfig<S extends ServicesMap = ServicesMap> {
   services: S;
   /** Sandbox timeout in seconds (default 1h). */
   timeoutSecs?: number;
+  /** Display metadata only; entrypoints retain their author-declared order. */
+  interactive?: { entrypoints: InteractiveEntrypoint[]; instructions?: string };
 }
 
 /**
@@ -2481,6 +2485,15 @@ export interface EnvironmentInput<
   /** Services and/or service groups, keyed by name. See
    *  {@link EnvironmentConfig.services} and {@link ServiceGroup}. */
   services: SI;
+  /** Links highlighted in the dashboard and PR previews, in list order.
+   * URL entries target declared service hostnames; terminal entries name services. */
+  interactive?: {
+    entrypoints?: InteractiveEntrypoints<keyof NoInfer<ExpandServices<SI>> & string>;
+    /** Concise, direct plain-text sign-in instructions shown in the dashboard
+     * and a collapsed PR comment section. Example: "Sign in as demo@example.com
+     * and use 000000 as the code". */
+    instructions?: string;
+  };
   /** Sandbox timeout in seconds (default 1h). */
   timeoutSecs?: number;
   /** Fake servers — see {@link defineFake}. Keyed by stable name; the key
@@ -2591,10 +2604,9 @@ export function defineEnvironment<
   F extends FakesMap = FakesMap,
 >(input: EnvironmentInput<SI, F>): DefinedEnvironment<ExpandServices<SI>, F> {
   type S = ExpandServices<SI>;
-  // Split fakes off the wire config and expand service groups; only
-  // { name, services, timeoutSecs } — with plain, fully-expanded services —
-  // is stored as `config` and shipped to the control plane.
-  const { fakes, services: rawServices, ...rest } = input;
+  // Split fakes off the wire config, expand service groups, and validate
+  // interactive destinations against the final service names.
+  const { fakes, interactive, services: rawServices, ...rest } = input;
   const expanded = expandServiceGroups(rawServices);
   for (const [key, svc] of Object.entries(expanded)) {
     for (const build of svc.imageBuilds ?? []) validateServiceImage(`${key} image ${build.reference}`, build.image);
@@ -2608,6 +2620,15 @@ export function defineEnvironment<
     services: expanded as S,
   };
   validateEnvironmentConfig(config);
+  if (interactive?.instructions !== undefined && typeof interactive.instructions !== "string") {
+    throw new Error("interactive.instructions must be a string");
+  }
+  if (interactive?.entrypoints !== undefined || interactive?.instructions !== undefined) {
+    config.interactive = {
+      entrypoints: interactive.entrypoints === undefined ? [] : resolveEntrypoints(interactive.entrypoints, config.services),
+      ...(interactive.instructions === undefined ? {} : { instructions: interactive.instructions }),
+    };
+  }
   if (fakes) validateFakes(config, fakes);
 
   // Every test created via this env's `.test(...)` is registered here. A

package/src/interactive-setup.test.ts

@@ -16,7 +16,10 @@ for (const withHook of [false, true]) {
       await writeFile(entry, `
         import { defineEnvironment } from ${JSON.stringify(new URL("./index.ts", import.meta.url).href)};
         export const calls = [];
-        const env = defineEnvironment({ name: "seed", services: {
+        const env = defineEnvironment({ name: "seed", interactive: {
+          entrypoints: [{ name: "App shell", terminal: "app" }],
+          instructions: "Sign in as demo@example.com and use 000000 as the code",
+        }, services: {
           app: { image: { type: "registry", reference: "busybox" },
             helpers: () => ({ label: "typed helper" }) },
         }});
@@ -43,7 +46,9 @@ for (const withHook of [false, true]) {
         import { METHODS } from ${JSON.stringify(new URL("./daemon.ts", import.meta.url).href)};
         import { calls } from ${JSON.stringify(entry)};
         const nativeFetch = globalThis.fetch;
-        await METHODS.load({});
+        const loaded = await METHODS.load({});
+        assert.deepEqual(loaded.environment.interactive.entrypoints, [{ name: "App shell", terminal: "app" }]);
+        assert.equal(loaded.environment.interactive.instructions, "Sign in as demo@example.com and use 000000 as the code");
         assert.equal((await METHODS.health({})).setupInteractive, ${withHook});
         await METHODS.projectSetup({});
         assert.deepEqual(calls, ["baseline"]);

package/src/interactive.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from "bun:test";
+import { defineEnvironment, serviceGroup, type InteractiveEntrypoints } from "./index.js";
+
+const services = {
+  web: { image: { type: "registry" as const, reference: "nginx" }, tls: [{ hostname: "app.test", port: 80 }] },
+  api: { image: { type: "registry" as const, reference: "nginx" }, hostnames: ["api.test"] },
+};
+
+describe("interactive entrypoints", () => {
+  test("instructions survive serialization without any entrypoints", () => {
+    const instructions = "Sign in as demo@example.com and use 000000 as the code";
+    const env = defineEnvironment({ name: "app", services, interactive: { instructions } });
+    expect(JSON.parse(JSON.stringify(env.project().environment)).interactive).toEqual({ entrypoints: [], instructions });
+  });
+
+  test("instructions must be a string", () => {
+    const invalid = () => defineEnvironment({ name: "app", services, interactive: {
+      // @ts-expect-error instructions are plain text
+      instructions: 123,
+    } });
+    expect(invalid).toThrow("interactive.instructions must be a string");
+  });
+  test("keeps mixed destinations in list order on the project wire config", () => {
+    const env = defineEnvironment({ name: "app", services, interactive: { entrypoints: [
+      { name: "Website", url: "https://app.test/admin?tab=users#invite" },
+      { name: "2", terminal: "api" },
+      { name: "1", url: "http://api.test/docs" },
+    ] } });
+    const config = JSON.parse(JSON.stringify(env.project().environment));
+    expect(config.interactive.entrypoints).toEqual([
+      { name: "Website", url: "https://app.test/admin?tab=users#invite" },
+      { name: "2", terminal: "api" },
+      { name: "1", url: "http://api.test/docs" },
+    ]);
+    expect(env.project().tests).toBeUndefined();
+  });
+
+  test("omitting entrypoints leaves existing projects unchanged", () => {
+    expect(defineEnvironment({ name: "app", services }).config.interactive).toBeUndefined();
+  });
+
+  test("terminal destinations can name expanded service-group members", () => {
+    const stack = serviceGroup({ primary: "api", services: () => ({ api: services.api, worker: services.web }) });
+    const env = defineEnvironment({ name: "app", services: { stack }, interactive: {
+      entrypoints: [{ name: "Worker shell", terminal: "stack-worker" }],
+    } });
+    expect(env.config.interactive?.entrypoints).toEqual([{ name: "Worker shell", terminal: "stack-worker" }]);
+  });
+
+  test.each([null, { App: "https://app.test" }])("requires a list: %j", (entries) => {
+    expect(() => defineEnvironment({ name: "app", services, interactive: {
+      entrypoints: entries as unknown as InteractiveEntrypoints<"web" | "api">,
+    } })).toThrow("must be a list");
+  });
+
+  test("terminal service names are checked statically and at runtime", () => {
+    const invalid = () => defineEnvironment({ name: "app", services, interactive: { entrypoints: [
+      // @ts-expect-error terminal targets must be declared services
+      { name: "Shell", terminal: "missing" },
+    ] } });
+    expect(invalid).toThrow("terminal must name a declared service");
+  });
+
+  test.each([
+    [{ name: "App", url: "https://external.test" }],
+    [{ name: "App", url: "/relative" }],
+    [{ name: "App", url: "javascript:alert(1)" }],
+    [{ name: "App", url: "https://user:pass@app.test" }],
+    [{ name: "App", url: "https://app.test:8443" }],
+    [{ name: "App", url: "https://app.test", terminal: "web" }],
+    [{ name: "App" }],
+    [{ name: "", terminal: "web" }],
+    [{ name: "Same", terminal: "web" }, { name: "Same", terminal: "api" }],
+  ])("rejects invalid destinations %j", (...entries) => {
+    expect(() => defineEnvironment({ name: "app", services, interactive: {
+      entrypoints: entries as unknown as InteractiveEntrypoints<"web" | "api">,
+    } })).toThrow("interactive.entrypoints");
+  });
+});

package/src/interactive.ts

@@ -0,0 +1,41 @@
+/** One destination highlighted in interactive environments and PR previews. */
+export type InteractiveEntrypoint<Service extends string = string> = { name: string } & (
+  | { url: string; terminal?: never }
+  | { terminal: Service; url?: never }
+);
+
+/** Display order is exactly the order of this list. */
+export type InteractiveEntrypoints<Service extends string = string> = readonly InteractiveEntrypoint<Service>[];
+
+export function resolveEntrypoints(
+  entries: InteractiveEntrypoints,
+  services: Record<string, { hostnames?: readonly string[]; tls?: readonly { hostname: string }[] }>,
+): InteractiveEntrypoint[] {
+  if (!Array.isArray(entries)) throw new Error("interactive.entrypoints must be a list");
+  const names = new Set<string>();
+  return entries.map((entry, index) => {
+    const fail = (reason: string): never => { throw new Error(`interactive.entrypoints[${index}]: ${reason}`); };
+    if (!entry || typeof entry.name !== "string" || !entry.name.trim()) fail("name must be a non-empty string");
+    const { name } = entry;
+    if (names.has(name)) fail(`duplicate name ${JSON.stringify(name)}`);
+    names.add(name);
+    if ((entry.url !== undefined) === (entry.terminal !== undefined)) fail("specify exactly one of url or terminal");
+    if (entry.terminal !== undefined) {
+      if (typeof entry.terminal !== "string" || !Object.hasOwn(services, entry.terminal)) {
+        fail("terminal must name a declared service");
+      }
+      return { name, terminal: entry.terminal };
+    }
+    if (typeof entry.url !== "string") return fail("expected an absolute HTTP or HTTPS URL");
+    let url: URL;
+    try { url = new URL(entry.url); } catch { return fail("expected an absolute HTTP or HTTPS URL"); }
+    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.port) {
+      fail("use an HTTP or HTTPS service URL without credentials or a non-default port");
+    }
+    const declared = Object.values(services).some((service) =>
+      [...(service.hostnames ?? []), ...(service.tls ?? []).map((tls) => tls.hostname)]
+        .some((host) => !host.startsWith("*.") && host.toLowerCase() === url.hostname));
+    if (!declared) fail(`hostname ${JSON.stringify(url.hostname)} is not a declared service endpoint`);
+    return { name, url: url.href };
+  });
+}