Add PlanetScale Postgres documentation #7433
Conversation
WalkthroughAdds PlanetScale Postgres documentation (multiple new MDX guides and an overview) and renames existing PlanetScale entries to explicitly indicate "PlanetScale MySQL"; updates sidebar, internal links, and capitalization consistency across docs and index data. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (6)
content/200-orm/050-overview/500-databases/855-planetscale-postgres.mdx (1)
114-120: Consider using template literal pattern for connection string consistency.Based on learnings from similar documentation, the Prisma docs convention for driver adapter examples uses the template literal pattern for environment variable access:
-const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL }) +const connectionString = `${process.env.DATABASE_URL}` +const adapter = new PrismaPg({ connectionString })This maintains consistency with other database adapter examples (PostgreSQL, MySQL/MariaDB) throughout the documentation.
content/100-getting-started/02-prisma-orm/200-add-to-existing-project/605-planetscale-postgres.mdx (1)
105-107: Consider using a placeholder for the database name.The connection string uses
postgresas a hardcoded database name while other values use placeholder syntax. For consistency and to avoid confusion, consider using a placeholder:-DATABASE_URL="postgresql://{username}:{password}@{host}:6432/postgres?sslmode=verify-full" +DATABASE_URL="postgresql://{username}:{password}@{host}:6432/{database}?sslmode=verify-full"This helps users understand they should replace this with their actual database name from PlanetScale.
content/100-getting-started/02-prisma-orm/200-add-to-existing-project/600-planetscale.mdx (1)
130-140: Consider using the template literal pattern for connection string consistency.Based on learnings, the Prisma docs convention for driver adapter examples uses the template literal pattern for environment variables. The current code passes
process.env.DATABASE_URLdirectly to the adapter options object. While functionally equivalent, using the template literal maintains consistency across all database adapter examples in the documentation.📝 Suggested change for consistency
import "dotenv/config"; import { PrismaPlanetScale } from '@prisma/adapter-planetscale' import { PrismaClient } from '../generated/prisma/client' import { fetch as undiciFetch } from 'undici' -const adapter = new PrismaPlanetScale({ url: process.env.DATABASE_URL, fetch: undiciFetch }) +const connectionString = `${process.env.DATABASE_URL}` + +const adapter = new PrismaPlanetScale({ url: connectionString, fetch: undiciFetch }) const prisma = new PrismaClient({ adapter }) export { prisma }content/100-getting-started/02-prisma-orm/100-quickstart/605-planetscale-postgres.mdx (2)
53-68: Consider adding a brief explanation forignoreDeprecations.The
ignoreDeprecations: "6.0"setting in tsconfig may puzzle readers unfamiliar with TypeScript 5.x deprecation warnings formoduleResolution: "node". A short inline comment or note explaining why this is needed would help developers understand this isn't a red flag.
199-214: Clarify thatmigrate devalready runsgenerateautomatically.The current text shows running
prisma migrate dev(Line 204) followed by a separateprisma generate(Line 212). Since Prisma 3.x+,migrate devautomatically runsgenerateafter successful migration. Running it again is harmless but redundant. You could either remove the explicit generate step or clarify it's optional/for emphasis.📝 Suggested clarification
This command creates the database tables based on your schema. -Now run the following command to generate the Prisma Client: +The `migrate dev` command automatically generates Prisma Client after applying migrations. If you need to regenerate manually (e.g., after schema changes without migration), run: ```terminal npx prisma generate</details> </blockquote></details> <details> <summary>content/100-getting-started/02-prisma-orm/100-quickstart/600-planetscale.mdx (1)</summary><blockquote> `212-222`: **Same template literal pattern note as the add-to-existing guide.** For consistency with other database adapter examples in the Prisma docs (and with the new Postgres quickstart in this PR which does use the pattern), consider using the template literal approach here as well. Based on learnings, the convention is `const connectionString = \`${process.env.DATABASE_URL}\``. <details> <summary>📝 Suggested change for consistency</summary> ```diff import "dotenv/config"; import { PrismaPlanetScale } from '@prisma/adapter-planetscale' import { PrismaClient } from '../generated/prisma/client' import { fetch as undiciFetch } from 'undici' -const adapter = new PrismaPlanetScale({ url: process.env.DATABASE_URL, fetch: undiciFetch }) +const connectionString = `${process.env.DATABASE_URL}` + +const adapter = new PrismaPlanetScale({ url: connectionString, fetch: undiciFetch }) const prisma = new PrismaClient({ adapter }) export { prisma }
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (9)
content/100-getting-started/02-prisma-orm/100-quickstart/600-planetscale.mdxcontent/100-getting-started/02-prisma-orm/100-quickstart/605-planetscale-postgres.mdxcontent/100-getting-started/02-prisma-orm/200-add-to-existing-project/600-planetscale.mdxcontent/100-getting-started/02-prisma-orm/200-add-to-existing-project/605-planetscale-postgres.mdxcontent/200-orm/050-overview/500-databases/850-planetscale.mdxcontent/200-orm/050-overview/500-databases/855-planetscale-postgres.mdxcontent/300-accelerate/900-compare.mdxsidebars.tssrc/data/indexData.ts
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2026-01-06T22:06:57.725Z
Learnt from: newclarityex
Repo: prisma/docs PR: 7425
File: content/200-orm/050-overview/500-databases/400-mysql.mdx:80-80
Timestamp: 2026-01-06T22:06:57.725Z
Learning: In Prisma docs, when showing examples of instantiating driver adapters with connection strings from environment variables, use the template literal pattern `const connectionString = `${process.env.DATABASE_URL}`` for consistency across all database adapter examples (PostgreSQL, MySQL/MariaDB, etc.).
Applied to files:
content/200-orm/050-overview/500-databases/855-planetscale-postgres.mdxcontent/100-getting-started/02-prisma-orm/200-add-to-existing-project/605-planetscale-postgres.mdxcontent/100-getting-started/02-prisma-orm/200-add-to-existing-project/600-planetscale.mdxcontent/100-getting-started/02-prisma-orm/100-quickstart/605-planetscale-postgres.mdxcontent/300-accelerate/900-compare.mdxcontent/200-orm/050-overview/500-databases/850-planetscale.mdxcontent/100-getting-started/02-prisma-orm/100-quickstart/600-planetscale.mdx
🪛 LanguageTool
content/100-getting-started/02-prisma-orm/200-add-to-existing-project/605-planetscale-postgres.mdx
[style] ~228-~228: Consider shortening or rephrasing this to strengthen your wording.
Context: ...pt.ts ``` ## 9. Evolve your schema To make changes to your database schema: ### 9.1. Update ...
(MAKE_CHANGES)
🔇 Additional comments (14)
content/300-accelerate/900-compare.mdx (1)
31-31: Capitalization corrections look good.These changes properly align the "PlanetScale" brand name with the correct casing throughout the comparison tables. Consistent branding across documentation is important for professionalism and searchability.
Also applies to: 102-102
content/200-orm/050-overview/500-databases/855-planetscale-postgres.mdx (1)
1-141: Well-structured documentation for PlanetScale Postgres.This is a solid addition to the Prisma docs. The document effectively:
- Distinguishes between PlanetScale Postgres and MySQL variants with clear cross-references
- Explains the PostgreSQL-compatible nature and standard
postgresqlprovider usage- Documents the dual connection approach (direct vs PgBouncer) with a helpful comparison table
- Provides complete code examples for schema and client setup
The note block at lines 13-17 is particularly helpful for users who may land on the wrong guide.
content/100-getting-started/02-prisma-orm/200-add-to-existing-project/605-planetscale-postgres.mdx (2)
182-193: Good adherence to documentation conventions.The Prisma Client instantiation correctly uses the template literal pattern for the connection string as per documentation standards:
const connectionString = `${process.env.DATABASE_URL}`This maintains consistency with other database adapter examples across the Prisma docs.
1-279: Comprehensive add-to-existing-project guide.This guide provides excellent step-by-step coverage for integrating Prisma ORM with an existing PlanetScale Postgres project. The workflow is logical:
- Set up dependencies
- Initialize Prisma
- Connect database
- Introspect existing schema
- Baseline for migrations
- Generate client and query
The baselining section (lines 142-166) is particularly valuable for users migrating existing databases, as this is often a point of confusion.
content/200-orm/050-overview/500-databases/850-planetscale.mdx (1)
2-15: Clear disambiguation between PlanetScale MySQL and Postgres.The title change to "PlanetScale MySQL" and the added note block effectively distinguish this guide from the new PlanetScale Postgres documentation. This is the right approach—users searching for PlanetScale guidance will now clearly understand which guide applies to their database variant.
The note at lines 11-15 provides a helpful redirect for users who may have landed here while using PlanetScale Postgres.
src/data/indexData.ts (1)
179-179: Brand name capitalization corrected.The
techlabel now correctly displays "PlanetScale" with proper casing. This ensures the UI matches the updated documentation and official brand spelling.content/100-getting-started/02-prisma-orm/200-add-to-existing-project/600-planetscale.mdx (1)
2-3: LGTM on the title and cross-reference updates.The renaming to "PlanetScale MySQL" and the updated note correctly directing users to the new PlanetScale Postgres guide are well done. This establishes clear disambiguation between the two PlanetScale offerings.
Also applies to: 16-17
content/100-getting-started/02-prisma-orm/100-quickstart/605-planetscale-postgres.mdx (3)
1-19: Well-structured frontmatter and introduction.The metadata is complete, and the cross-reference note to the MySQL guide mirrors the pattern used in the MySQL guide pointing back here. This bidirectional linking helps users find the right documentation.
219-230: LGTM on Prisma Client instantiation.The code correctly uses the
@prisma/adapter-pgwithPrismaPg, and follows the template literal pattern for the connection string as per documentation conventions.
130-148: Helpful connection type table.The table clearly distinguishing Direct (5432) vs PgBouncer (6432) ports with their use cases is excellent. This prevents a common pitfall where developers use pooled connections for migrations, which can cause issues.
sidebars.ts (3)
107-115: LGTM on quickstart sidebar updates.The existing PlanetScale entry is correctly relabeled to "PlanetScale MySQL" and the new "PlanetScale Postgres" entry follows with the correct doc ID. The ordering (MySQL before Postgres) maintains backward compatibility for existing users.
168-176: LGTM on add-to-existing-project sidebar updates.Mirrors the quickstart pattern correctly, maintaining consistency across both getting-started paths.
510-510: Formatting-only change, no semantic impact.The AI tutorials items array was reformatted to a single line. No functional change.
content/100-getting-started/02-prisma-orm/100-quickstart/600-planetscale.mdx (1)
2-3: LGTM on MySQL quickstart title and cross-reference.The renaming to "PlanetScale MySQL" and the note pointing to the Postgres quickstart are correct. The bidirectional linking between MySQL and Postgres guides creates a good user experience.
Also applies to: 17-17
- Add new PlanetScale Postgres database guide with connection pooling, branching, and replica information - Add PlanetScale Postgres quickstart guide - Add PlanetScale Postgres add-to-existing-project guide - Rename existing PlanetScale pages to 'PlanetScale MySQL' for clarity - Update sidebar with new PlanetScale Postgres entries - Fix 'Planetscale' -> 'PlanetScale' case sensitivity issues
mhartington
force-pushed
the
planetscale-postgres-docs
branch
from
88b0eb4 to
6413855
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
content/200-orm/050-overview/500-databases/855-planetscale-postgres.mdx (1)
114-120: Connection string pattern should use template literal for consistency.Based on learnings from this repository, driver adapter examples should use the template literal pattern
const connectionString = \${process.env.DATABASE_URL}`` for consistency across all database adapter examples.♻️ Suggested fix for consistency
```ts file=src/db/client.ts import { PrismaClient } from '../generated/prisma/client' import { PrismaPg } from '@prisma/adapter-pg' -const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL }) +const connectionString = `${process.env.DATABASE_URL}` + +const adapter = new PrismaPg({ connectionString }) export const prisma = new PrismaClient({ adapter })</details> </blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used**: Path: .coderabbit.yaml **Review profile**: CHILL **Plan**: Pro <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 88b0eb4872c0b1144b67080303434986d35231ba and 641385531e15f21df0176b779f88fc6f21fab2fd. </details> <details> <summary>📒 Files selected for processing (9)</summary> * `content/100-getting-started/02-prisma-orm/100-quickstart/600-planetscale.mdx` * `content/100-getting-started/02-prisma-orm/100-quickstart/605-planetscale-postgres.mdx` * `content/100-getting-started/02-prisma-orm/200-add-to-existing-project/600-planetscale.mdx` * `content/100-getting-started/02-prisma-orm/200-add-to-existing-project/605-planetscale-postgres.mdx` * `content/200-orm/050-overview/500-databases/850-planetscale.mdx` * `content/200-orm/050-overview/500-databases/855-planetscale-postgres.mdx` * `content/300-accelerate/900-compare.mdx` * `sidebars.ts` * `src/data/indexData.ts` </details> <details> <summary>🚧 Files skipped from review as they are similar to previous changes (4)</summary> * src/data/indexData.ts * content/100-getting-started/02-prisma-orm/200-add-to-existing-project/600-planetscale.mdx * content/100-getting-started/02-prisma-orm/100-quickstart/600-planetscale.mdx * content/100-getting-started/02-prisma-orm/100-quickstart/605-planetscale-postgres.mdx </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>🧠 Learnings (1)</summary> <details> <summary>📚 Learning: 2026-01-06T22:06:57.725Z</summary>Learnt from: newclarityex
Repo: prisma/docs PR: 7425
File: content/200-orm/050-overview/500-databases/400-mysql.mdx:80-80
Timestamp: 2026-01-06T22:06:57.725Z
Learning: In Prisma docs, when showing examples of instantiating driver adapters with connection strings from environment variables, use the template literal patternconst connectionString =${process.env.DATABASE_URL}`` for consistency across all database adapter examples (PostgreSQL, MySQL/MariaDB, etc.).**Applied to files:** - `content/200-orm/050-overview/500-databases/850-planetscale.mdx` - `content/100-getting-started/02-prisma-orm/200-add-to-existing-project/605-planetscale-postgres.mdx` - `content/200-orm/050-overview/500-databases/855-planetscale-postgres.mdx` - `content/300-accelerate/900-compare.mdx` </details> </details><details> <summary>🪛 LanguageTool</summary> <details> <summary>content/100-getting-started/02-prisma-orm/200-add-to-existing-project/605-planetscale-postgres.mdx</summary> [style] ~228-~228: Consider shortening or rephrasing this to strengthen your wording. Context: ...pt.ts ``` ## 9. Evolve your schema To make changes to your database schema: ### 9.1. Update ... (MAKE_CHANGES) </details> </details> </details> <details> <summary>🔇 Additional comments (15)</summary><blockquote> <details> <summary>content/300-accelerate/900-compare.mdx (1)</summary><blockquote> `31-31`: **Capitalization fixes look good.** The corrections from "Planetscale" to "PlanetScale" align with the company's official branding and maintain consistency across the documentation. Also applies to: 102-102 </blockquote></details> <details> <summary>sidebars.ts (3)</summary><blockquote> `169-176`: **Add-to-existing-project sidebar entries follow the same pattern — looks good.** Consistent with the Quickstart section structure. The referenced document `605-planetscale-postgres.mdx` is included in this PR. --- `510-510`: **Minor formatting change — no functional impact.** This is just a single-line reformatting of the array. No concerns here. --- `108-115`: **Sidebar entries for PlanetScale are correctly configured.** The renaming of the original "PlanetScale" entry to "PlanetScale MySQL" and the addition of "PlanetScale Postgres" provides clear differentiation between database variants. The doc IDs follow the established naming convention and all referenced documents exist with proper metadata. The same structure is consistently applied across both the quickstart and add-to-existing-project sections. </blockquote></details> <details> <summary>content/200-orm/050-overview/500-databases/850-planetscale.mdx (1)</summary><blockquote> `1-15`: **Clear disambiguation and cross-linking.** The updated title, metadata, and note block effectively distinguish this as the MySQL/Vitess guide while providing a helpful cross-reference to the Postgres variant. The "powered by Vitess" description accurately represents PlanetScale's MySQL technology stack. </blockquote></details> <details> <summary>content/200-orm/050-overview/500-databases/855-planetscale-postgres.mdx (3)</summary><blockquote> `1-50`: **Well-structured introduction and feature documentation.** The guide provides clear differentiation from the MySQL variant, accurate feature descriptions sourced from PlanetScale's documentation, and appropriate cross-linking. The commonalities section correctly identifies standard PostgreSQL compatibility. --- `51-97`: **Connection guidance is comprehensive and accurate.** The direct vs PgBouncer table clearly communicates when to use each connection type. The `prisma.config.ts` example correctly demonstrates environment variable usage with `env('DATABASE_URL')`. --- `128-141`: **Replica querying section and getting started links look good.** The section appropriately defers to PlanetScale's documentation for replica details while noting the capability. The getting started links point to the correct new documentation paths. </blockquote></details> <details> <summary>content/100-getting-started/02-prisma-orm/200-add-to-existing-project/605-planetscale-postgres.mdx (7)</summary><blockquote> `1-47`: **Prerequisites and setup section is well-organized.** Clear prerequisites, appropriate package explanations, and proper distinction from the MySQL variant. The package list correctly includes both runtime and dev dependencies with accurate descriptions. --- `48-91`: **Prisma initialization section provides clear guidance.** The generated files are explained well, and the schema uses the modern `prisma-client` generator with custom output path. This aligns with current Prisma best practices. --- `92-127`: **Connection configuration is thorough.** The direct vs PgBouncer table is helpful, and the recommendation to use PgBouncer for production applications is sound advice for serverless environments. --- `142-167`: **Baselining instructions are accurate and complete.** The three-step process (create directory, generate migration, mark as applied) correctly implements the Prisma Migrate baselining workflow for existing databases. --- `182-193`: **Prisma Client instantiation follows the established pattern.** The template literal pattern `const connectionString = \`${process.env.DATABASE_URL}\`` is used correctly here, maintaining consistency with other database adapter examples in the documentation. Based on learnings, this is the preferred approach. --- `226-264`: **Schema evolution section demonstrates the workflow clearly.** The example with `Post` and `User` models provides a practical demonstration of adding new models and relations. The `add-start`/`add-end` markers will render nicely for visual highlighting. --- `136-139`: The referenced image file exists at the correct location and will render properly in the documentation. No action needed. </blockquote></details> </blockquote></details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
2 participants
Summary
PlanetScale offers PostgreSQL databases in addition to our MySQL (Vitess) offering.
Changes
New pages:
content/200-orm/050-overview/500-databases/855-planetscale-postgres.mdx)content/100-getting-started/02-prisma-orm/100-quickstart/605-planetscale-postgres.mdx)content/100-getting-started/02-prisma-orm/200-add-to-existing-project/605-planetscale-postgres.mdx)Updated pages:
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.