Skip to content

Extend D1 docs with clarifications for one-way type conversions #22093

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
May 1, 2025
Merged

Extend D1 docs with clarifications for one-way type conversions #22093

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e299b6e
Extend D1 docs with clarifications for one-way type conversions
lambrospetrou Apr 30, 2025
df56fe4
PCX Review
Oxyjun May 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 32 additions & 14 deletions src/content/docs/d1/worker-api/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,26 +40,44 @@ const result = await env.MY_DB.prepare(

## 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 <sup>1</sup> | `INTEGER` |
| String | `TEXT` |
| Boolean <sup>2</sup> | `INTEGER` |
| ArrayBuffer | `BLOB` |
| undefined | Not supported. Queries with `undefined` values will return a `D1_TYPE_ERROR` |

<sup>1</sup> D1 supports 64-bit signed `INTEGER` values internally, however
D1 automatically converts supported JavaScript (including TypeScript) types passed as parameters via the Workers Binding API to their associated D1 types <sup>1</sup>.
This conversion is permanent and one-way only, meaning that when reading the written values back in your code you will get the converted values and not the originally inserted values.

:::note
We recommend using [STRICT tables](https://www.sqlite.org/stricttables.html) in your SQL schema to avoid issues with mismatched types actually stored in your database compared to what your schema defines.
:::

The type conversion during writes is as follows:

| JavaScript (write) | D1 | JavaScript (read) |
| -------------------- | --------------------------- | ------------------ |
| null | `NULL` | null |
| Number | `REAL` | Number |
| Number <sup>2</sup> | `INTEGER` | Number |
| String | `TEXT` | String |
| Boolean <sup>3</sup> | `INTEGER` | Number (`0`,`1`) |
| ArrayBuffer | `BLOB` | Array <sup>4</sup> |
| ArrayBuffer View | `BLOB` | Array <sup>4</sup> |
| undefined | Not supported. <sup>5</sup> | - |

<sup>1</sup> D1 types correspond to the underlying [SQLite
Copy link
Contributor Author

@lambrospetrou lambrospetrou Apr 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Oxyjun How can we make the footnotes to show on hover? I assume there is some component we can migrate too?

Feel free to checkout and edit this PR directly, BTW.

Copy link
Contributor

@Oxyjun Oxyjun May 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll tackle the footnotes in a separate PR across all the pages. For reference though, this is how the hover footnote works:

Text [^1]

[^1]: Footnote

https://developers.cloudflare.com/style-guide/components/footnotes/

types](https://www.sqlite.org/datatype3.html).

<sup>2</sup> 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).

<sup>2</sup> Booleans will be cast to an `INTEGER` type where `1` is `TRUE` and
<sup>3</sup> Booleans will be cast to an `INTEGER` type where `1` is `TRUE` and
`0` is `FALSE`.

<sup>4</sup> `ArrayBuffer` and [`ArrayBuffer`
views](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer/isView)
are converted using
[`Array.from`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from).

<sup>5</sup> Queries with `undefined` values will return a `D1_TYPE_ERROR`.

## 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](/d1/get-started/#write-queries-within-your-worker) code.
Expand Down
Loading