Class D1Api
- Namespace
- Cloudflare.NET.Accounts.D1
- Assembly
- Cloudflare.NET.dll
Implementation of Cloudflare D1 Database API operations.
public class D1Api : ApiResource, ID1Api- Inheritance
-
D1Api
- Implements
- Inherited Members
Remarks
D1 is Cloudflare's native serverless SQL database built on SQLite. All operations are account-scoped, using the account ID from configuration.
The REST API is subject to global Cloudflare API rate limits and is best suited for administrative operations. For high-throughput query access outside Workers, consider creating a proxy Worker with D1 Worker bindings.
Constructors
D1Api(HttpClient, IOptions<CloudflareApiOptions>, ILoggerFactory)
Initializes a new instance of the D1Api class.
public D1Api(HttpClient httpClient, IOptions<CloudflareApiOptions> options, ILoggerFactory loggerFactory)Parameters
httpClientHttpClientThe HttpClient for making requests.
optionsIOptions<CloudflareApiOptions>The Cloudflare API options containing the account ID.
loggerFactoryILoggerFactoryThe factory to create loggers.
Methods
CompleteImportAsync(string, string, string, CancellationToken)
Completes an import after uploading the SQL file.
public Task<D1ImportResponse> CompleteImportAsync(string databaseId, string etag, string filename, CancellationToken cancellationToken = default)Parameters
databaseIdstringThe database UUID.
etagstringThe MD5 hash/ETag of the uploaded file.
filenamestringThe filename returned from StartImportAsync(string, string, CancellationToken).
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<D1ImportResponse>
Import response with bookmark for polling.
CreateAsync(string, R2LocationHint?, D1Jurisdiction?, CancellationToken)
Creates a new D1 database.
public Task<D1Database> CreateAsync(string name, R2LocationHint? primaryLocationHint = null, D1Jurisdiction? jurisdiction = null, CancellationToken cancellationToken = default)Parameters
namestringThe name for the new database.
primaryLocationHintR2LocationHint?Optional region hint for database placement.
jurisdictionD1Jurisdiction?Optional jurisdictional restriction (overrides location hint).
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<D1Database>
The created database.
- See Also
DeleteAsync(string, CancellationToken)
Deletes a D1 database.
public Task DeleteAsync(string databaseId, CancellationToken cancellationToken = default)Parameters
databaseIdstringThe database UUID to delete.
cancellationTokenCancellationTokenCancellation token.
Returns
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.
public Task<D1Database> GetAsync(string databaseId, CancellationToken cancellationToken = default)Parameters
databaseIdstringThe database UUID.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<D1Database>
The database details.
- See Also
ListAllAsync(ListD1DatabasesFilters?, CancellationToken)
Lists all D1 databases, automatically handling pagination.
public IAsyncEnumerable<D1Database> ListAllAsync(ListD1DatabasesFilters? filters = null, CancellationToken cancellationToken = default)Parameters
filtersListD1DatabasesFiltersOptional filters for name search.
cancellationTokenCancellationTokenCancellation token.
Returns
- IAsyncEnumerable<D1Database>
An async enumerable of all databases.
Remarks
The D1 API returns total_count=0 and total_pages=0 in the pagination info, which is
inconsistent with the standard Cloudflare API schema. To work around this limitation, this implementation
checks if the current page is full (item count equals PerPage) to determine if there are more pages.
ListAsync(ListD1DatabasesFilters?, CancellationToken)
Lists D1 databases in the account.
public Task<PagePaginatedResult<D1Database>> ListAsync(ListD1DatabasesFilters? filters = null, CancellationToken cancellationToken = default)Parameters
filtersListD1DatabasesFiltersOptional filters for pagination and name search.
cancellationTokenCancellationTokenCancellation 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.
public Task<D1ExportResponse> PollExportAsync(string databaseId, string bookmark, CancellationToken cancellationToken = default)Parameters
databaseIdstringThe database UUID.
bookmarkstringThe bookmark from the previous response.
cancellationTokenCancellationTokenCancellation 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.
public Task<D1ImportResponse> PollImportAsync(string databaseId, string bookmark, CancellationToken cancellationToken = default)Parameters
databaseIdstringThe database UUID.
bookmarkstringThe bookmark from the previous response.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<D1ImportResponse>
Import status with progress information.
QueryAsync(string, string, IReadOnlyList<object?>?, CancellationToken)
Executes a SQL query and returns results as objects.
public Task<IReadOnlyList<D1QueryResult>> QueryAsync(string databaseId, string sql, IReadOnlyList<object?>? @params = null, CancellationToken cancellationToken = default)Parameters
databaseIdstringThe database UUID.
sqlstringThe SQL statement to execute.
paramsIReadOnlyList<object>Optional parameter values for parameterized queries.
cancellationTokenCancellationTokenCancellation 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.
public Task<IReadOnlyList<D1QueryResult<TRow>>> QueryAsync<TRow>(string databaseId, string sql, IReadOnlyList<object?>? @params = null, CancellationToken cancellationToken = default)Parameters
databaseIdstringThe database UUID.
sqlstringThe SQL statement to execute.
paramsIReadOnlyList<object>Optional parameter values for parameterized queries.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<IReadOnlyList<D1QueryResult<TRow>>>
Typed query results with metadata.
Type Parameters
TRowThe type to deserialize each row into.
QueryRawAsync(string, string, IReadOnlyList<object?>?, CancellationToken)
Executes a SQL query and returns results as arrays (raw format).
public Task<IReadOnlyList<D1RawQueryResult>> QueryRawAsync(string databaseId, string sql, IReadOnlyList<object?>? @params = null, CancellationToken cancellationToken = default)Parameters
databaseIdstringThe database UUID.
sqlstringThe SQL statement to execute.
paramsIReadOnlyList<object>Optional parameter values for parameterized queries.
cancellationTokenCancellationTokenCancellation 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.
public Task<D1ExportResponse> StartExportAsync(string databaseId, D1ExportDumpOptions? dumpOptions = null, CancellationToken cancellationToken = default)Parameters
databaseIdstringThe database UUID.
dumpOptionsD1ExportDumpOptionsOptional filtering options (schema only, data only, specific tables).
cancellationTokenCancellationTokenCancellation 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.
public Task<D1ImportResponse> StartImportAsync(string databaseId, string etag, CancellationToken cancellationToken = default)Parameters
databaseIdstringThe database UUID.
etagstringMD5 hash of the SQL file content.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<D1ImportResponse>
Response containing upload_url and filename for SQL file upload.
Remarks
Import workflow:
- Compute MD5 hash of your SQL file
- Call StartImportAsync(string, string, CancellationToken) with the hash to get upload URL and filename
- PUT your SQL file to the upload_url (verify ETag matches)
- Call CompleteImportAsync(string, string, string, CancellationToken) with etag and filename to start ingestion
- 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.
public Task<D1Database> UpdateAsync(string databaseId, UpdateD1DatabaseOptions options, CancellationToken cancellationToken = default)Parameters
databaseIdstringThe database UUID.
optionsUpdateD1DatabaseOptionsThe update options (e.g., read replication settings).
cancellationTokenCancellationTokenCancellation 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