Hyperdrive

Accelerate database access with Hyperdrive

Hyperdrive accelerates your existing database connections by caching queries and managing connection pooling. Use the API to create and manage Hyperdrive configurations.

Overview

Access the Hyperdrive API:

import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: process.env.CLOUDFLARE_API_TOKEN,
});

// Access Hyperdrive resources
const hyperdrive = client.hyperdrive;

Configurations

Manage Hyperdrive database configurations.

Create a configuration

Create a new Hyperdrive configuration for a database.

const config = await client.hyperdrive.configs.create({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  name: 'my-database-config',
  origin: {
    host: 'database.example.com',
    port: 5432,
    database: 'myapp',
    user: 'myuser',
    scheme: 'postgres',
  },
  caching: {
    disabled: false,
    max_age: 60,
    stale_while_revalidate: 15,
  },
});

account_id · string · required

Your Cloudflare account ID

name · string · required

Name for the Hyperdrive configuration

origin · object · required

Database origin configuration

origin.host · string · required

Database hostname or IP address

origin.port · number · required

Database port (e.g., 5432 for PostgreSQL, 3306 for MySQL)

origin.database · string

Database name

origin.user · string

Database username

origin.scheme · string

Database scheme: ‘postgres’, ‘postgresql’, or ‘mysql’

caching · object

Query caching configuration

caching.disabled · boolean

Set to true to disable caching (default: false)

caching.max_age · number

Maximum time in seconds to cache query results (default: 60)

caching.stale_while_revalidate · number

Time in seconds to serve stale results while revalidating (default: 15)

id · string

The configuration ID

name · string

The configuration name

origin · object

The database origin settings

created_on · string

ISO 8601 timestamp when the configuration was created

modified_on · string

ISO 8601 timestamp when the configuration was last modified

List configurations

Retrieve all Hyperdrive configurations in your account.

for await (const config of client.hyperdrive.configs.list({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
})) {
  console.log(config);
}

account_id · string · required

Your Cloudflare account ID

Get a configuration

Retrieve details about a specific Hyperdrive configuration.

const config = await client.hyperdrive.configs.get(
  'config-id',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

config_id · string · required

The configuration ID

account_id · string · required

Your Cloudflare account ID

Update a configuration

Update an existing Hyperdrive configuration.

const config = await client.hyperdrive.configs.update(
  'config-id',
  {
    account_id: '023e105f4ecef8ad9ca31a8372d0c353',
    name: 'updated-config-name',
    origin: {
      host: 'new-database.example.com',
      port: 5432,
      database: 'myapp',
      user: 'myuser',
      scheme: 'postgres',
    },
    caching: {
      disabled: false,
      max_age: 120,
    },
  }
);

config_id · string · required

The configuration ID to update

account_id · string · required

Your Cloudflare account ID

name · string

Updated configuration name

origin · object

Updated database origin settings

caching · object

Updated caching settings

Delete a configuration

Delete a Hyperdrive configuration.

await client.hyperdrive.configs.delete(
  'config-id',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

config_id · string · required

The configuration ID to delete

account_id · string · required

Your Cloudflare account ID

Advanced configuration

Cloudflare Access protected databases

Connect to databases protected by Cloudflare Access:

const config = await client.hyperdrive.configs.create({
  account_id: accountId,
  name: 'access-protected-db',
  origin: {
    host: 'database.example.com',
    database: 'myapp',
    user: 'myuser',
    scheme: 'postgres',
    access_client_id: 'your-access-client-id',
  },
});

origin.access_client_id · string

Cloudflare Access Client ID for authentication

Connection limits

Configure maximum connections:

const config = await client.hyperdrive.configs.create({
  account_id: accountId,
  name: 'my-config',
  origin: {...},
  origin_connection_limit: 100,
});

origin_connection_limit · number

Maximum number of connections to the origin database (soft limit)

mTLS

Configure mutual TLS for secure connections:

const config = await client.hyperdrive.configs.create({
  account_id: accountId,
  name: 'secure-db',
  origin: {...},
  mtls: {
    ca_certificate_id: 'ca-cert-id',
    mtls_certificate_id: 'mtls-cert-id',
    sslmode: 'verify-full',
  },
});

mtls · object

Mutual TLS configuration

mtls.ca_certificate_id · string

CA certificate ID for verifying the database server

mtls.mtls_certificate_id · string

Client certificate ID for mTLS authentication

mtls.sslmode · string

SSL mode: ‘require’, ‘verify-ca’, or ‘verify-full’

Using Hyperdrive in Workers

Bind a Hyperdrive configuration to your Worker:

const version = await client.workers.beta.workers.versions.create(
  workerId,
  {
    account_id: accountId,
    main_module: 'worker.mjs',
    compatibility_date: '2024-03-01',
    bindings: [
      {
        type: 'hyperdrive',
        name: 'HYPERDRIVE',
        id: 'config-id',
      },
    ],
    modules: [...],
  }
);

Then connect from your Worker:

import { Client } from 'pg';

export default {
  async fetch(request, env) {
    // Connect using Hyperdrive
    const client = new Client({
      connectionString: env.HYPERDRIVE.connectionString,
    });
    
    await client.connect();
    
    // Execute queries (automatically cached by Hyperdrive)
    const result = await client.query('SELECT * FROM users LIMIT 10');
    
    await client.end();
    
    return Response.json(result.rows);
  },
};

Best practices

1. Caching: Enable caching for read-heavy workloads to reduce database load
2. Connection pooling: Hyperdrive automatically manages connection pooling
3. Security: Use mTLS for production databases
4. Access control: Protect databases with Cloudflare Access for additional security
5. Query optimization: Cache frequently accessed data with appropriate max_age values
6. Stale-while-revalidate: Use this to serve cached results while fetching fresh data