Document local Prisma Postgres management in Node.js

[sorenbs]

Added instructions for managing a local Prisma Postgres server programmatically using Node.js, including a runnable example.

Summary by CodeRabbit

• Documentation
  • New guidance on programmatically managing a local Prisma Postgres server from Node.js using experimental APIs.
  • Includes a runnable TypeScript example that starts a server, connects, runs a query, and cleans up.
  • Covers unique ports/names, retrieving connection details, and test setup patterns.
  • Warns about risks of relying on unstable/undocumented APIs.
  • Note: content is duplicated on the page.

[github-actions]

original	preview
content/250-postgres/300-database/550-local-development.mdx	content/250-postgres/300-database/550-local-development.mdx

[github-actions]

Dangerous URL check

No absolute URLs to prisma.io/docs found.
No local URLs found.

[github-actions]

Redirect check

This PR probably requires the following redirects to be added to static/_redirects:

• This PR does not change any pages in a way that would require a redirect.

[coderabbitai]

Walkthrough

Adds a new documentation section demonstrating how to programmatically start, connect to, and stop a local Prisma Postgres server from Node.js using undocumented, unstable @prisma/dev APIs. The same content was inserted twice (duplicated) into the file.

Changes

Cohort / File(s)	Summary of Changes
Docs: Local Prisma Postgres server (programmatic) content/250-postgres/300-database/550-local-development.mdx	Added a new section "Manage local Prisma Postgres programmatically" with a runnable TypeScript example showing dynamic port selection, starting the server with a unique name, connecting via a PostgreSQL client, running a query, and cleanup. The same content was inserted twice (duplicated) in this file.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Pre-merge checks

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title concisely and accurately reflects the primary change of adding documentation for programmatic local Prisma Postgres management in Node.js, focusing on the main intent without extraneous details.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cloudflare-workers-and-pages]

Deploying docs with    Cloudflare Pages

Latest commit:	a36113a
Status:	✅  Deploy successful!
Preview URL:	https://d88cb8c1.docs-51g.pages.dev
Branch Preview URL:	https://programmatic-local-ppg-1.docs-51g.pages.dev

View logs

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (3)

content/250-postgres/300-database/550-local-development.mdx (3)

170-200: Make the example runnable everywhere and ensure clean shutdowns

• Avoid top-level await (works only in ESM). Wrap in an async IIFE.
• Await and move client.end() into finally.
• Guard server.close instead of using non-null assertion.

Apply this diff:

-```ts
+```ts
 import { Client } from 'pg'
 import { unstable_startServer } from '@prisma/dev'
 import { getPort } from 'get-port-please'
 
 async function startLocalPrisma(name: string) {
-    const port = await getPort()
-
-    return await unstable_startServer({
-        name, // use a unique name if running tests in parallel
-        port,
-        databasePort: port + 1,
-        shadowDatabasePort: port + 2,
-        persistenceMode: 'stateless'
-    })
+  const port = await getPort()
+
+  return await unstable_startServer({
+    name, // use a unique name if running tests in parallel
+    port,
+    databasePort: port + 1,
+    shadowDatabasePort: port + 2,
+    persistenceMode: 'stateless',
+  })
 }
 
-// Usage in tests
-const server = await startLocalPrisma(`my-tests-${Date.now()}`)
-try {
-    const client = new Client({ connectionString: server.database.connectionString })
-    await client.connect()
-
-    const res = await client.query(`SELECT 1 as "abba"`)
-    console.log(res.rows)
-
-    client.end()
-} finally {
-    await server.close!()
-}
+// Usage in tests
+void (async () => {
+  const server = await startLocalPrisma(`my-tests-${Date.now()}`)
+  let client: Client | undefined
+  try {
+    client = new Client({ connectionString: server.database.connectionString })
+    await client.connect()
+    const res = await client.query(`SELECT 1 as "abba"`)
+    console.log(res.rows)
+  } finally {
+    if (client) await client.end()
+    if (server.close) await server.close()
+  }
+})().catch((e) => {
+  console.error(e)
+  process.exit(1)
+})

---

175-184: Avoid assuming consecutive free ports

Deriving ports with +1/+2 can race with other processes. Allocate each port independently.

Apply this diff:

 async function startLocalPrisma(name: string) {
-  const port = await getPort()
-
-  return await unstable_startServer({
-    name, // use a unique name if running tests in parallel
-    port,
-    databasePort: port + 1,
-    shadowDatabasePort: port + 2,
-    persistenceMode: 'stateless',
-  })
+  const port = await getPort()
+  const databasePort = await getPort()
+  const shadowDatabasePort = await getPort()
+
+  return await unstable_startServer({
+    name, // use a unique name if running tests in parallel
+    port,
+    databasePort,
+    shadowDatabasePort,
+    persistenceMode: 'stateless',
+  })
 }

---

202-206: Add prerequisites to make the example truly runnable

Note the required packages and ESM caveat for top-level await.

Apply this diff:

 Notes:
 - Allocate unique ports and `name` values when running tests concurrently.
 - Use `server.database.connectionString` to connect with Postgres clients or ORMs.
 - This pattern is great for running tests that require a local database.
+- Install dependencies:
+
+  ```bash
+  npm i pg
+  npm i -D @prisma/dev get-port-please
+  ```
+
+- If not using ESM (`"type": "module"`), prefer the async IIFE pattern shown to avoid top‑level await.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 5b731cf and 7d528a1.

📒 Files selected for processing (1)

• content/250-postgres/300-database/550-local-development.mdx (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: runner / linkspector
• GitHub Check: Check internal links

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (3)

content/250-postgres/300-database/550-local-development.mdx (3)

214-218: Avoid assuming adjacent ports are free.

Add a note that each port should be probed independently; +1/+2 can be occupied by other processes.

Apply this diff:

 :::tip
-
-You can dynamically choose available ports using libraries like [`get-port-please`](https://www.npmjs.com/package/get-port-please) to avoid conflicts when running multiple instances.
+You can dynamically choose available ports using libraries like [`get-port-please`](https://www.npmjs.com/package/get-port-please) to avoid conflicts when running multiple instances. Probe each required port independently—in busy environments, `port + 1`/`+ 2` may already be taken.
 
 :::

---

222-224: Tighten phrasing: clarify client types for the connection string.

server.database.connectionString is a Postgres TCP URL; calling out “non‑Prisma ORMs” avoids confusion with prisma+postgres.

Apply this diff:

-- Use `server.database.connectionString` to connect with Postgres clients or ORMs.
+- Use `server.database.connectionString` to connect with Postgres clients or non‑Prisma ORMs.

---

206-213: Clarify databasePort semantics and default behavior.

• Prisma ORM connects via the HTTP server (port); databasePort is for the embedded Postgres process (used internally by Prisma server and by direct SQL clients).
• Default is calculated as port + 1 (51214 when port is 51213); update table to show port + 1 (51214 if port = 51213).

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between cc7328e and a36113a.

📒 Files selected for processing (1)

• content/250-postgres/300-database/550-local-development.mdx (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: runner / linkspector
• GitHub Check: Cloudflare Pages