@harperfast/rocksdb-js 2.1.0 → 2.3.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 +292 -12
- package/bin/rocksdb-js.mjs +290 -2
- package/dist/index.cjs +257 -24
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +355 -14
- package/dist/index.d.mts +355 -14
- package/dist/index.mjs +257 -26
- package/dist/index.mjs.map +1 -1
- package/package.json +16 -16
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 {
|
|
@@ -416,7 +551,7 @@ declare class DBIterator<T> implements Iterator<DBIteratorValue<T>> {
|
|
|
416
551
|
#private;
|
|
417
552
|
iterator: InstanceType<typeof NativeIteratorCls>;
|
|
418
553
|
store: Store;
|
|
419
|
-
constructor(iterator: InstanceType<typeof NativeIteratorCls>, store: Store, includeValues: boolean);
|
|
554
|
+
constructor(iterator: InstanceType<typeof NativeIteratorCls>, store: Store, includeValues: boolean, limit?: number);
|
|
420
555
|
[Symbol.iterator](): Iterator<DBIteratorValue<T>>;
|
|
421
556
|
next(): IteratorResult<DBIteratorValue<T>>;
|
|
422
557
|
return(value?: any): IteratorResult<DBIteratorValue<T>, any>;
|
|
@@ -626,6 +761,10 @@ declare class Store {
|
|
|
626
761
|
*/
|
|
627
762
|
transactionLogsPath?: string;
|
|
628
763
|
/**
|
|
764
|
+
* Whether this store's column family participates in the VerificationTable.
|
|
765
|
+
*/
|
|
766
|
+
verificationTable?: boolean;
|
|
767
|
+
/**
|
|
629
768
|
* The per-column-family memtable size in bytes at which the memtable is
|
|
630
769
|
* sealed and flushed.
|
|
631
770
|
*/
|
|
@@ -657,6 +796,17 @@ declare class Store {
|
|
|
657
796
|
*/
|
|
658
797
|
compact(options?: CompactOptions): Promise<void>;
|
|
659
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
|
+
/**
|
|
660
810
|
* Compacts the entire key range of the database synchronously.
|
|
661
811
|
* This triggers manual compaction which removes tombstones and reclaims space.
|
|
662
812
|
*
|
|
@@ -695,7 +845,7 @@ declare class Store {
|
|
|
695
845
|
* @returns The encoded value.
|
|
696
846
|
*/
|
|
697
847
|
encodeValue(value: any): BufferWithDataView | Uint8Array;
|
|
698
|
-
get(context: StoreContext, key: Key, alwaysCreateNewBuffer?: boolean,
|
|
848
|
+
get(context: StoreContext, key: Key, alwaysCreateNewBuffer?: boolean, options?: StoreGetOptions): any | undefined;
|
|
699
849
|
getCount(context: StoreContext, options?: StoreRangeOptions): number;
|
|
700
850
|
getKeys(context: StoreContext, options?: StoreIteratorOptions): any | undefined;
|
|
701
851
|
getKeysCount(context: StoreContext, options?: StoreRangeOptions): number;
|
|
@@ -772,6 +922,19 @@ declare class Store {
|
|
|
772
922
|
*/
|
|
773
923
|
useLog(context: StoreContext, name: string | number): TransactionLog;
|
|
774
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
|
+
/**
|
|
775
938
|
* Acquires a lock on the given key and calls the callback.
|
|
776
939
|
*
|
|
777
940
|
* @param key - The key to lock.
|
|
@@ -781,6 +944,21 @@ declare class Store {
|
|
|
781
944
|
withLock(key: Key, callback: () => void | Promise<void>): Promise<void>;
|
|
782
945
|
}
|
|
783
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;
|
|
784
962
|
/**
|
|
785
963
|
* Whether to skip decoding the value.
|
|
786
964
|
*
|
|
@@ -803,14 +981,25 @@ type NativeTransactionOptions = {
|
|
|
803
981
|
* @default false
|
|
804
982
|
*/
|
|
805
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;
|
|
806
995
|
};
|
|
807
996
|
type NativeTransaction = {
|
|
808
997
|
id: number;
|
|
809
998
|
new (context: NativeDatabase, options?: NativeTransactionOptions): NativeTransaction;
|
|
810
999
|
abort(): void;
|
|
811
|
-
commit(resolve: () => void, reject: (err: Error) => void): void;
|
|
1000
|
+
commit(resolve: (retrySignal?: number) => void, reject: (err: Error) => void): void;
|
|
812
1001
|
commitSync(): void;
|
|
813
|
-
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;
|
|
814
1003
|
getCount(options?: RangeOptions): number;
|
|
815
1004
|
getSync(keyLengthOrKeyBuffer: number | Buffer): Buffer | number | undefined;
|
|
816
1005
|
getTimestamp(): number;
|
|
@@ -960,6 +1149,13 @@ type NativeDatabaseOptions = {
|
|
|
960
1149
|
transactionLogMaxSize?: number;
|
|
961
1150
|
transactionLogRetentionMs?: number;
|
|
962
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;
|
|
963
1159
|
writeBufferSize?: number;
|
|
964
1160
|
};
|
|
965
1161
|
type ResolveCallback<T> = (value: T) => void;
|
|
@@ -968,24 +1164,39 @@ type UserSharedBufferCallback = () => void;
|
|
|
968
1164
|
type PurgeLogsOptions = {
|
|
969
1165
|
before?: number;
|
|
970
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;
|
|
971
1172
|
name?: string;
|
|
972
1173
|
};
|
|
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;
|
|
1181
|
+
};
|
|
973
1182
|
type NativeDatabase = {
|
|
974
1183
|
new (): NativeDatabase;
|
|
975
1184
|
addListener(event: string, callback: (...args: any[]) => void): void;
|
|
1185
|
+
backup(resolve: ResolveCallback<number>, reject: RejectCallback, backupDir: string, options?: BackupOptions): void;
|
|
976
1186
|
clear(resolve: ResolveCallback<void>, reject: RejectCallback): void;
|
|
977
1187
|
clearSync(): void;
|
|
978
1188
|
close(): void;
|
|
979
1189
|
compact(resolve: ResolveCallback<void>, reject: RejectCallback, start?: Key, end?: Key): void;
|
|
980
1190
|
compactSync(start?: Key, end?: Key): void;
|
|
981
1191
|
columns: string[];
|
|
1192
|
+
createCheckpoint(resolve: ResolveCallback<void>, reject: RejectCallback, targetPath: string): void;
|
|
982
1193
|
destroy(): void;
|
|
983
1194
|
drop(resolve: ResolveCallback<void>, reject: RejectCallback): void;
|
|
984
1195
|
dropSync(): void;
|
|
985
1196
|
flush(resolve: ResolveCallback<void>, reject: RejectCallback): void;
|
|
986
1197
|
flushSync(): void;
|
|
987
1198
|
notify(event: string | BufferWithDataView, args?: any[]): boolean;
|
|
988
|
-
get(keyLengthOrKeyBuffer: number | Buffer, resolve: ResolveCallback<Buffer>, reject: RejectCallback, txnId?: number): number;
|
|
1199
|
+
get(keyLengthOrKeyBuffer: number | Buffer, resolve: ResolveCallback<Buffer | number>, reject: RejectCallback, txnId?: number, expectedVersion?: number): number;
|
|
989
1200
|
getCount(options?: RangeOptions, txnId?: number): number;
|
|
990
1201
|
getDBIntProperty(propertyName: string): number | undefined;
|
|
991
1202
|
getDBProperty(propertyName: string): string | undefined;
|
|
@@ -994,14 +1205,21 @@ type NativeDatabase = {
|
|
|
994
1205
|
getStat(statName: string): number | StatsHistogramData;
|
|
995
1206
|
getStats(all?: false): StatsDefault;
|
|
996
1207
|
getStats(all: true): StatsAll;
|
|
997
|
-
getSync(keyLengthOrKeyBuffer: number | Buffer, flags: number, txnId?: number): Buffer;
|
|
1208
|
+
getSync(keyLengthOrKeyBuffer: number | Buffer, flags: number, txnId?: number, expectedVersion?: number): Buffer;
|
|
998
1209
|
getUserSharedBuffer(key: BufferWithDataView, defaultBuffer: ArrayBuffer, callback?: UserSharedBufferCallback): ArrayBuffer;
|
|
999
1210
|
hasLock(key: BufferWithDataView): boolean;
|
|
1000
1211
|
listeners(event: string | BufferWithDataView): number;
|
|
1001
1212
|
listLogs(): string[];
|
|
1002
1213
|
opened: boolean;
|
|
1003
1214
|
open(path: string, options?: NativeDatabaseOptions): void;
|
|
1004
|
-
|
|
1215
|
+
populateVersion(keyLengthOrKeyBuffer: number | Buffer, version: number): void;
|
|
1216
|
+
purgeLogs(options: PurgeLogsOptions & {
|
|
1217
|
+
includeEntryCounts: true;
|
|
1218
|
+
}): PurgedLog[];
|
|
1219
|
+
purgeLogs(options?: PurgeLogsOptions & {
|
|
1220
|
+
includeEntryCounts?: false;
|
|
1221
|
+
}): string[];
|
|
1222
|
+
purgeLogs(options?: PurgeLogsOptions): string[] | PurgedLog[];
|
|
1005
1223
|
putSync(key: BufferWithDataView, value: any, txnId?: number): void;
|
|
1006
1224
|
removeListener(event: string | BufferWithDataView, callback: () => void): boolean;
|
|
1007
1225
|
removeSync(key: BufferWithDataView, txnId?: number): void;
|
|
@@ -1011,10 +1229,19 @@ type NativeDatabase = {
|
|
|
1011
1229
|
tryLock(key: BufferWithDataView, callback?: () => void): boolean;
|
|
1012
1230
|
unlock(key: BufferWithDataView): void;
|
|
1013
1231
|
useLog(name: string): TransactionLog;
|
|
1232
|
+
verifyVersion(keyLengthOrKeyBuffer: number | Buffer, version: number): boolean;
|
|
1014
1233
|
withLock(key: BufferWithDataView, callback: () => void | Promise<void>): Promise<void>;
|
|
1015
1234
|
};
|
|
1016
1235
|
type RocksDatabaseConfig = {
|
|
1017
1236
|
blockCacheSize?: number;
|
|
1237
|
+
/**
|
|
1238
|
+
* Number of slots in the process-global verification table. Each slot is
|
|
1239
|
+
* 8 bytes; the default of 128K slots is 1 MB. Set to 0 to disable.
|
|
1240
|
+
*
|
|
1241
|
+
* Must be configured before the first database is opened. Once the table
|
|
1242
|
+
* is materialized, attempts to change this value will throw.
|
|
1243
|
+
*/
|
|
1244
|
+
verificationTableEntries?: number;
|
|
1018
1245
|
compactOnClose?: boolean;
|
|
1019
1246
|
/**
|
|
1020
1247
|
* Total memtable memory limit (bytes) shared across every database opened
|
|
@@ -1066,6 +1293,14 @@ declare const constants: {
|
|
|
1066
1293
|
ALWAYS_CREATE_NEW_BUFFER_FLAG: number;
|
|
1067
1294
|
NOT_IN_MEMORY_CACHE_FLAG: number;
|
|
1068
1295
|
ONLY_IF_IN_MEMORY_CACHE_FLAG: number;
|
|
1296
|
+
POPULATE_VERSION_FLAG: number;
|
|
1297
|
+
FRESH_VERSION_FLAG: number;
|
|
1298
|
+
/**
|
|
1299
|
+
* Sentinel value resolved (not rejected) by `commit()` when
|
|
1300
|
+
* `coordinatedRetry: true` and the transaction encountered an IsBusy
|
|
1301
|
+
* conflict. JS should retry the transaction body immediately.
|
|
1302
|
+
*/
|
|
1303
|
+
RETRY_NOW_VALUE: number;
|
|
1069
1304
|
TRANSACTION_LOG_TOKEN: number;
|
|
1070
1305
|
TRANSACTION_LOG_ENTRY_HEADER_SIZE: number;
|
|
1071
1306
|
TRANSACTION_LOG_FILE_HEADER_SIZE: number;
|
|
@@ -1084,6 +1319,23 @@ declare const TransactionLog: TransactionLog;
|
|
|
1084
1319
|
declare const registryStatus: () => RegistryStatus;
|
|
1085
1320
|
declare const shutdown: () => void;
|
|
1086
1321
|
declare const currentThreadId: () => number;
|
|
1322
|
+
/**
|
|
1323
|
+
* Advises the kernel that the file-backed pages of every mapped transaction log
|
|
1324
|
+
* are cold (Linux MADV_COLD), so they are reclaimed first under memory pressure
|
|
1325
|
+
* without being freed — useful during replication catch-up, where a full read of
|
|
1326
|
+
* the logs would otherwise inflate the container's reclaimable cache toward its
|
|
1327
|
+
* cgroup limit. No-op on kernels < 5.4, macOS, and Windows.
|
|
1328
|
+
*
|
|
1329
|
+
* The transaction log registry is a process-global singleton shared across all
|
|
1330
|
+
* worker threads, so a single call cools every worker's maps. Call it on an
|
|
1331
|
+
* interval from one thread (e.g. an `unref()`ed timer on the main thread).
|
|
1332
|
+
*
|
|
1333
|
+
* @returns the number of maps cooled and total file-backed bytes advised.
|
|
1334
|
+
*/
|
|
1335
|
+
declare const coolTransactionLogs: () => {
|
|
1336
|
+
maps: number;
|
|
1337
|
+
bytes: number;
|
|
1338
|
+
};
|
|
1087
1339
|
declare const stats: {
|
|
1088
1340
|
StatsLevel: {
|
|
1089
1341
|
DisableAll: number;
|
|
@@ -1098,6 +1350,13 @@ declare const stats: {
|
|
|
1098
1350
|
//#endregion
|
|
1099
1351
|
//#region src/transaction.d.ts
|
|
1100
1352
|
/**
|
|
1353
|
+
* Sentinel value returned by `commit()` when `coordinatedRetry: true` and the
|
|
1354
|
+
* transaction encountered an IsBusy conflict. The native layer parks on VT
|
|
1355
|
+
* slots and resolves only after the conflicting transaction releases its write
|
|
1356
|
+
* intent, so callers should retry immediately without any backoff delay.
|
|
1357
|
+
*/
|
|
1358
|
+
declare const RETRY_NOW: number;
|
|
1359
|
+
/**
|
|
1101
1360
|
* Provides transaction level operations to a transaction callback.
|
|
1102
1361
|
*/
|
|
1103
1362
|
declare class Transaction extends DBI {
|
|
@@ -1115,8 +1374,11 @@ declare class Transaction extends DBI {
|
|
|
1115
1374
|
abort(): void;
|
|
1116
1375
|
/**
|
|
1117
1376
|
* Commit the transaction.
|
|
1377
|
+
*
|
|
1378
|
+
* Returns `RETRY_NOW` when `coordinatedRetry: true` and an IsBusy conflict
|
|
1379
|
+
* was detected. The caller should retry the transaction body immediately.
|
|
1118
1380
|
*/
|
|
1119
|
-
commit(): Promise<void>;
|
|
1381
|
+
commit(): Promise<typeof RETRY_NOW | void>;
|
|
1120
1382
|
/**
|
|
1121
1383
|
* Commit the transaction synchronously.
|
|
1122
1384
|
*/
|
|
@@ -1217,6 +1479,12 @@ interface RangeOptions extends RocksDBOptions {
|
|
|
1217
1479
|
start?: Key | Uint8Array;
|
|
1218
1480
|
}
|
|
1219
1481
|
interface IteratorOptions extends RangeOptions {
|
|
1482
|
+
/**
|
|
1483
|
+
* The maximum number of entries to yield. When set, iteration stops after
|
|
1484
|
+
* `limit` entries regardless of the range bounds. Values <= 0 yield nothing.
|
|
1485
|
+
* Unset means no limit.
|
|
1486
|
+
*/
|
|
1487
|
+
limit?: number;
|
|
1220
1488
|
/**
|
|
1221
1489
|
* A specific key to match which may result in zero, one, or many values.
|
|
1222
1490
|
*/
|
|
@@ -1283,11 +1551,11 @@ declare class DBI<T extends DBITransactional | unknown = unknown> {
|
|
|
1283
1551
|
*
|
|
1284
1552
|
* Note: Used by HDBreplication.
|
|
1285
1553
|
*/
|
|
1286
|
-
getBinary(key: Key, options?: GetOptions & T): MaybePromise<Buffer | undefined>;
|
|
1554
|
+
getBinary(key: Key, options?: GetOptions & T): MaybePromise<Buffer | number | undefined>;
|
|
1287
1555
|
/**
|
|
1288
1556
|
* Synchronously retrieves the binary data for the given key.
|
|
1289
1557
|
*/
|
|
1290
|
-
getBinarySync(key: Key, options?: GetOptions & T): Buffer | undefined;
|
|
1558
|
+
getBinarySync(key: Key, options?: GetOptions & T): Buffer | number | undefined;
|
|
1291
1559
|
/**
|
|
1292
1560
|
* Retrieves the binary data for the given key using a preallocated,
|
|
1293
1561
|
* reusable buffer. Data in the buffer is only valid until the next get
|
|
@@ -1298,13 +1566,13 @@ declare class DBI<T extends DBITransactional | unknown = unknown> {
|
|
|
1298
1566
|
* - `.byteLength` is set to the size of the full allocated memory area for
|
|
1299
1567
|
* the buffer (usually much larger).
|
|
1300
1568
|
*/
|
|
1301
|
-
getBinaryFast(key: Key, options?: GetOptions & T): MaybePromise<Buffer | undefined>;
|
|
1569
|
+
getBinaryFast(key: Key, options?: GetOptions & T): MaybePromise<Buffer | number | undefined>;
|
|
1302
1570
|
/**
|
|
1303
1571
|
* Synchronously retrieves the binary data for the given key using a
|
|
1304
1572
|
* preallocated, reusable buffer. Data in the buffer is only valid until the
|
|
1305
1573
|
* next get operation (including cursor operations).
|
|
1306
1574
|
*/
|
|
1307
|
-
getBinaryFastSync(key: Key, options?: GetOptions & T): Buffer | undefined;
|
|
1575
|
+
getBinaryFastSync(key: Key, options?: GetOptions & T): Buffer | number | undefined;
|
|
1308
1576
|
/**
|
|
1309
1577
|
* Retrieves all keys within a range.
|
|
1310
1578
|
*/
|
|
@@ -1538,6 +1806,49 @@ declare class RocksDatabase extends DBI<DBITransactional> {
|
|
|
1538
1806
|
*/
|
|
1539
1807
|
compact(options?: CompactOptions): Promise<void>;
|
|
1540
1808
|
/**
|
|
1809
|
+
* Creates a backup of the entire database (all column families) into the
|
|
1810
|
+
* given directory, creating parent directories as needed, and resolves with
|
|
1811
|
+
* the new backup id. Use the `backups` namespace to restore, list, delete,
|
|
1812
|
+
* purge, or verify backups.
|
|
1813
|
+
*
|
|
1814
|
+
* When the database was opened with `disableWAL`, the memtable is flushed
|
|
1815
|
+
* before the backup by default so unflushed data is not lost.
|
|
1816
|
+
*
|
|
1817
|
+
* @example
|
|
1818
|
+
* ```typescript
|
|
1819
|
+
* import { backups } from '@harperfast/rocksdb-js';
|
|
1820
|
+
*
|
|
1821
|
+
* const db = RocksDatabase.open('/path/to/database');
|
|
1822
|
+
* const id = await db.backup('/path/to/backups');
|
|
1823
|
+
* ```
|
|
1824
|
+
*/
|
|
1825
|
+
backup(backupDir: string, options?: BackupOptions): Promise<number>;
|
|
1826
|
+
/**
|
|
1827
|
+
* Creates a hardlinked, point-in-time, fully independent copy of the entire
|
|
1828
|
+
* database (all column families) at `targetPath` and resolves once written.
|
|
1829
|
+
*
|
|
1830
|
+
* Unlike a backup, a checkpoint is a normal, writable sibling database: open
|
|
1831
|
+
* it with {@link RocksDatabase.open} and it diverges independently from the
|
|
1832
|
+
* source. SST and blob files are hardlinked when `targetPath` is on the same
|
|
1833
|
+
* filesystem as the database and copied otherwise (other files such as the
|
|
1834
|
+
* MANIFEST are always copied), so the operation is near-instant on the same
|
|
1835
|
+
* filesystem. The memtable is flushed so the checkpoint includes the latest
|
|
1836
|
+
* writes even when the WAL is disabled.
|
|
1837
|
+
*
|
|
1838
|
+
* Parent directories are created as needed. `targetPath` itself must not
|
|
1839
|
+
* already exist (RocksDB creates the checkpoint directory) and rejects with
|
|
1840
|
+
* `Create checkpoint failed: target path exists` if it does. The caller is
|
|
1841
|
+
* responsible for eventual cleanup of the directory.
|
|
1842
|
+
*
|
|
1843
|
+
* @example
|
|
1844
|
+
* ```typescript
|
|
1845
|
+
* const db = RocksDatabase.open('/path/to/database');
|
|
1846
|
+
* await db.createCheckpoint('/path/to/checkpoint');
|
|
1847
|
+
* const branch = RocksDatabase.open('/path/to/checkpoint');
|
|
1848
|
+
* ```
|
|
1849
|
+
*/
|
|
1850
|
+
createCheckpoint(targetPath: string): Promise<void>;
|
|
1851
|
+
/**
|
|
1541
1852
|
* Compacts the entire key range of the database synchronously.
|
|
1542
1853
|
* This triggers manual compaction which removes tombstones and reclaims space.
|
|
1543
1854
|
*
|
|
@@ -1735,6 +2046,26 @@ declare class RocksDatabase extends DBI<DBITransactional> {
|
|
|
1735
2046
|
hasLock(key: Key): boolean;
|
|
1736
2047
|
ifNoExists(_key: Key): Promise<void>;
|
|
1737
2048
|
/**
|
|
2049
|
+
* Checks the process-global verification table for a fresh version match
|
|
2050
|
+
* on `key`. Returns `true` when the table currently records `version`. Use
|
|
2051
|
+
* this as a fast cache-freshness check before falling back to a full read:
|
|
2052
|
+
*
|
|
2053
|
+
* ```typescript
|
|
2054
|
+
* if (db.verifyVersion(key, cachedEntry.version)) {
|
|
2055
|
+
* return cachedEntry.value;
|
|
2056
|
+
* }
|
|
2057
|
+
* const value = db.getSync(key);
|
|
2058
|
+
* db.populateVersion(key, extractVersion(value));
|
|
2059
|
+
* ```
|
|
2060
|
+
*/
|
|
2061
|
+
verifyVersion(key: Key, version: number): boolean;
|
|
2062
|
+
/**
|
|
2063
|
+
* Seeds the verification-table slot for `key` with `version`. Has no
|
|
2064
|
+
* effect if the slot is currently lock-tagged or if the verification
|
|
2065
|
+
* table is disabled.
|
|
2066
|
+
*/
|
|
2067
|
+
populateVersion(key: Key, version: number): void;
|
|
2068
|
+
/**
|
|
1738
2069
|
* Returns whether the database is open.
|
|
1739
2070
|
*
|
|
1740
2071
|
* @returns `true` if the database is open, `false` otherwise.
|
|
@@ -1786,8 +2117,18 @@ declare class RocksDatabase extends DBI<DBITransactional> {
|
|
|
1786
2117
|
get path(): string;
|
|
1787
2118
|
/**
|
|
1788
2119
|
* Purges transaction logs.
|
|
2120
|
+
*
|
|
2121
|
+
* By default returns the paths of the deleted log files. Pass
|
|
2122
|
+
* `includeEntryCounts: true` to instead return, for each deleted file, its
|
|
2123
|
+
* path and the number of entries it held (`{ path, entries }`).
|
|
1789
2124
|
*/
|
|
1790
|
-
purgeLogs(options
|
|
2125
|
+
purgeLogs(options: PurgeLogsOptions & {
|
|
2126
|
+
includeEntryCounts: true;
|
|
2127
|
+
}): PurgedLog[];
|
|
2128
|
+
purgeLogs(options?: PurgeLogsOptions & {
|
|
2129
|
+
includeEntryCounts?: false;
|
|
2130
|
+
}): string[];
|
|
2131
|
+
purgeLogs(options?: PurgeLogsOptions): string[] | PurgedLog[];
|
|
1791
2132
|
/**
|
|
1792
2133
|
* The status of the database.
|
|
1793
2134
|
*/
|
|
@@ -1910,5 +2251,5 @@ declare const versions: {
|
|
|
1910
2251
|
"rocksdb-js": string;
|
|
1911
2252
|
};
|
|
1912
2253
|
//#endregion
|
|
1913
|
-
export { DBI, DBIterator, type GetStatsMethod, type IteratorOptions, type Key, 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, constants, currentThreadId, parseTransactionLog, registryStatus, shutdown, stats, versions };
|
|
2254
|
+
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 };
|
|
1914
2255
|
//# sourceMappingURL=index.d.cts.map
|