Remove .end() calls, add handler notes#28160
Conversation
Co-authored-by: elithrar <elithrar@users.noreply.github.com>
github-actions
Bot
added
product:hyperdrive
|
This PR requires additional review attention because it affects the following areas: PartialsThis PR updates partial files, which are pieces of content used across multiple files in our Render component.
|
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
… page Add exact error messages from node-postgres, postgres.js, mysql2, mysql, and the Workers runtime so users (and agents) can search for these strings and find the troubleshooting guidance. Covers errors thrown when database clients are created in global scope or reused across requests.
|
Done. I've added a new "Stale connection and I/O context errors" section to Workers runtime errors (2 errors):
node-postgres (
Postgres.js (
mysql2 (3 errors):
mysql (3 errors):
Each error includes details about when it occurs and a recommended fix pointing users to create clients inside handlers, with a link back to the connection lifecycle docs. |
|
LGTM! Thank you, Matt! |
|
Done. Here's a summary of the changes to
This follows the same pattern used on the Durable Objects rules page with |
elithrar
left a comment
elithrar
left a comment
There was a problem hiding this comment.
The good/bad example = great.
5 participants
All changes are complete. Here's a summary of what was done:
Summary of changes
Problem
The Hyperdrive documentation incorrectly recommended calling
client.end(),sql.end(),connection.end()(viactx.waitUntil()) to clean up database clients. In reality, Workers-to-Hyperdrive connections are automatically cleaned up when the request/invocation ends. The docs also lacked guidance about not creating database clients in global scope.Changes made across 13 files:
Conceptual documentation (2 files):
src/content/docs/hyperdrive/concepts/connection-lifecycle.mdx- Rewrote the "Cleaning up client connections" section to clearly state.end()is not required. Updated the code example to remove thectx.waitUntil(client.end())call and added a comment explaining automatic cleanup. Added a:::note[Create database clients inside your handlers]callout warning against creating database clients or driver-level pools in global scope.src/content/docs/hyperdrive/concepts/query-caching.mdx- Wrapped the code snippets showing dual Hyperdrive configs inside properfetch()handler context with comments reinforcing "not in global scope".Overview and getting started (2 files):
src/content/docs/hyperdrive/index.mdx- Removedctx.waitUntil(client.end())from the PostgreSQL example andctx.waitUntil(connection.end())from the MySQL example.src/content/docs/hyperdrive/get-started.mdx- Removedctx.waitUntil(sql.end())from the PostgreSQL example andctx.waitUntil(connection.end())from the MySQL example. Updated the numbered explanation text for both tabs.Partials (reused across multiple pages) (4 files):
src/content/partials/hyperdrive/use-node-postgres-to-make-query.mdx- Removedctx.waitUntil(client.end()).src/content/partials/hyperdrive/use-postgres-js-to-make-query.mdx- Removedctx.waitUntil(sql.end()).src/content/partials/hyperdrive/use-mysql2-to-make-query.mdx- Removedctx.waitUntil(connection.end()).src/content/partials/hyperdrive/use-mysql-to-make-query.mdx- Removedconnection.end()from the callback-style mysql driver example.Driver/ORM examples (3 files):
src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx- Removedctx.waitUntil(client.end()).src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm.mdx- Removedctx.waitUntil(connection.end()).src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/prisma-orm.mdx- Removedctx.waitUntil(prisma.$disconnect()).Tutorial (1 file):
src/content/docs/hyperdrive/tutorials/serverless-timeseries-api-with-timescale.mdx- Removed bothctx.waitUntil(client.end())calls (POST and GET branches).Closes #28159
github run