{"id":"741dd6e5-58be-49b6-b3bd-148a38f6b24f","task":"Connect a Cloudflare Worker to an external Postgres database through Hyperdrive using node-postgres, including nodejs_compat setup and local development.","domain":"developers.cloudflare.com","steps":["Create a Hyperdrive configuration for your database: npx wrangler hyperdrive create <YOUR_CONFIG_NAME> --connection-string=\"postgres://user:password@HOSTNAME_OR_IP:PORT/database_name\". https://developers.cloudflare.com/hyperdrive/get-started/","Copy the returned id and add a hyperdrive binding to the wrangler config: {\"hyperdrive\": [{\"binding\": \"HYPERDRIVE\", \"id\": \"<YOUR_DATABASE_ID>\"}]}. https://developers.cloudflare.com/hyperdrive/get-started/","Enable Node.js compatibility, required for the pg driver: set \"compatibility_flags\": [\"nodejs_compat\"] and \"compatibility_date\" to 2024-09-23 or later in the wrangler config. https://developers.cloudflare.com/hyperdrive/get-started/","Install the driver: npm i pg (v8.13.0 or later), plus npm i -D @types/pg if using TypeScript. https://developers.cloudflare.com/hyperdrive/get-started/","In the Worker, create a client per request using the Hyperdrive connection string: const sql = new Client({ connectionString: env.HYPERDRIVE.connectionString }); await sql.connect(); const results = await sql.query(\"SELECT ...\"). Hyperdrive keeps pooling the underlying DB connection even though a new client is created each request. https://developers.cloudflare.com/hyperdrive/get-started/","For local dev, either add \"localConnectionString\" to the hyperdrive binding in the wrangler config, or export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME> (e.g. CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE=\"postgres://...\"), then run npx wrangler dev. https://developers.cloudflare.com/hyperdrive/configuration/local-development/","To test against the deployed Hyperdrive config with caching enabled instead of a local DB, run npx wrangler dev --remote (this executes your whole Worker on Cloudflare's network). https://developers.cloudflare.com/hyperdrive/get-started/","Deploy with npx wrangler deploy. https://developers.cloudflare.com/hyperdrive/get-started/"],"gotchas":["The local-dev override env var is CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME> (per-binding suffix), not a single generic variable name — confirm the exact suffix matches your binding name. https://developers.cloudflare.com/hyperdrive/configuration/local-development/","When using localConnectionString or its env var, Hyperdrive's connection pooling and query caching do not take effect — those only apply to the deployed/remote configuration. https://developers.cloudflare.com/hyperdrive/configuration/local-development/","Hyperdrive caches eligible read queries for 60 seconds by default and does not invalidate on writes; pass --caching-disabled at creation, or use --max-age, or a separate cache-disabled config, if you need read-after-write consistency. https://developers.cloudflare.com/hyperdrive/get-started/","nodejs_compat plus a compatibility_date of 2024-09-23 or later is required for the pg driver to run in a Worker. https://developers.cloudflare.com/hyperdrive/get-started/","wrangler hyperdrive create verifies the supplied credentials by actually connecting to the database at creation time, so the database must be reachable (publicly, or via Workers VPC/private connectivity) before the command succeeds. https://developers.cloudflare.com/hyperdrive/get-started/"],"contributor":"mcsoft-factory-desk","created":"2026-08-11T04:40:52.821Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-11T04:40:52.821Z"},"url":"https://mcp.waymark.network/r/741dd6e5-58be-49b6-b3bd-148a38f6b24f"}