@ocap/statedb-sqlite 1.31.7 → 1.31.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/esm/kysely.d.mts CHANGED
@@ -92,8 +92,25 @@ interface SqliteConfig {
92
92
  * Disabled by default (0 / undefined).
93
93
  */
94
94
  walCheckpointIntervalMs?: number;
95
+ /**
96
+ * `PRAGMA mmap_size` in bytes, applied to every better-sqlite3 / bun:sqlite connection (readonly included).
97
+ * Memory-mapped reads skip the pread syscall + copy into the small page cache on large databases.
98
+ * SQLite clamps the value to its compile-time `SQLITE_MAX_MMAP_SIZE` (better-sqlite3 11.x: 2147418112).
99
+ * `0` disables. Falls back to the `SQLITE_STATEDB_MMAP_SIZE` env var, then 8 GiB.
100
+ * Invalid values (negative, fractional, non-numeric) are ignored with a warning.
101
+ */
102
+ mmapSize?: number;
95
103
  }
96
104
  declare function resolveWalCheckpointIntervalMs(config: SqliteConfig): number | undefined;
105
+ /** Default `PRAGMA mmap_size` (8 GiB). */
106
+ declare const DEFAULT_MMAP_SIZE: number;
107
+ /** Env var overriding the default `PRAGMA mmap_size` (bytes, `0` disables). */
108
+ declare const MMAP_SIZE_ENV = "SQLITE_STATEDB_MMAP_SIZE";
109
+ /**
110
+ * Resolve `PRAGMA mmap_size`: valid `config.mmapSize` wins, then a valid `SQLITE_STATEDB_MMAP_SIZE`, then
111
+ * `DEFAULT_MMAP_SIZE`. Invalid input never becomes `0` (an empty env var is not "disable").
112
+ */
113
+ declare function resolveMmapSize(config: SqliteConfig, env?: Record<string, string | undefined>): number;
97
114
  /**
98
115
  * Create a Kysely instance with SQLite dialect
99
116
  * Automatically uses DurableObjectSqliteDialect when `config.doStorage` is provided,
@@ -112,6 +129,11 @@ declare function resolveWalCheckpointIntervalMs(config: SqliteConfig): number |
112
129
  * ```
113
130
  */
114
131
  declare function createKysely(config: SqliteConfig): Kysely<Database>;
132
+ /**
133
+ * Open a better-sqlite3 connection and apply connection pragmas (Node.js runtime path).
134
+ * Exported so tests running under bun can exercise this path with a fake driver.
135
+ */
136
+ declare function openBetterSqlite3(BetterSqlite3: new (filename: string, options: Record<string, unknown>) => any, filename: string, config: SqliteConfig): any;
115
137
  /**
116
138
  * Get the underlying SQLite database instance from Kysely
117
139
  * Useful for executing raw SQL or pragmas
@@ -119,4 +141,4 @@ declare function createKysely(config: SqliteConfig): Kysely<Database>;
119
141
  */
120
142
  declare function getRawDatabase(db: Kysely<Database>): any;
121
143
  //#endregion
122
- export { DurableObjectSqliteDialect, DurableObjectSqliteDialectConfig, IDurableObjectSqlStorage, IDurableObjectSqlStorageCursor, SqliteConfig, createKysely, getDoStorageWriteEpoch, getRawDatabase, resolveWalCheckpointIntervalMs };
144
+ export { DEFAULT_MMAP_SIZE, DurableObjectSqliteDialect, DurableObjectSqliteDialectConfig, IDurableObjectSqlStorage, IDurableObjectSqlStorageCursor, MMAP_SIZE_ENV, SqliteConfig, createKysely, getDoStorageWriteEpoch, getRawDatabase, openBetterSqlite3, resolveMmapSize, resolveWalCheckpointIntervalMs };
package/esm/kysely.mjs CHANGED
@@ -1515,6 +1515,25 @@ function resolveWalCheckpointIntervalMs(config) {
1515
1515
  const v = config.walCheckpointIntervalMs ?? fromEnv;
1516
1516
  return Number.isFinite(v) && v > 0 ? Math.floor(v) : void 0;
1517
1517
  }
1518
+ /** Default `PRAGMA mmap_size` (8 GiB). */
1519
+ const DEFAULT_MMAP_SIZE = 8 * 1024 * 1024 * 1024;
1520
+ /** Env var overriding the default `PRAGMA mmap_size` (bytes, `0` disables). */
1521
+ const MMAP_SIZE_ENV = "SQLITE_STATEDB_MMAP_SIZE";
1522
+ function parseMmapSize(value, source) {
1523
+ if (value === void 0) return void 0;
1524
+ let n;
1525
+ if (typeof value === "number") n = value;
1526
+ else if (typeof value === "string" && /^\d+$/.test(value.trim())) n = Number(value.trim());
1527
+ if (n !== void 0 && Number.isSafeInteger(n) && n >= 0) return n;
1528
+ console.warn(`[sqlite] ignoring invalid mmap_size from ${source}: ${JSON.stringify(String(value))}`);
1529
+ }
1530
+ /**
1531
+ * Resolve `PRAGMA mmap_size`: valid `config.mmapSize` wins, then a valid `SQLITE_STATEDB_MMAP_SIZE`, then
1532
+ * `DEFAULT_MMAP_SIZE`. Invalid input never becomes `0` (an empty env var is not "disable").
1533
+ */
1534
+ function resolveMmapSize(config, env = process.env) {
1535
+ return parseMmapSize(config.mmapSize, "config.mmapSize") ?? parseMmapSize(env[MMAP_SIZE_ENV], MMAP_SIZE_ENV) ?? DEFAULT_MMAP_SIZE;
1536
+ }
1518
1537
  /**
1519
1538
  * Create a Kysely instance with SQLite dialect
1520
1539
  * Automatically uses DurableObjectSqliteDialect when `config.doStorage` is provided,
@@ -1544,21 +1563,29 @@ function createKysely(config) {
1544
1563
  const bunReq = typeof __non_webpack_require__ === "function" ? __non_webpack_require__ : typeof __require === "function" ? __require : import.meta.require;
1545
1564
  const { BunSqliteDialect } = bunReq("kysely-bun-sqlite");
1546
1565
  const { Database: BunDatabase } = bunReq("bun:sqlite");
1547
- const sqlite$1 = new BunDatabase(filename, {
1566
+ const sqlite = new BunDatabase(filename, {
1548
1567
  create: config.readonly && filename !== ":memory:" ? false : config.create !== false,
1549
1568
  readonly: config.readonly === true
1550
1569
  });
1551
1570
  if (config.walMode !== false && !config.readonly && filename !== ":memory:") {
1552
- sqlite$1.exec("PRAGMA journal_mode = WAL");
1553
- sqlite$1.exec("PRAGMA synchronous = NORMAL");
1571
+ sqlite.exec("PRAGMA journal_mode = WAL");
1572
+ sqlite.exec("PRAGMA synchronous = NORMAL");
1554
1573
  const walCp = resolveWalAutoCheckpoint(config);
1555
- if (walCp !== void 0) sqlite$1.exec(`PRAGMA wal_autocheckpoint = ${walCp}`);
1574
+ if (walCp !== void 0) sqlite.exec(`PRAGMA wal_autocheckpoint = ${walCp}`);
1556
1575
  }
1557
- sqlite$1.exec("PRAGMA foreign_keys = ON");
1558
- sqlite$1.exec("PRAGMA busy_timeout = 5000");
1559
- return new Kysely({ dialect: new BunSqliteDialect({ database: sqlite$1 }) });
1576
+ sqlite.exec("PRAGMA foreign_keys = ON");
1577
+ sqlite.exec("PRAGMA busy_timeout = 5000");
1578
+ sqlite.exec(`PRAGMA mmap_size = ${resolveMmapSize(config)}`);
1579
+ return new Kysely({ dialect: new BunSqliteDialect({ database: sqlite }) });
1560
1580
  }
1561
- const sqlite = new (__require("better-sqlite3"))(filename, {
1581
+ return new Kysely({ dialect: new SqliteDialect({ database: openBetterSqlite3(__require("better-sqlite3"), filename, config) }) });
1582
+ }
1583
+ /**
1584
+ * Open a better-sqlite3 connection and apply connection pragmas (Node.js runtime path).
1585
+ * Exported so tests running under bun can exercise this path with a fake driver.
1586
+ */
1587
+ function openBetterSqlite3(BetterSqlite3, filename, config) {
1588
+ const sqlite = new BetterSqlite3(filename, {
1562
1589
  readonly: config.readonly === true,
1563
1590
  fileMustExist: config.readonly === true || config.create === false
1564
1591
  });
@@ -1570,7 +1597,8 @@ function createKysely(config) {
1570
1597
  }
1571
1598
  sqlite.pragma("foreign_keys = ON");
1572
1599
  sqlite.pragma("busy_timeout = 5000");
1573
- return new Kysely({ dialect: new SqliteDialect({ database: sqlite }) });
1600
+ sqlite.pragma(`mmap_size = ${resolveMmapSize(config)}`);
1601
+ return sqlite;
1574
1602
  }
1575
1603
  /**
1576
1604
  * Get the underlying SQLite database instance from Kysely
@@ -1583,4 +1611,4 @@ function getRawDatabase(db) {
1583
1611
  }
1584
1612
 
1585
1613
  //#endregion
1586
- export { DurableObjectSqliteDialect, createKysely, getDoStorageWriteEpoch, getRawDatabase, resolveWalCheckpointIntervalMs };
1614
+ export { DEFAULT_MMAP_SIZE, DurableObjectSqliteDialect, MMAP_SIZE_ENV, createKysely, getDoStorageWriteEpoch, getRawDatabase, openBetterSqlite3, resolveMmapSize, resolveWalCheckpointIntervalMs };
package/lib/kysely.cjs CHANGED
@@ -1515,6 +1515,25 @@ function resolveWalCheckpointIntervalMs(config) {
1515
1515
  const v = config.walCheckpointIntervalMs ?? fromEnv;
1516
1516
  return Number.isFinite(v) && v > 0 ? Math.floor(v) : void 0;
1517
1517
  }
1518
+ /** Default `PRAGMA mmap_size` (8 GiB). */
1519
+ const DEFAULT_MMAP_SIZE = 8 * 1024 * 1024 * 1024;
1520
+ /** Env var overriding the default `PRAGMA mmap_size` (bytes, `0` disables). */
1521
+ const MMAP_SIZE_ENV = "SQLITE_STATEDB_MMAP_SIZE";
1522
+ function parseMmapSize(value, source) {
1523
+ if (value === void 0) return void 0;
1524
+ let n;
1525
+ if (typeof value === "number") n = value;
1526
+ else if (typeof value === "string" && /^\d+$/.test(value.trim())) n = Number(value.trim());
1527
+ if (n !== void 0 && Number.isSafeInteger(n) && n >= 0) return n;
1528
+ console.warn(`[sqlite] ignoring invalid mmap_size from ${source}: ${JSON.stringify(String(value))}`);
1529
+ }
1530
+ /**
1531
+ * Resolve `PRAGMA mmap_size`: valid `config.mmapSize` wins, then a valid `SQLITE_STATEDB_MMAP_SIZE`, then
1532
+ * `DEFAULT_MMAP_SIZE`. Invalid input never becomes `0` (an empty env var is not "disable").
1533
+ */
1534
+ function resolveMmapSize(config, env = process.env) {
1535
+ return parseMmapSize(config.mmapSize, "config.mmapSize") ?? parseMmapSize(env[MMAP_SIZE_ENV], MMAP_SIZE_ENV) ?? DEFAULT_MMAP_SIZE;
1536
+ }
1518
1537
  /**
1519
1538
  * Create a Kysely instance with SQLite dialect
1520
1539
  * Automatically uses DurableObjectSqliteDialect when `config.doStorage` is provided,
@@ -1544,21 +1563,29 @@ function createKysely(config) {
1544
1563
  const bunReq = typeof __non_webpack_require__ === "function" ? __non_webpack_require__ : typeof require === "function" ? require : {}.require;
1545
1564
  const { BunSqliteDialect } = bunReq("kysely-bun-sqlite");
1546
1565
  const { Database: BunDatabase } = bunReq("bun:sqlite");
1547
- const sqlite$1 = new BunDatabase(filename, {
1566
+ const sqlite = new BunDatabase(filename, {
1548
1567
  create: config.readonly && filename !== ":memory:" ? false : config.create !== false,
1549
1568
  readonly: config.readonly === true
1550
1569
  });
1551
1570
  if (config.walMode !== false && !config.readonly && filename !== ":memory:") {
1552
- sqlite$1.exec("PRAGMA journal_mode = WAL");
1553
- sqlite$1.exec("PRAGMA synchronous = NORMAL");
1571
+ sqlite.exec("PRAGMA journal_mode = WAL");
1572
+ sqlite.exec("PRAGMA synchronous = NORMAL");
1554
1573
  const walCp = resolveWalAutoCheckpoint(config);
1555
- if (walCp !== void 0) sqlite$1.exec(`PRAGMA wal_autocheckpoint = ${walCp}`);
1574
+ if (walCp !== void 0) sqlite.exec(`PRAGMA wal_autocheckpoint = ${walCp}`);
1556
1575
  }
1557
- sqlite$1.exec("PRAGMA foreign_keys = ON");
1558
- sqlite$1.exec("PRAGMA busy_timeout = 5000");
1559
- return new kysely.Kysely({ dialect: new BunSqliteDialect({ database: sqlite$1 }) });
1576
+ sqlite.exec("PRAGMA foreign_keys = ON");
1577
+ sqlite.exec("PRAGMA busy_timeout = 5000");
1578
+ sqlite.exec(`PRAGMA mmap_size = ${resolveMmapSize(config)}`);
1579
+ return new kysely.Kysely({ dialect: new BunSqliteDialect({ database: sqlite }) });
1560
1580
  }
1561
- const sqlite = new (require("better-sqlite3"))(filename, {
1581
+ return new kysely.Kysely({ dialect: new kysely.SqliteDialect({ database: openBetterSqlite3(require("better-sqlite3"), filename, config) }) });
1582
+ }
1583
+ /**
1584
+ * Open a better-sqlite3 connection and apply connection pragmas (Node.js runtime path).
1585
+ * Exported so tests running under bun can exercise this path with a fake driver.
1586
+ */
1587
+ function openBetterSqlite3(BetterSqlite3, filename, config) {
1588
+ const sqlite = new BetterSqlite3(filename, {
1562
1589
  readonly: config.readonly === true,
1563
1590
  fileMustExist: config.readonly === true || config.create === false
1564
1591
  });
@@ -1570,7 +1597,8 @@ function createKysely(config) {
1570
1597
  }
1571
1598
  sqlite.pragma("foreign_keys = ON");
1572
1599
  sqlite.pragma("busy_timeout = 5000");
1573
- return new kysely.Kysely({ dialect: new kysely.SqliteDialect({ database: sqlite }) });
1600
+ sqlite.pragma(`mmap_size = ${resolveMmapSize(config)}`);
1601
+ return sqlite;
1574
1602
  }
1575
1603
  /**
1576
1604
  * Get the underlying SQLite database instance from Kysely
@@ -1583,8 +1611,12 @@ function getRawDatabase(db) {
1583
1611
  }
1584
1612
 
1585
1613
  //#endregion
1614
+ exports.DEFAULT_MMAP_SIZE = DEFAULT_MMAP_SIZE;
1586
1615
  exports.DurableObjectSqliteDialect = DurableObjectSqliteDialect;
1616
+ exports.MMAP_SIZE_ENV = MMAP_SIZE_ENV;
1587
1617
  exports.createKysely = createKysely;
1588
1618
  exports.getDoStorageWriteEpoch = getDoStorageWriteEpoch;
1589
1619
  exports.getRawDatabase = getRawDatabase;
1620
+ exports.openBetterSqlite3 = openBetterSqlite3;
1621
+ exports.resolveMmapSize = resolveMmapSize;
1590
1622
  exports.resolveWalCheckpointIntervalMs = resolveWalCheckpointIntervalMs;
package/lib/kysely.d.cts CHANGED
@@ -92,8 +92,25 @@ interface SqliteConfig {
92
92
  * Disabled by default (0 / undefined).
93
93
  */
94
94
  walCheckpointIntervalMs?: number;
95
+ /**
96
+ * `PRAGMA mmap_size` in bytes, applied to every better-sqlite3 / bun:sqlite connection (readonly included).
97
+ * Memory-mapped reads skip the pread syscall + copy into the small page cache on large databases.
98
+ * SQLite clamps the value to its compile-time `SQLITE_MAX_MMAP_SIZE` (better-sqlite3 11.x: 2147418112).
99
+ * `0` disables. Falls back to the `SQLITE_STATEDB_MMAP_SIZE` env var, then 8 GiB.
100
+ * Invalid values (negative, fractional, non-numeric) are ignored with a warning.
101
+ */
102
+ mmapSize?: number;
95
103
  }
96
104
  declare function resolveWalCheckpointIntervalMs(config: SqliteConfig): number | undefined;
105
+ /** Default `PRAGMA mmap_size` (8 GiB). */
106
+ declare const DEFAULT_MMAP_SIZE: number;
107
+ /** Env var overriding the default `PRAGMA mmap_size` (bytes, `0` disables). */
108
+ declare const MMAP_SIZE_ENV = "SQLITE_STATEDB_MMAP_SIZE";
109
+ /**
110
+ * Resolve `PRAGMA mmap_size`: valid `config.mmapSize` wins, then a valid `SQLITE_STATEDB_MMAP_SIZE`, then
111
+ * `DEFAULT_MMAP_SIZE`. Invalid input never becomes `0` (an empty env var is not "disable").
112
+ */
113
+ declare function resolveMmapSize(config: SqliteConfig, env?: Record<string, string | undefined>): number;
97
114
  /**
98
115
  * Create a Kysely instance with SQLite dialect
99
116
  * Automatically uses DurableObjectSqliteDialect when `config.doStorage` is provided,
@@ -112,6 +129,11 @@ declare function resolveWalCheckpointIntervalMs(config: SqliteConfig): number |
112
129
  * ```
113
130
  */
114
131
  declare function createKysely(config: SqliteConfig): Kysely<Database>;
132
+ /**
133
+ * Open a better-sqlite3 connection and apply connection pragmas (Node.js runtime path).
134
+ * Exported so tests running under bun can exercise this path with a fake driver.
135
+ */
136
+ declare function openBetterSqlite3(BetterSqlite3: new (filename: string, options: Record<string, unknown>) => any, filename: string, config: SqliteConfig): any;
115
137
  /**
116
138
  * Get the underlying SQLite database instance from Kysely
117
139
  * Useful for executing raw SQL or pragmas
@@ -119,4 +141,4 @@ declare function createKysely(config: SqliteConfig): Kysely<Database>;
119
141
  */
120
142
  declare function getRawDatabase(db: Kysely<Database>): any;
121
143
  //#endregion
122
- export { DurableObjectSqliteDialect, DurableObjectSqliteDialectConfig, IDurableObjectSqlStorage, IDurableObjectSqlStorageCursor, SqliteConfig, createKysely, getDoStorageWriteEpoch, getRawDatabase, resolveWalCheckpointIntervalMs };
144
+ export { DEFAULT_MMAP_SIZE, DurableObjectSqliteDialect, DurableObjectSqliteDialectConfig, IDurableObjectSqlStorage, IDurableObjectSqlStorageCursor, MMAP_SIZE_ENV, SqliteConfig, createKysely, getDoStorageWriteEpoch, getRawDatabase, openBetterSqlite3, resolveMmapSize, resolveWalCheckpointIntervalMs };
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@ocap/statedb-sqlite",
3
3
  "description": "OCAP statedb adapter that uses SQLite as backend",
4
- "version": "1.31.7",
4
+ "version": "1.31.8",
5
5
  "author": "wangshijun <shijun@arcblock.io> (https://www.arcblock.io)",
6
6
  "bugs": {
7
7
  "url": "https://github.com/ArcBlock/blockchain/issues",
@@ -14,7 +14,7 @@
14
14
  "wangshijun <shijun@arcblock.io> (https://www.arcblock.io)"
15
15
  ],
16
16
  "devDependencies": {
17
- "@ocap/statedb-test": "1.31.7"
17
+ "@ocap/statedb-test": "1.31.8"
18
18
  },
19
19
  "homepage": "https://github.com/ArcBlock/blockchain/tree/master/statedb/sqlite",
20
20
  "keywords": [
@@ -63,12 +63,12 @@
63
63
  "clean": "rm -rf lib esm"
64
64
  },
65
65
  "dependencies": {
66
- "@arcblock/did": "1.31.7",
67
- "@arcblock/did-util": "1.31.7",
68
- "@ocap/state": "1.31.7",
69
- "@ocap/statedb": "1.31.7",
70
- "@ocap/types": "1.31.7",
71
- "@ocap/util": "1.31.7",
66
+ "@arcblock/did": "1.31.8",
67
+ "@arcblock/did-util": "1.31.8",
68
+ "@ocap/state": "1.31.8",
69
+ "@ocap/statedb": "1.31.8",
70
+ "@ocap/types": "1.31.8",
71
+ "@ocap/util": "1.31.8",
72
72
  "better-sqlite3": "^11.8.1",
73
73
  "kysely": "^0.28.14",
74
74
  "kysely-bun-sqlite": "^0.4.0",