-
Notifications
You must be signed in to change notification settings - Fork 208
/
ECDb.ts
381 lines (355 loc) · 16.5 KB
/
ECDb.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
/*---------------------------------------------------------------------------------------------
* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
* See LICENSE.md in the project root for license terms and full copyright notice.
*--------------------------------------------------------------------------------------------*/
/** @packageDocumentation
* @module ECDb
*/
import { assert, DbResult, IDisposable, Logger, OpenMode } from "@itwin/core-bentley";
import { IModelJsNative } from "@bentley/imodeljs-native";
import { DbQueryRequest, ECSchemaProps, ECSqlReader, IModelError, QueryBinder, QueryOptions, QueryOptionsBuilder } from "@itwin/core-common";
import { BackendLoggerCategory } from "./BackendLoggerCategory";
import { ConcurrentQuery } from "./ConcurrentQuery";
import { ECSqlStatement } from "./ECSqlStatement";
import { IModelHost } from "./IModelHost";
import { SqliteStatement, StatementCache } from "./SqliteStatement";
const loggerCategory: string = BackendLoggerCategory.ECDb;
/** Modes for how to open [ECDb]($backend) files.
* @public
*/
export enum ECDbOpenMode {
Readonly,
ReadWrite,
/** Opens the file read-write and upgrades the file if necessary to the latest file format version. */
FileUpgrade,
}
/** An ECDb file
* @public
*/
export class ECDb implements IDisposable {
private _nativeDb?: IModelJsNative.ECDb;
private readonly _statementCache = new StatementCache<ECSqlStatement>();
private _sqliteStatementCache = new StatementCache<SqliteStatement>();
/** only for tests
* @internal
*/
public resetSqliteCache(size: number) {
this._sqliteStatementCache.clear();
this._sqliteStatementCache = new StatementCache<SqliteStatement>(size);
}
constructor() {
this._nativeDb = new IModelHost.platform.ECDb();
}
/** Call this function when finished with this ECDb object. This releases the native resources held by the
* ECDb object.
*/
public dispose(): void {
if (!this._nativeDb)
return;
this.closeDb();
this._nativeDb.dispose();
this._nativeDb = undefined;
}
/** Create an ECDb
* @param pathName The path to the ECDb file to create.
* @throws [IModelError]($common) if the operation failed.
*/
public createDb(pathName: string): void {
const status: DbResult = this.nativeDb.createDb(pathName);
if (status !== DbResult.BE_SQLITE_OK)
throw new IModelError(status, "Failed to created ECDb");
}
/** Open the ECDb.
* @param pathName The path to the ECDb file to open
* @param openMode Open mode
* @throws [IModelError]($common) if the operation failed.
*/
public openDb(pathName: string, openMode: ECDbOpenMode = ECDbOpenMode.Readonly): void {
const nativeOpenMode: OpenMode = openMode === ECDbOpenMode.Readonly ? OpenMode.Readonly : OpenMode.ReadWrite;
const tryUpgrade: boolean = openMode === ECDbOpenMode.FileUpgrade;
const status: DbResult = this.nativeDb.openDb(pathName, nativeOpenMode, tryUpgrade);
if (status !== DbResult.BE_SQLITE_OK)
throw new IModelError(status, "Failed to open ECDb");
}
/** Returns true if the ECDb is open */
public get isOpen(): boolean { return this.nativeDb.isOpen(); }
/** Close the Db after saving any uncommitted changes.
* @throws [IModelError]($common) if the database is not open.
*/
public closeDb(): void {
this._statementCache.clear();
this._sqliteStatementCache.clear();
this.nativeDb.closeDb();
}
/** @internal use to test statement caching */
public clearStatementCache() {
this._statementCache.clear();
}
/** @internal use to test statement caching */
public getCachedStatementCount() {
return this._statementCache.size;
}
/** Commit the outermost transaction, writing changes to the file. Then, restart the transaction.
* @param changesetName The name of the operation that generated these changes.
* @throws [IModelError]($common) if the database is not open or if the operation failed.
*/
public saveChanges(changesetName?: string): void {
const status: DbResult = this.nativeDb.saveChanges(changesetName);
if (status !== DbResult.BE_SQLITE_OK)
throw new IModelError(status, "Failed to save changes");
}
/** Abandon (cancel) the outermost transaction, discarding all changes since last save. Then, restart the transaction.
* @throws [IModelError]($common) if the database is not open or if the operation failed.
*/
public abandonChanges(): void {
const status: DbResult = this.nativeDb.abandonChanges();
if (status !== DbResult.BE_SQLITE_OK)
throw new IModelError(status, "Failed to abandon changes");
}
/** Import a schema.
*
* If the import was successful, the database is automatically saved to disk.
* @param pathName Path to ECSchema XML file to import.
* @throws [IModelError]($common) if the database is not open or if the operation failed.
*/
public importSchema(pathName: string): void {
const status: DbResult = this.nativeDb.importSchema(pathName);
if (status !== DbResult.BE_SQLITE_OK) {
Logger.logError(loggerCategory, `Failed to import schema from '${pathName}'.`);
throw new IModelError(status, `Failed to import schema from '${pathName}'.`);
}
}
/**
* Returns the full schema for the input name.
* @param name The name of the schema e.g. 'ECDbMeta'
* @returns The SchemaProps for the requested schema
* @throws if the schema can not be found or loaded.
*/
public getSchemaProps(name: string): ECSchemaProps {
return this.nativeDb.getSchemaProps(name);
}
/**
* Use a prepared ECSQL statement, potentially from the statement cache. If the requested statement doesn't exist
* in the statement cache, a new statement is prepared. After the callback completes, the statement is reset and saved
* in the statement cache so it can be reused in the future. Use this method for ECSQL statements that will be
* reused often and are expensive to prepare. The statement cache holds the most recently used statements, discarding
* the oldest statements as it fills. For statements you don't intend to reuse, instead use [[withStatement]].
* @param sql The SQLite SQL statement to execute
* @param callback the callback to invoke on the prepared statement
* @param logErrors Determines if error will be logged if statement fail to prepare
* @returns the value returned by `callback`.
* @see [[withStatement]]
* @public
*/
public withPreparedStatement<T>(ecsql: string, callback: (stmt: ECSqlStatement) => T, logErrors = true): T {
const stmt = this._statementCache.findAndRemove(ecsql) ?? this.prepareStatement(ecsql, logErrors);
const release = () => this._statementCache.addOrDispose(stmt);
try {
const val = callback(stmt);
if (val instanceof Promise) {
val.then(release, release);
} else {
release();
}
return val;
} catch (err) {
release();
throw err;
}
}
/**
* Prepared and execute a callback on an ECSQL statement. After the callback completes the statement is disposed.
* Use this method for ECSQL statements are either not expected to be reused, or are not expensive to prepare.
* For statements that will be reused often, instead use [[withPreparedStatement]].
* @param sql The SQLite SQL statement to execute
* @param callback the callback to invoke on the prepared statement
* @param logErrors Determines if error will be logged if statement fail to prepare
* @returns the value returned by `callback`.
* @see [[withPreparedStatement]]
* @public
*/
public withStatement<T>(ecsql: string, callback: (stmt: ECSqlStatement) => T, logErrors = true): T {
const stmt = this.prepareStatement(ecsql, logErrors);
const release = () => stmt.dispose();
try {
const val = callback(stmt);
if (val instanceof Promise) {
val.then(release, release);
} else {
release();
}
return val;
} catch (err) {
release();
throw err;
}
}
/** Prepare an ECSQL statement.
* @param ecsql The ECSQL statement to prepare
* @param logErrors Determines if error will be logged if statement fail to prepare
* @throws [IModelError]($common) if there is a problem preparing the statement.
*/
public prepareStatement(ecsql: string, logErrors = true): ECSqlStatement {
const stmt = new ECSqlStatement();
stmt.prepare(this.nativeDb, ecsql, logErrors);
return stmt;
}
/**
* Use a prepared SQL statement, potentially from the statement cache. If the requested statement doesn't exist
* in the statement cache, a new statement is prepared. After the callback completes, the statement is reset and saved
* in the statement cache so it can be reused in the future. Use this method for SQL statements that will be
* reused often and are expensive to prepare. The statement cache holds the most recently used statements, discarding
* the oldest statements as it fills. For statements you don't intend to reuse, instead use [[withSqliteStatement]].
* @param sql The SQLite SQL statement to execute
* @param callback the callback to invoke on the prepared statement
* @param logErrors Determines if error will be logged if statement fail to prepare
* @returns the value returned by `callback`.
* @see [[withPreparedStatement]]
* @public
*/
public withPreparedSqliteStatement<T>(sql: string, callback: (stmt: SqliteStatement) => T, logErrors = true): T {
const stmt = this._sqliteStatementCache.findAndRemove(sql) ?? this.prepareSqliteStatement(sql, logErrors);
const release = () => this._sqliteStatementCache.addOrDispose(stmt);
try {
const val: T = callback(stmt);
if (val instanceof Promise) {
val.then(release, release);
} else {
release();
}
return val;
} catch (err) {
release();
throw err;
}
}
/**
* Prepared and execute a callback on a SQL statement. After the callback completes the statement is disposed.
* Use this method for SQL statements are either not expected to be reused, or are not expensive to prepare.
* For statements that will be reused often, instead use [[withPreparedSqliteStatement]].
* @param sql The SQLite SQL statement to execute
* @param callback the callback to invoke on the prepared statement
* @param logErrors Determines if error will be logged if statement fail to prepare
* @returns the value returned by `callback`.
* @public
*/
public withSqliteStatement<T>(sql: string, callback: (stmt: SqliteStatement) => T, logErrors = true): T {
const stmt = this.prepareSqliteStatement(sql, logErrors);
const release = () => stmt.dispose();
try {
const val: T = callback(stmt);
if (val instanceof Promise) {
val.then(release, release);
} else {
release();
}
return val;
} catch (err) {
release();
throw err;
}
}
/** Prepare an SQL statement.
* @param sql The SQLite SQL statement to prepare
* @param logErrors Determines if error will be logged if statement fail to prepare
* @throws [IModelError]($common) if there is a problem preparing the statement.
* @internal
*/
public prepareSqliteStatement(sql: string, logErrors = true): SqliteStatement {
const stmt = new SqliteStatement(sql);
stmt.prepare(this.nativeDb, logErrors);
return stmt;
}
/** @internal */
public get nativeDb(): IModelJsNative.ECDb {
assert(undefined !== this._nativeDb);
return this._nativeDb;
}
/** Allow to execute query and read results along with meta data. The result are streamed.
*
* See also:
* - [ECSQL Overview]($docs/learning/backend/ExecutingECSQL)
* - [Code Examples]($docs/learning/backend/ECSQLCodeExamples)
* - [ECSQL Row Format]($docs/learning/ECSQLRowFormat)
*
* @param params The values to bind to the parameters (if the ECSQL has any).
* @param config Allow to specify certain flags which control how query is executed.
* @returns Returns an [ECSqlReader]($common) which helps iterate over the result set and also give access to metadata.
* @public
* */
public createQueryReader(ecsql: string, params?: QueryBinder, config?: QueryOptions): ECSqlReader {
if (!this._nativeDb || !this._nativeDb.isOpen()) {
throw new IModelError(DbResult.BE_SQLITE_ERROR, "db not open");
}
const executor = {
execute: async (request: DbQueryRequest) => {
return ConcurrentQuery.executeQueryRequest(this.nativeDb, request);
},
};
return new ECSqlReader(executor, ecsql, params, config);
}
/** Execute a query and stream its results
* The result of the query is async iterator over the rows. The iterator will get next page automatically once rows in current page has been read.
* [ECSQL row]($docs/learning/ECSQLRowFormat).
*
* See also:
* - [ECSQL Overview]($docs/learning/backend/ExecutingECSQL)
* - [Code Examples]($docs/learning/backend/ECSQLCodeExamples)
*
* @param ecsql The ECSQL statement to execute
* @param params The values to bind to the parameters (if the ECSQL has any).
* @param options Allow to specify certain flags which control how query is executed.
* @returns Returns the query result as an *AsyncIterableIterator<any>* which lazy load result as needed. The row format is determined by *rowFormat* parameter.
* See [ECSQL row format]($docs/learning/ECSQLRowFormat) for details about the format of the returned rows.
* @throws [IModelError]($common) If there was any error while submitting, preparing or stepping into query
* @deprecated in 3.7. Use [[createQueryReader]] instead; it accepts the same parameters.
*/
public async * query(ecsql: string, params?: QueryBinder, options?: QueryOptions): AsyncIterableIterator<any> {
const builder = new QueryOptionsBuilder(options);
const reader = this.createQueryReader(ecsql, params, builder.getOptions());
while (await reader.step())
yield reader.formatCurrentRow();
}
/** Compute number of rows that would be returned by the ECSQL.
*
* See also:
* - [ECSQL Overview]($docs/learning/backend/ExecutingECSQL)
* - [Code Examples]($docs/learning/backend/ECSQLCodeExamples)
*
* @param ecsql The ECSQL statement to execute
* @param params The values to bind to the parameters (if the ECSQL has any).
* See "[iTwin.js Types used in ECSQL Parameter Bindings]($docs/learning/ECSQLParameterTypes)" for details.
* @returns Return row count.
* @throws [IModelError]($common) If the statement is invalid
* @deprecated in 3.7. Count the number of results using `count(*)` where the original query is a subquery instead. E.g., `SELECT count(*) FROM (<query-whose-rows-to-count>)`.
*/
public async queryRowCount(ecsql: string, params?: QueryBinder): Promise<number> {
for await (const row of this.createQueryReader(`SELECT count(*) FROM (${ecsql})`, params)) {
return row[0] as number;
}
throw new IModelError(DbResult.BE_SQLITE_ERROR, "Failed to get row count");
}
/** Cancel any previous query with same token and run execute the current specified query.
* The result of the query is async iterator over the rows. The iterator will get next page automatically once rows in current page has been read.
* [ECSQL row]($docs/learning/ECSQLRowFormat).
*
* See also:
* - [ECSQL Overview]($docs/learning/backend/ExecutingECSQL)
* - [Code Examples]($docs/learning/backend/ECSQLCodeExamples)
*
* @param ecsql The ECSQL statement to execute
* @param token None empty restart token. The previous query with same token would be cancelled. This would cause
* exception which user code must handle.
* @param params The values to bind to the parameters (if the ECSQL has any).
* @param options Allow to specify certain flags which control how query is executed.
* @returns Returns the query result as an *AsyncIterableIterator<any>* which lazy load result as needed. The row format is determined by *rowFormat* parameter.
* See [ECSQL row format]($docs/learning/ECSQLRowFormat) for details about the format of the returned rows.
* @throws [IModelError]($common) If there was any error while submitting, preparing or stepping into query
* @deprecated in 3.7. Use [[createQueryReader]] instead. Pass in the restart token as part of the `config` argument; e.g., `{ restartToken: myToken }` or `new QueryOptionsBuilder().setRestartToken(myToken).getOptions()`.
*/
public async * restartQuery(token: string, ecsql: string, params?: QueryBinder, options?: QueryOptions): AsyncIterableIterator<any> {
for await (const row of this.createQueryReader(ecsql, params, new QueryOptionsBuilder(options).setRestartToken(token).getOptions())) {
yield row;
}
}
}