Translate getDocument PDO exceptions

[abnegate]

What does this PR do?

Translate PDO failures from SQL::getDocument() through the adapter-specific exception mapper.

A request timeout can fire while Database::find() resolves collection metadata. getDocument() previously leaked the raw PDOException, so Appwrite returned a generic HTTP 500 instead of the expected database-timeout 408. The result depended on whether collection metadata was already cached.

The query now uses the adapter execution hook, always attempts cursor cleanup, and preserves the primary operation exception if cleanup also fails. This also ensures Postgres applies and resets its statement timeout on this path.

Tests

• Added focused MySQL execute/fetch timeout translation coverage
• Added cleanup exception precedence coverage
• Added Postgres execute-hook timeout coverage
• Full unit suite: 404 tests, 2,263 assertions
• Pint
• PHPStan level 7

Summary by CodeRabbit

• Bug Fixes

  • Improved database document retrieval error handling.
  • Timeout errors are now consistently translated and preserved, even when cleanup encounters an additional error.
  • Ensured database cursors are closed reliably after document reads.
  • Improved PostgreSQL statement-timeout handling during document retrieval.

• Tests

  • Added coverage for timeout handling, cursor cleanup, and PostgreSQL execution behavior.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[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 Plus

Run ID: 989cbc94-13de-413b-a083-8c3775e310f1

📥 Commits

Reviewing files that changed from the base of the PR and between a1796fd and 656258b.

📒 Files selected for processing (2)

• src/Database/Adapter/SQL.php
• tests/unit/SQLGetDocumentTest.php

---

📝 Walkthrough

Walkthrough

getDocument() now handles execution and fetch failures through structured cleanup and exception normalization. New unit tests cover timeout translation, cursor cleanup, exception preservation, and PostgreSQL statement-timeout hooks.

Changes

Document read safety

Layer / File(s)	Summary
Safe document read execution src/Database/Adapter/SQL.php	getDocument() wraps execution and fetching in try/catch/finally, closes the cursor safely, and rethrows normalized exceptions.
Document read behavior tests tests/unit/SQLGetDocumentTest.php	Tests verify timeout handling during execution and fetching, cursor cleanup, preserved previous exceptions, and PostgreSQL timeout setup/reset hooks.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested reviewers: copilot

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly reflects the main change: translating PDO exceptions in getDocument().
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/get-document-timeout

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 PHPStan (2.2.5)

Composer install failed: this project depends on private packages that require authentication (e.g. GitLab/GitHub, Laravel Nova, etc.).
CodeRabbit tooling environment cannot access private registries.
If your project requires private packages, disable the PHPStan tool in your coderabbit settings.

Instead, run PHPStan in a CI/CD pipeline where you can use custom packages — our pipeline remediation tool can use the PHPStan output from your CI/CD pipeline.

---

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.}

[greptile-apps]

Greptile Summary

This PR translates PDO failures from SQL document reads through adapter-specific exception mapping.

• Routes getDocument() execution through the adapter hook, enabling PostgreSQL statement-timeout handling.
• Ensures cursor cleanup after prepare succeeds while preserving the primary PDO exception if cleanup also fails.
• Adds focused MySQL and PostgreSQL tests for timeout translation, cleanup precedence, and execution-hook behavior.

Confidence Score: 5/5

The PR appears safe to merge, with the changed exception translation and cleanup paths behaving consistently with the adapter contract.

The primary PDO failure is retained across cursor cleanup, translated only after cleanup, and PostgreSQL document reads now use the existing execution hook that applies and resets statement timeouts.

Important Files Changed

Filename	Overview
src/Database/Adapter/SQL.php	Routes document reads through the adapter execution hook and adds exception-safe cursor cleanup without revealing a concrete regression.
tests/unit/SQLGetDocumentTest.php	Adds focused coverage for execute and fetch timeout translation, cleanup-exception precedence, and PostgreSQL timeout-hook invocation.

_{Reviews (1): Last reviewed commit: "(fix): translate getDocument PDO excepti..." | Re-trigger Greptile}