Feature ETP-4296: Add guide for diagnosing idle in transaction connections - #701
Merged
Conversation
…tions Add a new how-to guide covering detection, root-cause investigation, and pool-level mitigation for Hibernate/DAL sessions left open outside DalFilter's lifecycle, which PostgreSQL reports as idle in transaction. Expand the external connection pool guide with the full list of pool properties and defaults referenced by the new guide, and register both pages in the nav (EN/ES).
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new troubleshooting how-to guide for identifying and mitigating PostgreSQL idle in transaction connections caused by Hibernate/DAL sessions left open outside DalFilter, and expands the external connection pool guide with a more complete pool-properties reference so the new guide can link to mitigation settings.
Changes:
- Added new “How to Diagnose Idle in Transaction Connections” guide (EN/ES), including detection SQL, code patterns (
commitAndClose()infinally), and pool-level mitigation knobs. - Expanded “How to Use an External Connection Pool” (EN/ES) with a detailed property reference, defaults, and sweeper behavior notes.
- Registered the new guide in
mkdocs.ymlnav and added its ES title translation mapping.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| mkdocs.yml | Adds the new how-to page to the nav and includes the Spanish title translation mapping. |
| docs/developer-guide/etendo-classic/how-to-guides/how-to-use-an-external-connection-pool.md | Expands pool configuration documentation with defaults and a full property reference. |
| docs/es/developer-guide/etendo-classic/how-to-guides/how-to-use-an-external-connection-pool.md | Spanish equivalent of the expanded pool configuration reference. |
| docs/developer-guide/etendo-classic/how-to-guides/how-to-diagnose-idle-in-transaction-connections.md | New EN troubleshooting guide for idle in transaction diagnosis and mitigation. |
| docs/es/developer-guide/etendo-classic/how-to-guides/how-to-diagnose-idle-in-transaction-connections.md | New ES troubleshooting guide for idle in transaction diagnosis and mitigation. |
Suppressed comments (2)
docs/developer-guide/etendo-classic/how-to-guides/how-to-use-an-external-connection-pool.md:68
- The table currently presents
db.pool.validationQuerywith a single "Default" value, but the correct query is DB-dependent (PostgreSQL vs Oracle). Listing both variants here would prevent readers from assuming the Oracle form works on PostgreSQL.
| `db.pool.validationQuery` | SQL used to validate a connection. Must not throw an exception. Required for `testOnBorrow`, `testOnReturn`, and `testWhileIdle` to have any effect. | `SELECT 1 FROM DUAL` |
docs/es/developer-guide/etendo-classic/how-to-guides/how-to-use-an-external-connection-pool.md:68
- La tabla muestra
db.pool.validationQuerycon un único "Valor predeterminado", pero la consulta válida depende de la base de datos (PostgreSQL vs Oracle). Incluir ambas variantes ayuda a evitar asumir que la forma de Oracle funciona en PostgreSQL.
| `db.pool.validationQuery` | SQL utilizada para validar una conexión. No debe lanzar una excepción. Es obligatoria para que `testOnBorrow`, `testOnReturn` y `testWhileIdle` tengan algún efecto. | `SELECT 1 FROM DUAL` |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Use xact_start instead of query_start in the idle-in-transaction detection query, since query_start reflects the last statement, not the open transaction's start. Clarify that the default db.pool.validationQuery value is Oracle syntax and document the PostgreSQL equivalent (SELECT 1).
Revert the previous claim that SELECT 1 FROM DUAL needs a PostgreSQL-specific override. Confirmed against a real PostgreSQL installation that Etendo's database creation scripts provision a DUAL compatibility table, so the default query runs unmodified on both PostgreSQL and Oracle.
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
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
how-to-diagnose-idle-in-transaction-connections.md, EN/ES) covering how to detect, investigate, and mitigate Hibernate/DAL sessions left open outsideDalFilter's lifecycle, which PostgreSQL reports asidle in transaction.how-to-use-an-external-connection-pool.md(EN/ES) with the full reference of pool properties and their defaults, since the new guide links to it for pool-level mitigation settings.mkdocs.ymlnav (EN/ES), alphabetically ordered.Related to ETP-4296 — the new guide's diagnostic methodology and fix pattern (closing the session in a
finallyblock withcommitAndClose()) directly matches the root cause described in that bug forcom.smf.securewebservices.Test plan
mkdocs build --strictpasses for the new/updated pages🤖 Generated with Claude Code