Table of Contents

Interface ID1Api

Namespace
Cloudflare.NET.Accounts.D1
Assembly
Cloudflare.NET.dll

Provides access to Cloudflare D1 database operations. D1 is Cloudflare's native serverless SQL database built on SQLite.

public interface ID1Api

Remarks

All operations are account-scoped. The account ID is configured via AccountId.

API Limits (Workers Paid plan):

  • Max databases: 50,000 per account
  • Max database size: 10 GB
  • Max account storage: 1 TB
  • Max SQL statement length: 100 KB
  • Max query duration: 30 seconds
  • Max bound parameters: 100 per query
  • Max row/string/BLOB size: 2 MB
  • Max columns per table: 100

Important: D1's REST API is best suited for administrative use as the global Cloudflare API rate limit applies. For high-throughput query access outside Workers, consider creating a proxy Worker with the D1 Worker binding.

Methods

CompleteImportAsync(string, string, string, CancellationToken)

Completes an import after uploading the SQL file.

Task<D1ImportResponse> CompleteImportAsync(string databaseId, string etag, string filename, CancellationToken cancellationToken = default)

Parameters

databaseId string

The database UUID.

etag string

The MD5 hash/ETag of the uploaded file.

filename string

The filename returned from StartImportAsync(string, string, CancellationToken).

cancellationToken CancellationToken

Cancellation token.

Returns

Task<D1ImportResponse>

Import response with bookmark for polling.

CreateAsync(string, R2LocationHint?, D1Jurisdiction?, CancellationToken)

Creates a new D1 database.

Task<D1Database> CreateAsync(string name, R2LocationHint? primaryLocationHint = null, D1Jurisdiction? jurisdiction = null, CancellationToken cancellationToken = default)

Parameters

name string

The name for the new database.

primaryLocationHint R2LocationHint?

Optional region hint for database placement.

jurisdiction D1Jurisdiction?

Optional jurisdictional restriction (overrides location hint).

cancellationToken CancellationToken

Cancellation token.

Returns

Task<D1Database>

The created database.

See Also

DeleteAsync(string, CancellationToken)

Deletes a D1 database.

Task DeleteAsync(string databaseId, CancellationToken cancellationToken = default)

Parameters

databaseId string

The database UUID to delete.

cancellationToken CancellationToken

Cancellation token.

Returns

Task

Remarks

This permanently deletes the database and all its data. The operation cannot be undone.

See Also

GetAsync(string, CancellationToken)

Gets a specific D1 database by ID.

Task<D1Database> GetAsync(string databaseId, CancellationToken cancellationToken = default)

Parameters

databaseId string

The database UUID.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<D1Database>

The database details.

See Also

ListAllAsync(ListD1DatabasesFilters?, CancellationToken)

Lists all D1 databases, automatically handling pagination.

IAsyncEnumerable<D1Database> ListAllAsync(ListD1DatabasesFilters? filters = null, CancellationToken cancellationToken = default)

Parameters

filters ListD1DatabasesFilters

Optional filters for name search.

cancellationToken CancellationToken

Cancellation token.

Returns

IAsyncEnumerable<D1Database>

An async enumerable of all databases.

ListAsync(ListD1DatabasesFilters?, CancellationToken)

Lists D1 databases in the account.

Task<PagePaginatedResult<D1Database>> ListAsync(ListD1DatabasesFilters? filters = null, CancellationToken cancellationToken = default)

Parameters

filters ListD1DatabasesFilters

Optional filters for pagination and name search.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<PagePaginatedResult<D1Database>>

A page of databases with pagination info.

See Also

PollExportAsync(string, string, CancellationToken)

Polls the status of an ongoing export operation.

Task<D1ExportResponse> PollExportAsync(string databaseId, string bookmark, CancellationToken cancellationToken = default)

Parameters

databaseId string

The database UUID.

bookmark string

The bookmark from the previous response.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<D1ExportResponse>

Export status. When complete, includes signed_url for download.

PollImportAsync(string, string, CancellationToken)

Polls the status of an ongoing import operation.

Task<D1ImportResponse> PollImportAsync(string databaseId, string bookmark, CancellationToken cancellationToken = default)

Parameters

databaseId string

The database UUID.

bookmark string

The bookmark from the previous response.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<D1ImportResponse>

Import status with progress information.

QueryAsync(string, string, IReadOnlyList<object?>?, CancellationToken)

Executes a SQL query and returns results as objects.

Task<IReadOnlyList<D1QueryResult>> QueryAsync(string databaseId, string sql, IReadOnlyList<object?>? @params = null, CancellationToken cancellationToken = default)

Parameters

databaseId string

The database UUID.

sql string

The SQL statement to execute.

params IReadOnlyList<object>

Optional parameter values for parameterized queries.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<IReadOnlyList<D1QueryResult>>

Query results with metadata.

Remarks

Use ? placeholders in SQL and provide values in params array. Multiple statements can be separated by semicolons for batch execution.

See Also

QueryAsync<TRow>(string, string, IReadOnlyList<object?>?, CancellationToken)

Executes a SQL query and returns strongly-typed results.

Task<IReadOnlyList<D1QueryResult<TRow>>> QueryAsync<TRow>(string databaseId, string sql, IReadOnlyList<object?>? @params = null, CancellationToken cancellationToken = default)

Parameters

databaseId string

The database UUID.

sql string

The SQL statement to execute.

params IReadOnlyList<object>

Optional parameter values for parameterized queries.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<IReadOnlyList<D1QueryResult<TRow>>>

Typed query results with metadata.

Type Parameters

TRow

The type to deserialize each row into.

QueryRawAsync(string, string, IReadOnlyList<object?>?, CancellationToken)

Executes a SQL query and returns results as arrays (raw format).

Task<IReadOnlyList<D1RawQueryResult>> QueryRawAsync(string databaseId, string sql, IReadOnlyList<object?>? @params = null, CancellationToken cancellationToken = default)

Parameters

databaseId string

The database UUID.

sql string

The SQL statement to execute.

params IReadOnlyList<object>

Optional parameter values for parameterized queries.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<IReadOnlyList<D1RawQueryResult>>

Raw query results with rows as arrays.

Remarks

The raw endpoint returns rows as arrays instead of objects, which is more efficient for large result sets. Column order matches the SELECT clause order.

See Also

StartExportAsync(string, D1ExportDumpOptions?, CancellationToken)

Initiates an export of the database to SQL format.

Task<D1ExportResponse> StartExportAsync(string databaseId, D1ExportDumpOptions? dumpOptions = null, CancellationToken cancellationToken = default)

Parameters

databaseId string

The database UUID.

dumpOptions D1ExportDumpOptions

Optional filtering options (schema only, data only, specific tables).

cancellationToken CancellationToken

Cancellation token.

Returns

Task<D1ExportResponse>

Initial export response with bookmark for polling.

Remarks

Export is an async operation that requires polling. Call PollExportAsync(string, string, CancellationToken) with the returned bookmark until status is "complete".

The database is unavailable for queries during export. Exports that aren't polled will auto-cancel.

See Also

StartImportAsync(string, string, CancellationToken)

Initiates an import operation by requesting an upload URL.

Task<D1ImportResponse> StartImportAsync(string databaseId, string etag, CancellationToken cancellationToken = default)

Parameters

databaseId string

The database UUID.

etag string

MD5 hash of the SQL file content.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<D1ImportResponse>

Response containing upload_url and filename for SQL file upload.

Remarks

Import workflow:

  1. Compute MD5 hash of your SQL file
  2. Call StartImportAsync(string, string, CancellationToken) with the hash to get upload URL and filename
  3. PUT your SQL file to the upload_url (verify ETag matches)
  4. Call CompleteImportAsync(string, string, string, CancellationToken) with etag and filename to start ingestion
  5. Poll with PollImportAsync(string, string, CancellationToken) until status is "complete"

The database is blocked during import operations.

See Also

UpdateAsync(string, UpdateD1DatabaseOptions, CancellationToken)

Updates a D1 database's configuration.

Task<D1Database> UpdateAsync(string databaseId, UpdateD1DatabaseOptions options, CancellationToken cancellationToken = default)

Parameters

databaseId string

The database UUID.

options UpdateD1DatabaseOptions

The update options (e.g., read replication settings).

cancellationToken CancellationToken

Cancellation token.

Returns

Task<D1Database>

The updated database.

Remarks

Use this to enable/disable read replication by setting ReadReplication.Mode to "auto" or "disabled".

See Also

See Also

https://developers.cloudflare.com/d1/
https://developers.cloudflare.com/d1/platform/limits/
Edit this page