Skip to content

Add TypeScript AppHost support to PostgreSQL integration docs#609

Open
davidfowl wants to merge 2 commits intomainfrom
ts-integrations-postgres
Open

Add TypeScript AppHost support to PostgreSQL integration docs#609
davidfowl wants to merge 2 commits intomainfrom
ts-integrations-postgres

Conversation

@davidfowl
Copy link
Contributor

Add TypeScript AppHost support to the PostgreSQL integration documentation.

Cherry-picked from ts-integrations branch (replaces #581, rebased onto main).

- Add TypeScript examples throughout postgres-host.mdx using synced C#/TS tabs
- Restructure postgres-get-started.mdx with separate C#/TypeScript quickstart paths
- Add new SyncedPivotSelector component to sync pivot selector with Starlight tabs
- Add new 'Connect to PostgreSQL' page with language-neutral connection reference
  (JavaScript, Python, Go, .NET examples)
- Move connection properties and env var reference from host page to connect page
- Mark client integration as .NET-specific in sidebar and page content
- Add aspire add postgres to both C# and TypeScript installation sections
- Show aspire.config.json update in TypeScript installation examples
- Rename 'Using with non-.NET applications' to neutral language
- Fix sidebar not auto-expanding current page group after SidebarPersister restore
- Fix typo: confgure → configure in postgres-host description

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot AI review requested due to automatic review settings March 25, 2026 14:47
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR updates the PostgreSQL integration documentation to include TypeScript AppHost examples, adds a language-neutral “Connect to PostgreSQL” reference page, and introduces UI plumbing to keep language selectors/tabs in sync.

Changes:

  • Add synced C#/TypeScript examples across the PostgreSQL hosting docs and restructure the PostgreSQL “get started” guide around AppHost language.
  • Introduce a new “Connect to PostgreSQL” page with cross-language connection guidance, and update .NET client docs to point to it.
  • Add a new SyncedPivotSelector component and a sidebar fix to keep the active page’s group expanded.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 8 comments.

Show a summary per file
File Description
src/frontend/src/content/docs/integrations/databases/postgres/postgres-host.mdx Adds synced C#/TS hosting examples and updates guidance/links.
src/frontend/src/content/docs/integrations/databases/postgres/postgres-get-started.mdx Splits quickstart by AppHost language; adds consumer-language tabs.
src/frontend/src/content/docs/integrations/databases/postgres/postgres-connect.mdx New cross-language connection/environment-variable reference page.
src/frontend/src/content/docs/integrations/databases/postgres/postgres-client.mdx Reframes as .NET-only client integration and links to connect page.
src/frontend/src/components/starlight/Sidebar.astro Adds logic intended to expand the current page’s sidebar group.
src/frontend/src/components/SyncedPivotSelector.astro New component to sync PivotSelector state with Starlight synced tabs.
src/frontend/config/sidebar/integrations.topics.ts Adds sidebar entry for “Connect to PostgreSQL” and renames client entry.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we rename this file because it is explicitly for .NET

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good call — will do this in a follow-up PR since renaming changes the URL slug and needs a redirect.

Use the standard `pgx` driver:

```bash title="Terminal"
go get github.com/jackc/pgx/v5
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why this one and not https://github.com/lib/pq?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added a note explaining pgx is recommended for new projects (better performance, native protocol support, active maintenance) with a link to lib/pq as an alternative.

### Add the PostgreSQL Hosting integration to the AppHost

<Pivot id="python">
```bash title="Terminal"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(nit) this looks different than the way we say to add the package to the app. Here:

Image

Lower in the page it is a selector:

Image

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Leaving as-is — hosting and client packages have genuinely different install flows (aspire add vs dotnet add package), so the different UX is expected.

Copy link
Member

@IEvangelist IEvangelist left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This feels broader than needed for adding TypeScript AppHost coverage to the PostgreSQL docs. I'd prefer to keep this PR focused on the docs changes, reuse the existing PivotSelector/Pivot pattern with one shared key across the Postgres articles so the AppHost choice persists, and split the unrelated sidebar behavior change into a separate PR. If we keep or add an in-page PivotSelector, please use marginTop={1} so the spacing matches the rest of the docs. For language examples, let's also make sure we're covering the canonical popular/actively maintained OSS clients, or explicitly explain why we're choosing one over another.

- Remove SyncedPivotSelector component; use PivotSelector directly (IEvangelist, eerhardt)
- Revert Sidebar.astro changes to split into separate PR (IEvangelist)
- Align PivotSelector keys across Postgres pages (IEvangelist)
- Fix env var naming: POSTGRESDB_DATABASE → POSTGRESDB_DATABASENAME (copilot-reviewer)
- Remove spurious default 'db' from Python examples (eerhardt)
- Use version-agnostic '*' in aspire.config.json example (eerhardt)
- Mention both WithReference (C#) and withReference (TS) (copilot-reviewer)
- Fix broken link to connection properties (copilot-reviewer)
- Add lib/pq note in Go section, explain pgx recommendation (eerhardt, IEvangelist)
- Remove explicit parameters from TS AppHost example to match C# (eerhardt)
- Clarify 'Choose a consuming language' section titles (eerhardt)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@davidfowl
Copy link
Contributor Author

@IEvangelist As we roll out TypeScript AppHost support to more integrations (Redis, MySQL, MongoDB, etc.), I'm noticing some patterns repeating across the Postgres pages that could be extracted into reusable components:

  1. AppHostLanguageSwitcher — standardize the PivotSelector + key + "Select your AppHost language" boilerplate that every integration page will need
  2. ClientLanguageTabs — the "install driver → import → read env vars → connect" pattern for JS/Python/Go/.NET that repeats across get-started and connect pages
  3. ConnectionPropertyTable — env var property tables (Host, Port, Username, Password, Uri, etc.) that will repeat for every database integration

Postgres is the first integration with the C#/TS AppHost pivot, so it's a good time to extract these before we repeat the same patterns everywhere else. Do you agree this is worth doing, or should we keep things inline for now?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants