@harperfast/rocksdb-js 2.0.0 → 2.2.0
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 +344 -31
- package/bin/rocksdb-js.mjs +290 -2
- package/dist/index.cjs +224 -34
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +770 -31
- package/dist/index.d.mts +770 -31
- package/dist/index.mjs +223 -35
- package/dist/index.mjs.map +1 -1
- package/docs/stats.md +459 -0
- package/docs/transaction-log.md +279 -0
- package/package.json +20 -19
package/dist/index.d.cts
CHANGED
|
@@ -1,5 +1,140 @@
|
|
|
1
1
|
import { ExtendedIterable } from "@harperfast/extended-iterable";
|
|
2
2
|
|
|
3
|
+
//#region src/backup.d.ts
|
|
4
|
+
/**
|
|
5
|
+
* Options for creating a backup via `db.backup()`.
|
|
6
|
+
*
|
|
7
|
+
* Backups are whole-database: every column family, the manifest, and (unless
|
|
8
|
+
* `backupLogFiles` is disabled) the write-ahead log are captured. A backup is
|
|
9
|
+
* not scoped to an individual `Store`.
|
|
10
|
+
*/
|
|
11
|
+
interface BackupOptions {
|
|
12
|
+
/**
|
|
13
|
+
* Flush the memtable before backing up. Defaults to `true` when the database
|
|
14
|
+
* was opened with `disableWAL` (otherwise unflushed data would be lost from
|
|
15
|
+
* the backup), and `false` otherwise.
|
|
16
|
+
*/
|
|
17
|
+
flushBeforeBackup?: boolean;
|
|
18
|
+
/**
|
|
19
|
+
* Arbitrary application metadata stored with the backup and returned by
|
|
20
|
+
* `backups.list()`.
|
|
21
|
+
*/
|
|
22
|
+
metadata?: string;
|
|
23
|
+
/**
|
|
24
|
+
* Share table/blob files between backups in the same directory to enable
|
|
25
|
+
* incremental backups. Defaults to `true`.
|
|
26
|
+
*/
|
|
27
|
+
shareTableFiles?: boolean;
|
|
28
|
+
/**
|
|
29
|
+
* Distinguish shared files by checksum to avoid collisions across databases.
|
|
30
|
+
* Defaults to `true`. Only relevant when `shareTableFiles` is enabled.
|
|
31
|
+
*/
|
|
32
|
+
shareFilesWithChecksum?: boolean;
|
|
33
|
+
/**
|
|
34
|
+
* Include write-ahead log files in the backup. Defaults to `true`.
|
|
35
|
+
*/
|
|
36
|
+
backupLogFiles?: boolean;
|
|
37
|
+
/**
|
|
38
|
+
* `fsync` backup files for crash consistency. Defaults to `true`.
|
|
39
|
+
*/
|
|
40
|
+
sync?: boolean;
|
|
41
|
+
/**
|
|
42
|
+
* Number of background threads used to copy files. Defaults to `1`.
|
|
43
|
+
*/
|
|
44
|
+
maxBackgroundOperations?: number;
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* The level of incremental restore to perform.
|
|
48
|
+
*
|
|
49
|
+
* - `purgeAllFiles` (default): purge the destination directory and restore all
|
|
50
|
+
* files from the backup. Destructive but always correct.
|
|
51
|
+
* - `keepLatestDbSessionIdFiles`: efficiently restore a healthy database,
|
|
52
|
+
* reusing existing files that match the backup.
|
|
53
|
+
* - `verifyChecksum`: reuse existing destination files whose checksums match the
|
|
54
|
+
* backup, replacing only mismatched/corrupt files.
|
|
55
|
+
*/
|
|
56
|
+
type RestoreMode = "purgeAllFiles" | "keepLatestDbSessionIdFiles" | "verifyChecksum";
|
|
57
|
+
/**
|
|
58
|
+
* Options for restoring a backup via `backups.restore()`.
|
|
59
|
+
*/
|
|
60
|
+
interface RestoreOptions {
|
|
61
|
+
/**
|
|
62
|
+
* The backup id to restore. Defaults to the latest non-corrupt backup.
|
|
63
|
+
*/
|
|
64
|
+
backupId?: number;
|
|
65
|
+
/**
|
|
66
|
+
* Directory to restore write-ahead log files into. Defaults to the database
|
|
67
|
+
* directory.
|
|
68
|
+
*/
|
|
69
|
+
walDir?: string;
|
|
70
|
+
/**
|
|
71
|
+
* Keep existing log files in `walDir` rather than overwriting them. Defaults
|
|
72
|
+
* to `false`.
|
|
73
|
+
*/
|
|
74
|
+
keepLogFiles?: boolean;
|
|
75
|
+
/**
|
|
76
|
+
* The restore strategy. Defaults to `purgeAllFiles`, which is destructive.
|
|
77
|
+
*/
|
|
78
|
+
mode?: RestoreMode;
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* Information about a single backup, as returned by `backups.list()`.
|
|
82
|
+
*/
|
|
83
|
+
interface BackupInfo {
|
|
84
|
+
/** The backup id (monotonically increasing integer). */
|
|
85
|
+
backupId: number;
|
|
86
|
+
/** Creation time in seconds since the epoch. */
|
|
87
|
+
timestamp: number;
|
|
88
|
+
/** Total size in bytes of the backed-up file payloads. */
|
|
89
|
+
size: number;
|
|
90
|
+
/** Number of files in the backup (some may be shared with other backups). */
|
|
91
|
+
numberFiles: number;
|
|
92
|
+
/** Application metadata supplied when the backup was created. */
|
|
93
|
+
appMetadata: string;
|
|
94
|
+
}
|
|
95
|
+
/**
|
|
96
|
+
* Backup management operations that act on a backup directory and do not
|
|
97
|
+
* require an open database. To create a backup, use the `db.backup()` instance
|
|
98
|
+
* method instead (it needs a live database for a consistent snapshot).
|
|
99
|
+
*
|
|
100
|
+
* @example
|
|
101
|
+
* ```typescript
|
|
102
|
+
* import { backups } from '@harperfast/rocksdb-js';
|
|
103
|
+
*
|
|
104
|
+
* const id = await db.backup('/path/to/backups');
|
|
105
|
+
* db.close();
|
|
106
|
+
* await backups.restore('/path/to/backups', '/path/to/restored-db');
|
|
107
|
+
* ```
|
|
108
|
+
*/
|
|
109
|
+
declare const backups: {
|
|
110
|
+
/**
|
|
111
|
+
* Restores a database from a backup directory into a (closed) database
|
|
112
|
+
* directory. The default mode purges the destination directory, so it must
|
|
113
|
+
* not point at a live database.
|
|
114
|
+
*/
|
|
115
|
+
restore(backupDir: string, dbDir: string, options?: RestoreOptions): Promise<void>;
|
|
116
|
+
/**
|
|
117
|
+
* Lists the non-corrupt backups in a backup directory, ordered by id.
|
|
118
|
+
*/
|
|
119
|
+
list(backupDir: string): Promise<BackupInfo[]>;
|
|
120
|
+
/**
|
|
121
|
+
* Deletes a specific backup. Shared files are reference-counted and only
|
|
122
|
+
* removed once no remaining backup references them.
|
|
123
|
+
*/
|
|
124
|
+
delete(backupDir: string, backupId: number): Promise<void>;
|
|
125
|
+
/**
|
|
126
|
+
* Deletes all but the newest `keepCount` backups.
|
|
127
|
+
*/
|
|
128
|
+
purge(backupDir: string, keepCount: number): Promise<void>;
|
|
129
|
+
/**
|
|
130
|
+
* Verifies a backup's file sizes, and optionally their checksums (which
|
|
131
|
+
* requires reading all backed-up data).
|
|
132
|
+
*/
|
|
133
|
+
verify(backupDir: string, backupId: number, options?: {
|
|
134
|
+
verifyWithChecksum?: boolean;
|
|
135
|
+
}): Promise<void>;
|
|
136
|
+
};
|
|
137
|
+
//#endregion
|
|
3
138
|
//#region src/encoding.d.ts
|
|
4
139
|
type Key = Key[] | string | symbol | number | boolean | Uint8Array | Buffer | null;
|
|
5
140
|
interface BufferWithDataView extends Buffer {
|
|
@@ -30,6 +165,374 @@ type KeyEncoding = "binary" | "ordered-binary" | "uint32";
|
|
|
30
165
|
type ReadKeyFunction<T> = (source: BufferWithDataView, start: number, end?: number) => T;
|
|
31
166
|
type WriteKeyFunction = (key: Key, target: BufferWithDataView, start: number) => number;
|
|
32
167
|
//#endregion
|
|
168
|
+
//#region src/stats.d.ts
|
|
169
|
+
/** Database-level RocksDB statistics types for `db.getStats()` / `db.getStat()`. */
|
|
170
|
+
type StatsHistogramData = {
|
|
171
|
+
average: number;
|
|
172
|
+
count: number;
|
|
173
|
+
max: number;
|
|
174
|
+
median: number;
|
|
175
|
+
min: number;
|
|
176
|
+
percentile95: number;
|
|
177
|
+
percentile99: number;
|
|
178
|
+
standardDeviation: number;
|
|
179
|
+
sum: number;
|
|
180
|
+
};
|
|
181
|
+
type StatsBasics = {
|
|
182
|
+
"rocksdb.num-immutable-mem-table": number;
|
|
183
|
+
"rocksdb.num-immutable-mem-table-flushed": number;
|
|
184
|
+
"rocksdb.mem-table-flush-pending": number;
|
|
185
|
+
"rocksdb.cur-size-active-mem-table": number;
|
|
186
|
+
"rocksdb.cur-size-all-mem-tables": number;
|
|
187
|
+
"rocksdb.size-all-mem-tables": number;
|
|
188
|
+
"rocksdb.num-entries-active-mem-table": number;
|
|
189
|
+
"rocksdb.num-deletes-active-mem-table": number;
|
|
190
|
+
"rocksdb.compaction-pending": number;
|
|
191
|
+
"rocksdb.estimate-pending-compaction-bytes": number;
|
|
192
|
+
"rocksdb.num-running-compactions": number;
|
|
193
|
+
"rocksdb.num-running-flushes": number;
|
|
194
|
+
"rocksdb.total-sst-files-size": number;
|
|
195
|
+
"rocksdb.live-sst-files-size": number;
|
|
196
|
+
"rocksdb.estimate-live-data-size": number;
|
|
197
|
+
"rocksdb.estimate-num-keys": number;
|
|
198
|
+
"rocksdb.block-cache-capacity": number;
|
|
199
|
+
"rocksdb.block-cache-usage": number;
|
|
200
|
+
"rocksdb.block-cache-pinned-usage": number;
|
|
201
|
+
"rocksdb.num-live-versions": number;
|
|
202
|
+
"rocksdb.current-super-version-number": number;
|
|
203
|
+
"rocksdb.oldest-snapshot-time": number;
|
|
204
|
+
"rocksdb.num-blob-files": number;
|
|
205
|
+
"rocksdb.total-blob-file-size": number;
|
|
206
|
+
"rocksdb.live-blob-file-size": number;
|
|
207
|
+
"txnlog.logCount": number;
|
|
208
|
+
"txnlog.fileCount": number;
|
|
209
|
+
"txnlog.totalSizeBytes": number;
|
|
210
|
+
"txnlog.mappedBytes": number;
|
|
211
|
+
"txnlog.overlayBytes": number;
|
|
212
|
+
"txnlog.activeMaps": number;
|
|
213
|
+
"txnlog.pendingTransactions": number;
|
|
214
|
+
"txnlog.uncommittedTransactions": number;
|
|
215
|
+
"txnlog.transactionsWritten": number;
|
|
216
|
+
"txnlog.bytesWritten": number;
|
|
217
|
+
"txnlog.replayGapBytes": number;
|
|
218
|
+
};
|
|
219
|
+
type StatsCuratedExtras = {
|
|
220
|
+
"rocksdb.block.cache.hit": number;
|
|
221
|
+
"rocksdb.block.cache.miss": number;
|
|
222
|
+
"rocksdb.block.cache.data.hit": number;
|
|
223
|
+
"rocksdb.block.cache.data.miss": number;
|
|
224
|
+
"rocksdb.block.cache.index.hit": number;
|
|
225
|
+
"rocksdb.block.cache.index.miss": number;
|
|
226
|
+
"rocksdb.block.cache.filter.hit": number;
|
|
227
|
+
"rocksdb.block.cache.filter.miss": number;
|
|
228
|
+
"rocksdb.bloom.filter.useful": number;
|
|
229
|
+
"rocksdb.bloom.filter.full.positive": number;
|
|
230
|
+
"rocksdb.bloom.filter.full.true.positive": number;
|
|
231
|
+
"rocksdb.db.iter.bytes.read": number;
|
|
232
|
+
"rocksdb.number.reseeks.iteration": number;
|
|
233
|
+
"rocksdb.number.keys.read": number;
|
|
234
|
+
"rocksdb.number.keys.written": number;
|
|
235
|
+
"rocksdb.bytes.read": number;
|
|
236
|
+
"rocksdb.bytes.written": number;
|
|
237
|
+
"rocksdb.memtable.hit": number;
|
|
238
|
+
"rocksdb.memtable.miss": number;
|
|
239
|
+
"rocksdb.txn.overhead.mutex.prepare": number;
|
|
240
|
+
"rocksdb.txn.overhead.mutex.old.commit.map": number;
|
|
241
|
+
"rocksdb.txn.overhead.mutex.snapshot": number;
|
|
242
|
+
"rocksdb.compact.read.bytes": number;
|
|
243
|
+
"rocksdb.compact.write.bytes": number;
|
|
244
|
+
"rocksdb.compaction.cancelled": number;
|
|
245
|
+
"rocksdb.stall.micros": number;
|
|
246
|
+
"rocksdb.no.file.errors": number;
|
|
247
|
+
"rocksdb.read.amp.estimate.useful.bytes": number;
|
|
248
|
+
"rocksdb.read.amp.total.read.bytes": number;
|
|
249
|
+
"rocksdb.db.get.micros": StatsHistogramData;
|
|
250
|
+
"rocksdb.db.write.micros": StatsHistogramData;
|
|
251
|
+
"rocksdb.db.seek.micros": StatsHistogramData;
|
|
252
|
+
"rocksdb.db.flush.micros": StatsHistogramData;
|
|
253
|
+
"rocksdb.db.write.stall": StatsHistogramData;
|
|
254
|
+
"rocksdb.blobdb.value.size": StatsHistogramData;
|
|
255
|
+
"rocksdb.sst.read.micros": StatsHistogramData;
|
|
256
|
+
"rocksdb.compaction.times.micros": StatsHistogramData;
|
|
257
|
+
};
|
|
258
|
+
type StatsAllExtras = {
|
|
259
|
+
"rocksdb.block.cache.add": number;
|
|
260
|
+
"rocksdb.block.cache.add.failures": number;
|
|
261
|
+
"rocksdb.block.cache.index.add": number;
|
|
262
|
+
"rocksdb.block.cache.index.bytes.insert": number;
|
|
263
|
+
"rocksdb.block.cache.filter.add": number;
|
|
264
|
+
"rocksdb.block.cache.filter.bytes.insert": number;
|
|
265
|
+
"rocksdb.block.cache.data.add": number;
|
|
266
|
+
"rocksdb.block.cache.data.bytes.insert": number;
|
|
267
|
+
"rocksdb.block.cache.bytes.read": number;
|
|
268
|
+
"rocksdb.block.cache.bytes.write": number;
|
|
269
|
+
"rocksdb.block.cache.compression.dict.miss": number;
|
|
270
|
+
"rocksdb.block.cache.compression.dict.hit": number;
|
|
271
|
+
"rocksdb.block.cache.compression.dict.add": number;
|
|
272
|
+
"rocksdb.block.cache.compression.dict.bytes.insert": number;
|
|
273
|
+
"rocksdb.block.cache.add.redundant": number;
|
|
274
|
+
"rocksdb.block.cache.index.add.redundant": number;
|
|
275
|
+
"rocksdb.block.cache.filter.add.redundant": number;
|
|
276
|
+
"rocksdb.block.cache.data.add.redundant": number;
|
|
277
|
+
"rocksdb.block.cache.compression.dict.add.redundant": number;
|
|
278
|
+
"rocksdb.secondary.cache.hits": number;
|
|
279
|
+
"rocksdb.secondary.cache.filter.hits": number;
|
|
280
|
+
"rocksdb.secondary.cache.index.hits": number;
|
|
281
|
+
"rocksdb.secondary.cache.data.hits": number;
|
|
282
|
+
"rocksdb.compressed.secondary.cache.dummy.hits": number;
|
|
283
|
+
"rocksdb.compressed.secondary.cache.hits": number;
|
|
284
|
+
"rocksdb.compressed.secondary.cache.promotions": number;
|
|
285
|
+
"rocksdb.compressed.secondary.cache.promotion.skips": number;
|
|
286
|
+
"rocksdb.bloom.filter.prefix.checked": number;
|
|
287
|
+
"rocksdb.bloom.filter.prefix.useful": number;
|
|
288
|
+
"rocksdb.bloom.filter.prefix.true.positive": number;
|
|
289
|
+
"rocksdb.persistent.cache.hit": number;
|
|
290
|
+
"rocksdb.persistent.cache.miss": number;
|
|
291
|
+
"rocksdb.sim.block.cache.hit": number;
|
|
292
|
+
"rocksdb.sim.block.cache.miss": number;
|
|
293
|
+
"rocksdb.l0.hit": number;
|
|
294
|
+
"rocksdb.l1.hit": number;
|
|
295
|
+
"rocksdb.l2andup.hit": number;
|
|
296
|
+
"rocksdb.compaction.key.drop.new": number;
|
|
297
|
+
"rocksdb.compaction.key.drop.obsolete": number;
|
|
298
|
+
"rocksdb.compaction.key.drop.range_del": number;
|
|
299
|
+
"rocksdb.compaction.key.drop.user": number;
|
|
300
|
+
"rocksdb.compaction.range_del.drop.obsolete": number;
|
|
301
|
+
"rocksdb.compaction.optimized.del.drop.obsolete": number;
|
|
302
|
+
"rocksdb.compaction.aborted": number;
|
|
303
|
+
"rocksdb.number.keys.updated": number;
|
|
304
|
+
"rocksdb.number.db.seek": number;
|
|
305
|
+
"rocksdb.number.db.next": number;
|
|
306
|
+
"rocksdb.number.db.prev": number;
|
|
307
|
+
"rocksdb.number.db.seek.found": number;
|
|
308
|
+
"rocksdb.number.db.next.found": number;
|
|
309
|
+
"rocksdb.number.db.prev.found": number;
|
|
310
|
+
"rocksdb.number.iter.skip": number;
|
|
311
|
+
"rocksdb.num.iterator.created": number;
|
|
312
|
+
"rocksdb.num.iterator.deleted": number;
|
|
313
|
+
"rocksdb.no.file.opens": number;
|
|
314
|
+
"rocksdb.db.mutex.wait.micros": number;
|
|
315
|
+
"rocksdb.number.multiget.get": number;
|
|
316
|
+
"rocksdb.number.multiget.keys.read": number;
|
|
317
|
+
"rocksdb.number.multiget.bytes.read": number;
|
|
318
|
+
"rocksdb.number.multiget.keys.found": number;
|
|
319
|
+
"rocksdb.number.merge.failures": number;
|
|
320
|
+
"rocksdb.getupdatessince.calls": number;
|
|
321
|
+
"rocksdb.wal.synced": number;
|
|
322
|
+
"rocksdb.wal.bytes": number;
|
|
323
|
+
"rocksdb.write.self": number;
|
|
324
|
+
"rocksdb.write.other": number;
|
|
325
|
+
"rocksdb.write.wal": number;
|
|
326
|
+
"rocksdb.flush.write.bytes": number;
|
|
327
|
+
"rocksdb.compact.read.marked.bytes": number;
|
|
328
|
+
"rocksdb.compact.read.periodic.bytes": number;
|
|
329
|
+
"rocksdb.compact.read.ttl.bytes": number;
|
|
330
|
+
"rocksdb.compact.write.marked.bytes": number;
|
|
331
|
+
"rocksdb.compact.write.periodic.bytes": number;
|
|
332
|
+
"rocksdb.compact.write.ttl.bytes": number;
|
|
333
|
+
"rocksdb.number.direct.load.table.properties": number;
|
|
334
|
+
"rocksdb.number.superversion_acquires": number;
|
|
335
|
+
"rocksdb.number.superversion_releases": number;
|
|
336
|
+
"rocksdb.number.superversion_cleanups": number;
|
|
337
|
+
"rocksdb.number.block.compressed": number;
|
|
338
|
+
"rocksdb.number.block.decompressed": number;
|
|
339
|
+
"rocksdb.bytes.compressed.from": number;
|
|
340
|
+
"rocksdb.bytes.compressed.to": number;
|
|
341
|
+
"rocksdb.bytes.compression_bypassed": number;
|
|
342
|
+
"rocksdb.bytes.compression.rejected": number;
|
|
343
|
+
"rocksdb.number.block_compression_bypassed": number;
|
|
344
|
+
"rocksdb.number.block_compression_rejected": number;
|
|
345
|
+
"rocksdb.bytes.decompressed.from": number;
|
|
346
|
+
"rocksdb.bytes.decompressed.to": number;
|
|
347
|
+
"rocksdb.merge.operation.time.nanos": number;
|
|
348
|
+
"rocksdb.filter.operation.time.nanos": number;
|
|
349
|
+
"rocksdb.compaction.total.time.cpu_micros": number;
|
|
350
|
+
"rocksdb.row.cache.hit": number;
|
|
351
|
+
"rocksdb.row.cache.miss": number;
|
|
352
|
+
"rocksdb.number.rate_limiter.drains": number;
|
|
353
|
+
"rocksdb.blobdb.num.put": number;
|
|
354
|
+
"rocksdb.blobdb.num.write": number;
|
|
355
|
+
"rocksdb.blobdb.num.get": number;
|
|
356
|
+
"rocksdb.blobdb.num.multiget": number;
|
|
357
|
+
"rocksdb.blobdb.num.seek": number;
|
|
358
|
+
"rocksdb.blobdb.num.next": number;
|
|
359
|
+
"rocksdb.blobdb.num.prev": number;
|
|
360
|
+
"rocksdb.blobdb.num.keys.written": number;
|
|
361
|
+
"rocksdb.blobdb.num.keys.read": number;
|
|
362
|
+
"rocksdb.blobdb.bytes.written": number;
|
|
363
|
+
"rocksdb.blobdb.bytes.read": number;
|
|
364
|
+
"rocksdb.blobdb.write.inlined": number;
|
|
365
|
+
"rocksdb.blobdb.write.inlined.ttl": number;
|
|
366
|
+
"rocksdb.blobdb.write.blob": number;
|
|
367
|
+
"rocksdb.blobdb.write.blob.ttl": number;
|
|
368
|
+
"rocksdb.blobdb.blob.file.bytes.written": number;
|
|
369
|
+
"rocksdb.blobdb.blob.file.bytes.read": number;
|
|
370
|
+
"rocksdb.blobdb.blob.file.synced": number;
|
|
371
|
+
"rocksdb.blobdb.blob.index.expired.count": number;
|
|
372
|
+
"rocksdb.blobdb.blob.index.expired.size": number;
|
|
373
|
+
"rocksdb.blobdb.blob.index.evicted.count": number;
|
|
374
|
+
"rocksdb.blobdb.blob.index.evicted.size": number;
|
|
375
|
+
"rocksdb.blobdb.gc.num.files": number;
|
|
376
|
+
"rocksdb.blobdb.gc.num.new.files": number;
|
|
377
|
+
"rocksdb.blobdb.gc.failures": number;
|
|
378
|
+
"rocksdb.blobdb.gc.num.keys.relocated": number;
|
|
379
|
+
"rocksdb.blobdb.gc.bytes.relocated": number;
|
|
380
|
+
"rocksdb.blobdb.fifo.num.files.evicted": number;
|
|
381
|
+
"rocksdb.blobdb.fifo.num.keys.evicted": number;
|
|
382
|
+
"rocksdb.blobdb.fifo.bytes.evicted": number;
|
|
383
|
+
"rocksdb.blobdb.cache.miss": number;
|
|
384
|
+
"rocksdb.blobdb.cache.hit": number;
|
|
385
|
+
"rocksdb.blobdb.cache.add": number;
|
|
386
|
+
"rocksdb.blobdb.cache.add.failures": number;
|
|
387
|
+
"rocksdb.blobdb.cache.bytes.read": number;
|
|
388
|
+
"rocksdb.blobdb.cache.bytes.write": number;
|
|
389
|
+
"rocksdb.txn.overhead.duplicate.key": number;
|
|
390
|
+
"rocksdb.txn.get.tryagain": number;
|
|
391
|
+
"rocksdb.files.marked.trash": number;
|
|
392
|
+
"rocksdb.files.marked.trash.deleted": number;
|
|
393
|
+
"rocksdb.files.deleted.immediately": number;
|
|
394
|
+
"rocksdb.error.handler.bg.error.count": number;
|
|
395
|
+
"rocksdb.error.handler.bg.io.error.count": number;
|
|
396
|
+
"rocksdb.error.handler.bg.retryable.io.error.count": number;
|
|
397
|
+
"rocksdb.error.handler.autoresume.count": number;
|
|
398
|
+
"rocksdb.error.handler.autoresume.retry.total.count": number;
|
|
399
|
+
"rocksdb.error.handler.autoresume.success.count": number;
|
|
400
|
+
"rocksdb.memtable.payload.bytes.at.flush": number;
|
|
401
|
+
"rocksdb.memtable.garbage.bytes.at.flush": number;
|
|
402
|
+
"rocksdb.verify_checksum.read.bytes": number;
|
|
403
|
+
"rocksdb.backup.read.bytes": number;
|
|
404
|
+
"rocksdb.backup.write.bytes": number;
|
|
405
|
+
"rocksdb.remote.compact.read.bytes": number;
|
|
406
|
+
"rocksdb.remote.compact.write.bytes": number;
|
|
407
|
+
"rocksdb.remote.compact.resumed.bytes": number;
|
|
408
|
+
"rocksdb.hot.file.read.bytes": number;
|
|
409
|
+
"rocksdb.warm.file.read.bytes": number;
|
|
410
|
+
"rocksdb.cool.file.read.bytes": number;
|
|
411
|
+
"rocksdb.cold.file.read.bytes": number;
|
|
412
|
+
"rocksdb.ice.file.read.bytes": number;
|
|
413
|
+
"rocksdb.hot.file.read.count": number;
|
|
414
|
+
"rocksdb.warm.file.read.count": number;
|
|
415
|
+
"rocksdb.cool.file.read.count": number;
|
|
416
|
+
"rocksdb.cold.file.read.count": number;
|
|
417
|
+
"rocksdb.ice.file.read.count": number;
|
|
418
|
+
"rocksdb.last.level.read.bytes": number;
|
|
419
|
+
"rocksdb.last.level.read.count": number;
|
|
420
|
+
"rocksdb.non.last.level.read.bytes": number;
|
|
421
|
+
"rocksdb.non.last.level.read.count": number;
|
|
422
|
+
"rocksdb.last.level.seek.filtered": number;
|
|
423
|
+
"rocksdb.last.level.seek.filter.match": number;
|
|
424
|
+
"rocksdb.last.level.seek.data": number;
|
|
425
|
+
"rocksdb.last.level.seek.data.useful.no.filter": number;
|
|
426
|
+
"rocksdb.last.level.seek.data.useful.filter.match": number;
|
|
427
|
+
"rocksdb.non.last.level.seek.filtered": number;
|
|
428
|
+
"rocksdb.non.last.level.seek.filter.match": number;
|
|
429
|
+
"rocksdb.non.last.level.seek.data": number;
|
|
430
|
+
"rocksdb.non.last.level.seek.data.useful.no.filter": number;
|
|
431
|
+
"rocksdb.non.last.level.seek.data.useful.filter.match": number;
|
|
432
|
+
"rocksdb.block.checksum.compute.count": number;
|
|
433
|
+
"rocksdb.block.checksum.mismatch.count": number;
|
|
434
|
+
"rocksdb.multiget.coroutine.count": number;
|
|
435
|
+
"rocksdb.read.async.micros": number;
|
|
436
|
+
"rocksdb.async.read.error.count": number;
|
|
437
|
+
"rocksdb.table.open.prefetch.tail.miss": number;
|
|
438
|
+
"rocksdb.table.open.prefetch.tail.hit": number;
|
|
439
|
+
"rocksdb.timestamp.filter.table.checked": number;
|
|
440
|
+
"rocksdb.timestamp.filter.table.filtered": number;
|
|
441
|
+
"rocksdb.readahead.trimmed": number;
|
|
442
|
+
"rocksdb.fifo.max.size.compactions": number;
|
|
443
|
+
"rocksdb.fifo.ttl.compactions": number;
|
|
444
|
+
"rocksdb.fifo.change_temperature.compactions": number;
|
|
445
|
+
"rocksdb.prefetch.bytes": number;
|
|
446
|
+
"rocksdb.prefetch.bytes.useful": number;
|
|
447
|
+
"rocksdb.prefetch.hits": number;
|
|
448
|
+
"rocksdb.footer.corruption.count": number;
|
|
449
|
+
"rocksdb.file.read.corruption.retry.count": number;
|
|
450
|
+
"rocksdb.file.read.corruption.retry.success.count": number;
|
|
451
|
+
"rocksdb.number.wbwi.ingest": number;
|
|
452
|
+
"rocksdb.sst.user.defined.index.load.fail.count": number;
|
|
453
|
+
"rocksdb.multiscan.prepare.calls": number;
|
|
454
|
+
"rocksdb.multiscan.prepare.errors": number;
|
|
455
|
+
"rocksdb.multiscan.blocks.prefetched": number;
|
|
456
|
+
"rocksdb.multiscan.blocks.from.cache": number;
|
|
457
|
+
"rocksdb.multiscan.prefetch.bytes": number;
|
|
458
|
+
"rocksdb.multiscan.prefetch.blocks.wasted": number;
|
|
459
|
+
"rocksdb.multiscan.io.requests": number;
|
|
460
|
+
"rocksdb.multiscan.io.coalesced.nonadjacent": number;
|
|
461
|
+
"rocksdb.multiscan.seek.errors": number;
|
|
462
|
+
"rocksdb.prefetch.memory.bytes.granted": number;
|
|
463
|
+
"rocksdb.prefetch.memory.bytes.released": number;
|
|
464
|
+
"rocksdb.prefetch.memory.requests.blocked": number;
|
|
465
|
+
"rocksdb.compaction.times.cpu_micros": StatsHistogramData;
|
|
466
|
+
"rocksdb.subcompaction.setup.times.micros": StatsHistogramData;
|
|
467
|
+
"rocksdb.table.sync.micros": StatsHistogramData;
|
|
468
|
+
"rocksdb.compaction.outfile.sync.micros": StatsHistogramData;
|
|
469
|
+
"rocksdb.wal.file.sync.micros": StatsHistogramData;
|
|
470
|
+
"rocksdb.manifest.file.sync.micros": StatsHistogramData;
|
|
471
|
+
"rocksdb.table.open.io.micros": StatsHistogramData;
|
|
472
|
+
"rocksdb.db.multiget.micros": StatsHistogramData;
|
|
473
|
+
"rocksdb.read.block.compaction.micros": StatsHistogramData;
|
|
474
|
+
"rocksdb.read.block.get.micros": StatsHistogramData;
|
|
475
|
+
"rocksdb.write.raw.block.micros": StatsHistogramData;
|
|
476
|
+
"rocksdb.numfiles.in.singlecompaction": StatsHistogramData;
|
|
477
|
+
"rocksdb.file.read.flush.micros": StatsHistogramData;
|
|
478
|
+
"rocksdb.file.read.compaction.micros": StatsHistogramData;
|
|
479
|
+
"rocksdb.file.read.db.open.micros": StatsHistogramData;
|
|
480
|
+
"rocksdb.file.read.get.micros": StatsHistogramData;
|
|
481
|
+
"rocksdb.file.read.multiget.micros": StatsHistogramData;
|
|
482
|
+
"rocksdb.file.read.db.iterator.micros": StatsHistogramData;
|
|
483
|
+
"rocksdb.file.read.verify.db.checksum.micros": StatsHistogramData;
|
|
484
|
+
"rocksdb.file.read.verify.file.checksums.micros": StatsHistogramData;
|
|
485
|
+
"rocksdb.sst.write.micros": StatsHistogramData;
|
|
486
|
+
"rocksdb.file.write.flush.micros": StatsHistogramData;
|
|
487
|
+
"rocksdb.file.write.compaction.micros": StatsHistogramData;
|
|
488
|
+
"rocksdb.file.write.db.open.micros": StatsHistogramData;
|
|
489
|
+
"rocksdb.num.subcompactions.scheduled": StatsHistogramData;
|
|
490
|
+
"rocksdb.bytes.per.read": StatsHistogramData;
|
|
491
|
+
"rocksdb.bytes.per.write": StatsHistogramData;
|
|
492
|
+
"rocksdb.bytes.per.multiget": StatsHistogramData;
|
|
493
|
+
"rocksdb.compression.times.nanos": StatsHistogramData;
|
|
494
|
+
"rocksdb.decompression.times.nanos": StatsHistogramData;
|
|
495
|
+
"rocksdb.read.num.merge_operands": StatsHistogramData;
|
|
496
|
+
"rocksdb.blobdb.key.size": StatsHistogramData;
|
|
497
|
+
"rocksdb.blobdb.write.micros": StatsHistogramData;
|
|
498
|
+
"rocksdb.blobdb.get.micros": StatsHistogramData;
|
|
499
|
+
"rocksdb.blobdb.multiget.micros": StatsHistogramData;
|
|
500
|
+
"rocksdb.blobdb.seek.micros": StatsHistogramData;
|
|
501
|
+
"rocksdb.blobdb.next.micros": StatsHistogramData;
|
|
502
|
+
"rocksdb.blobdb.prev.micros": StatsHistogramData;
|
|
503
|
+
"rocksdb.blobdb.blob.file.write.micros": StatsHistogramData;
|
|
504
|
+
"rocksdb.blobdb.blob.file.read.micros": StatsHistogramData;
|
|
505
|
+
"rocksdb.blobdb.blob.file.sync.micros": StatsHistogramData;
|
|
506
|
+
"rocksdb.blobdb.compression.micros": StatsHistogramData;
|
|
507
|
+
"rocksdb.blobdb.decompression.micros": StatsHistogramData;
|
|
508
|
+
"rocksdb.sst.batch.size": StatsHistogramData;
|
|
509
|
+
"rocksdb.multiget.io.batch.size": StatsHistogramData;
|
|
510
|
+
"rocksdb.num.index.and.filter.blocks.read.per.level": StatsHistogramData;
|
|
511
|
+
"rocksdb.num.sst.read.per.level": StatsHistogramData;
|
|
512
|
+
"rocksdb.num.level.read.per.multiget": StatsHistogramData;
|
|
513
|
+
"rocksdb.error.handler.autoresume.retry.count": StatsHistogramData;
|
|
514
|
+
"rocksdb.async.read.bytes": StatsHistogramData;
|
|
515
|
+
"rocksdb.poll.wait.micros": StatsHistogramData;
|
|
516
|
+
"rocksdb.compaction.prefetch.bytes": StatsHistogramData;
|
|
517
|
+
"rocksdb.prefetched.bytes.discarded": StatsHistogramData;
|
|
518
|
+
"rocksdb.async.prefetch.abort.micros": StatsHistogramData;
|
|
519
|
+
"rocksdb.table.open.prefetch.tail.read.bytes": StatsHistogramData;
|
|
520
|
+
"rocksdb.num.op.per.transaction": StatsHistogramData;
|
|
521
|
+
"rocksdb.multiscan.op.prepare.iterators.micros": StatsHistogramData;
|
|
522
|
+
"rocksdb.multiscan.prepare.micros": StatsHistogramData;
|
|
523
|
+
"rocksdb.multiscan.blocks.per.prepare": StatsHistogramData;
|
|
524
|
+
"rocksdb.block.key.distribution.cv": StatsHistogramData;
|
|
525
|
+
};
|
|
526
|
+
type StatsCurated = StatsBasics & StatsCuratedExtras;
|
|
527
|
+
type StatsAll = StatsCurated & StatsAllExtras;
|
|
528
|
+
type StatsValue = number | StatsHistogramData;
|
|
529
|
+
/** Returned by `getStats()` when `all` is omitted or `false`. Curated keys require `enableStats: true`. */
|
|
530
|
+
type StatsDefault = StatsBasics | StatsCurated;
|
|
531
|
+
interface GetStatsMethod {
|
|
532
|
+
getStats(all?: false): StatsDefault;
|
|
533
|
+
getStats(all: true): StatsAll;
|
|
534
|
+
}
|
|
535
|
+
//#endregion
|
|
33
536
|
//#region src/dbi-iterator.d.ts
|
|
34
537
|
interface DBIteratorValue<T> {
|
|
35
538
|
key: Key;
|
|
@@ -48,7 +551,7 @@ declare class DBIterator<T> implements Iterator<DBIteratorValue<T>> {
|
|
|
48
551
|
#private;
|
|
49
552
|
iterator: InstanceType<typeof NativeIteratorCls>;
|
|
50
553
|
store: Store;
|
|
51
|
-
constructor(iterator: InstanceType<typeof NativeIteratorCls>, store: Store, includeValues: boolean);
|
|
554
|
+
constructor(iterator: InstanceType<typeof NativeIteratorCls>, store: Store, includeValues: boolean, limit?: number);
|
|
52
555
|
[Symbol.iterator](): Iterator<DBIteratorValue<T>>;
|
|
53
556
|
next(): IteratorResult<DBIteratorValue<T>>;
|
|
54
557
|
return(value?: any): IteratorResult<DBIteratorValue<T>, any>;
|
|
@@ -258,6 +761,10 @@ declare class Store {
|
|
|
258
761
|
*/
|
|
259
762
|
transactionLogsPath?: string;
|
|
260
763
|
/**
|
|
764
|
+
* Whether this store's column family participates in the VerificationTable.
|
|
765
|
+
*/
|
|
766
|
+
verificationTable?: boolean;
|
|
767
|
+
/**
|
|
261
768
|
* The per-column-family memtable size in bytes at which the memtable is
|
|
262
769
|
* sealed and flushed.
|
|
263
770
|
*/
|
|
@@ -289,6 +796,17 @@ declare class Store {
|
|
|
289
796
|
*/
|
|
290
797
|
compact(options?: CompactOptions): Promise<void>;
|
|
291
798
|
/**
|
|
799
|
+
* Creates a backup of the entire database (all column families) into the
|
|
800
|
+
* given directory and resolves with the new backup id. Parent directories
|
|
801
|
+
* are created as needed. See `backups` for restore and management.
|
|
802
|
+
*
|
|
803
|
+
* @example
|
|
804
|
+
* ```typescript
|
|
805
|
+
* const id = await db.backup('/path/to/backups');
|
|
806
|
+
* ```
|
|
807
|
+
*/
|
|
808
|
+
backup(backupDir: string, options?: BackupOptions): Promise<number>;
|
|
809
|
+
/**
|
|
292
810
|
* Compacts the entire key range of the database synchronously.
|
|
293
811
|
* This triggers manual compaction which removes tombstones and reclaims space.
|
|
294
812
|
*
|
|
@@ -327,7 +845,7 @@ declare class Store {
|
|
|
327
845
|
* @returns The encoded value.
|
|
328
846
|
*/
|
|
329
847
|
encodeValue(value: any): BufferWithDataView | Uint8Array;
|
|
330
|
-
get(context: StoreContext, key: Key, alwaysCreateNewBuffer?: boolean,
|
|
848
|
+
get(context: StoreContext, key: Key, alwaysCreateNewBuffer?: boolean, options?: StoreGetOptions): any | undefined;
|
|
331
849
|
getCount(context: StoreContext, options?: StoreRangeOptions): number;
|
|
332
850
|
getKeys(context: StoreContext, options?: StoreIteratorOptions): any | undefined;
|
|
333
851
|
getKeysCount(context: StoreContext, options?: StoreRangeOptions): number;
|
|
@@ -404,6 +922,19 @@ declare class Store {
|
|
|
404
922
|
*/
|
|
405
923
|
useLog(context: StoreContext, name: string | number): TransactionLog;
|
|
406
924
|
/**
|
|
925
|
+
* Checks the process-global verification table for a fresh version match
|
|
926
|
+
* on `key`. Returns `true` when the table currently records `version` for
|
|
927
|
+
* this database+column-family. Provides a fast cache-freshness check
|
|
928
|
+
* before falling back to a full read.
|
|
929
|
+
*/
|
|
930
|
+
verifyVersion(key: Key, version: number): boolean;
|
|
931
|
+
/**
|
|
932
|
+
* Seeds the verification-table slot for `key` with `version`. Has no
|
|
933
|
+
* effect if the slot is currently lock-tagged or the table is disabled.
|
|
934
|
+
* Useful after a full read where the caller already knows the version.
|
|
935
|
+
*/
|
|
936
|
+
populateVersion(key: Key, version: number): void;
|
|
937
|
+
/**
|
|
407
938
|
* Acquires a lock on the given key and calls the callback.
|
|
408
939
|
*
|
|
409
940
|
* @param key - The key to lock.
|
|
@@ -413,6 +944,21 @@ declare class Store {
|
|
|
413
944
|
withLock(key: Key, callback: () => void | Promise<void>): Promise<void>;
|
|
414
945
|
}
|
|
415
946
|
interface GetOptions {
|
|
947
|
+
/**
|
|
948
|
+
* When set, the native layer checks the verification table before reading.
|
|
949
|
+
* If the slot holds this version, returns `FRESH_VERSION_FLAG` immediately
|
|
950
|
+
* (the cached value is still valid). After a DB read, also seeds the slot
|
|
951
|
+
* with the version extracted from the value.
|
|
952
|
+
*/
|
|
953
|
+
expectedVersion?: number;
|
|
954
|
+
/**
|
|
955
|
+
* When `true`, after a DB read the native layer automatically seeds the
|
|
956
|
+
* verification-table slot with the version extracted from the value.
|
|
957
|
+
* Eliminates the need for a separate `populateVersion` call on cold reads.
|
|
958
|
+
*
|
|
959
|
+
* @default false
|
|
960
|
+
*/
|
|
961
|
+
populateVersion?: boolean;
|
|
416
962
|
/**
|
|
417
963
|
* Whether to skip decoding the value.
|
|
418
964
|
*
|
|
@@ -435,14 +981,25 @@ type NativeTransactionOptions = {
|
|
|
435
981
|
* @default false
|
|
436
982
|
*/
|
|
437
983
|
disableSnapshot?: boolean;
|
|
984
|
+
/**
|
|
985
|
+
* When `true`, an `IsBusy` conflict at commit time is resolved with the
|
|
986
|
+
* `RETRY_NOW` sentinel value instead of being rejected. The native layer
|
|
987
|
+
* may park on a VT slot before resolving, so the JS retry fires only after
|
|
988
|
+
* the conflicting transaction has committed and released its write intent.
|
|
989
|
+
*
|
|
990
|
+
* Use together with `verificationTable: true` on the database.
|
|
991
|
+
*
|
|
992
|
+
* @default false
|
|
993
|
+
*/
|
|
994
|
+
coordinatedRetry?: boolean;
|
|
438
995
|
};
|
|
439
996
|
type NativeTransaction = {
|
|
440
997
|
id: number;
|
|
441
998
|
new (context: NativeDatabase, options?: NativeTransactionOptions): NativeTransaction;
|
|
442
999
|
abort(): void;
|
|
443
|
-
commit(resolve: () => void, reject: (err: Error) => void): void;
|
|
1000
|
+
commit(resolve: (retrySignal?: number) => void, reject: (err: Error) => void): void;
|
|
444
1001
|
commitSync(): void;
|
|
445
|
-
get(keyLengthOrKeyBuffer: number | Buffer, resolve: (value: Buffer) => void, reject: (err: Error) => void): number;
|
|
1002
|
+
get(keyLengthOrKeyBuffer: number | Buffer, resolve: (value: Buffer | number) => void, reject: (err: Error) => void, txnIdIgnored?: number, expectedVersion?: number): number;
|
|
446
1003
|
getCount(options?: RangeOptions): number;
|
|
447
1004
|
getSync(keyLengthOrKeyBuffer: number | Buffer): Buffer | number | undefined;
|
|
448
1005
|
getTimestamp(): number;
|
|
@@ -469,10 +1026,71 @@ type TransactionEntry = {
|
|
|
469
1026
|
data: Buffer;
|
|
470
1027
|
endTxn: boolean;
|
|
471
1028
|
};
|
|
1029
|
+
/**
|
|
1030
|
+
* A position within a transaction log, identifying a log file by its sequence
|
|
1031
|
+
* number and a byte `offset` within that file.
|
|
1032
|
+
*/
|
|
1033
|
+
type TransactionLogPosition = {
|
|
1034
|
+
sequence: number;
|
|
1035
|
+
offset: number;
|
|
1036
|
+
};
|
|
1037
|
+
/**
|
|
1038
|
+
* A detailed statistics snapshot for a single transaction log store, returned
|
|
1039
|
+
* by {@link TransactionLog.getStats}. All sizes are in bytes; timestamps are
|
|
1040
|
+
* milliseconds since the Unix epoch.
|
|
1041
|
+
*
|
|
1042
|
+
* Memory note: `memory.mappedBytes` is virtual address space — the active write
|
|
1043
|
+
* file is mapped at the full configured `maxFileSize` on POSIX, so it does not
|
|
1044
|
+
* reflect resident memory. `memory.overlayBytes` (POSIX only; 0 on Windows) is
|
|
1045
|
+
* the file-backed portion and is the closer proxy for real consumption.
|
|
1046
|
+
*/
|
|
1047
|
+
type TransactionLogStats = {
|
|
1048
|
+
name: string;
|
|
1049
|
+
path: string;
|
|
1050
|
+
fileCount: number;
|
|
1051
|
+
currentSequenceNumber: number;
|
|
1052
|
+
oldestSequenceNumber: number;
|
|
1053
|
+
totalSizeBytes: number;
|
|
1054
|
+
currentFileSize: number;
|
|
1055
|
+
pendingTransactions: number;
|
|
1056
|
+
uncommittedTransactions: number;
|
|
1057
|
+
replayGapBytes: number;
|
|
1058
|
+
memory: {
|
|
1059
|
+
mappedBytes: number;
|
|
1060
|
+
overlayBytes: number;
|
|
1061
|
+
activeMaps: number;
|
|
1062
|
+
};
|
|
1063
|
+
nextLogPosition: TransactionLogPosition;
|
|
1064
|
+
lastFlushedPosition: TransactionLogPosition;
|
|
1065
|
+
lastCommittedPosition: TransactionLogPosition | null;
|
|
1066
|
+
purge: {
|
|
1067
|
+
oldestFileAgeMs: number;
|
|
1068
|
+
purgeableFiles: number;
|
|
1069
|
+
retainedUnflushedFiles: number;
|
|
1070
|
+
lastPurgeMs: number;
|
|
1071
|
+
};
|
|
1072
|
+
totals: {
|
|
1073
|
+
transactionsWritten: number;
|
|
1074
|
+
entriesWritten: number;
|
|
1075
|
+
bytesWritten: number;
|
|
1076
|
+
rotations: number;
|
|
1077
|
+
filesPurged: number;
|
|
1078
|
+
bytesPurged: number;
|
|
1079
|
+
purgeRuns: number;
|
|
1080
|
+
databaseFlushes: number;
|
|
1081
|
+
writeFailures: number;
|
|
1082
|
+
};
|
|
1083
|
+
config: {
|
|
1084
|
+
maxFileSize: number;
|
|
1085
|
+
retentionMs: number;
|
|
1086
|
+
maxAgeThreshold: number;
|
|
1087
|
+
};
|
|
1088
|
+
};
|
|
472
1089
|
type TransactionLog = {
|
|
473
1090
|
new (db: NativeDatabase, name: string): TransactionLog;
|
|
474
1091
|
addEntry(data: Buffer | Uint8Array, txnId?: number): void;
|
|
475
1092
|
getLogFileSize(sequenceId?: number): number;
|
|
1093
|
+
getStats(): TransactionLogStats;
|
|
476
1094
|
name: string;
|
|
477
1095
|
path: string;
|
|
478
1096
|
query(options?: TransactionLogQueryOptions): IterableIterator<TransactionEntry>;
|
|
@@ -531,6 +1149,13 @@ type NativeDatabaseOptions = {
|
|
|
531
1149
|
transactionLogMaxSize?: number;
|
|
532
1150
|
transactionLogRetentionMs?: number;
|
|
533
1151
|
transactionLogsPath?: string;
|
|
1152
|
+
/**
|
|
1153
|
+
* When true, transaction writes to this column family invalidate the
|
|
1154
|
+
* VerificationTable slot for each written key at write time (not at
|
|
1155
|
+
* commit time). Enable only for column families whose records are
|
|
1156
|
+
* cached (e.g. the primary CF of a table). Default: false.
|
|
1157
|
+
*/
|
|
1158
|
+
verificationTable?: boolean;
|
|
534
1159
|
writeBufferSize?: number;
|
|
535
1160
|
};
|
|
536
1161
|
type ResolveCallback<T> = (value: T) => void;
|
|
@@ -539,22 +1164,25 @@ type UserSharedBufferCallback = () => void;
|
|
|
539
1164
|
type PurgeLogsOptions = {
|
|
540
1165
|
before?: number;
|
|
541
1166
|
destroy?: boolean;
|
|
1167
|
+
/**
|
|
1168
|
+
* When `true`, count the entries in each purged log file (extra work) and
|
|
1169
|
+
* return `PurgedLog[]` instead of the default `string[]` of file paths.
|
|
1170
|
+
*/
|
|
1171
|
+
includeEntryCounts?: boolean;
|
|
542
1172
|
name?: string;
|
|
543
1173
|
};
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
percentile99: number;
|
|
552
|
-
standardDeviation: number;
|
|
553
|
-
sum: number;
|
|
1174
|
+
/**
|
|
1175
|
+
* A purged transaction log file and the number of entries it held, returned by
|
|
1176
|
+
* `purgeLogs()` when `includeEntryCounts` is `true`.
|
|
1177
|
+
*/
|
|
1178
|
+
type PurgedLog = {
|
|
1179
|
+
path: string;
|
|
1180
|
+
entries: number;
|
|
554
1181
|
};
|
|
555
1182
|
type NativeDatabase = {
|
|
556
1183
|
new (): NativeDatabase;
|
|
557
1184
|
addListener(event: string, callback: (...args: any[]) => void): void;
|
|
1185
|
+
backup(resolve: ResolveCallback<number>, reject: RejectCallback, backupDir: string, options?: BackupOptions): void;
|
|
558
1186
|
clear(resolve: ResolveCallback<void>, reject: RejectCallback): void;
|
|
559
1187
|
clearSync(): void;
|
|
560
1188
|
close(): void;
|
|
@@ -567,22 +1195,30 @@ type NativeDatabase = {
|
|
|
567
1195
|
flush(resolve: ResolveCallback<void>, reject: RejectCallback): void;
|
|
568
1196
|
flushSync(): void;
|
|
569
1197
|
notify(event: string | BufferWithDataView, args?: any[]): boolean;
|
|
570
|
-
get(keyLengthOrKeyBuffer: number | Buffer, resolve: ResolveCallback<Buffer>, reject: RejectCallback, txnId?: number): number;
|
|
1198
|
+
get(keyLengthOrKeyBuffer: number | Buffer, resolve: ResolveCallback<Buffer | number>, reject: RejectCallback, txnId?: number, expectedVersion?: number): number;
|
|
571
1199
|
getCount(options?: RangeOptions, txnId?: number): number;
|
|
572
1200
|
getDBIntProperty(propertyName: string): number | undefined;
|
|
573
1201
|
getDBProperty(propertyName: string): string | undefined;
|
|
574
1202
|
getMonotonicTimestamp(): number;
|
|
575
1203
|
getOldestSnapshotTimestamp(): number;
|
|
576
1204
|
getStat(statName: string): number | StatsHistogramData;
|
|
577
|
-
getStats(all?:
|
|
578
|
-
|
|
1205
|
+
getStats(all?: false): StatsDefault;
|
|
1206
|
+
getStats(all: true): StatsAll;
|
|
1207
|
+
getSync(keyLengthOrKeyBuffer: number | Buffer, flags: number, txnId?: number, expectedVersion?: number): Buffer;
|
|
579
1208
|
getUserSharedBuffer(key: BufferWithDataView, defaultBuffer: ArrayBuffer, callback?: UserSharedBufferCallback): ArrayBuffer;
|
|
580
1209
|
hasLock(key: BufferWithDataView): boolean;
|
|
581
1210
|
listeners(event: string | BufferWithDataView): number;
|
|
582
1211
|
listLogs(): string[];
|
|
583
1212
|
opened: boolean;
|
|
584
1213
|
open(path: string, options?: NativeDatabaseOptions): void;
|
|
585
|
-
|
|
1214
|
+
populateVersion(keyLengthOrKeyBuffer: number | Buffer, version: number): void;
|
|
1215
|
+
purgeLogs(options: PurgeLogsOptions & {
|
|
1216
|
+
includeEntryCounts: true;
|
|
1217
|
+
}): PurgedLog[];
|
|
1218
|
+
purgeLogs(options?: PurgeLogsOptions & {
|
|
1219
|
+
includeEntryCounts?: false;
|
|
1220
|
+
}): string[];
|
|
1221
|
+
purgeLogs(options?: PurgeLogsOptions): string[] | PurgedLog[];
|
|
586
1222
|
putSync(key: BufferWithDataView, value: any, txnId?: number): void;
|
|
587
1223
|
removeListener(event: string | BufferWithDataView, callback: () => void): boolean;
|
|
588
1224
|
removeSync(key: BufferWithDataView, txnId?: number): void;
|
|
@@ -592,10 +1228,19 @@ type NativeDatabase = {
|
|
|
592
1228
|
tryLock(key: BufferWithDataView, callback?: () => void): boolean;
|
|
593
1229
|
unlock(key: BufferWithDataView): void;
|
|
594
1230
|
useLog(name: string): TransactionLog;
|
|
1231
|
+
verifyVersion(keyLengthOrKeyBuffer: number | Buffer, version: number): boolean;
|
|
595
1232
|
withLock(key: BufferWithDataView, callback: () => void | Promise<void>): Promise<void>;
|
|
596
1233
|
};
|
|
597
1234
|
type RocksDatabaseConfig = {
|
|
598
1235
|
blockCacheSize?: number;
|
|
1236
|
+
/**
|
|
1237
|
+
* Number of slots in the process-global verification table. Each slot is
|
|
1238
|
+
* 8 bytes; the default of 128K slots is 1 MB. Set to 0 to disable.
|
|
1239
|
+
*
|
|
1240
|
+
* Must be configured before the first database is opened. Once the table
|
|
1241
|
+
* is materialized, attempts to change this value will throw.
|
|
1242
|
+
*/
|
|
1243
|
+
verificationTableEntries?: number;
|
|
599
1244
|
compactOnClose?: boolean;
|
|
600
1245
|
/**
|
|
601
1246
|
* Total memtable memory limit (bytes) shared across every database opened
|
|
@@ -647,6 +1292,14 @@ declare const constants: {
|
|
|
647
1292
|
ALWAYS_CREATE_NEW_BUFFER_FLAG: number;
|
|
648
1293
|
NOT_IN_MEMORY_CACHE_FLAG: number;
|
|
649
1294
|
ONLY_IF_IN_MEMORY_CACHE_FLAG: number;
|
|
1295
|
+
POPULATE_VERSION_FLAG: number;
|
|
1296
|
+
FRESH_VERSION_FLAG: number;
|
|
1297
|
+
/**
|
|
1298
|
+
* Sentinel value resolved (not rejected) by `commit()` when
|
|
1299
|
+
* `coordinatedRetry: true` and the transaction encountered an IsBusy
|
|
1300
|
+
* conflict. JS should retry the transaction body immediately.
|
|
1301
|
+
*/
|
|
1302
|
+
RETRY_NOW_VALUE: number;
|
|
650
1303
|
TRANSACTION_LOG_TOKEN: number;
|
|
651
1304
|
TRANSACTION_LOG_ENTRY_HEADER_SIZE: number;
|
|
652
1305
|
TRANSACTION_LOG_FILE_HEADER_SIZE: number;
|
|
@@ -665,9 +1318,24 @@ declare const TransactionLog: TransactionLog;
|
|
|
665
1318
|
declare const registryStatus: () => RegistryStatus;
|
|
666
1319
|
declare const shutdown: () => void;
|
|
667
1320
|
declare const currentThreadId: () => number;
|
|
1321
|
+
/**
|
|
1322
|
+
* Advises the kernel that the file-backed pages of every mapped transaction log
|
|
1323
|
+
* are cold (Linux MADV_COLD), so they are reclaimed first under memory pressure
|
|
1324
|
+
* without being freed — useful during replication catch-up, where a full read of
|
|
1325
|
+
* the logs would otherwise inflate the container's reclaimable cache toward its
|
|
1326
|
+
* cgroup limit. No-op on kernels < 5.4, macOS, and Windows.
|
|
1327
|
+
*
|
|
1328
|
+
* The transaction log registry is a process-global singleton shared across all
|
|
1329
|
+
* worker threads, so a single call cools every worker's maps. Call it on an
|
|
1330
|
+
* interval from one thread (e.g. an `unref()`ed timer on the main thread).
|
|
1331
|
+
*
|
|
1332
|
+
* @returns the number of maps cooled and total file-backed bytes advised.
|
|
1333
|
+
*/
|
|
1334
|
+
declare const coolTransactionLogs: () => {
|
|
1335
|
+
maps: number;
|
|
1336
|
+
bytes: number;
|
|
1337
|
+
};
|
|
668
1338
|
declare const stats: {
|
|
669
|
-
histograms: string[];
|
|
670
|
-
tickers: string[];
|
|
671
1339
|
StatsLevel: {
|
|
672
1340
|
DisableAll: number;
|
|
673
1341
|
ExceptTickers: number;
|
|
@@ -681,6 +1349,13 @@ declare const stats: {
|
|
|
681
1349
|
//#endregion
|
|
682
1350
|
//#region src/transaction.d.ts
|
|
683
1351
|
/**
|
|
1352
|
+
* Sentinel value returned by `commit()` when `coordinatedRetry: true` and the
|
|
1353
|
+
* transaction encountered an IsBusy conflict. The native layer parks on VT
|
|
1354
|
+
* slots and resolves only after the conflicting transaction releases its write
|
|
1355
|
+
* intent, so callers should retry immediately without any backoff delay.
|
|
1356
|
+
*/
|
|
1357
|
+
declare const RETRY_NOW: number;
|
|
1358
|
+
/**
|
|
684
1359
|
* Provides transaction level operations to a transaction callback.
|
|
685
1360
|
*/
|
|
686
1361
|
declare class Transaction extends DBI {
|
|
@@ -698,8 +1373,11 @@ declare class Transaction extends DBI {
|
|
|
698
1373
|
abort(): void;
|
|
699
1374
|
/**
|
|
700
1375
|
* Commit the transaction.
|
|
1376
|
+
*
|
|
1377
|
+
* Returns `RETRY_NOW` when `coordinatedRetry: true` and an IsBusy conflict
|
|
1378
|
+
* was detected. The caller should retry the transaction body immediately.
|
|
701
1379
|
*/
|
|
702
|
-
commit(): Promise<void>;
|
|
1380
|
+
commit(): Promise<typeof RETRY_NOW | void>;
|
|
703
1381
|
/**
|
|
704
1382
|
* Commit the transaction synchronously.
|
|
705
1383
|
*/
|
|
@@ -800,6 +1478,12 @@ interface RangeOptions extends RocksDBOptions {
|
|
|
800
1478
|
start?: Key | Uint8Array;
|
|
801
1479
|
}
|
|
802
1480
|
interface IteratorOptions extends RangeOptions {
|
|
1481
|
+
/**
|
|
1482
|
+
* The maximum number of entries to yield. When set, iteration stops after
|
|
1483
|
+
* `limit` entries regardless of the range bounds. Values <= 0 yield nothing.
|
|
1484
|
+
* Unset means no limit.
|
|
1485
|
+
*/
|
|
1486
|
+
limit?: number;
|
|
803
1487
|
/**
|
|
804
1488
|
* A specific key to match which may result in zero, one, or many values.
|
|
805
1489
|
*/
|
|
@@ -866,11 +1550,11 @@ declare class DBI<T extends DBITransactional | unknown = unknown> {
|
|
|
866
1550
|
*
|
|
867
1551
|
* Note: Used by HDBreplication.
|
|
868
1552
|
*/
|
|
869
|
-
getBinary(key: Key, options?: GetOptions & T): MaybePromise<Buffer | undefined>;
|
|
1553
|
+
getBinary(key: Key, options?: GetOptions & T): MaybePromise<Buffer | number | undefined>;
|
|
870
1554
|
/**
|
|
871
1555
|
* Synchronously retrieves the binary data for the given key.
|
|
872
1556
|
*/
|
|
873
|
-
getBinarySync(key: Key, options?: GetOptions & T): Buffer | undefined;
|
|
1557
|
+
getBinarySync(key: Key, options?: GetOptions & T): Buffer | number | undefined;
|
|
874
1558
|
/**
|
|
875
1559
|
* Retrieves the binary data for the given key using a preallocated,
|
|
876
1560
|
* reusable buffer. Data in the buffer is only valid until the next get
|
|
@@ -881,13 +1565,13 @@ declare class DBI<T extends DBITransactional | unknown = unknown> {
|
|
|
881
1565
|
* - `.byteLength` is set to the size of the full allocated memory area for
|
|
882
1566
|
* the buffer (usually much larger).
|
|
883
1567
|
*/
|
|
884
|
-
getBinaryFast(key: Key, options?: GetOptions & T): MaybePromise<Buffer | undefined>;
|
|
1568
|
+
getBinaryFast(key: Key, options?: GetOptions & T): MaybePromise<Buffer | number | undefined>;
|
|
885
1569
|
/**
|
|
886
1570
|
* Synchronously retrieves the binary data for the given key using a
|
|
887
1571
|
* preallocated, reusable buffer. Data in the buffer is only valid until the
|
|
888
1572
|
* next get operation (including cursor operations).
|
|
889
1573
|
*/
|
|
890
|
-
getBinaryFastSync(key: Key, options?: GetOptions & T): Buffer | undefined;
|
|
1574
|
+
getBinaryFastSync(key: Key, options?: GetOptions & T): Buffer | number | undefined;
|
|
891
1575
|
/**
|
|
892
1576
|
* Retrieves all keys within a range.
|
|
893
1577
|
*/
|
|
@@ -1061,8 +1745,8 @@ interface TransactionOptions extends NativeTransactionOptions {
|
|
|
1061
1745
|
*/
|
|
1062
1746
|
retryOnBusy?: boolean;
|
|
1063
1747
|
}
|
|
1064
|
-
type RocksDBStat =
|
|
1065
|
-
type RocksDBStats =
|
|
1748
|
+
type RocksDBStat = StatsValue;
|
|
1749
|
+
type RocksDBStats = StatsDefault | StatsAll;
|
|
1066
1750
|
/**
|
|
1067
1751
|
* The main class for interacting with a RocksDB database.
|
|
1068
1752
|
*
|
|
@@ -1121,6 +1805,24 @@ declare class RocksDatabase extends DBI<DBITransactional> {
|
|
|
1121
1805
|
*/
|
|
1122
1806
|
compact(options?: CompactOptions): Promise<void>;
|
|
1123
1807
|
/**
|
|
1808
|
+
* Creates a backup of the entire database (all column families) into the
|
|
1809
|
+
* given directory, creating parent directories as needed, and resolves with
|
|
1810
|
+
* the new backup id. Use the `backups` namespace to restore, list, delete,
|
|
1811
|
+
* purge, or verify backups.
|
|
1812
|
+
*
|
|
1813
|
+
* When the database was opened with `disableWAL`, the memtable is flushed
|
|
1814
|
+
* before the backup by default so unflushed data is not lost.
|
|
1815
|
+
*
|
|
1816
|
+
* @example
|
|
1817
|
+
* ```typescript
|
|
1818
|
+
* import { backups } from '@harperfast/rocksdb-js';
|
|
1819
|
+
*
|
|
1820
|
+
* const db = RocksDatabase.open('/path/to/database');
|
|
1821
|
+
* const id = await db.backup('/path/to/backups');
|
|
1822
|
+
* ```
|
|
1823
|
+
*/
|
|
1824
|
+
backup(backupDir: string, options?: BackupOptions): Promise<number>;
|
|
1825
|
+
/**
|
|
1124
1826
|
* Compacts the entire key range of the database synchronously.
|
|
1125
1827
|
* This triggers manual compaction which removes tombstones and reclaims space.
|
|
1126
1828
|
*
|
|
@@ -1265,15 +1967,22 @@ declare class RocksDatabase extends DBI<DBITransactional> {
|
|
|
1265
1967
|
*/
|
|
1266
1968
|
getStat(statName: string): RocksDBStat;
|
|
1267
1969
|
/**
|
|
1268
|
-
* Gets the RocksDB statistics.
|
|
1970
|
+
* Gets the RocksDB statistics. The RocksDB ticker/histogram stats require
|
|
1971
|
+
* statistics to be enabled, but the result always includes a summarized,
|
|
1972
|
+
* aggregate set of `txnlog.*` keys (across all of this database's transaction
|
|
1973
|
+
* logs), regardless of whether statistics are enabled. For detailed per-log
|
|
1974
|
+
* statistics, including memory-map usage, use `log.getStats()` on the log
|
|
1975
|
+
* returned by {@link RocksDatabase#useLog}.
|
|
1269
1976
|
*
|
|
1270
1977
|
* @example
|
|
1271
1978
|
* ```typescript
|
|
1272
1979
|
* const db = RocksDatabase.open('/path/to/database');
|
|
1273
1980
|
* const stats = db.getStats();
|
|
1981
|
+
* stats['txnlog.totalSizeBytes']; // bytes across all transaction logs
|
|
1274
1982
|
* ```
|
|
1275
1983
|
*/
|
|
1276
|
-
getStats(all?:
|
|
1984
|
+
getStats(all?: false): StatsDefault;
|
|
1985
|
+
getStats(all: true): StatsAll;
|
|
1277
1986
|
/**
|
|
1278
1987
|
* Gets or creates a buffer that can be shared across worker threads.
|
|
1279
1988
|
*
|
|
@@ -1311,6 +2020,26 @@ declare class RocksDatabase extends DBI<DBITransactional> {
|
|
|
1311
2020
|
hasLock(key: Key): boolean;
|
|
1312
2021
|
ifNoExists(_key: Key): Promise<void>;
|
|
1313
2022
|
/**
|
|
2023
|
+
* Checks the process-global verification table for a fresh version match
|
|
2024
|
+
* on `key`. Returns `true` when the table currently records `version`. Use
|
|
2025
|
+
* this as a fast cache-freshness check before falling back to a full read:
|
|
2026
|
+
*
|
|
2027
|
+
* ```typescript
|
|
2028
|
+
* if (db.verifyVersion(key, cachedEntry.version)) {
|
|
2029
|
+
* return cachedEntry.value;
|
|
2030
|
+
* }
|
|
2031
|
+
* const value = db.getSync(key);
|
|
2032
|
+
* db.populateVersion(key, extractVersion(value));
|
|
2033
|
+
* ```
|
|
2034
|
+
*/
|
|
2035
|
+
verifyVersion(key: Key, version: number): boolean;
|
|
2036
|
+
/**
|
|
2037
|
+
* Seeds the verification-table slot for `key` with `version`. Has no
|
|
2038
|
+
* effect if the slot is currently lock-tagged or if the verification
|
|
2039
|
+
* table is disabled.
|
|
2040
|
+
*/
|
|
2041
|
+
populateVersion(key: Key, version: number): void;
|
|
2042
|
+
/**
|
|
1314
2043
|
* Returns whether the database is open.
|
|
1315
2044
|
*
|
|
1316
2045
|
* @returns `true` if the database is open, `false` otherwise.
|
|
@@ -1362,8 +2091,18 @@ declare class RocksDatabase extends DBI<DBITransactional> {
|
|
|
1362
2091
|
get path(): string;
|
|
1363
2092
|
/**
|
|
1364
2093
|
* Purges transaction logs.
|
|
2094
|
+
*
|
|
2095
|
+
* By default returns the paths of the deleted log files. Pass
|
|
2096
|
+
* `includeEntryCounts: true` to instead return, for each deleted file, its
|
|
2097
|
+
* path and the number of entries it held (`{ path, entries }`).
|
|
1365
2098
|
*/
|
|
1366
|
-
purgeLogs(options
|
|
2099
|
+
purgeLogs(options: PurgeLogsOptions & {
|
|
2100
|
+
includeEntryCounts: true;
|
|
2101
|
+
}): PurgedLog[];
|
|
2102
|
+
purgeLogs(options?: PurgeLogsOptions & {
|
|
2103
|
+
includeEntryCounts?: false;
|
|
2104
|
+
}): string[];
|
|
2105
|
+
purgeLogs(options?: PurgeLogsOptions): string[] | PurgedLog[];
|
|
1367
2106
|
/**
|
|
1368
2107
|
* The status of the database.
|
|
1369
2108
|
*/
|
|
@@ -1486,5 +2225,5 @@ declare const versions: {
|
|
|
1486
2225
|
"rocksdb-js": string;
|
|
1487
2226
|
};
|
|
1488
2227
|
//#endregion
|
|
1489
|
-
export { DBI, DBIterator, type IteratorOptions, type Key, type RocksDBStat, type RocksDBStats, RocksDatabase, type RocksDatabaseOptions, type StatsHistogramData, Store, type StoreContext, type StoreGetOptions, type StoreIteratorOptions, type StorePutOptions, type StoreRangeOptions, type StoreRemoveOptions, Transaction, type TransactionEntry, TransactionLog, constants, currentThreadId, parseTransactionLog, registryStatus, shutdown, stats, versions };
|
|
2228
|
+
export { type BackupInfo, type BackupOptions, DBI, DBIterator, type GetStatsMethod, type IteratorOptions, type Key, type RestoreMode, type RestoreOptions, type RocksDBStat, type RocksDBStats, RocksDatabase, type RocksDatabaseOptions, type StatsAll, type StatsAllExtras, type StatsBasics, type StatsCurated, type StatsCuratedExtras, type StatsDefault, type StatsHistogramData, type StatsValue, Store, type StoreContext, type StoreGetOptions, type StoreIteratorOptions, type StorePutOptions, type StoreRangeOptions, type StoreRemoveOptions, Transaction, type TransactionEntry, TransactionLog, type TransactionLogPosition, type TransactionLogStats, backups, constants, coolTransactionLogs, currentThreadId, parseTransactionLog, registryStatus, shutdown, stats, versions };
|
|
1490
2229
|
//# sourceMappingURL=index.d.cts.map
|