priv/docs/d1.md

Select File:
# D1

## Create D1 Database

**POST** `/accounts/{account_id}/d1/database`

Returns the created D1 database.

### Responses

#### 200 Returns the created D1 database's metadata

> Data is at `body["result"]`

```json
{
  "created_at": "*string*",
  "file_size": "*number*",
  "name": "*string*",
  "num_tables": "*number*",
  "read_replication": {
    "mode": "*string*"
  },
  "uuid": "*string*",
  "version": "*string*"
}
```

#### 4XX Database details response failure

```json
{
  "errors": [
    {
      "code": "*integer*",
      "message": "*string*"
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "message": "*string*"
    }
  ],
  "result": {},
  "success": "*boolean*"
}
```



## List D1 Databases

**GET** `/accounts/{account_id}/d1/database`

Returns a list of D1 databases.

### Responses

#### 200 List D1 databases response

> Data is at `body["result"]`

```json
[
  {
    "created_at": "*string*",
    "name": "*string*",
    "uuid": "*string*",
    "version": "*string*"
  }
]
```

#### 4XX List D1 databases response failure

```json
{
  "errors": [
    {
      "code": "*integer*",
      "message": "*string*"
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "message": "*string*"
    }
  ],
  "result": {},
  "success": "*boolean*"
}
```



## Update D1 Database

**PUT** `/accounts/{account_id}/d1/database/{database_id}`

Updates the specified D1 database.

### Responses

#### 200 Database details response

> Data is at `body["result"]`

```json
{
  "created_at": "*string*",
  "file_size": "*number*",
  "name": "*string*",
  "num_tables": "*number*",
  "read_replication": {
    "mode": "*string*"
  },
  "uuid": "*string*",
  "version": "*string*"
}
```

#### 4XX Update D1 database response failure

```json
{
  "errors": [
    {
      "code": "*integer*",
      "message": "*string*"
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "message": "*string*"
    }
  ],
  "result": {},
  "success": "*boolean*"
}
```



## Update D1 Database partially

**PATCH** `/accounts/{account_id}/d1/database/{database_id}`

Updates partially the specified D1 database.

### Responses

#### 200 Database details response

> Data is at `body["result"]`

```json
{
  "created_at": "*string*",
  "file_size": "*number*",
  "name": "*string*",
  "num_tables": "*number*",
  "read_replication": {
    "mode": "*string*"
  },
  "uuid": "*string*",
  "version": "*string*"
}
```

#### 4XX Update D1 database response failure

```json
{
  "errors": [
    {
      "code": "*integer*",
      "message": "*string*"
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "message": "*string*"
    }
  ],
  "result": {},
  "success": "*boolean*"
}
```



## Get D1 Database

**GET** `/accounts/{account_id}/d1/database/{database_id}`

Returns the specified D1 database.

### Responses

#### 200 Database details response

> Data is at `body["result"]`

```json
{
  "created_at": "*string*",
  "file_size": "*number*",
  "name": "*string*",
  "num_tables": "*number*",
  "read_replication": {
    "mode": "*string*"
  },
  "uuid": "*string*",
  "version": "*string*"
}
```

#### 4XX Database details response failure

```json
{
  "errors": [
    {
      "code": "*integer*",
      "message": "*string*"
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "message": "*string*"
    }
  ],
  "result": {},
  "success": "*boolean*"
}
```



## Delete D1 Database

**DELETE** `/accounts/{account_id}/d1/database/{database_id}`

Deletes the specified D1 database.

### Responses

#### 200 Delete D1 database response

> Data is at `body["result"]`

```json
{}
```

#### 4XX Delete D1 database response failure

```json
{
  "errors": [
    {
      "code": "*integer*",
      "message": "*string*"
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "message": "*string*"
    }
  ],
  "result": {},
  "success": "*boolean*"
}
```



## Export D1 Database as SQL

**POST** `/accounts/{account_id}/d1/database/{database_id}/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.


### Responses

#### 200 Polled successfully, task no longer running (errored or complete)

> Data is at `body["result"]`

```json
{
  "at_bookmark": "*string*",
  "error": "*string*",
  "messages": [
    "*string*"
  ],
  "result": {
    "filename": "*string*",
    "signed_url": "*string*"
  },
  "status": "*string*",
  "success": "*boolean*",
  "type": "*string*"
}
```

#### 202 Polled successfully, task is currently running

> Data is at `body["result"]`

```json
{
  "at_bookmark": "*string*",
  "messages": [
    "*string*"
  ],
  "status": "*string*",
  "success": "*boolean*",
  "type": "*string*"
}
```

#### 4XX Poll failed (API error)

```json
{
  "errors": [
    {
      "code": "*integer*",
      "message": "*string*"
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "message": "*string*"
    }
  ],
  "result": {},
  "success": "*boolean*"
}
```



## Import SQL into your D1 Database

**POST** `/accounts/{account_id}/d1/database/{database_id}/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.


### Responses

#### 200 Successful action. Import is either ready to start, under way, or finished (succeeded or failed).

> Data is at `body["result"]`

```json
{
  "at_bookmark": "*string*",
  "error": "*string*",
  "filename": "*string*",
  "messages": [
    "*string*"
  ],
  "result": {
    "final_bookmark": "*string*",
    "meta": {
      "changed_db": "*boolean*",
      "changes": "*number*",
      "duration": "*number*",
      "last_row_id": "*number*",
      "rows_read": "*number*",
      "rows_written": "*number*",
      "served_by_colo": "*string*",
      "served_by_primary": "*boolean*",
      "served_by_region": "*string*",
      "size_after": "*number*",
      "timings": {
        "sql_duration_ms": "*number*"
      }
    },
    "num_queries": "*number*"
  },
  "status": "*string*",
  "success": "*boolean*",
  "type": "*string*",
  "upload_url": "*string*"
}
```

#### 202 Polled successfully, task is currently running

> Data is at `body["result"]`

```json
{
  "at_bookmark": "*string*",
  "messages": [
    "*string*"
  ],
  "status": "*string*",
  "success": "*boolean*",
  "type": "*string*"
}
```

#### 4XX Poll failed (API error)

```json
{
  "errors": [
    {
      "code": "*integer*",
      "message": "*string*"
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "message": "*string*"
    }
  ],
  "result": {},
  "success": "*boolean*"
}
```



## Query D1 Database

**POST** `/accounts/{account_id}/d1/database/{database_id}/query`

Returns the query result as an object.

### Responses

#### 200 Query response

> Data is at `body["result"]`

```json
[
  {
    "meta": {
      "changed_db": "*boolean*",
      "changes": "*number*",
      "duration": "*number*",
      "last_row_id": "*number*",
      "rows_read": "*number*",
      "rows_written": "*number*",
      "served_by_colo": null,
      "served_by_primary": "*boolean*",
      "served_by_region": null,
      "size_after": "*number*",
      "timings": {
        "sql_duration_ms": null
      }
    },
    "results": [
      {}
    ],
    "success": "*boolean*"
  }
]
```

#### 4XX Query response failure

```json
{
  "errors": [
    {
      "code": "*integer*",
      "message": "*string*"
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "message": "*string*"
    }
  ],
  "result": {},
  "success": "*boolean*"
}
```



## Raw D1 Database query

**POST** `/accounts/{account_id}/d1/database/{database_id}/raw`

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

### Responses

#### 200 Raw query response

> Data is at `body["result"]`

```json
[
  {
    "meta": {
      "changed_db": "*boolean*",
      "changes": "*number*",
      "duration": "*number*",
      "last_row_id": "*number*",
      "rows_read": "*number*",
      "rows_written": "*number*",
      "served_by_colo": null,
      "served_by_primary": "*boolean*",
      "served_by_region": null,
      "size_after": "*number*",
      "timings": {
        "sql_duration_ms": null
      }
    },
    "results": {
      "columns": [
        "*string*"
      ],
      "rows": [
        [
          null
        ]
      ]
    },
    "success": "*boolean*"
  }
]
```

#### 4XX Query response failure

```json
{
  "errors": [
    {
      "code": "*integer*",
      "message": "*string*"
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "message": "*string*"
    }
  ],
  "result": {},
  "success": "*boolean*"
}
```



## Get D1 database bookmark

**GET** `/accounts/{account_id}/d1/database/{database_id}/time_travel/bookmark`

Retrieves the current bookmark, or the nearest bookmark at or before a provided timestamp.
Bookmarks can be used with the restore endpoint to revert the database to a previous point in time.


### Responses

#### 200 Bookmark retrieved successfully

> Data is at `body["result"]`

```json
{
  "bookmark": "*string*"
}
```

#### 4XX Failed to retrieve bookmark

```json
{
  "errors": [
    {
      "code": "*integer*",
      "message": "*string*"
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "message": "*string*"
    }
  ],
  "result": {},
  "success": "*boolean*"
}
```



## Restore D1 Database to a bookmark or point in time

**POST** `/accounts/{account_id}/d1/database/{database_id}/time_travel/restore`

Restores a D1 database to a previous point in time either via a bookmark or a timestamp.


### Responses

#### 200 Database restored successfully

> Data is at `body["result"]`

```json
{
  "bookmark": "*string*",
  "message": "*string*",
  "previous_bookmark": "*string*"
}
```

#### 4XX Restore operation failed

```json
{
  "errors": [
    {
      "code": "*integer*",
      "message": "*string*"
    }
  ],
  "messages": [
    {
      "code": "*integer*",
      "message": "*string*"
    }
  ],
  "result": {},
  "success": "*boolean*"
}
```