Feat: DC-5300 migrate "connection-uris"

[carlagn]

Fixes #DC-5300

Summary by CodeRabbit

• Documentation
  • Added “Introduction to PostgreSQL connection URIs” guide. Covers URI structure, required/optional components (scheme, userspec, host/port, database, parameters), percent-encoding rules, and composing parameter lists.
  • Includes practical examples for local, SSL, cloud, and multi-host setups, plus guidance on choosing URI schemes and common pitfalls.
  • Improves clarity for configuring connections and troubleshooting connection string issues.

[github-actions]

Dangerous URL check

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

[github-actions]

original	preview
content/200-orm/800-more/600-help-and-troubleshooting/050-dataguide/05-connection-uris.mdx	content/200-orm/800-more/600-help-and-troubleshooting/050-dataguide/05-connection-uris.mdx

[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 MDX documentation page introducing PostgreSQL connection URIs, covering URI structure, percent-encoding, components (schema, userspec, hostspec, database, parameters), examples, and selection/composition guidance. No changes to exported/public entities.

Changes

Cohort / File(s)	Summary of changes
Docs: PostgreSQL connection URIs guide content/200-orm/800-more/600-help-and-troubleshooting/050-dataguide/05-connection-uris.mdx	Adds an MDX doc detailing PostgreSQL connection URI structure, encoding rules, components, examples, and parameter composition guidance.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 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 uses the Jira feature tag and refers to migrating connection-uris, which aligns with adding the new connection URI documentation. Although concise, it remains tied to the core change. It omits explicit mention of adding a documentation guide, but still conveys the key area affected.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

---

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

[cloudflare-workers-and-pages]

Deploying docs with    Cloudflare Pages

Latest commit:	1045557
Status:	✅  Deploy successful!
Preview URL:	https://37d14c24.docs-51g.pages.dev
Branch Preview URL:	https://feat-dc-5300-dataguide-migra.docs-51g.pages.dev

View logs

[coderabbitai]

Actionable comments posted: 4

🧹 Nitpick comments (1)

src/theme/DocCard/index.tsx (1)

74-74: Refactor long conditional into a helper for readability.

Line 74 exceeds 200 characters and embeds a long description string inline, making it difficult to read and maintain.

Consider extracting this logic into a helper function or computing the description before the return statement:

 function CardCategory({ item }: { item: PropSidebarItemCategory }): JSX.Element | null {
   const href = findFirstSidebarItemLink(item);
   const categoryItemsPlural = useCategoryItemsPlural();
+  
+  const DATAGUIDE_DESCRIPTION = "Learn how databases work, how to choose the right one, and how to use databases with your applications to their full potential.";
+  const description = item.description ?? (item.label === "Dataguide" ? DATAGUIDE_DESCRIPTION : "");

   // Unexpected: categories that don't have a link have been filtered upfront
   if (!href) {
     return null;
   }
   return (
-    <CardLayout href={href} icon="🗃️" title={item.label} description={item.description ?? item.label === "Dataguide" ? "Learn how databases work, how to choose the right one, and how to use databases with your applications to their full potential." : ""} />
+    <CardLayout href={href} icon="🗃️" title={item.label} description={description} />
   );
 }

📜 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 2b7c440 and 0e8c94f.

📒 Files selected for processing (6)

• content/200-orm/800-more/600-help-and-troubleshooting/050-dataguide/05-connection-uris.mdx (1 hunks)
• content/200-orm/800-more/600-help-and-troubleshooting/050-dataguide/index.mdx (1 hunks)
• src/theme/DocCard/index.tsx (1 hunks)
• src/theme/DocCard/styles.module.css (1 hunks)
• src/theme/DocCard/styles.module.scss (1 hunks)
• src/theme/DocCardList/index.tsx (1 hunks)

🧰 Additional context used

🪛 GitHub Actions: Documentation Checks

content/200-orm/800-more/600-help-and-troubleshooting/050-dataguide/index.mdx

[error] 2-2: CSpell: Unknown word 'Dataguide'.

---

[error] 3-3: CSpell: Unknown word 'Dataguide'.

---

[error] 15-15: CSpell: Unknown word 'Dataguide'.

⏰ 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: Check internal links
• GitHub Check: runner / linkspector

🔇 Additional comments (3)

src/theme/DocCard/styles.module.scss (1)

44-46: LGTM! Ensures description width constraint.

The max-width: 100% rule ensures the card description respects container boundaries.

content/200-orm/800-more/600-help-and-troubleshooting/050-dataguide/05-connection-uris.mdx (2)

7-194: LGTM! Comprehensive PostgreSQL connection URI documentation.

The documentation provides thorough coverage of PostgreSQL connection URI structure, including percent-encoding, authentication, hostspec, parameters, and practical examples. The content is well-organized and educational.

---

11-11: Verify link /intro/database-glossary#authentication.
No database-glossary file found under content/; ensure the linked document and #authentication heading exist or update the path.

[coderabbitai]

Actionable comments posted: 1

📜 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 24f99ba and c27537b.

📒 Files selected for processing (2)

• content/200-orm/800-more/600-help-and-troubleshooting/050-dataguide/05-connection-uris.mdx (1 hunks)
• content/200-orm/800-more/600-help-and-troubleshooting/050-dataguide/050-database-glossary.mdx (1 hunks)

🧰 Additional context used

🪛 GitHub Actions: Documentation Checks

content/200-orm/800-more/600-help-and-troubleshooting/050-dataguide/050-database-glossary.mdx

[error] 44-44: CSpell: Unknown word (BCNF)

---

[error] 45-45: CSpell: Unknown word (multivalued)

---

[error] 137-137: CSpell: Unknown word (BCNF)

---

[error] 138-138: CSpell: Unknown word (BCNF)

---

[error] 138-138: CSpell: Unknown word (Boyce)

---

[error] 138-138: CSpell: Unknown word (Codd)

---

[error] 219-219: CSpell: Unknown word (superkey)

---

[error] 693-693: CSpell: Unknown word (HTAP)

---

[error] 694-694: CSpell: Unknown word (HTAP)

---

[error] 900-900: CSpell: Unknown word (Multiversion)

---

[error] 901-901: CSpell: Unknown word (Multiversion)

---

[error] 901-901: CSpell: Unknown word (MVCC)

---

[error] 903-903: CSpell: Unknown word (MVCC)

---

[error] 904-904: CSpell: Unknown word (MVCC)

---

[error] 961-961: CSpell: Unknown word (Nonrepeatable)

---

[error] 962-962: CSpell: Unknown word (nonrepeatable)

---

[error] 963-963: CSpell: Unknown word (nonrepeatable)

---

[error] 978-978: CSpell: Unknown word (OLAP)

---

[error] 979-979: CSpell: Unknown word (OLAP)

---

[error] 981-981: CSpell: Unknown word (OLAP)

---

[error] 987-987: CSpell: Unknown word (OLTP)

---

[error] 988-988: CSpell: Unknown word (OLTP)

---

[error] 990-990: CSpell: Unknown word (OLTP)

---

[error] 992-992: CSpell: Unknown word (OLTP)

---

[error] 1160-1160: CSpell: Unknown word (Nonrepeatable)

---

[error] 1183-1183: CSpell: Unknown word (nonrepeatable)

---

[error] 1221-1221: CSpell: Unknown word (RDBMS)

---

[error] 1222-1222: CSpell: Unknown word (RDBMS)

---

[error] 1224-1224: CSpell: Unknown word (RDBMS)

---

[error] 1230-1230: CSpell: Unknown word (nonrepeatable)

---

[error] 1346-1346: CSpell: Unknown word (nonrepeatable)

---

[error] 1431-1431: CSpell: Unknown word (Superkey)

---

[error] 1432-1432: CSpell: Unknown word (superkey)

---

[error] 1435-1435: CSpell: Unknown word (superkey)

---

[error] 1436-1436: CSpell: Unknown word (superkey)

⏰ 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: 12

♻️ Duplicate comments (1)

content/200-orm/800-more/600-help-and-troubleshooting/050-dataguide/050-database-glossary.mdx (1)

44-49: Unblock CI: whitelist domain terms for cSpell (inline or cSpell.json).

cSpell is red on BCNF, multivalued, Boyce, Codd, MVCC, HTAP, OLAP, OLTP, RDBMS, superkey/Superkey, Nonrepeatable/nonrepeatable, Multiversion. Add an inline ignore near the top or add these to cSpell.json.

Suggested quick fix (inline ignore):

 --- 
 title: 'Glossary of common database terminology'
 metaTitle: "Database glossary | Prisma's Data Guide"
 metaDescription: 'Database terminology can be difficult to understand.  This glossary was designed to help you learn important terminology by providing definitions and context in one place.'
 ---
 
+<!-- cSpell:ignore BCNF Boyce Codd multivalued HTAP MVCC Multiversion Nonrepeatable nonrepeatable OLAP OLTP RDBMS superkey Superkey -->
+
 ## Introduction

Alternatively, add these tokens to the repository cSpell.json "words" list.

Also applies to: 137-145, 219-227, 693-701, 900-909, 961-969, 978-986, 987-995, 1156-1162, 1160-1160, 1183-1183, 1221-1230, 1431-1437

🧹 Nitpick comments (1)

content/200-orm/800-more/600-help-and-troubleshooting/050-dataguide/050-database-glossary.mdx (1)

1152-1154: Use Markdown link; remove JSX space artifact.

-  algorithm to implement than alternatives like{' '}
-  <a href="https://en.wikipedia.org/wiki/Paxos_(computer_science)">Paxos</a>.
+  algorithm to implement than alternatives like [Paxos](https://en.wikipedia.org/wiki/Paxos_(computer_science)).

📜 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 c27537b and 6847766.

📒 Files selected for processing (4)

• cSpell.json (1 hunks)
• content/200-orm/800-more/600-help-and-troubleshooting/050-dataguide/05-connection-uris.mdx (1 hunks)
• content/200-orm/800-more/600-help-and-troubleshooting/050-dataguide/050-database-glossary.mdx (1 hunks)
• content/200-orm/800-more/600-help-and-troubleshooting/050-dataguide/index.mdx (1 hunks)

✅ Files skipped from review due to trivial changes (1)

• content/200-orm/800-more/600-help-and-troubleshooting/050-dataguide/05-connection-uris.mdx

🚧 Files skipped from review as they are similar to previous changes (2)

• cSpell.json
• content/200-orm/800-more/600-help-and-troubleshooting/050-dataguide/index.mdx

🧰 Additional context used

🪛 GitHub Actions: Documentation Checks

content/200-orm/800-more/600-help-and-troubleshooting/050-dataguide/050-database-glossary.mdx

[error] 44-44: cspell: Unknown word 'BCNF'.

---

[error] 45-45: cspell: Unknown word 'multivalued'.

---

[error] 137-137: cspell: Unknown word 'BCNF'.

---

[error] 138-138: cspell: Unknown word 'BCNF'.

---

[error] 138-138: cspell: Unknown word 'Boyce'.

---

[error] 138-138: cspell: Unknown word 'Codd'.

---

[error] 138-138: cspell: Unknown word 'HTAP'.

---

[error] 138-138: cspell: Unknown word 'HTAP'.

---

[error] 219-219: cspell: Unknown word 'superkey'.

---

[error] 693-693: cspell: Unknown word 'MVCC'.

---

[error] 694-694: cspell: Unknown word 'MVCC'.

---

[error] 694-694: cspell: Unknown word 'HTAP'.

---

[error] 900-900: cspell: Unknown word 'Multiversion'.

---

[error] 901-901: cspell: Unknown word 'Multiversion'.

---

[error] 901-901: cspell: Unknown word 'MVCC'.

---

[error] 903-903: cspell: Unknown word 'MVCC'.

---

[error] 904-904: cspell: Unknown word 'MVCC'.

---

[error] 961-961: cspell: Unknown word 'Nonrepeatable'.

---

[error] 962-962: cspell: Unknown word 'nonrepeatable'.

---

[error] 963-963: cspell: Unknown word 'nonrepeatable'.

---

[error] 978-978: cspell: Unknown word 'OLAP'.

---

[error] 979-979: cspell: Unknown word 'OLAP'.

---

[error] 981-981: cspell: Unknown word 'OLAP'.

---

[error] 987-987: cspell: Unknown word 'OLTP'.

---

[error] 988-988: cspell: Unknown word 'OLTP'.

---

[error] 990-990: cspell: Unknown word 'OLTP'.

---

[error] 992-992: cspell: Unknown word 'OLTP'.

---

[error] 1160-1160: cspell: Unknown word 'Nonrepeatable'.

---

[error] 1183-1183: cspell: Unknown word 'nonrepeatable'.

---

[error] 1221-1221: cspell: Unknown word 'RDBMS'.

---

[error] 1222-1222: cspell: Unknown word 'RDBMS'.

---

[error] 1224-1224: cspell: Unknown word 'RDBMS'.

---

[error] 1230-1230: cspell: Unknown word 'nonrepeatable'.

---

[error] 1346-1346: cspell: Unknown word 'nonrepeatable'.

---

[error] 1431-1431: cspell: Unknown word 'Superkey'.

---

[error] 1432-1432: cspell: Unknown word 'superkey'.

---

[error] 1435-1435: cspell: Unknown word 'superkey'.

---

[error] 1436-1436: cspell: Unknown word 'superkey'.

⏰ 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

🔇 Additional comments (1)

content/200-orm/800-more/600-help-and-troubleshooting/050-dataguide/050-database-glossary.mdx (1)

11-11: Verify issue tracker target (dataguide → docs?).

This content now lives in prisma/docs; consider pointing suggestions to the docs repo.

Suggested change:

-This glossary ... please open a [GitHub issue](https://github.com/prisma/dataguide/issues/new?title=Glossary%20suggestion%3A%20) to add your suggestions.
+This glossary ... please open a [GitHub issue](https://github.com/prisma/docs/issues/new?title=Glossary%20suggestion%3A%20) to add your suggestions.

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (2)

content/200-orm/800-more/600-help-and-troubleshooting/050-dataguide/05-connection-uris.mdx (2)

132-134: Add IPv6 host note (avoid breaking valid hosts).

Readers may percent‑encode brackets after the earlier guidance. Add a brief note and example showing bracketed IPv6 without encoding.

Apply this diff:

 The `hostspec` consists of a `host` and an optional `port`. The `host` can either be a locally resolvable host name, a name resolved by an external name system like DNS, or an IP address or other direct address. The port signifies the port number where PostgreSQL is listening.
+
+Note: For IPv6 addresses, enclose the host in square brackets and do not percent‑encode the brackets. For example:
+
+```
+postgresql://username:password@[2001:db8::1]:5432/sales
+```

---

30-30: Tighten wording and minor grammar fixes.

Small edits improve clarity and consistency.

Apply this diff:

-These have special meaning within the connection URI.
+These characters have special meaning within the connection URI.
@@
-A quick description of each of the individual components:
+A brief description of each of the individual components:
@@
-  - `host`: An optional IP address, DNS name, or locally resolvable name of the server to connect to. The host continues until a colon (`:`) (if a port is included) or until a slash (if a port is not included)
+  - `host`: An optional IP address, DNS name, or locally resolvable name of the server to connect to. The host continues until a colon (`:`) (if a port is included) or until a slash (`/`) (if a port is not included)
@@
-Applications are able to interpret this data as the `userspec` by noting the inclusion of the terminating at sign (`@`). If only one field is provided (if no colon is present between the slashes and the at sign), it is interpreted as a username.
+Applications can interpret this data as the `userspec` by noting the inclusion of the terminating at sign (`@`). If only one field is provided (if no colon is present between the slashes and the at sign), it is interpreted as a username.
@@
-You can actually provide more than one host and port pairs, separated by the commas (`,`) to tell the application to try the latter servers if the first cannot be reached. For example, to extend the previous example to include a fallback server listening on port 5555 on `198.51.100.33`, you could use:
+You can provide more than one host-and-port pair, separated by commas (,) to tell the application to try the subsequent servers if the first cannot be reached. For example, to extend the previous example to include a fallback server listening on port 5555 on `198.51.100.33`, you could use:
@@
-Conforming clients and applications will try to first connect to the server listening at `198.51.100.22:3333`. If that fails, they will try to reach a PostgreSQL database listening on `198.51.100.33:5555`.
+Conforming clients and applications will first try to connect to the server listening at `198.51.100.22:3333`. If that fails, they will try to reach a PostgreSQL database listening on `198.51.100.33:5555`.
@@
-For example, to specify that the client should apply a 10 second timeout for the connection we were previously defining, you could use:
+For example, to specify that the client should apply a 10-second timeout for the connection we were previously defining, you could use:
@@
-If you wanted to provide additional parameters, you'd add them afterwards with an ampersand (`&`) between each pair. For instance, we could additionally specify that we require SSL and want to connect only if the server is a primary in a replica set, we could additionally add:
+If you wanted to provide additional parameters, you'd add them afterward with an ampersand (`&`) between each pair. For instance, if we require SSL and want to connect only if the server is a primary in a replica set, we could additionally add:

Also applies to: 70-70, 77-77, 126-126, 152-152, 158-158, 178-178, 184-184

📜 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 60a153a and 1045557.

📒 Files selected for processing (1)

• content/200-orm/800-more/600-help-and-troubleshooting/050-dataguide/05-connection-uris.mdx (1 hunks)

🧰 Additional context used

🪛 LanguageTool

content/200-orm/800-more/600-help-and-troubleshooting/050-dataguide/05-connection-uris.mdx

[grammar] ~19-~19: There might be a mistake here.
Context: ...uld percent-encode include: - (space): %20 - %: %25 - &: %26 - /: %2F - ::...

(QB_NEW_EN)

---

[grammar] ~20-~20: There might be a mistake here.
Context: ...ncode include: - (space): %20 - %: %25 - &: %26 - /: %2F - :: %3A - =:...

(QB_NEW_EN)

---

[grammar] ~21-~21: There might be a mistake here.
Context: ...: - (space): %20 - %: %25 - &: %26 - /: %2F - :: %3A - =: %3D - ?:...

(QB_NEW_EN)

---

[grammar] ~22-~22: There might be a mistake here.
Context: ... %20 - %: %25 - &: %26 - /: %2F - :: %3A - =: %3D - ?: %3F - @:...

(QB_NEW_EN)

---

[grammar] ~23-~23: There might be a mistake here.
Context: ... %25 - &: %26 - /: %2F - :: %3A - =: %3D - ?: %3F - @: %40 - [:...

(QB_NEW_EN)

---

[grammar] ~24-~24: There might be a mistake here.
Context: ... %26 - /: %2F - :: %3A - =: %3D - ?: %3F - @: %40 - [: %5B - ]:...

(QB_NEW_EN)

---

[grammar] ~25-~25: There might be a mistake here.
Context: ... %2F - :: %3A - =: %3D - ?: %3F - @: %40 - [: %5B - ]: %5D These...

(QB_NEW_EN)

---

[grammar] ~26-~26: There might be a mistake here.
Context: ... %3A - =: %3D - ?: %3F - @: %40 - [: %5B - ]: %5D These have special...

(QB_NEW_EN)

---

[style] ~44-~44: The word ‘anyways’ is informal American English. Did you mean “anyway”?
Context: ...encoded, it's usually best to encode it anyways. For example, if you are unsure if the ...

(ANYWAYS)

---

[style] ~70-~70: Consider using the synonym “brief” (= concise, using a few words, not lasting long) to strengthen your wording.
Context: ...formation you can encode in the URI. A quick description of each of the individual c...

(QUICK_BRIEF)

---

[style] ~72-~72: To form a complete sentence, be sure to include a subject.
Context: ... postgres[ql]: The schema identifier. Can be postgresql or simply postgres. -...

(MISSING_IT_THERE)

---

[grammar] ~79-~79: There might be a mistake here.
Context: ...f the individual database to connect to. - parameter list: An optional list of additional paramet...

(QB_NEW_EN)

---

[style] ~126-~126: As a shorter alternative for ‘able to’, consider using “can”.
Context: ...://username:password@ ``` Applications are able to interpret this data as the userspec b...

(BE_ABLE_TO)

---

[grammar] ~178-~178: Use a hyphen to join words.
Context: ...pecify that the client should apply a 10 second timeout for the connection we wer...

(QB_NEW_EN_HYPHEN)

---

[locale-violation] ~184-~184: In American English, ‘afterward’ is the preferred variant. ‘Afterwards’ is more commonly used in British English and other dialects.
Context: ...e additional parameters, you'd add them afterwards with an ampersand (&) between each pa...

(AFTERWARDS_US)

---

[style] ~194-~194: Consider removing “of” to be more concise
Context: ...ion information. Connection URIs encode all of the information required to connect to a gi...

(ALL_OF_THE)

⏰ 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). (3)

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