diff --git a/src/content/docs/d1/worker-api/index.mdx b/src/content/docs/d1/worker-api/index.mdx index 343460d33f248e..4263ee2b34c409 100644 --- a/src/content/docs/d1/worker-api/index.mdx +++ b/src/content/docs/d1/worker-api/index.mdx @@ -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 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 +D1 automatically converts supported JavaScript (including TypeScript) types passed as parameters via the Workers Binding API to their associated D1 types 1. +This conversion is permanent and one-way only. This means that when reading the written values back in your code, you will get the converted values rather than 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 between values that are actually stored in your database compared to values defined by your schema. +::: + +The type conversion during writes is as follows: + +| JavaScript (write) | D1 | JavaScript (read) | +| -------------------- | --------------------------- | ------------------ | +| null | `NULL` | null | +| Number | `REAL` | Number | +| Number 2 | `INTEGER` | Number | +| String | `TEXT` | String | +| Boolean 3 | `INTEGER` | Number (`0`,`1`) | +| ArrayBuffer | `BLOB` | Array 4 | +| ArrayBuffer View | `BLOB` | Array 4 | +| undefined | Not supported. 5 | - | + +1 D1 types correspond to the underlying [SQLite +types](https://www.sqlite.org/datatype3.html). + +2 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 +3 Booleans will be cast to an `INTEGER` type where `1` is `TRUE` and `0` is `FALSE`. +4 `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). + +5 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.