database

Creates, updates, deletes, gets or lists a database resource.

Overview

Name	database
Type	Resource
Id	cloudflare.d1.database

Fields

The following fields are returned by SELECT queries:

get

Database details response

Name	Datatype	Description
name	string	D1 database name. (example: my-database)
created_at	string (date-time)	Specifies the timestamp the resource was created as an ISO8601 string. (example: 2022-11-15T18:25:44.442097Z)
file_size	number	The D1 database's size, in bytes.
jurisdiction	string	Specify the location to restrict the D1 database to run and store data. If this option is present, the location hint is ignored. (eu, fedramp) (example: eu)
num_tables	number
read_replication	object	Configuration for D1 read replication.
uuid	string	D1 database identifier (UUID). (example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
version	string	(example: production)

list

List D1 databases response

Name	Datatype	Description
name	string	D1 database name. (example: my-database)
created_at	string (date-time)	Specifies the timestamp the resource was created as an ISO8601 string. (example: 2022-11-15T18:25:44.442097Z)
jurisdiction	string	Specify the location to restrict the D1 database to run and store data. If this option is present, the location hint is ignored. (eu, fedramp) (example: eu)
uuid	string	D1 database identifier (UUID). (example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
version	string	(example: production)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	account_id, database_id		Returns the specified D1 database.
list	select	account_id	name, page, per_page	Returns a list of D1 databases.
create	insert	account_id, name		Returns the created D1 database.
edit	update	account_id, database_id		Updates partially the specified D1 database.
update	replace	account_id, database_id, read_replication		Updates the specified D1 database.
delete	delete	account_id, database_id		Deletes the specified D1 database.
export	exec	account_id, database_id, output_format		Returns a URL where the SQL contents of your D1 can be downloaded. Note: this process may take some time for larger DBs, during which your D1 will be unavailable to serve queries. To avoid blocking your DB unnecessarily, an in-progress export must be continually polled or will automatically cancel.
import	exec	account_id, database_id, action		Generates a temporary URL for uploading an SQL file to, then instructing the D1 to import it and polling it for status updates. Imports block the D1 for their duration.
create_raw	exec	account_id, database_id		Returns the query result rows as arrays rather than objects. This is a performance-optimized version of the /query endpoint.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
account_id	string	The Cloudflare account ID.
database_id	string	The D1 database ID.
name	string
page	number
per_page	number

SELECT examples

get

Returns the specified D1 database.

SELECT
name,
created_at,
file_size,
jurisdiction,
num_tables,
read_replication,
uuid,
version
FROM cloudflare.d1.database
WHERE account_id = '{{ account_id }}' -- required
AND database_id = '{{ database_id }}' -- required
;

list

Returns a list of D1 databases.

SELECT
name,
created_at,
jurisdiction,
uuid,
version
FROM cloudflare.d1.database
WHERE account_id = '{{ account_id }}' -- required
AND name = '{{ name }}'
AND page = '{{ page }}'
AND per_page = '{{ per_page }}'
;

INSERT examples

create

Returns the created D1 database.

INSERT INTO cloudflare.d1.database (
jurisdiction,
name,
primary_location_hint,
account_id
)
SELECT 
'{{ jurisdiction }}',
'{{ name }}' /* required */,
'{{ primary_location_hint }}',
'{{ account_id }}'
RETURNING
errors,
messages,
result,
success
;

Manifest

# Description fields are for documentation purposes
- name: database
props:
  - name: account_id
    value: "{{ account_id }}"
    description: Required parameter for the database resource.
  - name: jurisdiction
    value: "{{ jurisdiction }}"
    description: |
      Specify the location to restrict the D1 database to run and store data. If this option is present, the location hint is ignored.
    valid_values: ['eu', 'fedramp']
  - name: name
    value: "{{ name }}"
    description: |
      D1 database name.
  - name: primary_location_hint
    value: "{{ primary_location_hint }}"
    description: |
      Specify the region to create the D1 primary, if available. If this option is omitted, the D1 will be created as close as possible to the current user.
    valid_values: ['wnam', 'enam', 'weur', 'eeur', 'apac', 'oc']

UPDATE examples

edit

Updates partially the specified D1 database.

UPDATE cloudflare.d1.database
SET 
read_replication = '{{ read_replication }}'
WHERE 
account_id = '{{ account_id }}' --required
AND database_id = '{{ database_id }}' --required
RETURNING
errors,
messages,
result,
success;

REPLACE examples

update

Updates the specified D1 database.

REPLACE cloudflare.d1.database
SET 
read_replication = '{{ read_replication }}'
WHERE 
account_id = '{{ account_id }}' --required
AND database_id = '{{ database_id }}' --required
AND read_replication = '{{ read_replication }}' --required
RETURNING
errors,
messages,
result,
success;

DELETE examples

delete

Deletes the specified D1 database.

DELETE FROM cloudflare.d1.database
WHERE account_id = '{{ account_id }}' --required
AND database_id = '{{ database_id }}' --required
;

Lifecycle Methods

export

Returns a URL where the SQL contents of your D1 can be downloaded. Note: this process may take some time for larger DBs, during which your D1 will be unavailable to serve queries. To avoid blocking your DB unnecessarily, an in-progress export must be continually polled or will automatically cancel.

EXEC cloudflare.d1.database.export 
@account_id='{{ account_id }}' --required, 
@database_id='{{ database_id }}' --required 
@@json=
'{
"current_bookmark": "{{ current_bookmark }}", 
"dump_options": "{{ dump_options }}", 
"output_format": "{{ output_format }}"
}'
;

import

Generates a temporary URL for uploading an SQL file to, then instructing the D1 to import it and polling it for status updates. Imports block the D1 for their duration.

EXEC cloudflare.d1.database.import 
@account_id='{{ account_id }}' --required, 
@database_id='{{ database_id }}' --required 
@@json=
'{
"action": "{{ action }}", 
"etag": "{{ etag }}", 
"filename": "{{ filename }}", 
"current_bookmark": "{{ current_bookmark }}"
}'
;

create_raw

Returns the query result rows as arrays rather than objects. This is a performance-optimized version of the /query endpoint.

EXEC cloudflare.d1.database.create_raw 
@account_id='{{ account_id }}' --required, 
@database_id='{{ database_id }}' --required 
@@json=
'{
"params": "{{ params }}", 
"sql": "{{ sql }}", 
"batch": "{{ batch }}"
}'
;