Skip to content

Commit a23a18b

Browse files
TrevorBurnhamaduh95
authored andcommitted
doc: explain how sqlite binds numbers and BigInts
A JavaScript number is always bound with sqlite3_bind_double(), so it is written as REAL even when it has no fractional part. A BigInt is bound with sqlite3_bind_int64() and is the way to write an INTEGER. The type conversion table listed number under both INTEGER and REAL without saying which applies when, so the rule had to be discovered by experiment. Column type affinity hides this most of the time, which is why the cases it does not cover are surprising. Comparing against a TEXT column is the worst of them: the number 3 compares as '3.0' and silently fails to match a stored '3', with no error to point at the cause. Document the rule, the reason for it, and that case, and remove number from the table's INTEGER row. Point the virtual table section's link at the new text. better-sqlite3 binds numbers the same way and has fielded the same question repeatedly (WiseLibs/better-sqlite3#165, #627, #897, #1144, #1313), each time closed as working as intended. Fixes: #63826 Refs: WiseLibs/better-sqlite3#627 Assisted-by: Claude Opus 5.5 Signed-off-by: Trevor Burnham <trevorburnham@gmail.com> PR-URL: #67424 Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com> Reviewed-By: Guilherme Araújo <arauujogui@gmail.com>
1 parent cfb5501 commit a23a18b

1 file changed

Lines changed: 50 additions & 6 deletions

File tree

‎doc/api/sqlite.md‎

Lines changed: 50 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -102,11 +102,14 @@ exception.
102102
| Storage class | JavaScript to SQLite | SQLite to JavaScript |
103103
| ------------- | --------------------------------------------------------------- | ------------------------------------- |
104104
| `NULL` | {null} or {undefined} | {null} |
105-
| `INTEGER` | {number}, {bigint}, or {boolean} | {number} or {bigint} _(configurable)_ |
105+
| `INTEGER` | {bigint} or {boolean} | {number} or {bigint} _(configurable)_ |
106106
| `REAL` | {number} | {number} |
107107
| `TEXT` | {string} | {string} |
108108
| `BLOB` | {TypedArray}, {DataView}, {ArrayBuffer}, or {SharedArrayBuffer} | {Uint8Array} |
109109

110+
A {number} is always written as `REAL`, even when it has no fractional part;
111+
see [Writing numbers and BigInts][].
112+
110113
Booleans are written as the `INTEGER` values `1` and `0`. Like any other
111114
`INTEGER` value, they are read back as {number} by default, or as {bigint}
112115
values (`1n` and `0n`) when reading BigInts is enabled. Writing a {bigint} that
@@ -124,6 +127,45 @@ option for user-defined functions. If Node.js reads an `INTEGER` value from
124127
SQLite that is outside the JavaScript [safe integer][] range, and the option to
125128
read BigInts is not enabled, then an `ERR_OUT_OF_RANGE` error will be thrown.
126129

130+
### Writing numbers and BigInts
131+
132+
A {number} is always written as `REAL`, even when it has no fractional part,
133+
because every JavaScript {number} is a double. Use a {bigint} to write
134+
`INTEGER`:
135+
136+
```js
137+
const database = new Database(':memory:');
138+
139+
console.log(database.prepare('SELECT typeof(?) AS type').get(3));
140+
// Prints: [Object: null prototype] { type: 'real' }
141+
console.log(database.prepare('SELECT typeof(?) AS type').get(3n));
142+
// Prints: [Object: null prototype] { type: 'integer' }
143+
```
144+
145+
This distinction keeps the mapping between the two languages unambiguous: it is
146+
what makes it possible to write a `REAL` such as `3.0`, which would otherwise be
147+
indistinguishable from the `INTEGER` `3`.
148+
149+
Most of the time the distinction does not matter, because a column's [type
150+
affinity][] converts the value on the way in. Writing the {number} `3` to a
151+
column declared `INTEGER` stores the `INTEGER` `3`. It matters when no affinity
152+
applies, such as a column declared `TEXT`, a column declared without a type, or
153+
an expression:
154+
155+
```js
156+
const database = new Database(':memory:');
157+
database.exec('CREATE TABLE users(id TEXT, name TEXT)');
158+
database.exec("INSERT INTO users VALUES ('3', 'Alice')");
159+
160+
const query = database.prepare('SELECT name FROM users WHERE id = ?');
161+
162+
// The number 3 is REAL, so it compares as '3.0' and does not match.
163+
console.log(query.get(3));
164+
// Prints: undefined
165+
console.log(query.get(3n));
166+
// Prints: [Object: null prototype] { name: 'Alice' }
167+
```
168+
127169
## Class: `Database`
128170

129171
<!-- YAML
@@ -916,11 +958,11 @@ in two ways:
916958
Hidden columns can be used to pass parameters to the `rows` function using
917959
table-valued function syntax (e.g., `SELECT * FROM module_name(param1, param2)`).
918960

919-
Values yielded by `rows` follow the conversion rules in [Type conversion between
920-
JavaScript and SQLite][]: a {number} is stored as `REAL` and a {bigint} is
921-
stored as `INTEGER`, regardless of the column's declared `type`. Unlike an
922-
ordinary table, a virtual table does not apply column affinity to the values it
923-
returns, so yield a {bigint} when a column needs `INTEGER` storage:
961+
Values yielded by `rows` follow the rules in [Writing numbers and BigInts][]:
962+
a {number} is stored as `REAL` and a {bigint} is stored as `INTEGER`,
963+
regardless of the column's declared `type`. Unlike an ordinary table, a virtual
964+
table does not apply column affinity to the values it returns, so yield a
965+
{bigint} when a column needs `INTEGER` storage:
924966

925967
```js
926968
db.createModule('counter', {
@@ -2105,6 +2147,7 @@ callback function to indicate what type of operation is being authorized.
21052147
[Run-Time Limits]: https://www.sqlite.org/c3ref/limit.html
21062148
[SQL injection]: https://en.wikipedia.org/wiki/SQL_injection
21072149
[Type conversion between JavaScript and SQLite]: #type-conversion-between-javascript-and-sqlite
2150+
[Writing numbers and BigInts]: #writing-numbers-and-bigints
21082151
[`'sqlite.db.query'`]: diagnostics_channel.md#event-sqlitedbquery
21092152
[`ATTACH DATABASE`]: https://www.sqlite.org/lang_attach.html
21102153
[`ERR_INVALID_STATE`]: errors.md#err_invalid_state
@@ -2165,3 +2208,4 @@ callback function to indicate what type of operation is being authorized.
21652208
[parameters are bound]: https://www.sqlite.org/c3ref/bind_blob.html
21662209
[prepared statement]: https://www.sqlite.org/c3ref/stmt.html
21672210
[safe integer]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isSafeInteger
2211+
[type affinity]: https://www.sqlite.org/datatype3.html#type_affinity

0 commit comments

Comments
 (0)