@supatype/cli 0.1.6 → 0.1.9

package/dist/self-host-compose.d.ts

@@ -1,5 +1,6 @@
 import { type DockerBrandOptions } from "./docker-runtime.js";
 import { type SupatypeProjectConfig } from "./project-config.js";
+import { type FieldMaskingTier } from "./field-masking-tier.js";
 /** Env keys written when `versions` pins exist in supatype.config.ts. */
 export declare const COMPOSE_PINNED_IMAGE_ENV_KEYS: readonly ["SUPATYPE_ENGINE_IMAGE", "SUPATYPE_SERVER_IMAGE", "SUPATYPE_POSTGRES_IMAGE"];
 /** Compose image env vars that may be overridden manually in `.env`. */
@@ -23,7 +24,7 @@ export declare function composePullNeedsIgnoreFailures(config: SupatypeProjectCo
 /**
  * Schema-engine image for a one-off `docker compose run` when pushing schema.
  * Uses config pin when set; otherwise CDN engine semver (Docker Hub `:latest` can lag).
- * Does not touch `.env` — server/postgres still use compose `:latest` defaults.
+ * Does not touch `.env`, server/postgres still use compose `:latest` defaults.
  */
 export declare function schemaEngineImageForPush(config: SupatypeProjectConfig): Promise<string | undefined>;
 export interface SelfHostComposePaths {
@@ -40,8 +41,31 @@ export declare const COMPOSE_STUDIO_HOST_URL = "http://host.docker.internal:3002
 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 declare function renderSelfHostCompose(config: SupatypeProjectConfig, cwd?: string, options?: SelfHostComposeOptions): string;
+/**
+ * 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 declare function loopbackExternalHost(config: SupatypeProjectConfig): string | undefined;
 export declare function writeSelfHostCompose(cwd: string, config: SupatypeProjectConfig, options?: SelfHostComposeOptions): SelfHostComposePaths;
 export interface RunDockerComposeOptions {
     /** Suppress docker compose progress UI (container status lines). */
@@ -52,7 +76,7 @@ export interface RunDockerComposeOptions {
 /** Exit with a friendly compose failure message. */
 export declare function exitComposeFailed(status: number, context: string, brand?: DockerBrandOptions): never;
 export declare function runDockerCompose(composePath: string, args: string[], projectRoot?: string, composeProject?: string, options?: RunDockerComposeOptions): number;
-/** Compose project name for a Supatype project — isolates docker state per project. */
+/** Compose project name for a Supatype project, isolates docker state per project. */
 export declare function composeProjectName(projectName: string): string;
 export {};
 //# sourceMappingURL=self-host-compose.d.ts.map

package/dist/self-host-compose.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"self-host-compose.d.ts","sourceRoot":"","sources":["../src/self-host-compose.ts"],"names":[],"mappings":"AAGA,OAAO,EAAuB,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAElF,OAAO,EAAyD,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAA;AAIvH,yEAAyE;AACzE,eAAO,MAAM,6BAA6B,wFAIhC,CAAA;AAEV,wEAAwE;AACxE,eAAO,MAAM,sBAAsB,qOAOzB,CAAA;AAEV,KAAK,kBAAkB,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAA;AAE1D,gEAAgE;AAChE,wBAAgB,cAAc,CAC5B,SAAS,EAAE,kBAAkB,EAC7B,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,qBAAqB,GAC7B,MAAM,CAeR;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAe3F;AAED,8FAA8F;AAC9F,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAQ/D;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAS1E;AAcD;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,qBAAqB,EAC7B,GAAG,GAAE,MAAsB,GAC1B,OAAO,CAGT;AAED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAM7B;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAA;IACX,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,CAQtE;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,GAAG,SAAS,CAIvF;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,GAAG,SAAS,CAIrF;AAwBD,oEAAoE;AACpE,eAAO,MAAM,uBAAuB,qCAAqC,CAAA;AAwCzE,MAAM,WAAW,sBAAsB;IACrC,yFAAyF;IACzF,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,qBAAqB,EAC7B,GAAG,GAAE,MAAsB,EAC3B,OAAO,CAAC,EAAE,sBAAsB,GAC/B,MAAM,CAqRR;AAqBD,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,qBAAqB,EAC7B,OAAO,CAAC,EAAE,sBAAsB,GAC/B,oBAAoB,CAyBtB;AAED,MAAM,WAAW,uBAAuB;IACtC,oEAAoE;IACpE,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,4DAA4D;IAC5D,KAAK,CAAC,EAAE,kBAAkB,CAAA;CAC3B;AAED,oDAAoD;AACpD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,kBAAkB,GACzB,KAAK,CAMP;AAED,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EAAE,EACd,WAAW,GAAE,MAAsB,EACnC,cAAc,CAAC,EAAE,MAAM,EACvB,OAAO,CAAC,EAAE,uBAAuB,GAChC,MAAM,CAsCR;AAED,uFAAuF;AACvF,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAG9D"}
+{"version":3,"file":"self-host-compose.d.ts","sourceRoot":"","sources":["../src/self-host-compose.ts"],"names":[],"mappings":"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"}

package/dist/self-host-compose.js

@@ -3,9 +3,11 @@ import { dirname, join, relative, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import { requireDockerDaemon } from "./docker-runtime.js";
 import { fatalError } from "./ui/fatal.js";
-import { preferredFunctionsPathFromProject, selfHostTlsEnabled } from "./project-config.js";
+import { apiSchemaList, externalDatabaseUrl, hooksPathFromProject, preferredFunctionsPathFromProject, realtimeEnabled, serviceRoleRoutes, selfHostTlsEnabled, usesExternalDatabase, } 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 } from "./field-masking-tier.js";
 /** Env keys written when `versions` pins exist in supatype.config.ts. */
 export const COMPOSE_PINNED_IMAGE_ENV_KEYS = [
     "SUPATYPE_ENGINE_IMAGE",
@@ -108,7 +110,7 @@ export function composePullNeedsIgnoreFailures(config, cwd = process.cwd()) {
 /**
  * Schema-engine image for a one-off `docker compose run` when pushing schema.
  * Uses config pin when set; otherwise CDN engine semver (Docker Hub `:latest` can lag).
- * Does not touch `.env` — server/postgres still use compose `:latest` defaults.
+ * Does not touch `.env`, server/postgres still use compose `:latest` defaults.
  */
 export async function schemaEngineImageForPush(config) {
     const pinned = pinnedVersion("engine", config);
@@ -143,7 +145,7 @@ export function staticDirForCompose(config) {
 /**
  * Bind-mount source for `/project` in generated compose files.
  * Paths are resolved from `--project-directory` (always the project root in `runDockerCompose`),
- * not from the compose file directory — use `.` not `../..`.
+ * not from the compose file directory, use `.` not `../..`.
  */
 function projectMountPath(_cwd) {
     return ".";
@@ -159,9 +161,45 @@ function relativeFromProjectRoot(cwd, target) {
 function kongMountPath(_cwd) {
     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, scheme = "postgresql") {
+    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) {
+    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";
-/** Studio container — always Docker Hub unless SUPATYPE_STUDIO_IMAGE is set in .env. */
+/** Studio container: always Docker Hub unless SUPATYPE_STUDIO_IMAGE is set in .env. */
 function studioServiceBlock() {
     return `    image: \${SUPATYPE_STUDIO_IMAGE:-supatype/studio:latest}`;
 }
@@ -200,6 +238,14 @@ function serverAppEnvForCompose(config, devLocal) {
 export function renderSelfHostCompose(config, cwd = process.cwd(), options) {
     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() ?? "";
@@ -274,60 +320,122 @@ ${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:
@@ -337,31 +445,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:
@@ -373,16 +476,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:
@@ -399,10 +499,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}
@@ -411,9 +511,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
@@ -422,9 +522,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
@@ -432,9 +530,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:
@@ -453,10 +549,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"
@@ -474,30 +567,169 @@ ${kongDependsOn}${kongValkeyDepends}
 
 ${volumesBlock}`;
 }
-function ensureComposeManifest(cwd) {
+/** 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, config) {
     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) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+    }
+    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, config) {
     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, config) {
+    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) {
+    const url = externalDatabaseUrl(config);
+    if (url === undefined)
+        return undefined;
+    let host;
+    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) {
+    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, config, options) {
+    if (options?.fieldMaskingTier !== undefined)
+        return options.fieldMaskingTier;
+    return fieldMaskingTierFromProject(cwd, config);
 }
 export function writeSelfHostCompose(cwd, config, options) {
+    assertExternalUrlMatchesEnv(cwd, config);
+    const tier = resolveFieldMaskingTier(cwd, config, options);
+    const resolved = {
+        ...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();
@@ -558,7 +790,7 @@ export function runDockerCompose(composePath, args, projectRoot = process.cwd(),
     }
     return result.status ?? 1;
 }
-/** Compose project name for a Supatype project — isolates docker state per project. */
+/** Compose project name for a Supatype project, isolates docker state per project. */
 export function composeProjectName(projectName) {
     const slug = projectName.toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
     return `supatype-${slug || "project"}`;