docs(cloudflare): troubleshoot DB client error (#131)

Author: vicb

pages/cloudflare/troubleshooting.mdx

@@ -40,3 +40,49 @@ You may want to modify how Wrangler resolves multiple exports, such that when yo
 WRANGLER_BUILD_CONDITIONS=""
 WRANGLER_BUILD_PLATFORM="node"
 ```
+
+### `Error: Cannot perform I/O on behalf of a different request.`
+
+Some DB clients (i.e. [`postgres`](https://www.npmjs.com/package/postgres)) create a connection to the DB server when they are first instantiated and re-use it for later requests.
+This programming model is not compatible with the Workers runtime where a connection can not be re-used in a different request.
+
+The following error is generated in such a case:
+
+```text
+⨯ Error: Cannot perform I/O on behalf of a different request. I/O objects (such as streams, request/response bodies, and others) created in the context of one request handler cannot be accessed from a different request's handler. This is a limitation of Cloudflare Workers which allows us to improve overall performance. (I/O type: Writable)
+```
+
+To solve this, you should create the DB client inside a request context and not keep a global DB client.
+
+A global client would not work:
+
+```ts
+// src/lib/db.ts
+import postgres from "postgres";
+
+// `client` is global.
+// As the connection would be shared across requests, it fails on worker
+export const client = postgres(process.env.DATABASE_URL, { max: 5 });
+
+// src/app/api/route.ts
+import { client } from "@/db/db";
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  return new Response(JSON.stringify(await client`SELECT * FROM users;`));
+}
+```
+
+It can fixed by creating the client for each incoming request:
+
+```ts
+// src/app/api/route.ts
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  // The client is created for each incoming request and no connection is shared across requests
+  const client = postgres(process.env.DATABASE_URL, { max: 5 });
+  return new Response(JSON.stringify(await client`SELECT * FROM users;`));
+}
+```