docs: add client configuration guides for MPG#2371
Merged
Conversation
PeterCxy
reviewed
Mar 25, 2026
jphenow
added a commit
that referenced
this pull request
Apr 14, 2026
- Remove pool size table and recommended values until actual PgBouncer limits per plan are confirmed - Remove unexplained queue_target/queue_interval from Ecto example - Merge duplicate prepared statement troubleshooting entries into a single section with clearer explanation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
jphenow
added a commit
that referenced
this pull request
Apr 14, 2026
) - Fill in PgBouncer connection limits table with actual values per plan - Add SSL note (enabled by default, no sslmode needed) - Expand connect-your-client with DATABASE_URL setup context - Add direct URL migration setup with fly.toml example Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This adds comprehensive documentation for configuring Managed Postgres client connections, addressing a critical gap where users lacked guidance on preventing dropped connections during proxy maintenance. The core problem: Fly's edge proxy restarts periodically (typically during deployments), and connections held longer than the proxy's 15-minute shutdown timeout are forcibly closed. Without proper configuration, most applications encounter `ECONNRESET` or `tcp recv (idle): closed` errors during these restarts. Connection pool configuration is the fix, but it was poorly documented across the MPG docs. This change adds two guides. "Connect Your Client" is a quick-start checklist covering the essential settings: max connection lifetime (600s), idle timeout (300s), pool size recommendations, and prepared statement handling. "Client-Side Connection Configuration" is a comprehensive reference with language-specific examples for Node.js, Python, Go, Ruby, and Elixir, detailed explanations of how PgBouncer modes affect client behavior, connection limit tables per plan tier, and a full troubleshooting section addressing common errors. The navigation has been restructured to surface both guides prominently, and existing guides (cluster configuration, Phoenix) now cross-link to the new documentation. This makes the recommended connection settings discoverable at the point where users need them most — when connecting their applications to MPG.
The client configuration guide lists examples for seven different languages and drivers. This creates a long, dense page that's difficult to scan. Wrapping each language section in `<details>` tags makes the page more discoverable—users can quickly find their language of choice and expand only what they need. This also improves the reading experience for users who are only interested in one or two specific languages, reducing visual clutter while keeping all reference material readily accessible.
…tinue to work on some of the proxy handling
- Remove pool size table and recommended values until actual PgBouncer limits per plan are confirmed - Remove unexplained queue_target/queue_interval from Ecto example - Merge duplicate prepared statement troubleshooting entries into a single section with clearer explanation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
) - Fill in PgBouncer connection limits table with actual values per plan - Add SSL note (enabled by default, no sslmode needed) - Expand connect-your-client with DATABASE_URL setup context - Add direct URL migration setup with fly.toml example Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
jphenow
force-pushed
the
jphenow/mpg-client-docs
branch
from
3136caf to
08ffdd3
Compare
- Rename configuration → cluster-configuration to distinguish cluster-side settings from client-side settings - Merge connect-your-client into client-configuration with a Quick Start section up top and detailed reference below - Delete connect-your-client (now redundant) - Update nav: collapse "Connection & Clients" into "Getting Started", fix all cross-references Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
|
Hi, Django is one of our best-supported Python frameworks. Is it possible to please add a section on Django? CONN_MAX_AGE=600 is the thing to add to use a pool of persistent connections and recycle them after 10 minutes. The default is 0 which means a new connection for each request and tearing it down when the request context is closed. |
- Node.js: maxLifetimeMillis → maxLifetimeSeconds (value 600, not 600_000), version corrected to pg-pool 3.5.1 / pg 8.8+ - Python: prepare_threshold=0 → None (0 means "prepare on first execution", None actually disables) - Ruby: max_lifetime → max_age, Rails 7.2 → Rails 8.1, remove reference to nonexistent activerecord-connection_reaper gem - Elixir: PgBouncer server_lifetime default is 3600s, not 1800s Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The .html.md files are ERB-processed, so <%= %> in code blocks gets evaluated and then HTML-escaped, rendering as <%= instead of literal ERB syntax. Drop the ERB delimiters since this is just showing the config pattern. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
<password> and <cluster> in code blocks get HTML-escaped by the ERB/Sitepress pipeline, rendering as <password>. Replace with YOUR_PASSWORD and YOUR_CLUSTER. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The env syntax hint causes ampersands in the connection string to render as & entities. Plain code fence avoids this. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Ampersands inside <details> blocks get HTML-entity-escaped regardless of code fences. Replace the inline connection string with a parameter table and a single inline-code URL. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary of changes
This adds comprehensive documentation for configuring Managed Postgres client connections, addressing a critical gap where users lacked guidance on preventing dropped connections during proxy maintenance.
The core problem: Fly's edge proxy restarts periodically (typically during deployments), and connections held longer than the proxy's shutdown timeout are forcibly closed. Without proper configuration, most applications encounter
ECONNRESETortcp recv (idle): closederrors during these restarts. Connection pool configuration is the fix, but it was poorly documented across the MPG docs.This change adds two guides. "Connect Your Client" is a quick-start checklist covering the essential settings: max connection lifetime (600s), idle timeout (300s), pool size recommendations, and prepared statement handling. "Client-Side Connection Configuration" is a comprehensive reference with language-specific examples for Node.js, Python, Go, Ruby, and Elixir, detailed explanations of how PgBouncer modes affect client behavior, connection limit tables per plan tier, and a full troubleshooting section addressing common errors.
The navigation has been restructured to surface both guides prominently, and existing guides (cluster configuration, Phoenix) now cross-link to the new documentation. This makes the recommended connection settings discoverable at the point where users need them most — when connecting their applications to MPG.
Preview
Related Fly.io community and GitHub links
Notes