docs: show the one-line job that migrates a shared database from CI; fix db.close() in ten guides

apps/docs/content/docs/cli/migration-status.mdx

@@ -6,7 +6,7 @@ metaTitle: migration status | Prisma ORM CLI
 metaDescription: Learn how to inspect the Prisma ORM migration path and pending migrations.
 ---
 
-`migration status` shows which migrations are pending between the database marker and the target contract.
+The database stores a marker, a row that says which version of your contract it currently matches. `migration status` compares that marker with a target version and lists the migrations in between. The target is the contract you last ran `contract emit` on, unless `--to` names another.
 
 Use it before and after [`db migrate`](/cli/db-migrate), and when debugging why an environment is not at the expected contract state.
 
@@ -40,8 +40,16 @@ npx prisma@latest migration status --ascii
 
 ## Reading the result
 
-With `--db`, status compares the on-disk migration packages to what has been applied in the database. With `--from`, it computes the path offline instead, without a database.
+With `--db`, status reads the marker from the database and compares it with the target. With `--from`, it starts from the state you name instead and needs no database.
 
-The `migration` group has three more read-only views: `migration graph` for topology, `migration log` for executed history, and `migration list` for on-disk enumeration. Run each with `--help` for details.
+With `--json`, the command prints one `"kind": "result"` line. Inside its `envelope`:
+
+- `result.summary` is the sentence the human output ends with, such as `Up to date` or a count of pending migrations.
+- `result.spaces[].migrations[]` lists each migration on disk with a `status`: `pending` (on the way to the target, not yet applied), `applied` (on the way to the target, already applied), or `null` (not on the way to the target).
+- `diagnostics[]`, beside `result` rather than inside it, lists each problem found. Each entry has a `code`, for example `MIGRATION.MARKER_NOT_IN_HISTORY`, a `summary`, and a `severity`, which this command always sets to `warn`.
+
+The exit code is 0 even when `diagnostics` is not empty. A non-zero exit code means the command itself failed, for example with `MIGRATION.REF_NOT_FOUND` when `--to` names a ref that does not exist.
+
+The `migration` group has three more read-only views: `migration graph` draws the chain of migrations, `migration log` lists what has run, and `migration list` lists the migrations on disk. Run each with `--help` for details.
 
 Use [`db verify`](/cli/db-verify) after applying migrations to check the final database shape against the emitted contract.

apps/docs/content/docs/guides/database/data-migration.mdx

@@ -113,7 +113,7 @@ await db.orm.public.Post.create({ title: "Release notes", content: "v1.0", publi
 const posts = await db.orm.public.Post.select("id", "title", "published").all();
 console.log(posts);
 
-await db.runtime().close();
+await db.close();
 ```
 
 ```bash
@@ -325,7 +325,7 @@ const posts = await db.orm.public.Post
   .all();
 console.log(posts);
 
-await db.runtime().close();
+await db.close();
 ```
 
 ```bash

apps/docs/content/docs/guides/database/multiple-databases.mdx

@@ -322,8 +322,8 @@ async function main() {
   });
 
   console.log("Seeded", alice.email, "and", bob.email, "with one post each.");
-  await usersDb.runtime().close();
-  await postsDb.runtime().close();
+  await usersDb.close();
+  await postsDb.close();
 }
 
 main().catch((error) => {
@@ -467,7 +467,7 @@ Commands without `--config` fail once the default config is gone. Running `npx p
 
 - **No relations across databases.** A contract covers one database. Keep a plain id column such as `authorId` on the side that references the other database, and join in application code.
 - **`npx prisma@latest init` writes a third config.** It creates a `prisma.config.ts` that holds only the `skills` section for agent skills. That is expected; the database commands keep using `--config` with the two database configs.
-- **Do not close a client per request.** In `page.tsx` and route handlers, never call `usersDb.runtime().close()`. The pools are shared across requests and close when the process exits. Only scripts such as `prisma/seed.ts` close them.
+- **Do not close a client per request.** In `page.tsx` and route handlers, never call `usersDb.close()`. The pools are shared across requests and close when the process exits. Only scripts such as `prisma/seed.ts` close them.
 - **`orm init` picks the package manager from your lockfile.** Run it after `create-next-app` has written `package-lock.json`, `pnpm-lock.yaml`, or `bun.lock`, or it may install with a different package manager than the one you use.
 
 ## Prompt your coding agent

apps/docs/content/docs/guides/database/schema-changes.mdx

@@ -591,6 +591,8 @@ App space
 
 `migration check` is offline and verifies every migration's hash and the graph's integrity. Run it in CI on every pull request so a `migration.ts` edited without a recompile, or a `migration.json` edited by hand, fails before it reaches a shared database.
 
+`migration check` reads only the files, so it cannot tell you whether a database matches them. `db verify` does. Run `npx prisma db verify --db "$DATABASE_URL"` after `db migrate`, and it fails if the database's marker or its tables differ from the contract you emitted. A pipeline that migrates a shared database runs `db migrate` alone; it refuses a database whose marker is outside your history with `MIGRATION.MARKER_MISMATCH` before it runs anything. [Migrate a shared database from a workflow](/guides/integrations/github-actions#migrate-a-shared-database) shows the job.
+
 ### 4.4. Commit
 
 Commit the same set of files your teammates did:

apps/docs/content/docs/guides/deployment/bun-workspaces.mdx

@@ -37,7 +37,7 @@ Create a Bun workspaces monorepo with a shared Prisma ORM database package and a
 1. Create `my-monorepo` with a root `package.json` that sets `"workspaces": ["apps/*", "packages/*"]`, then create `apps/` and `packages/database/`. Give `packages/database` a `package.json` with `"name": "database"`, `"private": true`, `"type": "module"` and `"main": "index.ts"`.
 2. In `packages/database`, run `bunx prisma@latest orm init --yes --target postgres --authoring psl`. Then run `bunx prisma@latest init` there so the Prisma agent skills are installed and stay current, and use them. Get a database connection string: use the one I give you, or create a Prisma Postgres database with `bunx create-db@latest` and show me the claim URL it prints. Write it as `DATABASE_URL` into `packages/database/.env`.
 3. Add package scripts to `packages/database`: `db:init` (`prisma db init`), `db:update` (`prisma db update`), `db:seed` (`bun src/prisma/seed.ts`). Run `bun run db:init` there.
-4. Create `packages/database/index.ts` that re-exports `db` from `./src/prisma/db`, and `packages/database/src/prisma/seed.ts` that upserts three users with `db.orm.public.User.upsert({ create, update: {}, conflictOn: { email } })` and ends with `await db.runtime().close()`, following https://www.prisma.io/docs/guides/deployment/bun-workspaces.md. Run `bun run db:seed`.
+4. Create `packages/database/index.ts` that re-exports `db` from `./src/prisma/db`, and `packages/database/src/prisma/seed.ts` that upserts three users with `db.orm.public.User.upsert({ create, update: {}, conflictOn: { email } })` and ends with `await db.close()`, following https://www.prisma.io/docs/guides/deployment/bun-workspaces.md. Run `bun run db:seed`.
 5. Add root scripts `dev`, `build`, `start`, `db:init`, `db:update` and `seed` that use `bun run --filter <package> <script>`.
 6. In `apps/`, run `bun create next-app@latest web --yes`, delete `apps/web/.git`, add `"database": "workspace:*"` to its dependencies, copy `packages/database/.env` to `apps/web/.env`, and run `bun install` from the root.
 7. Replace `apps/web/app/page.tsx` with a server component that exports `dynamic = "force-dynamic"` and lists users from `db.orm.public.User.select("id", "name", "email").all()`.
@@ -172,7 +172,7 @@ export type { Contract } from "./src/prisma/contract.d";
 
 ### 2.5. Seed the database
 
-Create the seed script. `upsert` with `conflictOn` makes it safe to run more than once, and `await db.runtime().close()` at the end lets the process exit instead of waiting on the connection pool:
+Create the seed script. `upsert` with `conflictOn` makes it safe to run more than once, and `await db.close()` at the end lets the process exit instead of waiting on the connection pool:
 
 ```ts title="packages/database/src/prisma/seed.ts"
 import { db } from "./db";
@@ -192,7 +192,7 @@ for (const user of users) {
 }
 
 console.log(`Seeded ${users.length} users.`);
-await db.runtime().close();
+await db.close();
 ```
 
 Model access is namespace-qualified on PostgreSQL: `db.orm.public.User`, where `public` is the default schema.
@@ -446,7 +446,7 @@ Without `export const dynamic = "force-dynamic"`, Next.js prerenders the page at
 
 :::
 
-Do not call `db.runtime().close()` in a server component or route handler. The client in `packages/database` is a module-level singleton whose connection pool is shared across requests; close it only in short-lived scripts such as the seed.
+Do not call `db.close()` in a server component or route handler. The client in `packages/database` is a module-level singleton whose connection pool is shared across requests; close it only in short-lived scripts such as the seed.
 
 ## Prompt your coding agent
 

apps/docs/content/docs/guides/deployment/docker.mdx

@@ -525,7 +525,7 @@ Running Studio as a Compose service, as the Prisma ORM 7 guide did, does not wor
 
 :::warning
 
-Do not call `db.runtime().close()` in a route handler. The client's connection pool is shared across requests; close it only on process shutdown.
+Do not call `db.close()` in a route handler. The client's connection pool is shared across requests; close it only on process shutdown.
 
 :::
 

apps/docs/content/docs/guides/deployment/pnpm-workspaces.mdx

@@ -37,7 +37,7 @@ Set up a pnpm workspaces monorepo with a shared Prisma 8 database package and a
 1. Create `my-monorepo` with `pnpm init`, a `pnpm-workspace.yaml` listing `apps/*` and `packages/*` with `allowBuilds` for `esbuild`, `msgpackr-extract`, and `workerd`, and the directories `apps` and `packages/database`.
 2. In `packages/database`, run `pnpm init`, then `npx prisma@latest orm init --yes --target postgres --authoring psl`. Then run `pnpm prisma init` in the same directory so the Prisma agent skills are installed, and use them.
 3. Write `packages/database/.env` with `DATABASE_URL` (use the connection string I give you, or create a Prisma Postgres database with `npx create-db@latest` and show me the claim URL it prints). Run `pnpm prisma db init` in `packages/database`.
-4. Add `src/index.ts` exporting `db` from `./prisma/db`, set `"exports": { ".": "./src/index.ts" }` in the package's package.json, add a `src/seed.ts` that upserts two users with `db.orm.public.User.upsert(...)` and closes with `await db.runtime().close()`, and run it with `node src/seed.ts`.
+4. Add `src/index.ts` exporting `db` from `./prisma/db`, set `"exports": { ".": "./src/index.ts" }` in the package's package.json, add a `src/seed.ts` that upserts two users with `db.orm.public.User.upsert(...)` and closes with `await db.close()`, and run it with `node src/seed.ts`.
 5. In `apps`, run `pnpm create next-app@latest web --yes --skip-install`, delete `apps/web/.git` and `apps/web/pnpm-workspace.yaml`, add `"database": "workspace:*"` to `apps/web/package.json`, copy `packages/database/.env` to `apps/web/.env`, and run `pnpm install` from the workspace root.
 6. Replace `apps/web/app/page.tsx` with a server component that imports `{ db } from "database"`, exports `dynamic = "force-dynamic"`, queries `db.orm.public.User.select("id", "email", "name").all()`, and renders the list.
 7. Add root scripts `dev`, `build`, `start`, `db:init`, `db:update`, and `seed` that filter to the right package, start `pnpm dev` in the background, verify http://localhost:3000 renders the seeded users, then stop it. Finally run `pnpm build` and confirm it completes.
@@ -195,7 +195,7 @@ for (const user of users) {
 
 console.log(await db.orm.public.User.select("id", "email", "name").all());
 
-await db.runtime().close();
+await db.close();
 ```
 
 Point the package at the entry point and add scripts for the database steps. Replace the `main` field `pnpm init` wrote with an `exports` map, and drop the placeholder `test` script:
@@ -396,7 +396,7 @@ Open the URL Studio prints. The `user` and `post` tables appear under **Tables**
 
 - If `pnpm prisma contract emit` reports `CLI.CONFIG_UNREADABLE` with `Cannot find module '@prisma/cli-engine'` or `No "exports" main defined`, the `@prisma/cli-engine` link in `packages/database/node_modules` is dangling. `pnpm install --force` does not repair it; `pnpm add -D prisma@latest @prisma/cli-engine@latest` does.
 - Every Prisma command reads `DATABASE_URL` from `packages/database/.env` through `prisma.config.ts`, and the app reads `apps/web/.env`. Keep the two files in sync, or export the variable in your shell and drop both files.
-- Do not call `db.runtime().close()` in a page or route handler. The client is a module-level singleton whose connection pool is shared across requests; close it only in scripts that exit, like `seed.ts`.
+- Do not call `db.close()` in a page or route handler. The client is a module-level singleton whose connection pool is shared across requests; close it only in scripts that exit, like `seed.ts`.
 - After you change `src/prisma/contract.prisma`, run `pnpm --filter database contract:emit` so the app sees the new types, then `pnpm db:update` to apply the change. The root `build` script emits for you before every build.
 
 ## Prompt your coding agent

apps/docs/content/docs/guides/deployment/turborepo.mdx

@@ -449,7 +449,7 @@ if (existing.length === 0) {
   await db.orm.public.User.create({ email: "bob@prisma.io", name: "Bob" });
 }
 console.log(await db.orm.public.User.select("id", "email", "name").all());
-await db.runtime().close();
+await db.close();
 ```
 
 Add it as a script and run it:
@@ -564,7 +564,7 @@ Without a `db` ref or `--from`, `migration plan` has no origin and refuses with
 
 :::warning
 
-In the web app, never call `db.runtime().close()` in a page or route handler; the client's connection pool is shared across requests. Close it only in one-off scripts like the seed.
+In the web app, never call `db.close()` in a page or route handler; the client's connection pool is shared across requests. Close it only in one-off scripts like the seed.
 
 :::
 

apps/docs/content/docs/guides/frameworks/solid-start.mdx

@@ -38,7 +38,7 @@ Create a new SolidStart app with Prisma ORM, seed it, and serve users from an AP
 1. Scaffold: `npm init solid@latest my-solid-prisma-app -- -s --v2 -t basic --ts`. Delete the `pnpm-lock.yaml` the template ships (otherwise Prisma picks pnpm), then `cd my-solid-prisma-app` and run `npm install`.
 2. Add Prisma ORM: `npx prisma@latest orm init --yes --target postgres --authoring psl`. Then run `npx prisma@latest init` so the Prisma agent skills are installed and stay current, and use them. Get a database connection string: use the one I give you, or create a Prisma Postgres database with `npx create-db@latest` and show me the claim URL it prints. Write it to `.env` as `DATABASE_URL`.
 3. Run `npx prisma@latest db init` to create the tables from `src/prisma/contract.prisma`.
-4. Add `src/prisma/seed.ts` that creates two users with posts through `db.orm.public.User.create` and `db.orm.public.Post.create`, closes with `await db.runtime().close()`, and run it once with `node src/prisma/seed.ts`.
+4. Add `src/prisma/seed.ts` that creates two users with posts through `db.orm.public.User.create` and `db.orm.public.Post.create`, closes with `await db.close()`, and run it once with `node src/prisma/seed.ts`.
 5. Add `src/routes/api/users.ts` with a `GET` handler that returns `db.orm.public.User.include("posts").all()` as JSON, and replace `src/routes/index.tsx` with a page that loads the same query through a `"use server"` function wrapped in `query` and `createAsync`, with `<Suspense>` for loading and `<ErrorBoundary>` for errors, following https://www.prisma.io/docs/guides/frameworks/solid-start.md. Catch Prisma errors inside the server function and rethrow a plain `Error`.
 6. Start `npm run dev` in the background, wait until it reports ready, verify `curl http://localhost:3000/api/users` returns the seeded users and `curl http://localhost:3000/` includes their names, then stop the dev server.
 ```
@@ -223,7 +223,7 @@ async function main() {
     }
     console.log(`Seeded ${created.email} with ${posts.length} post(s)`);
   }
-  await db.runtime().close();
+  await db.close();
 }
 
 main().catch((error) => {
@@ -371,7 +371,7 @@ The server-rendered HTML contains `<h3>Alice</h3>` and `<h3>Bob</h3>` with their
 
 :::warning
 
-Don't call `db.runtime().close()` in API routes or server functions. The client in `src/prisma/db.ts` is constructed once and its connection pool is shared across requests; close it only in one-off scripts like the seed.
+Don't call `db.close()` in API routes or server functions. The client in `src/prisma/db.ts` is constructed once and its connection pool is shared across requests; close it only in one-off scripts like the seed.
 
 :::
 

apps/docs/content/docs/guides/integrations/ai-sdk.mdx

@@ -454,7 +454,7 @@ If the model reply is `An error occurred.` and the server log shows `AI_LoadAPIK
 
 :::warning
 
-Do not call `db.runtime().close()` in a route handler. The client in `src/prisma/db.ts` lives for the whole process and its pool is shared across requests; close it only on process shutdown.
+Do not call `db.close()` in a route handler. The client in `src/prisma/db.ts` lives for the whole process and its pool is shared across requests; close it only on process shutdown.
 
 :::