@supatype/cli 0.1.6 → 0.1.7

package/src/self-host-compose.ts

@@ -3,9 +3,21 @@ import { dirname, join, relative, resolve } from "node:path"
 import { spawnSync } from "node:child_process"
 import { requireDockerDaemon, type DockerBrandOptions } from "./docker-runtime.js"
 import { fatalError } from "./ui/fatal.js"
-import { preferredFunctionsPathFromProject, selfHostTlsEnabled, type SupatypeProjectConfig } from "./project-config.js"
+import {
+  apiSchemaList,
+  externalDatabaseUrl,
+  hooksPathFromProject,
+  preferredFunctionsPathFromProject,
+  realtimeEnabled,
+  serviceRoleRoutes,
+  selfHostTlsEnabled,
+  usesExternalDatabase,
+  type SupatypeProjectConfig,
+} from "./project-config.js"
 import { hasEngineOverride, hasStudioOverride, pinnedVersion, fetchLatestVersion, VERSION_PIN_LOCAL } from "./binary-cache.js"
 import { buildKongDeclarative } from "./kong-config.js"
+import { readEnvFile } from "./env-file.js"
+import { fieldMaskingTierFromProject, type FieldMaskingTier } from "./field-masking-tier.js"
 
 /** Env keys written when `versions` pins exist in supatype.config.ts. */
 export const COMPOSE_PINNED_IMAGE_ENV_KEYS = [
@@ -181,6 +193,47 @@ function kongMountPath(_cwd: string): string {
   return ".supatype/self-host/kong.yml"
 }
 
+/**
+ * The DSN every service uses for the schema-owning role.
+ *
+ * One expression instead of six identical constructions of `@db:5432`. With an external database it
+ * becomes `${DATABASE_URL:?…}`: the URL is the operator's, so there is nothing for the generator to
+ * build — and interpolating the value into the compose file would write a password into a generated
+ * file. Compose resolves the variable from `.env` at up-time, the same place the config's
+ * `process.env.DATABASE_URL` read it from.
+ */
+function ownerDatabaseUrl(config: SupatypeProjectConfig, scheme = "postgresql"): string {
+  if (usesExternalDatabase(config)) {
+    return "${DATABASE_URL:?DATABASE_URL is missing from .env — required by database.external}"
+  }
+  return (
+    `${scheme}://\${POSTGRES_USER:-supatype_admin}:` +
+    "\${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is missing from .env}" +
+    "@db:5432/\${POSTGRES_DB:-supatype}"
+  )
+}
+
+/**
+ * PostgREST's DSN, which connects as `authenticator` rather than the owner.
+ *
+ * For an external database the host, port, database and query string are taken from the operator's
+ * URL and only the password stays a variable. The alternative — a second full URL in `.env` — is one
+ * more thing to keep in step with the first, and two URLs that disagree about *which database* is a
+ * split-brain nobody notices until the API is serving one and migrations are landing in the other.
+ * A hostname is not the secret here; the password is, and it stays out of the generated file.
+ */
+function postgrestDatabaseUrl(config: SupatypeProjectConfig): string {
+  const password = "${AUTHENTICATOR_PASSWORD:?AUTHENTICATOR_PASSWORD is missing from .env}"
+  const externalUrl = externalDatabaseUrl(config)
+  if (externalUrl === undefined) {
+    return `postgresql://authenticator:${password}@db:5432/\${POSTGRES_DB:-supatype}`
+  }
+
+  const parsed = new URL(externalUrl)
+  const port = parsed.port ? `:${parsed.port}` : ""
+  return `postgresql://authenticator:${password}@${parsed.hostname}${port}${parsed.pathname}${parsed.search}`
+}
+
 /** Host Vite dev server as seen from Kong inside Docker Compose. */
 export const COMPOSE_STUDIO_HOST_URL = "http://host.docker.internal:3002"
 
@@ -225,6 +278,14 @@ function serverAppEnvForCompose(config: SupatypeProjectConfig, devLocal: boolean
 export interface SelfHostComposeOptions {
   /** `supatype dev` with provider docker: internal-only db/server; Kong on host :18473. */
   devLocal?: boolean
+  /**
+   * Which mechanism enforces per-column rules, when the caller knows.
+   *
+   * Only the call sites that have loaded the schema can say — see `field-masking-tier.ts`. Left
+   * unset, the exposed schema list is today's, which is correct for every project without field
+   * rules and for every project on `supatype/postgres`.
+   */
+  fieldMaskingTier?: FieldMaskingTier
 }
 
 export function renderSelfHostCompose(
@@ -234,6 +295,14 @@ export function renderSelfHostCompose(
 ): string {
   const projectMount = projectMountPath(cwd)
   const kongMount = kongMountPath(cwd)
+  const external = usesExternalDatabase(config)
+  const ownerUrl = ownerDatabaseUrl(config)
+  // GoTrue's driver wants the `postgres://` spelling; an external URL is used as given.
+  const gotrueUrl = external ? ownerUrl : ownerDatabaseUrl(config, "postgres")
+  // An external URL may already carry query parameters (`?sslmode=require` is common on managed
+  // providers), and appending a second `?` produces a DSN that fails to parse.
+  const gotrueSearchPathSeparator = externalDatabaseUrl(config)?.includes("?") ? "&" : "?"
+  const postgrestUrl = postgrestDatabaseUrl(config)
   const devLocal = options?.devLocal === true
   const tlsEnabled = selfHostTlsEnabled(config, devLocal)
   const domain = config.server.domain?.trim() ?? ""
@@ -308,61 +377,126 @@ ${studioService}
   #   server: { mode: "standalone", domain: "your.domain", tls: { email: "you@example.com" } }
   # then re-run \`supatype self-host compose up -d\`. Kong publishes :80/:443 and provisions certs automatically.
 `
+  // An external database is not ours to declare a volume for.
   const volumesBlock = `volumes:
-  db-data:
-  minio-data:
+${external ? "" : "  db-data:\n"}  minio-data:
   valkey-data:
 `
 
-  return `# Generated by supatype self-host compose
-# Kong → supatype-server (unified gateway) → internal PostgREST / storage / etc.
-services:
-  db:
+  // `depends_on` for the services that talk to Postgres. With an external database there is no
+  // container to wait on, so the clause disappears entirely and each service retries on connect
+  // instead — which is also what covers a database that restarts *after* boot, something no
+  // healthcheck ever did.
+  const dbDependencyClause = external
+    ? ""
+    : `      db:
+        condition: service_healthy
+`
+  const dbDependency = external ? "" : `    depends_on:\n${dbDependencyClause}`
+
+  // Realtime, omitted entirely when the project has turned it off.
+  //
+  // Not started-and-disabled: the service degrades gracefully on its own (it reports the reason on
+  // /health/ready rather than crash-looping), so this switch is for the operator who has read
+  // `supatype db check`, knows their database cannot do logical decoding, and would rather not run a
+  // container that can only report that. The server then has no realtime URL, which is what makes
+  // subscription requests fail with a clear route error instead of hanging against a dead upstream.
+  const realtime = realtimeEnabled(config)
+  const realtimeBlock = realtime
+    ? `  realtime:
+    image: \${SUPATYPE_REALTIME_IMAGE:-supatype/realtime:latest}
+    expose:
+      - "4000"
+    environment:
+      PORT: "4000"
+      DATABASE_URL: "${ownerUrl}"
+      JWT_SECRET: \${JWT_SECRET:?JWT_SECRET is missing from .env}
+      SLOT_NAME: supatype_realtime
+      # Matches the publication the supatype/postgres image creates. Read by nothing today —
+      # wal2json decodes from the slot — and kept for a future pgoutput decoder.
+      PUBLICATION_NAME: supatype_realtime
+${dbDependency}`
+    : `  # No \`realtime\` service: database.external.realtime is false. Subscriptions are
+  # unavailable; REST, storage, auth and functions are unaffected.
+`
+  const realtimeDependency = realtime
+    ? `      realtime:
+        condition: service_started
+`
+    : ""
+  const realtimeServerEnv = realtime ? "      SUPATYPE_REALTIME_URL: http://realtime:4000" : ""
+
+  const dbServiceBlock = external
+    ? `  # No \`db\` service: database.external points this stack at a Postgres it does not manage.
+  # Every service reads \${DATABASE_URL} from .env, and \`supatype db check\` reports what that
+  # database still needs (roles, extensions, wal_level for realtime).
+`
+    : `  db:
     image: \${SUPATYPE_POSTGRES_IMAGE:-supatype/postgres:latest}
     environment:
       POSTGRES_USER: \${POSTGRES_USER:-supatype_admin}
-      POSTGRES_PASSWORD: \${POSTGRES_PASSWORD:-postgres}
+      POSTGRES_PASSWORD: \${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is missing from .env}
       POSTGRES_DB: \${POSTGRES_DB:-supatype}
+      # Read by the image's init to password the \`authenticator\` role PostgREST connects as.
+      AUTHENTICATOR_PASSWORD: \${AUTHENTICATOR_PASSWORD:?AUTHENTICATOR_PASSWORD is missing from .env}
 ${dbPorts}    volumes:
       - db-data:/var/lib/postgresql/data
     healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U \${POSTGRES_USER:-supatype_admin}"]
+      # -h 127.0.0.1 forces TCP. Without it \`pg_isready\` uses the Unix socket, which the
+      # entrypoint's temporary init server is already listening on while TCP is still refused —
+      # so the container reported healthy, \`depends_on: service_healthy\` released, and every
+      # service that connects over the network died with ECONNREFUSED on first boot. PostgREST
+      # survived only because it retries. Observed on a clean stack: server, storage and
+      # realtime all exited 1 while db said "healthy".
+      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U \${POSTGRES_USER:-supatype_admin} -d \${POSTGRES_DB:-supatype}"]
       interval: 5s
       timeout: 5s
+      # First boot runs initdb plus every bootstrap migration. Failures inside the start period
+      # do not count against retries, so a slow init waits rather than being declared unhealthy.
+      start_period: 90s
       retries: 20
 
-  postgrest:
+`
+
+  return `# Generated by supatype self-host compose
+# Kong → supatype-server (unified gateway) → internal PostgREST / storage / etc.
+services:
+${dbServiceBlock}  postgrest:
     image: postgrest/postgrest:v12.2.8
     expose:
       - "3000"
     environment:
-      PGRST_DB_URI: postgresql://\${POSTGRES_USER:-supatype_admin}:\${POSTGRES_PASSWORD:-postgres}@db:5432/\${POSTGRES_DB:-supatype}
-      PGRST_DB_SCHEMA: "public, supatype, graphql_public, auth"
+      # Connects as \`authenticator\`, not \${POSTGRES_USER} — which is a superuser, and a
+      # superuser session may SET ROLE to any role in the cluster, so a request whose JWT
+      # named one got it. \`authenticator\` is NOINHERIT with membership in only
+      # anon/authenticated/service_role, so the same SET ROLE is refused.
+      #
+      # Its own credential, not POSTGRES_PASSWORD: yours is for direct SQL access and
+      # rotating it must not take the REST API down. \`supatype init\` generates this.
+      PGRST_DB_URI: ${postgrestUrl}
+      # Derived from schema.pg_schema (or schema.api_schemas). Hardcoding this is why choosing a
+      # non-public pg_schema used to give a correct push and an API that answered PGRST106 for
+      # everything — the engine moved and PostgREST was never told.
+      PGRST_DB_SCHEMA: "${apiSchemaList(config, options?.fieldMaskingTier)}"
       PGRST_DB_ANON_ROLE: anon
-      PGRST_JWT_SECRET: \${JWT_SECRET:-super-secret-jwt-token-change-in-production}
+      PGRST_JWT_SECRET: \${JWT_SECRET:?JWT_SECRET is missing from .env}
       PGRST_DB_EXTRA_SEARCH_PATH: public,extensions
       PGRST_DB_POOL: 3
-    depends_on:
-      db:
-        condition: service_healthy
-
+${dbDependency}
   storage:
     image: \${SUPATYPE_STORAGE_IMAGE:-supatype/storage:latest}
     expose:
       - "5000"
     environment:
       PORT: 5000
-      DATABASE_URL: "postgresql://\${POSTGRES_USER:-supatype_admin}:\${POSTGRES_PASSWORD:-postgres}@db:5432/\${POSTGRES_DB:-supatype}"
-      JWT_SECRET: \${JWT_SECRET:-super-secret-jwt-token-change-in-production}
+      DATABASE_URL: "${ownerUrl}"
+      JWT_SECRET: \${JWT_SECRET:?JWT_SECRET is missing from .env}
       S3_ENDPOINT: http://minio:9000
       S3_REGION: us-east-1
       S3_ACCESS_KEY: supatype
       S3_SECRET_KEY: supatype-secret
       S3_FORCE_PATH_STYLE: "true"
-    depends_on:
-      db:
-        condition: service_healthy
-
+${dbDependency}
   functions-worker:
     image: \${SUPATYPE_FUNCTIONS_WORKER_IMAGE:-supatype/functions-worker:latest}
     expose:
@@ -372,31 +506,26 @@ ${dbPorts}    volumes:
     environment:
       SUPATYPE_FUNCTIONS_ROOT: /project/functions
       SUPATYPE_DENO_FUNCTIONS_DIR: /project/functions
+      # Model hooks, served by this same worker under a hooks/ route the gateway refuses from
+      # outside. One worker rather than two: a second container would cost a pod per project on
+      # cloud, for isolation the route boundary already provides.
+      SUPATYPE_HOOKS_ROOT: /project/hooks
       PORT: "8001"
-      SUPATYPE_URL: \${API_EXTERNAL_URL:-${externalUrlFallback}}
+      # In-compose loopback to Kong (not API_EXTERNAL_URL / localhost — unreachable from this container).
+      SUPATYPE_URL: http://kong:8000
+      SUPATYPE_INTERNAL_URL: http://kong:8000
       SUPATYPE_ANON_KEY: \${ANON_KEY:-}
+      # Present so the worker can hand it to hooks — which are procedural and unreachable from
+      # outside — and to the public functions named below. Withheld from every other handler before
+      # any of them is imported: a function is a public endpoint, and an ambient admin credential made
+      # each one able to read past every access rule in the schema.
       SUPATYPE_SERVICE_ROLE_KEY: \${SERVICE_ROLE_KEY:-}
+      SUPATYPE_SERVICE_ROLE_ROUTES: "${serviceRoleRoutes(config).join(",")}"
       STRIPE_SECRET_KEY: \${STRIPE_SECRET_KEY:-}
       STRIPE_WEBHOOK_SECRET: \${STRIPE_WEBHOOK_SECRET:-}
       SITE_URL: \${SITE_URL:-\${API_EXTERNAL_URL:-${externalUrlFallback}}}
-    depends_on:
-      db:
-        condition: service_healthy
-
-  realtime:
-    image: \${SUPATYPE_REALTIME_IMAGE:-supatype/realtime:latest}
-    expose:
-      - "4000"
-    environment:
-      PORT: "4000"
-      DATABASE_URL: "postgresql://\${POSTGRES_USER:-supatype_admin}:\${POSTGRES_PASSWORD:-postgres}@db:5432/\${POSTGRES_DB:-supatype}"
-      JWT_SECRET: \${JWT_SECRET:-super-secret-jwt-token-change-in-production}
-      SLOT_NAME: supatype_realtime
-      PUBLICATION_NAME: supatype_realtime_pub
-    depends_on:
-      db:
-        condition: service_healthy
-
+${dbDependency}
+${realtimeBlock}
   control-plane:
     image: \${SUPATYPE_CONTROL_PLANE_IMAGE:-supatype/control-plane:latest}
     expose:
@@ -408,16 +537,13 @@ ${dbPorts}    volumes:
       PORT: "8080"
       SUPATYPE_PROJECT_REF: ${JSON.stringify(config.project.name)}
       SUPATYPE_PROJECT_ROOT: /project
-      DATABASE_URL: "postgresql://\${POSTGRES_USER:-supatype_admin}:\${POSTGRES_PASSWORD:-postgres}@db:5432/\${POSTGRES_DB:-supatype}"
+      DATABASE_URL: "${ownerUrl}"
       SUPATYPE_FUNCTIONS_ROOT: /project/functions
       SUPATYPE_STATIC_ROOT: /project/${staticDir.replace(/^\.\//, "")}
       SUPATYPE_DEPLOYMENTS_DIR: /project/.supatype/deployments
       COMPOSE_PROJECT_NAME: ${composeProject}
       SUPATYPE_ENGINE_BIN: supatype-engine
-    depends_on:
-      db:
-        condition: service_healthy
-
+${dbDependency}
   server:
     image: \${SUPATYPE_SERVER_IMAGE:-\${SUPATYPE_AUTH_IMAGE:-supatype/server:latest}}
 ${serverPorts}    volumes:
@@ -434,10 +560,10 @@ ${serverPorts}    volumes:
       SUPATYPE_URL: \${API_EXTERNAL_URL:-${externalUrlFallback}}
       SUPATYPE_ANON_KEY: \${ANON_KEY:-}
       SUPATYPE_SERVICE_ROLE_KEY: \${SERVICE_ROLE_KEY:-}
-      SUPATYPE_SQL_DATABASE_URL: "postgresql://\${POSTGRES_USER:-supatype_admin}:\${POSTGRES_PASSWORD:-postgres}@db:5432/\${POSTGRES_DB:-supatype}"
+      SUPATYPE_SQL_DATABASE_URL: "${ownerUrl}"
       SUPATYPE_DENO_FUNCTIONS_DIR: /project/functions
       SUPATYPE_FUNCTIONS_WORKER_URL: http://functions-worker:8001
-      SUPATYPE_REALTIME_URL: http://realtime:4000
+${realtimeServerEnv}
       SUPATYPE_CONTROL_PLANE_URL: http://control-plane:8080
       SUPATYPE_VALKEY_ADDR: valkey:6379
 ${appEnv}
@@ -446,9 +572,9 @@ ${appEnv}
       API_EXTERNAL_URL: \${API_EXTERNAL_URL:-${externalUrlFallback}}
       GOTRUE_API_EXTERNAL_URL: \${API_EXTERNAL_URL:-${externalUrlFallback}}
       GOTRUE_DB_DRIVER: postgres
-      GOTRUE_DB_DATABASE_URL: "postgres://\${POSTGRES_USER:-supatype_admin}:\${POSTGRES_PASSWORD:-postgres}@db:5432/\${POSTGRES_DB:-supatype}?search_path=auth"
+      GOTRUE_DB_DATABASE_URL: "${gotrueUrl}${gotrueSearchPathSeparator}search_path=auth"
       GOTRUE_SITE_URL: \${SITE_URL:-${siteUrlFallback}}
-      GOTRUE_JWT_SECRET: \${JWT_SECRET:-super-secret-jwt-token-change-in-production}
+      GOTRUE_JWT_SECRET: \${JWT_SECRET:?JWT_SECRET is missing from .env}
       GOTRUE_JWT_EXP: 3600
       GOTRUE_JWT_AUD: authenticated
       GOTRUE_JWT_DEFAULT_GROUP_NAME: authenticated
@@ -457,9 +583,7 @@ ${appEnv}
       GOTRUE_DISABLE_SIGNUP: \${DISABLE_SIGNUP:-false}
 ${devLocal ? "      STUDIO_OPEN_DEV: \"1\"\n" : ""}
     depends_on:
-      db:
-        condition: service_healthy
-      valkey:
+${dbDependencyClause}      valkey:
         condition: service_started
       postgrest:
         condition: service_started
@@ -467,9 +591,7 @@ ${devLocal ? "      STUDIO_OPEN_DEV: \"1\"\n" : ""}
         condition: service_started
       functions-worker:
         condition: service_started
-      realtime:
-        condition: service_started
-      control-plane:
+${realtimeDependency}      control-plane:
         condition: service_started
 
   minio:
@@ -488,10 +610,7 @@ ${minioPorts}    volumes:
     volumes:
       - ${projectMount}:/project
     working_dir: /project
-    depends_on:
-      db:
-        condition: service_healthy
-${studioBlock}${valkeyBlock}${tlsHintComment}  kong:
+${dbDependency}${studioBlock}${valkeyBlock}${tlsHintComment}  kong:
     image: kong:3.6
     environment:
       KONG_DATABASE: "off"
@@ -510,23 +629,173 @@ ${kongDependsOn}${kongValkeyDepends}
 ${volumesBlock}`
 }
 
-function ensureComposeManifest(cwd: string): void {
+/** In-compose worker address — matches the `functions-worker` service this file always generates. */
+const COMPOSE_FUNCTIONS_WORKER_URL = "http://functions-worker:8001"
+
+function ensureComposeManifest(cwd: string, config: SupatypeProjectConfig): void {
   const manifestPath = join(cwd, ".supatype", "manifest.json")
-  if (existsSync(manifestPath)) return
   mkdirSync(dirname(manifestPath), { recursive: true })
+
+  // The manifest is generated, not operator-authored, but `push` writes real values into it (the
+  // schema, for one), so an existing file is repaired rather than replaced.
+  if (existsSync(manifestPath)) {
+    repairComposeFunctionsFlag(manifestPath)
+    return
+  }
+
   const manifest = {
     schema: "public",
     postgrest_url: "http://postgrest:3000",
     storage_url: "http://storage:5000",
-    realtime_enabled: true,
-    realtime_url: "http://realtime:4000",
-    functions_enabled: false,
+    // Matches the compose file: a manifest advertising a service that was not generated is how
+    // the server ends up proxying subscriptions to a host that does not resolve.
+    realtime_enabled: realtimeEnabled(config),
+    ...(realtimeEnabled(config) && { realtime_url: "http://realtime:4000" }),
+    // True because this file *always* generates a `functions-worker` service and hands the server
+    // `SUPATYPE_FUNCTIONS_WORKER_URL`. It said false, so the server answered 404 for every function
+    // in a stack that was running a worker for them — provisioned, then switched off.
+    functions_enabled: true,
+    functions_worker_url: COMPOSE_FUNCTIONS_WORKER_URL,
   }
   writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8")
 }
 
+/**
+ * Turn functions on in a manifest written by an older CLI, leaving every other key alone.
+ *
+ * Without this, only new projects get working functions: a stack generated before the flag was
+ * corrected keeps `functions_enabled: false` on disk, and regenerating the compose file — the
+ * obvious thing to try — does not fix it.
+ */
+function repairComposeFunctionsFlag(manifestPath: string): void {
+  let parsed: Record<string, unknown>
+  try {
+    parsed = JSON.parse(readFileSync(manifestPath, "utf8")) as Record<string, unknown>
+  } catch {
+    return // Malformed: leave it for the server to complain about rather than overwrite it here.
+  }
+  if (typeof parsed !== "object" || parsed === null) return
+  if (parsed["functions_enabled"] === true && parsed["functions_worker_url"] !== undefined) return
+
+  parsed["functions_enabled"] = true
+  if (parsed["functions_worker_url"] === undefined) {
+    parsed["functions_worker_url"] = COMPOSE_FUNCTIONS_WORKER_URL
+  }
+  writeFileSync(manifestPath, `${JSON.stringify(parsed, null, 2)}\n`, "utf8")
+}
+
 function ensureProjectFunctionsDir(cwd: string, config: SupatypeProjectConfig): void {
   mkdirSync(preferredFunctionsPathFromProject(config, cwd), { recursive: true })
+  // Both roots must exist before compose mounts the project read-only: a missing directory becomes
+  // a bind mount of a file that is not there, and the worker fails to start rather than serving the
+  // half it does have.
+  mkdirSync(hooksPathFromProject(config, cwd), { recursive: true })
+}
+
+/**
+ * The config's external URL and `.env`'s `DATABASE_URL` must be the same string.
+ *
+ * The CLI resolves the URL from config; Compose substitutes `.env` at up-time. If the two disagree,
+ * `push` migrates one database while the services serve another — which reads as data loss and
+ * isn't. It also makes the generated GoTrue DSN wrong, since whether to append `search_path` with
+ * `?` or `&` is decided from the config URL's query string.
+ */
+function assertExternalUrlMatchesEnv(cwd: string, config: SupatypeProjectConfig): void {
+  const configured = externalDatabaseUrl(config)
+  if (configured === undefined) return
+
+  const fromEnv = readEnvFile(cwd)["DATABASE_URL"]
+  if (fromEnv === undefined) {
+    // Nothing to disagree with. Compose's own `:?` guard reports this at up-time, and the operator
+    // may be exporting the variable in their shell rather than keeping a file.
+    return
+  }
+  if (fromEnv.trim() === configured) return
+
+  fatalError(
+    "DATABASE_URL in .env does not match database.external.url",
+    [
+      `.env:    ${fromEnv.trim()}`,
+      `config:  ${configured}`,
+      "",
+      "The CLI connects using the config value and the stack connects using .env, so a push would",
+      "land in one database while the services serve the other.",
+      "Point the config at the same variable to keep them in step:",
+      "  database: { external: { url: process.env.DATABASE_URL! } }",
+    ],
+    { brand: { intro: "Self-host compose" } },
+  )
+}
+
+/**
+ * A loopback host in the external URL cannot work from inside a container.
+ *
+ * `127.0.0.1` means "this container" to every service in the stack, so an external database on the
+ * host machine is unreachable — while the *CLI* reaches it fine, because the CLI runs on the host.
+ * That asymmetry is the trap: `supatype db check` passes, `push` applies the schema, and then
+ * storage, realtime and the server all die with ECONNREFUSED against their own loopback. Found by
+ * rehearsing exactly that.
+ *
+ * Refused rather than rewritten. The compose file interpolates one `${DATABASE_URL}` for every
+ * service, so silently substituting a different host would mean the CLI and the stack no longer
+ * agree about which database they are talking to — the thing every other check here exists to
+ * prevent.
+ */
+export function loopbackExternalHost(config: SupatypeProjectConfig): string | undefined {
+  const url = externalDatabaseUrl(config)
+  if (url === undefined) return undefined
+
+  let host: string
+  try {
+    host = new URL(url).hostname.toLowerCase()
+  } catch {
+    return undefined // Shape is validated at config load; nothing useful to add here.
+  }
+  // Node strips the brackets from an IPv6 hostname, and 127.0.0.0/8 is all loopback.
+  const loopback =
+    host === "localhost" ||
+    host === "::1" ||
+    host === "[::1]" ||
+    /^127\.\d+\.\d+\.\d+$/.test(host)
+  return loopback ? host : undefined
+}
+
+function assertExternalUrlReachableFromContainers(config: SupatypeProjectConfig): void {
+  const host = loopbackExternalHost(config)
+  if (host === undefined) return
+
+  fatalError(
+    `database.external.url points at ${host}, which no container can reach`,
+    [
+      "Inside a container, localhost is that container — not the machine running Docker. Every",
+      "service in the stack would fail to connect, while the CLI succeeds because it runs on the host.",
+      "",
+      "Use a host the containers can resolve:",
+      "  host.docker.internal   (Docker Desktop on macOS and Windows)",
+      "  172.17.0.1             (the docker0 bridge on Linux, or add an extra_hosts entry)",
+      "  the database's LAN address or hostname",
+      "",
+      "The CLI reaches the same address, so one value keeps working for both.",
+    ],
+    { brand: { intro: "Self-host compose" } },
+  )
+}
+
+/**
+ * The tier to write into the compose file.
+ *
+ * Resolved here so every caller gets it, rather than threaded through four call sites that load the
+ * schema a moment later anyway. A schema that fails to load falls back to the default list: compose
+ * generation is the wrong place to report a syntax error, and `push`/`dev` do it properly seconds
+ * later with the file and line.
+ */
+function resolveFieldMaskingTier(
+  cwd: string,
+  config: SupatypeProjectConfig,
+  options?: SelfHostComposeOptions,
+): FieldMaskingTier | undefined {
+  if (options?.fieldMaskingTier !== undefined) return options.fieldMaskingTier
+  return fieldMaskingTierFromProject(cwd, config)
 }
 
 export function writeSelfHostCompose(
@@ -534,11 +803,18 @@ export function writeSelfHostCompose(
   config: SupatypeProjectConfig,
   options?: SelfHostComposeOptions,
 ): SelfHostComposePaths {
+  assertExternalUrlMatchesEnv(cwd, config)
+  const tier = resolveFieldMaskingTier(cwd, config, options)
+  const resolved: SelfHostComposeOptions = {
+    ...options,
+    ...(tier !== undefined && { fieldMaskingTier: tier }),
+  }
+  assertExternalUrlReachableFromContainers(config)
   const paths = selfHostComposePaths(cwd)
   mkdirSync(paths.dir, { recursive: true })
   ensureProjectFunctionsDir(cwd, config)
-  ensureComposeManifest(cwd)
-  writeFileSync(paths.composePath, renderSelfHostCompose(config, cwd, options), "utf8")
+  ensureComposeManifest(cwd, config)
+  writeFileSync(paths.composePath, renderSelfHostCompose(config, cwd, resolved), "utf8")
   const studioHostDev = options?.devLocal === true && hasStudioOverride(config)
   const tlsEnabled = selfHostTlsEnabled(config, options?.devLocal === true)
   const domain = config.server.domain?.trim()

package/src/service-role-check.ts

@@ -0,0 +1,111 @@
+/**
+ * Check that every name in `functions.serviceRole` is a function that exists.
+ *
+ * The grant fails **closed**: a typo, or a function that has since been renamed, means that function
+ * quietly does not receive the service-role key. Nothing breaks loudly — the handler simply reads
+ * `undefined` and whatever it does with the key stops working, at runtime, in a deploy that reported
+ * success. So the name is checked where it is declared, against the directory it must match.
+ *
+ * `serviceRoleRoutes()` claimed this was already true. It was not: nothing read the list except the two
+ * places that turn it into an env var.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs"
+import { join, relative } from "node:path"
+
+import {
+  functionsPathCandidatesFromProject,
+  serviceRoleRoutes,
+  type SupatypeProjectConfig,
+} from "./project-config.js"
+
+export interface ServiceRoleProblems {
+  /** Names with no matching function. Each line is ready to print. */
+  errors: string[]
+  /** The same names, unformatted, for callers that need to mark them rather than print them. */
+  missing: string[]
+  /** Entries that are harmless but say nothing, e.g. a hook. */
+  warnings: string[]
+  /** Function names available to be granted, for the "did you mean" line. */
+  available: string[]
+}
+
+/** Function directory names, matching how the worker discovers routes. */
+function availableFunctions(dirs: readonly string[]): string[] {
+  const names = new Set<string>()
+  for (const dir of dirs) {
+    if (!existsSync(dir)) continue
+    for (const entry of readdirSync(dir)) {
+      if (entry.startsWith("_") || entry.startsWith(".")) continue
+      const full = join(dir, entry)
+      if (statSync(full).isDirectory()) {
+        if (existsSync(join(full, "index.ts"))) names.add(entry)
+      } else if (entry.endsWith(".ts") && !entry.endsWith(".d.ts")) {
+        names.add(entry.replace(/\.ts$/, ""))
+      }
+    }
+  }
+  return [...names].sort()
+}
+
+/**
+ * Resolve the declared grants against what is on disk.
+ *
+ * Returns the problems rather than throwing, so `push` can refuse while `doctor` reports alongside
+ * everything else it found.
+ */
+export function checkServiceRoleRoutes(
+  cfg: SupatypeProjectConfig,
+  cwd: string,
+): ServiceRoleProblems {
+  const declared = serviceRoleRoutes(cfg)
+  if (declared.length === 0) return { errors: [], missing: [], warnings: [], available: [] }
+
+  const dirs = functionsPathCandidatesFromProject(cfg, cwd)
+  const available = availableFunctions(dirs)
+  const known = new Set(available)
+  // Forward slashes and the candidates listed separately: joining them into one path produced
+  // "no functions or supatype\functions/send-email/index.ts", which reads as neither a path nor a list.
+  const searched = dirs.map((dir) => (relative(cwd, dir) || dir).replace(/\\/g, "/"))
+  const primary = searched[0] ?? "functions"
+
+  const errors: string[] = []
+  const missing: string[] = []
+  const warnings: string[] = []
+
+  for (const name of declared) {
+    if (name.startsWith("hooks/")) {
+      // Not an error: it was the documented form once, and the worker grants hooks whatever this says.
+      // Still worth saying, because a reader would reasonably assume the line is what does the granting.
+      warnings.push(
+        `  "${name}" is not needed — a hook receives the service-role key because only the API server ` +
+          `can reach it`,
+      )
+      continue
+    }
+    if (!known.has(name)) {
+      const where =
+        searched.length > 1 ? ` (searched ${searched.join(", ")})` : ""
+      errors.push(`  "${name}" — no ${primary}/${name}/index.ts${where}`)
+      missing.push(name)
+    }
+  }
+
+  return { errors, missing, warnings, available }
+}
+
+/** The full message for a refusal, including what *is* available to name. */
+export function serviceRoleProblemLines(problems: ServiceRoleProblems): string[] {
+  if (problems.errors.length === 0) return []
+  const lines = [...problems.errors, ""]
+  lines.push(
+    problems.available.length > 0
+      ? `Functions found: ${problems.available.join(", ")}`
+      : "No functions found. Create one with: supatype functions new <name>",
+  )
+  lines.push("")
+  lines.push(
+    "A name that matches nothing grants nothing, and says so nowhere: the function reads no key at " +
+      "runtime, in a deploy that reported success.",
+  )
+  return lines
+}