Add some notes to hyperdrive docs (#19616)

* Note optimal postgres.js connection settings

* Note that retrying internal errors is appropriate

* Update src/content/docs/hyperdrive/get-started.mdx

* Update src/content/docs/workers/tutorials/postgres/index.mdx

* Update src/content/partials/hyperdrive/create-hyperdrive-config.mdx

* Update src/content/partials/hyperdrive/use-postgresjs-to-make-query.mdx

---------

Co-authored-by: Jun Lee <[email protected]>

Author: ReppCodes

src/content/docs/hyperdrive/configuration/connect-to-postgres.mdx

@@ -161,4 +161,4 @@ To identify active connections to your Postgres database server from Hyperdrive:
 
 - Refer to the list of [supported database integrations](/workers/databases/connecting-to-databases/) to understand other ways to connect to existing databases.
 - Learn more about how to use the [Socket API](/workers/runtime-apis/tcp-sockets) in a Worker.
-- Understand the [protocols supported by Workers](/workers/reference/protocols/).
+- Understand the [protocols supported by Workers](/workers/reference/protocols/).

src/content/docs/hyperdrive/get-started.mdx

@@ -195,7 +195,19 @@ export default {
 		// Hyperdrive generates a unique connection string you can pass to
 		// supported drivers, including node-postgres, Postgres.js, and the many
 		// ORMs and query builders that use these drivers.
-		const sql = postgres(env.HYPERDRIVE.connectionString);
+		const sql = postgres(
+            env.HYPERDRIVE.connectionString,
+            {
+                // Workers limit the number of concurrent external connections, so be sure to limit
+                // the size of the local connection pool that postgres.js may establish.
+                max: 5,
+
+                // If you are using array types in your Postgres schema, it is necessary to fetch
+                // type information to correctly de/serialize them. However, if you are not using
+                // those, disabling this will save you an extra round-trip every time you connect.
+                fetch_types: false,
+            },
+        );
 
 		try {
 			// Test query
@@ -245,4 +257,4 @@ By finishing this tutorial, you have created a Hyperdrive configuration, a Worke
 - How to [configure query caching](/hyperdrive/configuration/query-caching/).
 - [Troubleshooting common issues](/hyperdrive/observability/troubleshooting/) when connecting a database to Hyperdrive.
 
-If you have any feature requests or notice any bugs, share your feedback directly with the Cloudflare team by joining the [Cloudflare Developers community on Discord](https://discord.cloudflare.com).
+If you have any feature requests or notice any bugs, share your feedback directly with the Cloudflare team by joining the [Cloudflare Developers community on Discord](https://discord.cloudflare.com).

src/content/docs/hyperdrive/observability/troubleshooting.mdx

@@ -38,7 +38,7 @@ Hyperdrive may also encounter `ErrorResponse` wire protocol messages sent by you
 
 | Error Message                                          | Details                                                                                         | Recommended fixes                                                                                                                                                                                                                                                                              |
 | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Internal error.`                                      | Something is broken on our side.                                                                | Check for an ongoing incident affecting Hyperdrive, and contact Cloudflare Support.                                                                                                                                                                                                            |
+| `Internal error.`                                      | Something is broken on our side.                                                                | Check for an ongoing incident affecting Hyperdrive, and contact Cloudflare Support.  Retrying the query is appropriate, if it makes sense for your usage pattern.                                                                                                                              |
 | `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. |
 
@@ -50,4 +50,4 @@ Hyperdrive may also encounter `ErrorResponse` wire protocol messages sent by you
 
 ### Improve performance
 
-Having query traffic written as transactions can limit performance. This is because in the case of a transaction, the connection must be held for the duration of the transaction, which limits connection multiplexing. If there are multiple queries per transaction, this can be particularly impactful on connection multiplexing. Where possible, we recommend not wrapping queries in transactions to allow the connections to be shared more aggressively.
+Having query traffic written as transactions can limit performance. This is because in the case of a transaction, the connection must be held for the duration of the transaction, which limits connection multiplexing. If there are multiple queries per transaction, this can be particularly impactful on connection multiplexing. Where possible, we recommend not wrapping queries in transactions to allow the connections to be shared more aggressively.

src/content/docs/pages/functions/bindings.mdx

@@ -834,4 +834,4 @@ When developing locally, add secrets by creating a `.dev.vars` file in the root
 
 ```
 SECRET_NAME=<SECRET_VALUE>
-```
+```

src/content/docs/workers/tutorials/postgres/index.mdx

@@ -195,7 +195,19 @@ import postgres from "postgres";
 
 export default {
 	async fetch(request, env, ctx): Promise<Response> {
-		const sql = postgres(env.DB_URL);
+		const sql = postgres(
+            env.DB_URL,
+            {
+                // Workers limit the number of concurrent external connections, so be sure to limit
+                // the size of the local connection pool that postgres.js may establish.
+                max: 5,
+
+                // If you are using array types in your Postgres schema, it is necessary to fetch
+                // type information to correctly de/serialize them. However, if you are not using
+                // those, disabling this will save you an extra round-trip every time you connect.
+                fetch_types: false,
+            },
+        );
 
 		// Query the products table
 		const result = await sql`SELECT * FROM products;`;
@@ -368,4 +380,4 @@ Your Worker application is now live and accessible at `<YOUR_WORKER>.<YOUR_SUBDO
 
 To build more with databases and Workers, refer to [Tutorials](/workers/tutorials) and explore the [Databases documentation](/workers/databases).
 
-If you have any questions, need assistance, or would like to share your project, join the Cloudflare Developer community on [Discord](https://discord.cloudflare.com) to connect with fellow developers and the Cloudflare team.
+If you have any questions, need assistance, or would like to share your project, join the Cloudflare Developer community on [Discord](https://discord.cloudflare.com) to connect with fellow developers and the Cloudflare team.

src/content/partials/hyperdrive/create-hyperdrive-config.mdx

@@ -72,7 +72,19 @@ export default {
 		// Hyperdrive generates a unique connection string you can pass to
 		// supported drivers, including node-postgres, Postgres.js, and the many
 		// ORMs and query builders that use these drivers.
-		const sql = postgres(env.HYPERDRIVE.connectionString);
+		const sql = postgres(
+            env.HYPERDRIVE.connectionString,
+            {
+                // Workers limit the number of concurrent external connections, so be sure to limit
+                // the size of the local connection pool that postgres.js may establish.
+                max: 5,
+
+                // If you are using array types in your Postgres schema, it is necessary to fetch
+                // type information to correctly de/serialize them. However, if you are not using
+                // those, disabling this will save you an extra round-trip every time you connect.
+                fetch_types: false,
+            },
+        );
 
 		try {
 			// Test query
@@ -92,4 +104,4 @@ export default {
 
 - Learn more about [How Hyperdrive Works](/hyperdrive/configuration/how-hyperdrive-works/).
 - Refer to the [troubleshooting guide](/hyperdrive/observability/troubleshooting/) to debug common issues.
-- Understand more about other [storage options](/workers/platform/storage-options/) available to Cloudflare Workers.
+- Understand more about other [storage options](/workers/platform/storage-options/) available to Cloudflare Workers.

src/content/partials/hyperdrive/use-postgresjs-to-make-query.mdx

@@ -23,7 +23,19 @@ export default {
 	async fetch(request: Request, env: Env, ctx: ExecutionContext) {
 		// NOTE: if `prepare: false` is passed when connecting, performance will
 		// be slower but still correctly supported.
-		const sql = postgres(env.HYPERDRIVE.connectionString);
+		const sql = postgres(
+            env.HYPERDRIVE.connectionString,
+            {
+                // Workers limit the number of concurrent external connections, so be sure to limit
+                // the size of the local connection pool that postgres.js may establish.
+                max: 5,
+
+                // If you are using array types in your Postgres schema, it is necessary to fetch
+                // type information to correctly de/serialize them. However, if you are not using
+                // those, disabling this will save you an extra round-trip every time you connect.
+                fetch_types: false,
+            },
+        );
 
 		try {
 			// A very simple test query
@@ -41,4 +53,4 @@ export default {
 		}
 	},
 } satisfies ExportedHandler<Env>;
-```
+```