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)

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

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

Core Resources

Workers & Serverless

Application Services

Security & Access

Network Services

Developer Platform

Management & Monitoring

Overview

Configurations

Create a configuration

List configurations

Get a configuration

Update a configuration

Delete a configuration

Advanced configuration

Cloudflare Access protected databases

Connection limits

mTLS

Using Hyperdrive in Workers

Best practices

Build docs developers (and LLMs) love

Core Resources

Workers & Serverless

Application Services

Security & Access

Network Services

Developer Platform

Management & Monitoring

Documentation Index

​Overview

​Configurations

​Create a configuration

​List configurations

​Get a configuration

​Update a configuration

​Delete a configuration

​Advanced configuration

​Cloudflare Access protected databases

​Connection limits

​mTLS

​Using Hyperdrive in Workers

​Best practices

Build docs developers (and LLMs) love

Overview

Configurations

Create a configuration

List configurations

Get a configuration

Update a configuration

Delete a configuration

Advanced configuration

Cloudflare Access protected databases

Connection limits

mTLS

Using Hyperdrive in Workers

Best practices