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,
},
});
Your Cloudflare account ID
Name for the Hyperdrive configuration
Database origin configuration
Database hostname or IP address
Database port (e.g., 5432 for PostgreSQL, 3306 for MySQL)
Database scheme: ‘postgres’, ‘postgresql’, or ‘mysql’
Query caching configuration
Set to true to disable caching (default: false)
Maximum time in seconds to cache query results (default: 60)
caching.stale_while_revalidate
Time in seconds to serve stale results while revalidating (default: 15)
The database origin settings
ISO 8601 timestamp when the configuration was created
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);
}
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' }
);
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,
},
}
);
The configuration ID to update
Your Cloudflare account ID
Updated configuration name
Updated database origin settings
Delete a configuration
Delete a Hyperdrive configuration.
await client.hyperdrive.configs.delete(
'config-id',
{ account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);
The configuration ID to delete
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',
},
});
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,
});
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',
},
});
CA certificate ID for verifying the database server
Client certificate ID for mTLS authentication
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: [...],
}
);
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