@zukhruf/sqlite-snapshot 0.6.13 → 0.6.15

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/README.md CHANGED
@@ -2,6 +2,8 @@
2
2
 
3
3
  Some programs keep their data in a SQLite database, and write it while they run. Another program can read that database, but the reader must not see half of a change. For example, it must not read a row from one table before a commit and a row from another table after it. Also, the newest rows can be in the WAL file, not in the database file. This package opens such a database read-only, and holds one moment with a read transaction. Thus each query of the snapshot sees the same moment, and the tables agree. This is also known as snapshot isolation of a WAL reader.
4
4
 
5
+ Some owners let no reader in. Chromium holds its History with SQLite's exclusive locking mode, so a read fails with "database is locked". `Snapshot.ofExclusiveOwner` reads such a database from a checked copy at the last commit of the owner.
6
+
5
7
  The words in these documents have one meaning each. See the glossary in [CONTEXT.md](./CONTEXT.md).
6
8
 
7
9
  ## Use it
@@ -67,26 +69,57 @@ true
67
69
  - The package throws its own errors: `UnavailableError` and `MissingColumnsError`. `UnavailableError` is the class of `@zukhruf/sqlite-reader`, which opens the connection. The package exports it, so a catch with `instanceof` works with either package. A host that needs its own error translates the error of the package at its boundary, and keeps the error of the package as `cause`. [ADR 0002](./docs/adr/0002-the-package-throws-its-own-errors.md) tells why.
68
70
  - Dispose commits the read transaction and closes the connection. A second dispose does nothing.
69
71
 
72
+ ## An owner that lets no reader in
73
+
74
+ An exclusive owner holds SQLite's exclusive locking mode. It takes the lock at its first write and keeps it until it closes the database. Chrome, Edge, Brave, Arc and Dia hold their History this way. `new Snapshot(path)` then fails with `SQLITE_BUSY` (5). Read the database with `Snapshot.ofExclusiveOwner(path)`:
75
+
76
+ ```ts
77
+ import { DatabaseChangingError, Snapshot } from '@zukhruf/sqlite-snapshot';
78
+
79
+ try {
80
+ using history = await Snapshot.ofExclusiveOwner(path);
81
+ history.requireColumns({ urls: ['id', 'url', 'title'] });
82
+ for (const row of history.iterate('SELECT id, url, title FROM urls'))
83
+ console.log(row.url);
84
+ } catch (error) {
85
+ if (!(error instanceof DatabaseChangingError)) throw error;
86
+ console.log('The owner kept writing. Read it again later.');
87
+ }
88
+ ```
89
+
90
+ - The snapshot reads an owner copy: a clone of the database and its rollback journal in a private folder. APFS and Btrfs clone a file with no time and no space. Other file systems copy the bytes.
91
+ - The file stamps of the database and the journal must be the same before and after the copy. When the owner wrote during the copy, the snapshot tries again at once, up to 5 times. Then it throws `DatabaseChangingError`.
92
+ - The snapshot opens the copy for writing one time, so that SQLite rolls back a hot journal in the copy. The snapshot holds the last commit of the owner, and no page of a transaction that the owner did not commit.
93
+ - The snapshot never writes a file of the owner. A journal that a dead owner left stays as it is.
94
+ - Dispose deletes the copy. Dispose the snapshot as soon as the read ends.
95
+ - `MissingColumnsError` and `UnavailableError` name the path of the owner, not the copy.
96
+
97
+ [ADR 0003](./docs/adr/0003-an-exclusive-owner-is-read-from-a-checked-copy.md) tells why.
98
+
70
99
  ## Errors
71
100
 
72
- | Error | When |
73
- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
74
- | `UnavailableError` | SQLite cannot open the file: `SQLITE_CANTOPEN` (14), for a missing file or a file that the system denies, a privacy denial too. `path` is the path. `cause` is the error of SQLite. |
75
- | `MissingColumnsError` | `requireColumns` finds a missing column. `path` is the path, and `missing` gives each missing column as `table.column`. The snapshot is closed. |
76
- | The error of SQLite | All other failures, for example a file that is not a database. The constructor closes the connection before it throws. |
101
+ | Error | When |
102
+ | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
103
+ | `UnavailableError` | SQLite cannot open the file: `SQLITE_CANTOPEN` (14), for a missing file or a file that the system denies, a privacy denial too. `path` is the path. `cause` is the error of SQLite. `ofExclusiveOwner` throws it when it cannot copy the file (`ENOENT`, `EACCES`, `EPERM`); then `cause` is the error of the file system. |
104
+ | `MissingColumnsError` | `requireColumns` finds a missing column. `path` is the path, and `missing` gives each missing column as `table.column`. The snapshot is closed. |
105
+ | `DatabaseChangingError` | `ofExclusiveOwner` found a write of the owner during each of 5 copies. `path` is the path, and `attempts` is the number of copies. No copy stays. |
106
+ | The error of SQLite | All other failures, for example a file that is not a database. The constructor closes the connection before it throws. |
77
107
 
78
108
  ## The same concepts in other systems
79
109
 
80
- | System | What it does |
81
- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
82
- | SQLite WAL readers | A read transaction sees the database as it was at its first read, also while a writer commits. An open read stops the checkpoint at its end mark. See "Write-Ahead Logging" in the SQLite documentation. |
83
- | Datasette `immutable` mode | It opens a file with `immutable=1`, for a file that nobody writes. SQLite then skips the locks and the WAL. This package is the opposite case: the owner writes the file. |
84
- | `sqlite3 -readonly` | It opens a database read-only. Each statement outside a transaction can see a different moment. |
110
+ | System | What it does |
111
+ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
112
+ | SQLite WAL readers | A read transaction sees the database as it was at its first read, also while a writer commits. An open read stops the checkpoint at its end mark. See "Write-Ahead Logging" in the SQLite documentation. |
113
+ | Datasette `immutable` mode | It opens a file with `immutable=1`, for a file that nobody writes. SQLite then skips the locks and the WAL. This package is the opposite case: the owner writes the file. |
114
+ | `sqlite3 -readonly` | It opens a database read-only. Each statement outside a transaction can see a different moment. |
115
+ | Chromium `sql::Database` | It opens each database with the exclusive locking mode, as `exclusive_locking_ = true` in `sql/database.h`. No other process can read the database while the browser runs. |
116
+ | yt-dlp `_open_database_copy` | It copies the cookie database of a running Chromium and reads the copy. It copies the database file only, with no check. |
85
117
 
86
118
  ## Documentation
87
119
 
88
120
  - [0001 Never immutable, and held only while reading](./docs/adr/0001-never-immutable-and-held-only-while-reading.md)
89
121
  - [0002 The package throws its own errors](./docs/adr/0002-the-package-throws-its-own-errors.md)
122
+ - [0003 An exclusive owner is read from a checked copy](./docs/adr/0003-an-exclusive-owner-is-read-from-a-checked-copy.md)
90
123
 
91
124
  ## Development
92
125
 
@@ -101,8 +134,11 @@ npx nx run sqlite-snapshot:build # compiles src/ to dist/
101
134
 
102
135
  ```
103
136
  src/
104
- index.ts the exports
105
- snapshot.ts Snapshot and SnapshotColumns
106
- missing-columns-error.ts MissingColumnsError
107
- snapshot.test.ts the tests, on real SQLite files
137
+ index.ts the exports
138
+ snapshot.ts Snapshot and SnapshotColumns
139
+ owner-copy.ts the checked copy of an exclusive owner
140
+ missing-columns-error.ts MissingColumnsError
141
+ database-changing-error.ts DatabaseChangingError
142
+ snapshot.test.ts the tests, on real SQLite files
143
+ exclusive-owner.test.ts the tests, with an owner in another process
108
144
  ```
@@ -0,0 +1,7 @@
1
+ /** The owner wrote the database while each copy of it was taken. */
2
+ export declare class DatabaseChangingError extends Error {
3
+ readonly path: string;
4
+ readonly attempts: number;
5
+ constructor(path: string, attempts: number);
6
+ }
7
+ //# sourceMappingURL=database-changing-error.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"database-changing-error.d.ts","sourceRoot":"","sources":["../src/database-changing-error.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAQ3C"}
@@ -0,0 +1,12 @@
1
+ /** The owner wrote the database while each copy of it was taken. */
2
+ export class DatabaseChangingError extends Error {
3
+ path;
4
+ attempts;
5
+ constructor(path, attempts) {
6
+ super(`The owner of the database at ${JSON.stringify(path)} wrote it while each of ${attempts} copies was taken. Read it again later.`);
7
+ this.name = 'DatabaseChangingError';
8
+ this.path = path;
9
+ this.attempts = attempts;
10
+ }
11
+ }
12
+ //# sourceMappingURL=database-changing-error.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"database-changing-error.js","sourceRoot":"","sources":["../src/database-changing-error.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IACrC,IAAI,CAAS;IACb,QAAQ,CAAS;IAE1B,YAAY,IAAY,EAAE,QAAgB;QACxC,KAAK,CACH,gCAAgC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,2BAA2B,QAAQ,yCAAyC,CACjI,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF"}
package/dist/index.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ export { DatabaseChangingError } from './database-changing-error.ts';
1
2
  export { MissingColumnsError } from './missing-columns-error.ts';
2
3
  export { Snapshot, type SnapshotColumns } from './snapshot.ts';
3
4
  export { UnavailableError } from '@zukhruf/sqlite-reader';
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC"}
package/dist/index.js CHANGED
@@ -1,3 +1,4 @@
1
+ export { DatabaseChangingError } from "./database-changing-error.js";
1
2
  export { MissingColumnsError } from "./missing-columns-error.js";
2
3
  export { Snapshot } from "./snapshot.js";
3
4
  export { UnavailableError } from '@zukhruf/sqlite-reader';
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,QAAQ,EAAwB,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,QAAQ,EAAwB,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC"}
@@ -0,0 +1,16 @@
1
+ /**
2
+ * A private copy of a database whose owner holds SQLite's exclusive locking
3
+ * mode, at the last commit of the owner. The copy holds the database and its
4
+ * rollback journal as they were at one moment: the stamps of both files are
5
+ * the same before and after the copy, so the owner wrote neither while it was
6
+ * taken. Opened once for writing, SQLite rolls back a hot journal in the
7
+ * copy, never in the owner's files.
8
+ */
9
+ export declare class OwnerCopy implements Disposable {
10
+ #private;
11
+ readonly file: string;
12
+ private constructor();
13
+ static take(path: string): Promise<OwnerCopy>;
14
+ [Symbol.dispose](): void;
15
+ }
16
+ //# sourceMappingURL=owner-copy.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"owner-copy.d.ts","sourceRoot":"","sources":["../src/owner-copy.ts"],"names":[],"mappings":"AAyBA;;;;;;;GAOG;AACH,qBAAa,SAAU,YAAW,UAAU;;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAGtB,OAAO;WAKM,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IA+CnD,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAGzB"}
@@ -0,0 +1,92 @@
1
+ import { constants, rmSync } from 'node:fs';
2
+ import { copyFile, mkdtemp, rm } from 'node:fs/promises';
3
+ import { tmpdir } from 'node:os';
4
+ import { basename, join } from 'node:path';
5
+ import { DatabaseSync } from 'node:sqlite';
6
+ import { FileStamps, isErrno } from '@zukhruf/fs';
7
+ import { UnavailableError } from '@zukhruf/sqlite-reader';
8
+ import { DatabaseChangingError } from "./database-changing-error.js";
9
+ // Tries at once, without a wait: a commit writes the journal and the database
10
+ // with syncs between them, so the next copy lands in a quiet moment.
11
+ const attempts = 5;
12
+ // A missing file, or one this process may not read: EACCES for its mode,
13
+ // EPERM for the privacy controls of macOS.
14
+ const unreadable = (error) => ['ENOENT', 'EACCES', 'EPERM'].some((code) => isErrno(error, code));
15
+ // A clone where the file system can make one, as APFS and Btrfs can: it takes
16
+ // no time and no space. Elsewhere, a copy of the bytes.
17
+ const clone = (from, to) => copyFile(from, to, constants.COPYFILE_FICLONE);
18
+ /**
19
+ * A private copy of a database whose owner holds SQLite's exclusive locking
20
+ * mode, at the last commit of the owner. The copy holds the database and its
21
+ * rollback journal as they were at one moment: the stamps of both files are
22
+ * the same before and after the copy, so the owner wrote neither while it was
23
+ * taken. Opened once for writing, SQLite rolls back a hot journal in the
24
+ * copy, never in the owner's files.
25
+ */
26
+ export class OwnerCopy {
27
+ file;
28
+ #folder;
29
+ constructor(folder, file) {
30
+ this.#folder = folder;
31
+ this.file = file;
32
+ }
33
+ static async take(path) {
34
+ const folder = await mkdtemp(join(tmpdir(), 'zukhruf-snapshot-'));
35
+ const copy = new OwnerCopy(folder, join(folder, basename(path)));
36
+ try {
37
+ await copy.#fill(path);
38
+ return copy;
39
+ }
40
+ catch (error) {
41
+ copy[Symbol.dispose]();
42
+ throw error;
43
+ }
44
+ }
45
+ async #fill(path) {
46
+ const files = [path, `${path}-journal`];
47
+ const stamps = () => FileStamps.read(files).catch((cause) => {
48
+ if (unreadable(cause))
49
+ throw new UnavailableError(path, cause);
50
+ throw cause;
51
+ });
52
+ for (let attempt = 0; attempt < attempts; attempt++) {
53
+ const before = await stamps();
54
+ await this.#copy(path);
55
+ if ((await stamps()).equals(before)) {
56
+ rollBack(this.file);
57
+ return;
58
+ }
59
+ }
60
+ throw new DatabaseChangingError(path, attempts);
61
+ }
62
+ async #copy(path) {
63
+ const journal = `${this.file}-journal`;
64
+ await rm(this.file, { force: true });
65
+ await rm(journal, { force: true });
66
+ try {
67
+ await clone(path, this.file);
68
+ }
69
+ catch (cause) {
70
+ if (unreadable(cause))
71
+ throw new UnavailableError(path, cause);
72
+ throw cause;
73
+ }
74
+ try {
75
+ await clone(`${path}-journal`, journal);
76
+ }
77
+ catch (cause) {
78
+ if (!isErrno(cause, 'ENOENT'))
79
+ throw cause;
80
+ }
81
+ }
82
+ [Symbol.dispose]() {
83
+ rmSync(this.#folder, { recursive: true, force: true });
84
+ }
85
+ }
86
+ // A first read through a connection that may write rolls back a hot journal,
87
+ // so the copy holds the last commit and no part of an open transaction.
88
+ function rollBack(file) {
89
+ using database = new DatabaseSync(file);
90
+ database.prepare('SELECT 1 FROM sqlite_schema LIMIT 1').get();
91
+ }
92
+ //# sourceMappingURL=owner-copy.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"owner-copy.js","sourceRoot":"","sources":["../src/owner-copy.ts"],"names":[],"mappings":"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"}
@@ -1,9 +1,11 @@
1
1
  import type { SQLInputValue, SQLOutputValue } from 'node:sqlite';
2
+ import { OwnerCopy } from './owner-copy.ts';
2
3
  export type SnapshotColumns = Readonly<Record<string, readonly string[]>>;
3
4
  export declare class Snapshot implements Disposable {
4
5
  #private;
5
6
  readonly path: string;
6
- constructor(path: string);
7
+ constructor(path: string, copy?: OwnerCopy);
8
+ static ofExclusiveOwner(path: string): Promise<Snapshot>;
7
9
  requireColumns(columns: SnapshotColumns): void;
8
10
  missingColumns(columns: SnapshotColumns): string[];
9
11
  all(sql: string, ...parameters: SQLInputValue[]): Record<string, SQLOutputValue>[];
@@ -1 +1 @@
1
- {"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAO/E,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;AAO1E,qBAAa,QAAS,YAAW,UAAU;;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAGV,IAAI,EAAE,MAAM;IAgBxB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAU9C,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,EAAE;IAalD,GAAG,CACD,GAAG,EAAE,MAAM,EACX,GAAG,UAAU,EAAE,aAAa,EAAE,GAC7B,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,EAAE;IAKnC,OAAO,CACL,GAAG,EAAE,MAAM,EACX,GAAG,UAAU,EAAE,aAAa,EAAE,GAC7B,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,EAAE,SAAS,CAAC;IAI5D,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAKzB"}
1
+ {"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAK/E,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG5C,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;AAO1E,qBAAa,QAAS,YAAW,UAAU;;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAKV,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,SAAS;WAmB7B,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAM9D,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAU9C,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,EAAE;IAalD,GAAG,CACD,GAAG,EAAE,MAAM,EACX,GAAG,UAAU,EAAE,aAAa,EAAE,GAC7B,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,EAAE;IAKnC,OAAO,CACL,GAAG,EAAE,MAAM,EACX,GAAG,UAAU,EAAE,aAAa,EAAE,GAC7B,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,EAAE,SAAS,CAAC;IAI5D,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAOzB"}
package/dist/snapshot.js CHANGED
@@ -1,5 +1,6 @@
1
1
  import { openReader } from '@zukhruf/sqlite-reader';
2
2
  import { MissingColumnsError } from "./missing-columns-error.js";
3
+ import { OwnerCopy } from "./owner-copy.js";
3
4
  // A SQLite database another process owns and writes while it runs, read
4
5
  // read-only and pinned to one moment by a read transaction, so its tables
5
6
  // agree. Never opened immutable: the owner keeps a persistent WAL, where the
@@ -8,9 +9,12 @@ import { MissingColumnsError } from "./missing-columns-error.js";
8
9
  export class Snapshot {
9
10
  path;
10
11
  #database;
11
- constructor(path) {
12
+ #copy;
13
+ // copy is the private copy that ofExclusiveOwner reads in place of path.
14
+ constructor(path, copy) {
12
15
  this.path = path;
13
- this.#database = openReader(path);
16
+ this.#copy = copy ?? { [Symbol.dispose]() { } };
17
+ this.#database = openReader(copy?.file ?? path);
14
18
  try {
15
19
  // The first read pins the snapshot, so it is taken now rather than at
16
20
  // the caller's first query; a file that is no database fails here.
@@ -22,6 +26,13 @@ export class Snapshot {
22
26
  throw cause;
23
27
  }
24
28
  }
29
+ // A database whose owner holds SQLite's exclusive locking mode, as Chromium
30
+ // holds its History: the owner lets no reader in, so the snapshot reads a
31
+ // private copy at the owner's last commit. Dispose it as soon as the read
32
+ // ends: the copy is a file until then.
33
+ static async ofExclusiveOwner(path) {
34
+ return new Snapshot(path, await OwnerCopy.take(path));
35
+ }
25
36
  // Refuses a layout without these columns, and closes the database: the
26
37
  // check a reader makes while it opens the snapshot.
27
38
  requireColumns(columns) {
@@ -50,11 +61,12 @@ export class Snapshot {
50
61
  return this.#database.prepare(sql).iterate(...parameters);
51
62
  }
52
63
  [Symbol.dispose]() {
53
- if (!this.#database.isOpen)
54
- return;
55
- if (this.#database.isTransaction)
56
- this.#database.exec('COMMIT');
57
- this.#database.close();
64
+ if (this.#database.isOpen) {
65
+ if (this.#database.isTransaction)
66
+ this.#database.exec('COMMIT');
67
+ this.#database.close();
68
+ }
69
+ this.#copy[Symbol.dispose]();
58
70
  }
59
71
  }
60
72
  //# sourceMappingURL=snapshot.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAKjE,wEAAwE;AACxE,0EAA0E;AAC1E,6EAA6E;AAC7E,6EAA6E;AAC7E,yBAAyB;AACzB,MAAM,OAAO,QAAQ;IACV,IAAI,CAAS;IACb,SAAS,CAAe;IAEjC,YAAY,IAAY;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,SAAS,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC;YACH,sEAAsE;YACtE,mEAAmE;YACnE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC7B,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,qCAAqC,CAAC,CAAC,GAAG,EAAE,CAAC;QACtE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;YACvB,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,uEAAuE;IACvE,oDAAoD;IACpD,cAAc,CAAC,OAAwB;QACrC,MAAM,OAAO,GAAG,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;QAC7C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QACjC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,mBAAmB,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACpD,CAAC;IAED,uEAAuE;IACvE,oEAAoE;IACpE,gCAAgC;IAChC,cAAc,CAAC,OAAwB;QACrC,OAAO,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE;YACxD,MAAM,OAAO,GAAG,IAAI,GAAG,CACrB,IAAI,CAAC,GAAG,CAAC,uCAAuC,EAAE,KAAK,CAAC,CAAC,GAAG,CAC1D,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CACxB,CACF,CAAC;YACF,OAAO,KAAK;iBACT,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;iBACpC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,KAAK,IAAI,IAAI,EAAE,CAAC,CAAC;QACvC,CAAC,CAAC,CAAC;IACL,CAAC;IAED,GAAG,CACD,GAAW,EACX,GAAG,UAA2B;QAE9B,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC;IACxD,CAAC;IAED,2DAA2D;IAC3D,OAAO,CACL,GAAW,EACX,GAAG,UAA2B;QAE9B,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,UAAU,CAAC,CAAC;IAC5D,CAAC;IAED,CAAC,MAAM,CAAC,OAAO,CAAC;QACd,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM;YAAE,OAAO;QACnC,IAAI,IAAI,CAAC,SAAS,CAAC,aAAa;YAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAChE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;CACF"}
1
+ {"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@zukhruf/sqlite-snapshot",
3
- "version": "0.6.13",
4
- "description": "A read-only snapshot of a SQLite database that another process owns and writes. One read transaction, so the tables agree; the newest rows in the WAL show. Checks the columns a reader needs. Throws its own UnavailableError and MissingColumnsError.",
3
+ "version": "0.6.15",
4
+ "description": "A read-only snapshot of a SQLite database that another process owns and writes, held by one read transaction so the tables agree, or by a checked copy when the owner holds the exclusive lock. Checks the columns a reader needs.",
5
5
  "license": "MIT",
6
6
  "repository": {
7
7
  "type": "git",
@@ -40,9 +40,10 @@
40
40
  "access": "public"
41
41
  },
42
42
  "dependencies": {
43
- "@zukhruf/sqlite-reader": "^0.6.13"
43
+ "@zukhruf/fs": "^0.6.15",
44
+ "@zukhruf/sqlite-reader": "^0.6.15"
44
45
  },
45
46
  "devDependencies": {
46
- "@zukhruf/testing": "^0.6.13"
47
+ "@zukhruf/testing": "^0.6.15"
47
48
  }
48
49
  }