Examples, the scaffolder and the deploy guide follow the dev loop by borisno2 · Pull Request #1228 · OpenSaasAU/stack

borisno2 · 2026-09-06T14:52:32Z

Implements #1159. Part of #1125.

Documents and wires the loop that #1157 and #1158 shipped: opensaas dev starts the Dev database, generates, reconciles and spawns the app; opensaas db update promotes a staged change.

Examples (twelve database-backed)

auth-demo, blog, composable-dashboard, custom-field, file-upload-demo, json-demo, mcp-demo, rag-ollama-demo, rag-openai-chatbot, starter, starter-auth, tiptap-demo:

dev → opensaas dev (a custom port becomes opensaas dev -- next dev -p <port>)
db:push → db:update → opensaas db update
READMEs drop the schema-apply pre-step; reset is rm -rf .opensaas/dev-db
.env.example ships no DATABASE_URL, only a commented escape line
the two starters migrate/migrate:deploy → prisma migration plan / prisma db migrate
examples/file-upload-demo/.gitignore stops ignoring prisma/migrations/

examples/plain-css-theming is untouched — it has no dependencies and no database.

Scaffolder

Post-step is install → generate; the .env it writes sets no DATABASE_URL. DbProvider is gone from env.ts/setup.ts — there is one env shape now. The isolated first-run guard asserts scaffold → generate with no database and no .opensaas/dev-db.

Deploy guide

production migrates from the committed migrations/ directory with prisma db migrate; authoring is prisma migration plan
a Database escape section, with the pgvector provisioning and privilege paragraph beside it (ADR-0065): Prisma runs CREATE EXTENSION from the committed Extension contract space on every path, a pre-installed extension is skipped, a missing one fails naming the space and SQL state 58P01
the bundling section loses outputFileTracingIncludes and every prisma-client mention

Verification

pnpm build, pnpm lint (0 errors, 2 pre-existing warnings), pnpm format, pnpm manypkg fix
package tests pass per package: core 1550, cli 372, ui 53 files, auth 17, rag 16, storage 8, storage-s3 1, storage-vercel 1, create-opensaas-app 37
the real scaffolder binary run in an OS temp dir with DATABASE_URL/DIRECT_DATABASE_URL unset completes and writes an .env with no active DATABASE_URL
opensaas dev in that scaffolded project brought up a Dev database (postgres://postgres@127.0.0.1:64471/postgres), applied Create table "Note" through db update, and spawned the app child with PROVENANCE dev-database and no injected DATABASE_URL

Out of scope

Example opensaas.config.ts files still declare provider: 'sqlite' and import @prisma/adapter-better-sqlite3, so example builds fail on this branch exactly as they do on prisma-8 today. That is spec 9 (#1129); the scaffolded project above had to be given a Prisma 8 config to exercise the loop. The deploy guide's Step 2 ("Switch Your Config to PostgreSQL", Prisma 7 driver adapters) is left for the same owner.

🤖 Generated with Claude Code

Every database-backed example's `dev` script is now `opensaas dev`, its `db:push` is `opensaas db update`, its README drops the schema-apply pre-step, and its `.env.example` ships no default `DATABASE_URL` — a fresh clone takes the Dev database branch (ADR-0063). The two starter templates' `migrate`/`migrate:deploy` point at `prisma migration plan` and `prisma db migrate`. The scaffolder's post-step is install and generate only, and the `.env` it writes sets no `DATABASE_URL`, so scaffolding reaches no database and the first `pnpm dev` brings one up. The deploy guide migrates from the committed `migrations/` directory with `prisma db migrate`, carries the pgvector provisioning and privilege paragraph beside the Database escape (ADR-0065), and loses the file-tracing pin along with the `prisma-client` tree that no longer exists. `examples/plain-css-theming` is untouched: it has no package dependencies and no database. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

changeset-bot · 2026-09-06T14:52:37Z

🦋 Changeset detected

Latest commit: 9fc28ca

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
create-opensaas-app	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

chatgpt-codex-connector · 2026-09-06T14:52:38Z

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

vercel · 2026-09-06T14:52:39Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
stack-docs	Ready	Preview	Sep 6, 2026 9:13pm UTC

borisno2 · 2026-09-06T14:59:10Z

-This creates the SQLite database (`dev.db`) with your schema.
-
-### 5. Run the Test Script
+### 4. Run the Test Script


Step 4 now runs a database-dependent script before anything creates a database. Previously step 4 was pnpm db:push, which created dev.db; now the only thing that brings a database up is pnpm dev at step 5. Following the README in order, the test script calls getContext() → resolveDatabaseUrl(), which finds no DATABASE_URL (the new .env.example leaves it commented) and no .opensaas/dev-db state file, and throws DatabaseUrlUnresolvedError. Either move the test-script step after "Start the Admin UI", or say it needs pnpm dev running in another terminal — the way examples/rag-openai-chatbot was updated in this same PR.

borisno2 · 2026-09-06T14:59:11Z

-```
-
-### 5. Seed Some Data (Optional)
+### 4. Seed Some Data (Optional)


Same ordering problem as rag-ollama-demo: the seed/inspect step (and pnpm db:studio two lines below) is now numbered ahead of pnpm dev, but pnpm db:push was the step that used to create the database and it is gone. With no DATABASE_URL and no running dev loop there is no connection to resolve, so pnpm db:studio fails at step 4. It needs to come after "Run Development Server", or say it requires pnpm dev running in a second terminal.

borisno2 · 2026-09-06T14:59:12Z

-    "db:push": "prisma db push",
-    "migrate": "prisma migrate dev",
-    "migrate:deploy": "prisma migrate deploy",
+    "db:update": "opensaas db update",


Removing db:push here breaks the Playwright e2e harness, which is not updated in this PR. e2e/global-setup.ts targets examples/starter-auth and calls setupDatabase(), which runs execSync('pnpm db:push --accept-data-loss', { cwd: exampleDir }) (e2e/utils/db.ts:43) — that script no longer exists, so global setup dies with "Command db:push not found" before any test runs. The same file also seeds .env with envContent.replace(/DATABASE_URL=.*/, ...); the new .env.example only carries DATABASE_URL on a commented line, so that substitution now rewrites a comment and leaves the variable unset. The e2e job is gated on github.base_ref == 'main' so it does not run on this PR, but it will fail the moment prisma-8 targets main.

borisno2 · 2026-09-06T14:59:13Z

-    "db:push": "prisma db push",
-    "migrate": "prisma migrate dev",
-    "migrate:deploy": "prisma migrate deploy",
+    "db:update": "opensaas db update",


The nightly published-create-e2e job still drives the scaffolded project through the removed script: .github/workflows/nightly.yml runs pnpm generate; pnpm db:push; pnpm build and then asserts test -f dev.db, with DATABASE_URL: file:./dev.db. Once this scaffolder change is published, pnpm db:push will not exist in the generated project and the job fails. The examples-build job in the same file also still claims each .env.example "defaults DATABASE_URL to a value that matches its config's Prisma provider", which is no longer true for any example after this PR.

borisno2 · 2026-09-06T14:59:14Z

@@ -230,17 +236,16 @@ openssl rand -base64 32

 ## Step 4: Author the First Migration



This step dropped the # Ensure DATABASE_URL + DIRECT_DATABASE_URL are set prerequisite, but the command still needs a live connection: the guide itself says so at "Authoring Migrations in CI" — "Planning a new one needs a database to plan against — prisma migration plan resolves its origin through the db ref ... and the connection prisma.config.ts gives it". A reader who follows Step 4 literally, with no DATABASE_URL set (which is now the documented local default) and no opensaas dev running, gets a connection failure rather than a planned migration. Restore the prerequisite line, or say to run it with pnpm dev up / DIRECT_DATABASE_URL pointed at a disposable Postgres.

borisno2 · 2026-09-06T14:59:15Z

 ### "Migration failed"

-**Symptoms:** `prisma migrate deploy` errors
+**Symptoms:** `prisma db migrate` errors


The symptom line was updated to prisma db migrate but the two solutions immediately below it were not, and they are now wrong on both counts: "Check migration files in prisma/migrations/" contradicts line 246, which says the packages live in migrations/ at the project root, and npx prisma migrate resolve is a Prisma 7 command that no longer exists in the migration plan / db migrate surface this guide now documents. Someone hitting a failed migration is sent to an empty directory and a command that errors.

borisno2 · 2026-09-06T14:59:16Z

+pnpm dev

-# 4. Seed the knowledge base
+# 4. Seed the knowledge base, from a second terminal


This is a single pasteable bash block, and pnpm dev on the line above never exits — so nothing after it runs. The prose "from a second terminal" is right, but a reader copying the block (which is the point of a QUICKSTART) hangs at step 3 and never seeds. Split the seed into its own fenced block under a "in a second terminal" heading.

borisno2 · 2026-09-06T14:59:17Z

-
-    // The two documented setup steps, run via the borrowed toolchain.
+    const setupEnv = { ...process.env }
+    delete setupEnv.DATABASE_URL


Only DATABASE_URL is cleared, but findDatabaseUrl consults DIRECT_DATABASE_URL first (packages/core/src/db/url.ts, CONNECTION_VARIABLES = ["DIRECT_DATABASE_URL", "DATABASE_URL"]). On any machine or runner that exports DIRECT_DATABASE_URL, generate takes the environment branch and the guard silently stops proving what its name and the assertions below claim — that the scaffold reaches a Generated bundle with no database anywhere. Delete both variables.

github-actions · 2026-09-06T15:01:35Z