[Bug]: High failure rate (~95%) with `useDatabase` and Cloudflare Hyperdrive compared to manual connection

[imbytecat]

Environment

Operating System: macOS / Windows - locally, but issue is on Cloudflare Workers

Bun Version: v1.3.5

Nitro Version: nitro-nightly@3.0.1-20251219-124228-00598a8a

PackageManager: bun

Deployment Target: Cloudflare Workers

Database: PostgreSQL (via Cloudflare Hyperdrive)

Reproduction

I am using the experimental useDatabase feature in Nitro 3 with a Cloudflare Hyperdrive binding.

1. Configuration (nitro.config.ts):

export default defineNitroConfig({
  experimental: {
    database: true,
  },
  database: {
    default: {
      connector: 'cloudflare-hyperdrive-postgresql',
      options: {
        bindingName: 'HYPERDRIVE' 
      }
    }
  }
})

2. The Failing Implementation (Using useDatabase): When using the built-in useDatabase with db0/integrations/drizzle, requests fail with a 500 error approximately 95% of the time.

import { os } from '@orpc/server'
import { drizzle } from 'db0/integrations/drizzle'
import { useDatabase } from 'nitro/database'
import type { schema } from '#server/database'

export const dbProvider = os.middleware(async ({ context, next }) => {
  // This fails 95% of the time with 500 errors
  const db0 = useDatabase()
  const db = drizzle<typeof schema>(db0)

  return next({
    context: {
      ...context,
      db,
    },
  })
})

3. The Working Implementation (Manual Connection): When I manually create the connection using the Hyperdrive connection string directly (bypassing useDatabase abstraction), it works 100% of the time.

import type { Hyperdrive } from '@cloudflare/workers-types'
import { os } from '@orpc/server'
import { drizzle } from 'drizzle-orm/node-postgres'
import type { H3Event } from 'nitro/h3'
import { useRuntimeConfig } from 'nitro/runtime-config'
import { schema } from '#server/database'

type CloudflareEnv = {
  HYPERDRIVE?: Hyperdrive
}

const getDbUrl = (event: H3Event): string => {
  const env = event.runtime?.cloudflare?.env as CloudflareEnv | undefined
  const config = useRuntimeConfig()

  return env?.HYPERDRIVE?.connectionString ?? (config.databaseUrl as string)
}

export const dbProvider = os
  .$context<{ event: H3Event }>()
  .middleware(async ({ context, next }) => {
    const dbUrl = getDbUrl(context.event)
    const db = drizzle(dbUrl, { schema })

    return next({
      context: {
        ...context,
        db,
      },
    })
  })

Describe the bug

When deploying to Cloudflare Workers and using the cloudflare-hyperdrive-postgresql connector via useDatabase, database queries fail sporadically but frequently (almost 95% failure rate).

The symptoms are:

1. Requests return a 500 Internal Server Error.

Additional context

No response

Logs

[coderabbitai]

🔗 Similar Issues

Related Issues

• Can't transfer request in miniflare due to module-handler.ts buffering the requst body #3499
• [cloudflare_module]: Attempting to call readRawBody in a Nitro route for a DELETE request throws a 500 error and terminates the request #3708
• Module Path Resolution Error When Using Monorepo + Nitro + Prisma #3403
• [v3] Using nitro/vite with cloudflare preset fails to start #3637

👤 Suggested Assignees

• pnwmatt
• adamdehaven
• MagmaBlock
• franklin-tina

---

Enable issue planning

_{To enable issue planning, add the following to your .coderabbit.yaml:}

issue_enrichment:
  planning:
    enabled: true

_{You can then request a plan by commenting @coderabbitai plan on any issue.}

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[imbytecat]

Log from Workers:

  "exceptions": [
    {
      "name": "Error",
      "message": "The Workers runtime canceled this request because it detected that your Worker's code had hung and would never generate a response. Refer to: https://developers.cloudflare.com/workers/observability/errors/",
      "timestamp": 1766383707230
    }
  ],

[imbytecat]

It appears to function correctly after every redeployment to Cloudflare Workers. Do you think this might have something to do with the workers global scope?

[pi0]

@imbytecat yes it is my guess too however in your example, i see you call useDatabas within reuqest handlers. Maybe you also do it somewhere else globlly?

[imbytecat]

I only call useDatabase inside the request handler, not at the global level.

I’m not an expert on serverless, but my understanding is that in serverless environments like Cloudflare Workers, while each request is isolated, the global scope can be shared across multiple executions. If a database object is placed in the global scope, it might lead to issues where the connection is unexpectedly closed or fails to function correctly.

Looking at this code, it seems the database object is being cached globally (if I’m understanding it correctly). Do we need to implement specific handling or patterns tailored for serverless environments to address this?

nitro/src/runtime/internal/database.ts

Lines 5 to 17 in 0f3740d

	const instances: Record<string, Database> = Object.create(null);
	export function useDatabase(name = "default"): Database {
	if (instances[name]) {
	return instances[name];
	}
	if (!connectionConfigs[name]) {
	throw new Error(`Database connection "${name}" not configured.`);
	}
	return (instances[name] = createDatabase(
	connectionConfigs[name].connector(connectionConfigs[name].options || {})
	));
	}