D1 Database

Manage serverless SQL databases with D1

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',
});

account_id · string · required

Your Cloudflare account ID

name · string · required

Name for the database

uuid · string

The database UUID identifier

name · string

The database name

created_at · string

ISO 8601 timestamp when the database was created

version · string

The database version

file_size · number

Database size in bytes

num_tables · number

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);
}

account_id · string · required

Your Cloudflare account ID

name · string

Filter by database name

page · number

Page number for pagination

per_page · number

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' }
);

database_id · string · required

The database UUID

account_id · string · required

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',
    },
  }
);

database_id · string · required

The database UUID

account_id · string · required

Your Cloudflare account ID

read_replication · object

Read replication configuration

read_replication.mode · string

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' }
);

database_id · string · required

The database UUID to delete

account_id · string · required

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'],
  }
);

database_id · string · required

The database UUID

account_id · string · required

Your Cloudflare account ID

sql · string · required

The SQL query to execute

params · array

Query parameters for prepared statements

results · array

Array of result rows

success · boolean

Whether the query was successful

meta · object

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', '[e-mail]');
    `,
  }
);

database_id · string · required

The database UUID

account_id · string · required

Your Cloudflare account ID

sql · string · required

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',
  }
);

database_id · string · required

The database UUID

account_id · string · required

Your Cloudflare account ID

output_format · string

Export format: ‘polling’ or ‘download’

url · string

URL to download the exported SQL file

status · string

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,
  }
);

database_id · string · required

The database UUID

account_id · string · required

Your Cloudflare account ID

sql · string · required

SQL content to import

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',
  }
);

database_id · string · required

The database UUID

account_id · string · required

Your Cloudflare account ID

bookmark · string · required

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: [...],
  }
);

Then query from your Worker:

export default {
  async fetch(request, env) {
    const results = await env.DB.prepare(
      'SELECT * FROM users WHERE id = ?'
    )
      .bind(123)
      .all();
    
    return Response.json(results);
  },
};