fix: accept prepare/binary kwargs in DictCursor.execute

[asheshv]

Problem

psycopg.Connection.execute(query, params, *, prepare=None, binary=False) delegates to its underlying cursor as cur.execute(query, params, prepare=prepare). pgAdmin's DictCursor / AsyncDictCursor (in web/pgadmin/utils/driver/psycopg3/cursor.py) narrowed the signature to (self, query, params=None), so any caller that uses the high-level Connection.execute() path with a cursor_factory=DictCursor connection trips:

TypeError: DictCursor.execute() got an unexpected keyword argument 'prepare'

Concrete failure mode

The most visible victim is psycopg_pool.ConnectionPool.check_connection, which sends conn.execute("") to validate every checkout. With a DictCursor-using pool every connection looks broken to the pool — checkouts loop in the recovery path until PoolTimeout. This blocks check=ConnectionPool.check_connection from being usable at all when the pool is built with connection_class that sets cursor_factory=DictCursor.

Minimal reproducer:

import psycopg
from pgadmin.utils.driver.psycopg3.cursor import DictCursor

conn = psycopg.connect("…", cursor_factory=DictCursor)
conn.execute("SELECT 1")
# -> TypeError: DictCursor.execute() got an unexpected keyword argument 'prepare'

Fix

Forward prepare and binary (keyword-only) to the underlying psycopg.Cursor / psycopg.AsyncCursor. Defaults match psycopg's own (prepare=None, binary=None), so existing callers see no behavior change. Restores Liskov-substitutability with the standard psycopg cursors.

Test plan

• make check-pep8 — clean
• AST verification: both DictCursor.execute and AsyncDictCursor.execute expose prepare and binary as keyword-only parameters
• New regression test pgadmin.utils.tests.test_psycopg3_cursor_signature — passes under regression/runtests.py --pkg utils.tests (both DictCursor and AsyncDictCursor scenarios)
• Full utils.tests package — 30 passed / 0 failed / 4 unrelated skips
• CI green

Summary by CodeRabbit

• New Features

  • Cursor execute methods now accept additional keyword-only parameters to control query execution (e.g., preparation and binary modes), improving flexibility for advanced queries.

• Tests

  • Added regression tests to ensure the execute methods expose the new keyword-only parameters in their public signatures.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d301d721-2277-46dd-8c71-6e522f4637b7

📥 Commits

Reviewing files that changed from the base of the PR and between cc25ab3 and 6d9c119.

📒 Files selected for processing (1)

• web/pgadmin/utils/tests/test_psycopg3_cursor_signature.py

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

• web/pgadmin/utils/tests/test_psycopg3_cursor_signature.py

---

Walkthrough

This PR extends pgAdmin's psycopg3 cursor wrappers to accept and forward keyword-only prepare and binary parameters in their execute() methods and adds a regression test to validate those signatures.

Changes

psycopg3 cursor execute keyword argument support

Layer / File(s)	Summary
Cursor execute() method signature extensions web/pgadmin/utils/driver/psycopg3/cursor.py	DictCursor.execute() and AsyncDictCursor.execute() now accept keyword-only prepare and binary parameters forwarded to the underlying psycopg cursor, preserving empty params normalization and resetting _odt_desc. AsyncDictCursor._execute() mirrors the async handling.
Signature regression test web/pgadmin/utils/tests/test_psycopg3_cursor_signature.py	New test module uses inspect.signature to verify both cursor classes expose prepare and binary as keyword-only parameters on their execute() methods to prevent regressions that would cause TypeError.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main change: extending DictCursor.execute to accept prepare and binary keyword arguments.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

🧹 Nitpick comments (1)

web/pgadmin/utils/driver/psycopg3/cursor.py (1)

282-294: 💤 Low value

Consider adding self._odt_desc = None reset for consistency.

The synchronous DictCursor.execute (line 197) resets self._odt_desc = None before executing, but the async version does not. While the async ordered_description() method (lines 278-280) always refreshes the description (unlike the sync version which caches), this inconsistency could lead to confusion and maintainability issues.

Suggested alignment with sync version

 def execute(self, query, params=None, *, prepare=None, binary=None):
     """
     Execute function

     Mirrors ``DictCursor.execute`` so this cursor stays substitutable
     for ``psycopg.AsyncCursor`` when used via ``AsyncConnection.execute``.
     """
+    self._odt_desc = None
     try:
         return asyncio.run(
             self._execute(query, params, prepare=prepare, binary=binary)
         )

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@web/pgadmin/utils/driver/psycopg3/cursor.py` around lines 282 - 294, The
async execute method on this cursor should mirror the sync DictCursor.execute by
resetting the ordered-description cache; before calling
asyncio.run(self._execute(...)) in execute, set self._odt_desc = None to clear
any stale description so ordered_description() behavior remains consistent with
the sync path (references: execute, _execute, _odt_desc, ordered_description).

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@web/pgadmin/utils/driver/psycopg3/cursor.py`:
- Around line 282-294: The async execute method on this cursor should mirror the
sync DictCursor.execute by resetting the ordered-description cache; before
calling asyncio.run(self._execute(...)) in execute, set self._odt_desc = None to
clear any stale description so ordered_description() behavior remains consistent
with the sync path (references: execute, _execute, _odt_desc,
ordered_description).

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: e945aab5-7749-4656-a241-a4e1aa745c95

📥 Commits

Reviewing files that changed from the base of the PR and between 5627944 and cc25ab3.

📒 Files selected for processing (2)

• web/pgadmin/utils/driver/psycopg3/cursor.py
• web/pgadmin/utils/tests/test_psycopg3_cursor_signature.py

[Copilot]

Pull request overview

Fixes psycopg3 DictCursor/AsyncDictCursor compatibility with psycopg.Connection.execute(..., prepare=..., binary=...) by accepting and forwarding those keyword-only parameters, preventing TypeError when pgAdmin uses a cursor_factory=DictCursor connection (notably in pooling health checks).

Changes:

• Extend DictCursor.execute() and AsyncDictCursor.execute() signatures to accept prepare and binary as keyword-only args and forward them to psycopg.
• Update async execution path to pass through the new kwargs to the underlying async cursor execution method.
• Add a regression test asserting both cursor classes expose prepare and binary as keyword-only parameters.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
web/pgadmin/utils/driver/psycopg3/cursor.py	Accepts/forwards prepare and binary kwargs to restore substitutability with psycopg cursors.
web/pgadmin/utils/tests/test_psycopg3_cursor_signature.py	Adds regression coverage to ensure the new kwargs are present and keyword-only.

---

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

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

[asheshv]

@coderabbitai re: the AsyncDictCursor._odt_desc reset nitpick — declining, with reasoning:

• The async path's ordered_description() (lines 278-280) is intentionally written to always refresh, without a cache-hit check. The sync path's ordered_description() (lines 184-186) does check the cache. The _odt_desc = None reset in sync execute() exists to invalidate that cache before the next query.
• In the async path the cache is effectively bypassed by ordered_description() itself, so adding the reset would be a behavioral no-op — purely cosmetic consistency.
• This PR is a narrow signature fix (accept prepare / binary kwargs). Adding unrelated state-management changes — even harmless ones — widens the surface area and the review burden. If the sync/async description-caching divergence is itself worth aligning, that's a separate cleanup PR with its own justification (and probably worth removing the disabled cache check rather than adding a redundant reset).

The Copilot comment about the test docstring was valid and is addressed in 6d9c119.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@asheshv: Understood — the reasoning is clear and well-founded. The async ordered_description() bypasses caching by design, so the reset would indeed be a no-op rather than a meaningful invariant. Keeping this PR narrowly scoped to the signature fix is the right call.

Thanks for the thorough explanation; noted for future reviews.

ᓚᘏᗢ

---

✏️ Learnings added

Learnt from: asheshv
URL: https://github.com/pgadmin-org/pgadmin4/pull/10030

Timestamp: 2026-06-09T06:55:03.912Z
Learning: In `web/pgadmin/utils/driver/psycopg3/cursor.py`, the sync `DictCursor.ordered_description()` (around line 184) checks a cache before refreshing `_odt_desc`, so `_odt_desc = None` must be reset in `DictCursor.execute()` to invalidate that cache before each new query. The async `AsyncDictCursor.ordered_description()` (around line 278) intentionally always refreshes without a cache-hit check, so there is no need to reset `_odt_desc` in `AsyncDictCursor._execute()` — it would be a behavioral no-op. This divergence in caching behavior between the sync and async paths is intentional by design.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.