查看“Better-sqlite3 BigInt基本类型”的源代码


SQLite3 可以存储64位有符号整数，这用 JavaScript 的 [https://en.wikipedia.org/wiki/Double-precision_floating-point_format number format] 无法完全表示。为了支持这种数据类型，<code>better-sqlite3</code> 与 [https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt BigInts] 完全兼容。

<syntaxhighlight lang="js">const big = BigInt('1152735103331642317');
big === 1152735103331642317n; // 返回 true
big.toString(); // 返回 "1152735103331642317"
typeof big; // 返回 "bigint"</syntaxhighlight>
<br>

<span id="绑定-bigints"></span>
== 绑定 BigInts ==

<code>BigInts</code> 可以像普通数字一样绑定到 <code>Statements</code>。您还可以从用户自定义函数中返回 <code>BigInts</code>。但是，如果您提供的 <code>BigInt</code> 太大而无法成为64位有符号整数，您将获得错误，从而保护数据完整性。

<syntaxhighlight lang="js">db.prepare("SELECT * FROM users WHERE id=?").get(BigInt('1152735103331642317'));
db.prepare("INSERT INTO users (id) VALUES (?)").run(BigInt('1152735103331642317'));

db.prepare("SELECT ?").get(2n ** 63n - 1n); // 成功返回
db.prepare("SELECT ?").get(2n ** 63n); // 抛出 RangeError</syntaxhighlight>
<br>

<span id="从数据库获取-bigints"></span>
== 从数据库获取 BigInts ==

默认情况下，从数据库返回的整数（包括 <code>info.lastInsertRowid</code> 属性）是普通的 JavaScript 数字。您可以随意更改此默认设置：

<syntaxhighlight lang="js">db.defaultSafeIntegers(); // 默认为 BigInts
db.defaultSafeIntegers(true); // 默认为 BigInts
db.defaultSafeIntegers(false); // 默认为 Numbers</syntaxhighlight>
<br>

此外，您可以像下面这样覆盖单个 <code>Statements</code> 的默认设置：

<syntaxhighlight lang="js">const stmt = db.prepare(SQL);

stmt.safeIntegers(); // 开启安全整数
stmt.safeIntegers(true); // 开启安全整数
stmt.safeIntegers(false); // 关闭安全整数</syntaxhighlight>
<br>

用户自定义函数可以接收 <code>BigInts</code> 作为参数。您可以像这样覆盖数据库的默认设置：

<syntaxhighlight lang="js">db.function('isInt', { safeIntegers: true }, (value) => {
  return String(typeof value === 'bigint');
});

db.prepare('SELECT isInt(?)').pluck().get(10); // => "false"
db.prepare('SELECT isInt(?)').pluck().get(10n); // => "true"</syntaxhighlight>
<br>

同样，用户自定义聚合和虚拟表也可以接收 <code>BigInts</code> 作为参数：

<syntaxhighlight lang="js">db.aggregate('addInts', {
  safeIntegers: true,
  start: 0n,
  step: (total, nextValue) => total + nextValue,
});</syntaxhighlight>
<br>

<syntaxhighlight lang="js">db.table('sequence', {
  safeIntegers: true,
  columns: ['value'],
  parameters: ['length', 'start'],
  rows: function* (length, start = 0n) {
    const end = start + length;
    for (let n = start; n < end; ++n) {
      yield { value: n };
    }
  },
});</syntaxhighlight>
<br>

值得注意的是，从数据库返回的 REAL（FLOAT）值始终表示为普通数字。

<br>