Update files

Author: hotlong

CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added — Cloud control plane: Postgres driver support ⭐
+- **`buildControlDriver` in `@objectstack/service-cloud/cloud-stack.ts`** now recognises `postgres://`, `postgresql://`, and `pg://` URLs and dispatches them to `@objectstack/driver-sql` with `client: 'pg'`. Previously only `libsql:` / `https:` (Turso) and `file:` (SQLite) were recognised, so a `postgres://…` value was silently rewritten into a SQLite filename — a particularly nasty data-routing bug in production. The function now eagerly `import('pg')` so a missing-driver situation surfaces with an explicit, actionable error at boot.
+- **Pool sizing knobs**: `OS_CONTROL_PG_POOL_MIN` (default `0`) and `OS_CONTROL_PG_POOL_MAX` (default `10`) tune the knex `pg` pool without code changes.
+- **`pg` promoted to a runtime dependency of `apps/cloud`** so `pnpm deploy --prod` ships it inside the Docker image; image size unchanged at ~691 MB.
+- **`.env.cloudflare.secrets.example`, `setup-cloudflare-secrets.sh` (cloud + objectos), and `apps/cloud/README.md`** updated with the new env vars and a "Postgres in production" section that covers Neon / Supabase / RDS / Hyperdrive guidance.
+- **End-to-end verified**: `docker run` with `OS_CONTROL_DATABASE_URL=postgres://os:test@pg-test:5432/cloud` boots cleanly, `/api/v1/health` returns 200, and the full `sys_*` control-plane schema (Accounts, Activity, Agent, API Keys, Apps, Audit, Flows, OAuth, Organization, Packages, …) is materialised in Postgres on first boot.
+
 ### Changed — Slimmer production Docker images (`apps/objectos`, `apps/cloud`)
 - **3-stage builder → pruner → runner Dockerfiles**: full pnpm workspace is restored only in the builder; the pruner runs `pnpm --filter ... deploy --prod --legacy /deploy` to materialize a flat, devDeps-stripped tree; the runner copies just `/deploy` plus the freshly built `dist/` of the target app. CMD now runs `node node_modules/@objectstack/cli/bin/run.js serve dist/objectstack.config.js --prebuilt` directly — no `pnpm` at runtime.
 - **`@objectstack/cli` promoted to `dependencies`** in both `apps/objectos/package.json` and `apps/cloud/package.json` so the production entrypoint survives `--prod` pruning.

apps/cloud/.env.cloudflare.secrets.example

@@ -3,9 +3,25 @@
 # this file across both apps.
 
 # ── Required for both apps ─────────────────────────────────────────────────
-# Remote libSQL/Turso URL — Cloudflare Containers' filesystem is ephemeral,
-# do NOT use file:/data/...
+# Control-plane database URL. Cloudflare Containers' local filesystem is
+# **ephemeral**, so a remote database is mandatory in production.
+#
+# Supported schemes:
+#   • postgres://user:pass@host:5432/db   (recommended for apps/cloud)
+#   • postgresql://user:pass@host/db
+#   • libsql://<db>.turso.io               (Turso / libSQL)
+#   • https://<db>.turso.io                (Turso HTTP)
+#   • file:/data/control.db                (local Docker only — data lost on cold start)
+#
+# For apps/cloud, you almost certainly want Postgres in production.
+# Tune connection pool size with OS_CONTROL_PG_POOL_MIN / OS_CONTROL_PG_POOL_MAX
+# (defaults: 0 / 10).
+#
+# `OS_CONTROL_DATABASE_URL` takes priority over `OS_DATABASE_URL` when both are set.
 OS_DATABASE_URL=
+# Optional: dedicated URL for the *control plane* if it differs from OS_DATABASE_URL.
+# OS_CONTROL_DATABASE_URL=postgres://user:pass@host:5432/objectstack_cloud
+# Auth token for libSQL/Turso. Not used by Postgres (use the URL's password instead).
 OS_DATABASE_AUTH_TOKEN=
 # Cookie/session signing secret. Generate with: openssl rand -hex 32
 AUTH_SECRET=

apps/cloud/README.md

@@ -93,10 +93,14 @@ docker buildx build --platform linux/amd64 \
 wrangler containers push \
   registry.cloudflare.com/<account-id>/objectstack-cloud:latest
 
-# Secrets — the control plane MUST be on remote libSQL/Turso; the
-# container filesystem is wiped on cold-start.
+# Secrets — the control plane MUST be on a remote database. The container
+# filesystem is wiped on cold-start, so file:/... will lose all data.
+# For production, Postgres is recommended:
+#   postgres://user:pass@host:5432/db
+# libSQL/Turso also works:
+#   libsql://<db>.turso.io  +  OS_DATABASE_AUTH_TOKEN
 wrangler secret put OS_DATABASE_URL        --config apps/cloud/wrangler.toml
-wrangler secret put OS_DATABASE_AUTH_TOKEN --config apps/cloud/wrangler.toml
+wrangler secret put OS_DATABASE_AUTH_TOKEN --config apps/cloud/wrangler.toml   # libSQL only
 wrangler secret put AUTH_SECRET            --config apps/cloud/wrangler.toml
 wrangler secret put TURSO_API_TOKEN        --config apps/cloud/wrangler.toml
 wrangler secret put TURSO_ORG_NAME         --config apps/cloud/wrangler.toml
@@ -109,11 +113,33 @@ Required runtime env vars (set as Cloudflare secrets, **not** in
 
 | Var | Purpose |
 |---|---|
-| `OS_DATABASE_URL` | `libsql://<db>.turso.io` — control DB. |
-| `OS_DATABASE_AUTH_TOKEN` | Turso auth token. |
+| `OS_DATABASE_URL` | Control-plane DB URL. Supports `postgres://…`, `postgresql://…`, `libsql://…`, `https://…` (Turso), or `file:/…` (local Docker only). |
+| `OS_CONTROL_DATABASE_URL` | Optional override for the control DB when it differs from `OS_DATABASE_URL`. Takes priority when both are set. |
+| `OS_DATABASE_AUTH_TOKEN` | Auth token for libSQL/Turso. Unused for Postgres (put the password in the URL). |
+| `OS_CONTROL_PG_POOL_MIN` / `OS_CONTROL_PG_POOL_MAX` | Postgres pool sizing (default `0` / `10`). |
 | `AUTH_SECRET` | Cookie/session signing secret. |
 | `TURSO_API_TOKEN` / `TURSO_ORG_NAME` | Used by the provisioning workflow to create per-project Turso DBs. |
 
+### Postgres in production
+
+`apps/cloud` ships with the `pg` driver included. To run the control plane
+on Postgres (Neon / Supabase / RDS / Cloudflare Hyperdrive / self-hosted):
+
+```bash
+export OS_DATABASE_URL='postgres://user:pass@host:5432/objectstack_cloud'
+# Optional fine-tuning:
+export OS_CONTROL_PG_POOL_MAX=20
+```
+
+Schema migrations are applied automatically on first boot by the
+`@objectstack/driver-sql` engine using knex. The cloud control plane
+expects a database it can DDL freely — point it at a dedicated database
+(not one shared with unrelated tables).
+
+> **Hyperdrive note**: Cloudflare Hyperdrive accelerates Postgres
+> connections from Workers, not Containers. For Containers, point
+> `OS_DATABASE_URL` directly at your Postgres instance.
+
 Pair this with an `apps/objectos` deployment (see its README) and set
 `OS_CLOUD_URL=https://<cloud-worker>.<account>.workers.dev` on the
 runtime node so it talks to this control plane.

apps/cloud/package.json

@@ -23,6 +23,7 @@
   "dependencies": {
     "@hono/node-server": "^2.0.2",
     "@libsql/client": "^0.17.3",
+    "@objectstack/cli": "workspace:*",
     "@objectstack/driver-memory": "workspace:*",
     "@objectstack/driver-sql": "workspace:*",
     "@objectstack/driver-turso": "workspace:*",
@@ -42,17 +43,18 @@
     "@objectstack/service-package": "workspace:*",
     "@objectstack/service-tenant": "workspace:*",
     "@objectstack/spec": "workspace:*",
-    "@objectstack/cli": "workspace:*",
-    "hono": "^4.12.18"
+    "hono": "^4.12.18",
+    "pg": "^8.20.0"
   },
   "devDependencies": {
     "@cloudflare/containers": "^0.3.3",
     "@cloudflare/workers-types": "^4.20260510.1",
+    "@types/pg": "^8.20.0",
     "esbuild": "^0.28.0",
     "ts-node": "^10.9.2",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
     "typescript": "^6.0.3",
     "wrangler": "^4.90.0"
   }
-}
+}

apps/cloud/scripts/setup-cloudflare-secrets.sh

@@ -38,7 +38,8 @@ case "$APP_BASENAME" in
     KEYS=( OS_DATABASE_URL OS_DATABASE_AUTH_TOKEN AUTH_SECRET
            OS_CLOUD_URL OS_CLOUD_API_KEY OS_COOKIE_DOMAIN ) ;;
   cloud)
-    KEYS=( OS_DATABASE_URL OS_DATABASE_AUTH_TOKEN AUTH_SECRET
+    KEYS=( OS_DATABASE_URL OS_CONTROL_DATABASE_URL OS_DATABASE_AUTH_TOKEN AUTH_SECRET
+           OS_CONTROL_PG_POOL_MIN OS_CONTROL_PG_POOL_MAX
            TURSO_API_TOKEN TURSO_ORG_NAME OS_COOKIE_DOMAIN ) ;;
   *)
     echo "✗ unknown app dir: $APP_BASENAME" >&2; exit 1 ;;

apps/objectos/scripts/setup-cloudflare-secrets.sh

@@ -38,7 +38,8 @@ case "$APP_BASENAME" in
     KEYS=( OS_DATABASE_URL OS_DATABASE_AUTH_TOKEN AUTH_SECRET
            OS_CLOUD_URL OS_CLOUD_API_KEY OS_COOKIE_DOMAIN ) ;;
   cloud)
-    KEYS=( OS_DATABASE_URL OS_DATABASE_AUTH_TOKEN AUTH_SECRET
+    KEYS=( OS_DATABASE_URL OS_CONTROL_DATABASE_URL OS_DATABASE_AUTH_TOKEN AUTH_SECRET
+           OS_CONTROL_PG_POOL_MIN OS_CONTROL_PG_POOL_MAX
            TURSO_API_TOKEN TURSO_ORG_NAME OS_COOKIE_DOMAIN ) ;;
   *)
     echo "✗ unknown app dir: $APP_BASENAME" >&2; exit 1 ;;

packages/services/service-cloud/src/cloud-stack.ts

@@ -50,9 +50,37 @@ export interface CloudStackConfig {
 
 async function buildControlDriver(url: string, authToken?: string): Promise<{
     driver: IDataDriver;
-    driverName: 'sqlite' | 'turso';
+    driverName: 'sqlite' | 'turso' | 'postgres';
     databaseUrl: string;
 }> {
+    // Postgres / CockroachDB / any pg-wire database.
+    // Accept both `postgres://` and `postgresql://` schemes; `pg://` is also recognised
+    // for parity with the per-tenant artifact registry.
+    if (/^(postgres(ql)?|pg):\/\//i.test(url)) {
+        const { SqlDriver } = await import('@objectstack/driver-sql');
+        // `pg` is a peer/optional dep of knex; bring it in here so a clear error
+        // surfaces at boot if the host forgot to install it.
+        try {
+            await import('pg');
+        } catch (err) {
+            throw new Error(
+                `[service-cloud] Control-plane URL "${url}" requires the "pg" driver. `
+                + `Add \`pg\` to your application dependencies. Original: ${(err as Error).message}`,
+            );
+        }
+        const poolMin = Number.parseInt(process.env.OS_CONTROL_PG_POOL_MIN ?? '0', 10);
+        const poolMax = Number.parseInt(process.env.OS_CONTROL_PG_POOL_MAX ?? '10', 10);
+        const driver = new SqlDriver({
+            client: 'pg',
+            connection: url,
+            pool: {
+                min: Number.isFinite(poolMin) ? poolMin : 0,
+                max: Number.isFinite(poolMax) ? poolMax : 10,
+            },
+        });
+        return { driver: driver as unknown as IDataDriver, driverName: 'postgres', databaseUrl: url };
+    }
+
     if (/^(libsql|https?):\/\//i.test(url)) {
         const { TursoDriver } = await import('@objectstack/driver-turso');
         const driver = new TursoDriver({ url, authToken });