---
title: Workers Binding API · Cloudflare D1 docs
description: You can execute SQL queries on your D1 database from a Worker using the Worker Binding API. To do this, you can perform the following steps:
lastUpdated: 2025-04-09T22:35:27.000Z
source_url:
  html: https://zt-dark-mode-changelog.preview.developers.cloudflare.com/d1/worker-api/index.md
  md: https://zt-dark-mode-changelog.preview.developers.cloudflare.com/d1/worker-api/
---

You can execute SQL queries on your D1 database from a Worker using the Worker Binding API. To do this, you can perform the following steps:

1. [Bind the D1 Database](https://developers.cloudflare.com/d1/worker-api/d1-database).
2. [Prepare a statement](https://developers.cloudflare.com/d1/worker-api/d1-database/#prepare).
3. [Run the prepared statement](https://developers.cloudflare.com/d1/worker-api/prepared-statements).
4. Analyze the [return object](https://developers.cloudflare.com/d1/worker-api/return-object) (if necessary).

Refer to the relevant sections for the API documentation.

## TypeScript support

D1 Worker Bindings API is fully-typed via the [`@cloudflare/workers-types`](https://developers.cloudflare.com/workers/languages/typescript/#typescript) package, and also supports [generic types](https://www.typescriptlang.org/docs/handbook/2/generics.html#generic-types) as part of its TypeScript API. A generic type allows you to provide an optional `type parameter` so that a function understands the type of the data it is handling.

When using the query statement methods [`D1PreparedStatement::run`](https://developers.cloudflare.com/d1/worker-api/prepared-statements/#run), [`D1PreparedStatement::raw`](https://developers.cloudflare.com/d1/worker-api/prepared-statements/#raw) and [`D1PreparedStatement::first`](https://developers.cloudflare.com/d1/worker-api/prepared-statements/#first), you can provide a type representing each database row. D1's API will [return the result object](https://developers.cloudflare.com/d1/worker-api/return-object/#d1result) with the correct type.

For example, providing an `OrderRow` type as a type parameter to [`D1PreparedStatement::run`](https://developers.cloudflare.com/d1/worker-api/prepared-statements/#run) will return a typed `Array<OrderRow>` object instead of the default `Record<string, unknown>` type:

```ts
// Row definition
type OrderRow = {
Id: string;
CustomerName: string;
OrderDate: number;
};


// Elsewhere in your application
const result = await env.MY_DB.prepare(
"SELECT Id, CustomerName, OrderDate FROM [Order] ORDER BY ShippedDate DESC LIMIT 100",
).run<OrderRow>();
```

## Type conversion

D1 automatically converts supported JavaScript (including TypeScript) types passed as parameters via the Workers Binding API to their associated D1 types. The type conversion is as follows:

| JavaScript | D1 |
| - | - |
| null | `NULL` |
| Number | `REAL` |
| Number 1 | `INTEGER` |
| String | `TEXT` |
| Boolean 2 | `INTEGER` |
| ArrayBuffer | `BLOB` |
| undefined | Not supported. Queries with `undefined` values will return a `D1_TYPE_ERROR` |

1 D1 supports 64-bit signed `INTEGER` values internally, however [BigInts](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) are not currently supported in the API yet. JavaScript integers are safe up to [`Number.MAX_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER).

2 Booleans will be cast to an `INTEGER` type where `1` is `TRUE` and `0` is `FALSE`.

## API playground

The D1 Worker Binding API playground is an `index.js` file where you can test each of the documented Worker Binding APIs for D1. The file builds from the end-state of the [Get started](https://developers.cloudflare.com/d1/get-started/#write-queries-within-your-worker) code.

You can use this alongside the API documentation to better understand how each API works.

Follow the steps to setup your API playground.

### 1. Complete the Get started tutorial

Complete the [Get started](https://developers.cloudflare.com/d1/get-started/#write-queries-within-your-worker) tutorial. Ensure you use JavaScript instead of TypeScript.

### 2. Modify the content of `index.js`

Replace the contents of your `index.js` file with the code below to view the effect of each API.

### 3. Deploy the Worker

1. Navigate to your tutorial directory you created by following step 1.

2. Run `npx wrangler deploy`.

   ```sh
   npx wrangler deploy
   ```

   ```sh
   ⛅️ wrangler 3.112.0
   --------------------


   Total Upload: 1.90 KiB / gzip: 0.59 KiB
   Your worker has access to the following bindings:
   - D1 Databases:
     - DB: DATABASE_NAME (<DATABASE_ID>)
   Uploaded WORKER_NAME (7.01 sec)
   Deployed WORKER_NAME triggers (1.25 sec)
     https://jun-d1-rr.d1-sandbox.workers.dev
   Current Version ID: VERSION_ID
   ```

3. Open a browser at the specified address.

### 4. Test the APIs

Change the URL to test the various D1 Worker Binding APIs.
