Hyperdrive error and supported postgres feature documentation improvements

content/hyperdrive/configuration/connect-to-postgres.md

@@ -193,19 +193,6 @@ export default {
 {{</tab>}}
 {{</tabs>}}
 
-## Transaction and statement support
-
-Hyperdrive's connection pooling mode is equivalent to the `transaction` mode of connection poolers like [PgBouncer](https://www.pgbouncer.org/) and [PgCat](https://github.com/postgresml/pgcat).
-
-Hyperdrive does not support the following PostgreSQL features:
-
-- `SET` statements.
-- Advisory locks ([PostgreSQL documentation](https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS)).
-- `LISTEN` and `NOTIFY`.
-- `PREPARE` and `DEALLOCATE`.
-
-In cases where you need to issue these unsupported statements from your application, the Hyperdrive team recommends setting up a second, direct client without Hyperdrive.
-
 ## Identify connections from Hyperdrive
 
 To identify active connections to your Postgres database server from Hyperdrive:

content/hyperdrive/configuration/how-hyperdrive-works.md

@@ -34,9 +34,18 @@ The connection pool operates in transaction mode, where the client that executes
 
 When that transaction has completed, the connection is returned to the pool.
 
-{{<Aside type="warning">}}
-Named prepared statements (which are rarely used), `SET` commands, and advisory locks are not supported. Use features such as `LOCAL` and `pg_advisory_xact_lock` which are scoped to single transactions. In cases where you need to issue these unsupported statements from your application, the Hyperdrive team recommends setting up a second, direct client without Hyperdrive.
-{{</Aside>}}
+Hyperdrive supports named prepared statements as implemented in the `postgres.js` and `node-postgres` drivers. Named prepared statements in other drivers may have worse performance.
+
+Hyperdrive does not support the following PostgreSQL features:
+
+- `SET` statements.
+- SQL-level management of prepared statements, such as using `PREPARE`, `DISCARD`, `DEALLOCATE`, or `EXECUTE`.
+- Advisory locks ([PostgreSQL documentation](https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS)).
+- `LISTEN` and `NOTIFY`.
+- `PREPARE` and `DEALLOCATE`.
+- Any modification to per-session state not explicitly documented as supported elsewhere.
+
+In cases where you need to issue these unsupported statements from your application, the Hyperdrive team recommends setting up a second, direct client without Hyperdrive.
 
 ## Query Caching
 

content/hyperdrive/observability/troubleshooting.md

@@ -8,7 +8,7 @@ weight: 10
 
 Troubleshoot and debug errors commonly associated with connecting to a database with Hyperdrive.
 
-## Connection errors
+## Configuration errors
 
 When creating a new Hyperdrive configuration, or updating the connection parameters associated with an existing configuration, Hyperdrive performs a test connection to your database in the background before creating or updating the configuration.
 
@@ -25,3 +25,20 @@ Hyperdrive will also issue an empty test query, a `;` in PostgreSQL, to validate
 | `2014`     | The specified database name does not exist.                                                      | Check that the database (not table) name you provided exists on the database you are asking Hyperdrive to connect to.                                          |
 | `2015`     | Generic error.                                                                                   | Hyperdrive failed to connect and could not determine a reason. Open a support ticket so Cloudflare can investigate.                                            |
 | `2016`     | Test query failed.                                                                               | Confirm that the user Hyperdrive is connecting as has permissions to issue read and write queries to the given database.                                       |
+
+## Connection errors
+
+Hyperdrive may also return errors at runtime. This can happen during initial connection setup, or in response to a query or other wire-protocol command sent by your driver.
+
+These errors are returned as `ErrorResponse` wire protocol messages, which are handled by most drivers by throwing from the responsible query or by triggering an error event.
+Hyperdrive errors that do not map 1:1 with an error message code [documented by PostgreSQL](https://www.postgresql.org/docs/current/errcodes-appendix.html) use the `58000` error code.
+
+Hyperdrive may also encounter `ErrorResponse` wire protocol messages sent by your database. Hyperdrive will pass these errors through unchanged when possible.
+
+### Hyperdrive specific errors
+
+| Error Message                                             | Details                                                                                          | Recommended fixes                                                                                                                                              |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Internal error.`                                         | Something is broken on our side.                                                                 | Check for an ongoing incident affecting Hyperdrive, and contact Cloudflare Support.                                                                            |
+| `Failed to acquire a connection from the pool.`           | Hyperdrive timed out while waiting for a connection to your database, or cannot connect at all.  | If you are seeing this error intermittently, your Hyperdrive pool is being exhausted because too many connections are being held open for too long by your worker. This can be caused by a myriad of different issues, but long-running queries/transactions are a common offender. |
+| `Server connection attempt failed: connection_refused`    | Hyperdrive is unable to create new connections to your origin database.                          | A network firewall or access control list (ACL) is likely rejecting requests from Hyperdrive. Ensure you have allowed connections from the public Internet. Sometimes, this can be caused by your database host provider refusing incoming connections when you go over your connection limit. |