Cloudflare D1 is a serverless SQL database built on SQLite. Use the API to create databases, execute queries, and manage data.
Overview
Access the D1 API:
import Cloudflare from 'cloudflare';
const client = new Cloudflare({
apiToken: process.env.CLOUDFLARE_API_TOKEN,
});
// Access D1 resources
const d1 = client.d1;
Databases
Manage D1 database instances.
Create a database
Create a new D1 database.
const database = await client.d1.database.create({
account_id: '023e105f4ecef8ad9ca31a8372d0c353',
name: 'my-database',
});
Your Cloudflare account ID
The database UUID identifier
ISO 8601 timestamp when the database was created
Number of tables in the database
List databases
Retrieve all D1 databases in your account.
for await (const database of client.d1.database.list({
account_id: '023e105f4ecef8ad9ca31a8372d0c353',
})) {
console.log(database);
}
Your Cloudflare account ID
Page number for pagination
Number of databases per page (default: 20, max: 100)
Get a database
Retrieve details about a specific database.
const database = await client.d1.database.get(
'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
{ account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);
Your Cloudflare account ID
Update a database
Update database configuration.
const database = await client.d1.database.update(
'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
{
account_id: '023e105f4ecef8ad9ca31a8372d0c353',
read_replication: {
mode: 'auto',
},
}
);
Your Cloudflare account ID
Read replication configuration
Replication mode: ‘auto’ or ‘disabled’
Delete a database
Delete a D1 database.
await client.d1.database.delete(
'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
{ account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);
The database UUID to delete
Your Cloudflare account ID
Query
Execute SQL queries against a D1 database.
Execute a query
Run a SQL query against a database.
const result = await client.d1.database.query(
'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
{
account_id: '023e105f4ecef8ad9ca31a8372d0c353',
sql: 'SELECT * FROM users WHERE id = ?',
params: ['123'],
}
);
Your Cloudflare account ID
Query parameters for prepared statements
Whether the query was successful
Query metadata including rows affected and duration
Execute raw SQL
Execute raw SQL statements.
const result = await client.d1.database.raw(
'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
{
account_id: '023e105f4ecef8ad9ca31a8372d0c353',
sql: `
CREATE TABLE users (
id INTEGER PRIMARY KEY,
name TEXT NOT NULL,
email TEXT UNIQUE
);
INSERT INTO users (name, email) VALUES ('Alice', '[email protected]');
`,
}
);
Your Cloudflare account ID
Raw SQL statements to execute
Import and export
Export database
Export a database as SQL.
const exportUrl = await client.d1.database.export(
'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
{
account_id: '023e105f4ecef8ad9ca31a8372d0c353',
output_format: 'polling',
}
);
Your Cloudflare account ID
Export format: ‘polling’ or ‘download’
URL to download the exported SQL file
Export status: ‘pending’, ‘in_progress’, or ‘complete’
Import SQL
Import SQL into a database.
const result = await client.d1.database.import(
'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
{
account_id: '023e105f4ecef8ad9ca31a8372d0c353',
sql: sqlFileContent,
}
);
Your Cloudflare account ID
Time travel
Restore a database to a previous point in time.
Get time travel bookmark
Get a bookmark for restoring the database.
const bookmark = await client.d1.database.timeTravel.getBookmark(
'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
{ account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);
Restore database
Restore a database to a specific bookmark.
const result = await client.d1.database.timeTravel.restore(
'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
{
account_id: '023e105f4ecef8ad9ca31a8372d0c353',
bookmark: 'bookmark-string',
}
);
Your Cloudflare account ID
The bookmark to restore to
Using D1 in Workers
Bind a D1 database 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: 'd1',
name: 'DB',
id: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
},
],
modules: [...],
}
);
export default {
async fetch(request, env) {
const results = await env.DB.prepare(
'SELECT * FROM users WHERE id = ?'
)
.bind(123)
.all();
return Response.json(results);
},
};