From: Clickin (@Clickin) <noreply+Clickin@github.com>
To: pgjdbc/pgjdbc <noreply+pgjdbc-pgjdbc@github.com>
Subject: [pgjdbc/pgjdbc] PR #4523: fix: retry PreparedStatement.getMetaData() after a cached plan is invalidated
Date: Sun, 08 Nov 2026 10:51:30 +0000
Message-ID: <gh-pgjdbc-pgjdbc-4523@github.com> (raw)
Fixes #2944
If a server-prepared statement's result type changes through DDL on another connection and `getMetaData()` is the first call afterwards, the caller gets `ERROR: cached plan must not change result type`. `PgStatement.execute()` already recovers from this error, but `PgPreparedStatement.getMetaData()` sends its describe without that retry.
`getMetaData()` now applies the same rule as `execute()`: if the query has no subqueries and `willHealOnRetry(e)` is true, it closes the cached query and describes once more. In a failed transaction with autosave `never`, `willHealOnRetry()` is false, so the original error is still reported. The success path is unchanged.
Tests added to `PreparedStatementTest`, skipped when `preferQueryMode=simple`, which does not describe:
* `testGetMetaDataRetriesInvalidatedPlan`: after the column changes from `int` to `text` on another connection, `getMetaData()` reports `VARCHAR`. Without the change it fails with `cached plan must not change result type` in both binary modes.
* `testGetMetaDataDoesNotRetryFailedTransaction`: inside an open transaction, the original `0A000` error is still thrown.
* `testGetMetaDataPreservesSyntaxError`: `select from` still throws `42601`.
Ran `PreparedStatementTest` on Java 21 and Java 8 against PostgreSQL 17.11, and the full `:postgresql:test` on Java 21 with no failures. `./gradlew styleCheck` passes.
### All Submissions:
* [x] Have you followed the guidelines in our [Contributing](https://github.com/pgjdbc/pgjdbc/blob/master/CONTRIBUTING.md) document?
* [x] Have you checked to ensure there aren't other open [Pull Requests](../../pulls) for the same update/change?
### Changes to Existing Features:
* [ ] Does this break existing behaviour? If so please explain. No. Only the case that previously threw `cached plan must not change result type` from `getMetaData()` changes.
* [x] Have you added an explanation of what your changes do and why you'd like us to include them?
* [x] Have you written new tests for your core changes, as applicable?
* [x] Have you successfully run tests with your changes locally?
Written with AI assistance: OpenAI GPT-6 Astra wrote the change and tests, and Claude Opus 5.5 reviewed them and wrote this description. Both are listed as co-authors in the commit trailers.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
inline patch 1: pgjdbc/src/main/java/org/postgresql/jdbc/PgPreparedStatement.java, pgjdbc/src/test/java/org/postgresql/test/jdbc2/PreparedStatementTest.java (+73/-2 lines) download inline-1.patchdiff --git a/pgjdbc/src/main/java/org/postgresql/jdbc/PgPreparedStatement.java b/pgjdbc/src/main/java/org/postgresql/jdbc/PgPreparedStatement.javaindex a3a8b08d5a..dba70a8a5a 100644--- a/pgjdbc/src/main/java/org/postgresql/jdbc/PgPreparedStatement.java+++ b/pgjdbc/src/main/java/org/postgresql/jdbc/PgPreparedStatement.java@@ -1208,8 +1208,19 @@ public void addBatch() throws SQLException {
flags |= QueryExecutor.QUERY_ONESHOT;
}
StatementResultHandler handler = new StatementResultHandler();
- connection.getQueryExecutor().execute(preparedQuery.query, preparedParameters, handler, 0, 0,- flags);+ try {+ connection.getQueryExecutor().execute(preparedQuery.query, preparedParameters, handler, 0, 0,+ flags);+ } catch (SQLException e) {+ if (preparedQuery.query.getSubqueries() != null+ || !connection.getQueryExecutor().willHealOnRetry(e)) {+ throw e;+ }+ preparedQuery.query.close();+ handler = new StatementResultHandler();+ connection.getQueryExecutor().execute(preparedQuery.query, preparedParameters, handler, 0, 0,+ flags);+ }
ResultWrapper wrapper = handler.getResults();
if (wrapper != null) {
rs = wrapper.getResultSet();
diff --git a/pgjdbc/src/test/java/org/postgresql/test/jdbc2/PreparedStatementTest.java b/pgjdbc/src/test/java/org/postgresql/test/jdbc2/PreparedStatementTest.javaindex 17ab9ea268..32ab4a75dc 100644--- a/pgjdbc/src/test/java/org/postgresql/test/jdbc2/PreparedStatementTest.java+++ b/pgjdbc/src/test/java/org/postgresql/test/jdbc2/PreparedStatementTest.java@@ -1769,6 +1769,66 @@ public void testGetMetaDataDoesNotBypassPrepareThreshold() throws SQLException {
assertEquals(0, getNumberOfServerPreparedStatements("SELECT 44"), "prepareThreshold=5 and the statement was never executed, so describing it should not server-prepare it");
}
+ @Test+ public void testGetMetaDataRetriesInvalidatedPlan() throws SQLException {+ assumeTrue(preferQueryMode != PreferQueryMode.SIMPLE,+ "simple protocol does not support describe requests");+ String table = "metadata_retry_" + binaryMode;+ try (Connection other = TestUtil.openDB(); Statement ddl = other.createStatement()) {+ TestUtil.createTable(other, table, "value int");+ try (PreparedStatement pstmt = con.prepareStatement("select * from " + table)) {+ ((PGStatement) pstmt).setPrepareThreshold(1);+ ddl.executeUpdate("insert into " + table + " values (42)");+ try (ResultSet rs = pstmt.executeQuery()) {+ assertEquals(Types.INTEGER, rs.getMetaData().getColumnType(1));+ }+ ddl.executeUpdate("alter table " + table + " alter value type text");+ assertEquals(Types.VARCHAR, pstmt.getMetaData().getColumnType(1));+ try (ResultSet rs = pstmt.executeQuery()) {+ assertTrue(rs.next());+ assertEquals("42", rs.getString(1));+ }+ } finally {+ TestUtil.dropTable(other, table);+ }+ }+ }++ @Test+ public void testGetMetaDataDoesNotRetryFailedTransaction() throws SQLException {+ assumeTrue(preferQueryMode != PreferQueryMode.SIMPLE,+ "simple protocol does not support describe requests");+ String table = "metadata_failed_" + binaryMode;+ try (Connection other = TestUtil.openDB(); Statement ddl = other.createStatement()) {+ TestUtil.createTable(other, table, "value int");+ try (PreparedStatement pstmt = con.prepareStatement("select * from " + table)) {+ ((PGStatement) pstmt).setPrepareThreshold(1);+ try (ResultSet rs = pstmt.executeQuery()) {+ assertEquals(Types.INTEGER, rs.getMetaData().getColumnType(1));+ }+ ddl.executeUpdate("alter table " + table + " alter value type text");+ con.setAutoCommit(false);+ try (Statement begin = con.createStatement()) {+ begin.execute("select 1");+ }+ assertEquals("0A000", assertThrows(SQLException.class, pstmt::getMetaData).getSQLState());+ } finally {+ con.rollback();+ con.setAutoCommit(true);+ TestUtil.dropTable(other, table);+ }+ }+ }++ @Test+ public void testGetMetaDataPreservesSyntaxError() throws SQLException {+ assumeTrue(preferQueryMode != PreferQueryMode.SIMPLE,+ "simple protocol does not support describe requests");+ try (PreparedStatement pstmt = con.prepareStatement("select from")) {+ assertEquals("42601", assertThrows(SQLException.class, pstmt::getMetaData).getSQLState());+ }+ }+
@Test
public void testInappropriateStatementSharing() throws SQLException {
PreparedStatement ps = con.prepareStatement("SELECT ?::timestamp");