node-firebird 2.3.3 → 2.4.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.
Files changed (109) hide show
  1. package/README.md +544 -6
  2. package/lib/callback.d.ts +20 -0
  3. package/lib/callback.js +6 -16
  4. package/lib/firebird.msg.json +1370 -1370
  5. package/lib/gdscodes.d.ts +1519 -1520
  6. package/lib/gdscodes.js +5 -5
  7. package/lib/ieee754-decimal.d.ts +38 -0
  8. package/lib/ieee754-decimal.js +71 -118
  9. package/lib/index.d.ts +37 -338
  10. package/lib/index.js +97 -86
  11. package/lib/messages.d.ts +6 -0
  12. package/lib/messages.js +135 -162
  13. package/lib/pool.d.ts +23 -0
  14. package/lib/pool.js +34 -47
  15. package/lib/srp.d.ts +51 -0
  16. package/lib/srp.js +62 -72
  17. package/lib/types.d.ts +375 -0
  18. package/lib/types.js +22 -0
  19. package/lib/unix-crypt.d.ts +1 -0
  20. package/lib/unix-crypt.js +126 -152
  21. package/lib/utils.d.ts +16 -0
  22. package/lib/utils.js +24 -48
  23. package/lib/wire/connection.d.ts +100 -0
  24. package/lib/wire/connection.js +1029 -1009
  25. package/lib/wire/const.d.ts +567 -0
  26. package/lib/wire/const.js +620 -599
  27. package/lib/wire/database.d.ts +57 -0
  28. package/lib/wire/database.js +111 -108
  29. package/lib/wire/eventConnection.d.ts +16 -0
  30. package/lib/wire/eventConnection.js +29 -31
  31. package/lib/wire/fbEventManager.d.ts +45 -0
  32. package/lib/wire/fbEventManager.js +38 -57
  33. package/lib/wire/serialize.d.ts +97 -0
  34. package/lib/wire/serialize.js +42 -141
  35. package/lib/wire/service.d.ts +66 -0
  36. package/lib/wire/service.js +374 -401
  37. package/lib/wire/socket.d.ts +59 -0
  38. package/lib/wire/socket.js +79 -40
  39. package/lib/wire/statement.d.ts +25 -0
  40. package/lib/wire/statement.js +13 -9
  41. package/lib/wire/transaction.d.ts +21 -0
  42. package/lib/wire/transaction.js +33 -61
  43. package/lib/wire/xsqlvar.d.ts +175 -0
  44. package/lib/wire/xsqlvar.js +169 -269
  45. package/package.json +12 -4
  46. package/src/callback.ts +55 -0
  47. package/{poc/node_modules/node-firebird/lib/gdscodes.js → src/gdscodes.ts} +3 -3
  48. package/{poc/node_modules/node-firebird/lib/ieee754-decimal.js → src/ieee754-decimal.ts} +7 -14
  49. package/src/index.ts +157 -0
  50. package/{poc/node_modules/node-firebird/lib/messages.js → src/messages.ts} +163 -162
  51. package/src/pool.ts +209 -0
  52. package/{poc/node_modules/node-firebird/lib/srp.js → src/srp.ts} +74 -33
  53. package/src/types.ts +419 -0
  54. package/{poc/node_modules/node-firebird/lib/unix-crypt.js → src/unix-crypt.ts} +6 -12
  55. package/{poc/node_modules/node-firebird/lib/utils.js → src/utils.ts} +11 -20
  56. package/{poc/node_modules/node-firebird/lib/wire/connection.js → src/wire/connection.ts} +611 -129
  57. package/{poc/node_modules/node-firebird/lib/wire/const.js → src/wire/const.ts} +96 -9
  58. package/{poc/node_modules/node-firebird/lib/wire/database.js → src/wire/database.ts} +110 -44
  59. package/{poc/node_modules/node-firebird/lib/wire/eventConnection.js → src/wire/eventConnection.ts} +29 -14
  60. package/{poc/node_modules/node-firebird/lib/wire/fbEventManager.js → src/wire/fbEventManager.ts} +39 -30
  61. package/{poc/node_modules/node-firebird/lib/wire/serialize.js → src/wire/serialize.ts} +78 -59
  62. package/{poc/node_modules/node-firebird/lib/wire/service.js → src/wire/service.ts} +90 -88
  63. package/src/wire/socket.ts +262 -0
  64. package/src/wire/statement.ts +71 -0
  65. package/{poc/node_modules/node-firebird/lib/wire/transaction.js → src/wire/transaction.ts} +25 -19
  66. package/{poc/node_modules/node-firebird/lib/wire/xsqlvar.js → src/wire/xsqlvar.ts} +244 -143
  67. package/.eslintrc.json +0 -12
  68. package/.github/workflows/codeql.yml +0 -76
  69. package/.github/workflows/node.js.yml +0 -95
  70. package/BIGINT_MIGRATION.md +0 -374
  71. package/CI_DEBUGGING_GUIDE.md +0 -148
  72. package/ENCRYPTION_CALLBACK.md +0 -152
  73. package/FIREBIRD_LOG_FEATURE.md +0 -145
  74. package/MINIMAL_CHANGES_SUMMARY.md +0 -136
  75. package/PR_SUMMARY.md +0 -96
  76. package/ROADMAP.md +0 -223
  77. package/SRP_PROTOCOL.md +0 -482
  78. package/poc/README.md +0 -160
  79. package/poc/helpers.js +0 -59
  80. package/poc/node_modules/.package-lock.json +0 -14
  81. package/poc/node_modules/node-firebird/.eslintrc.json +0 -12
  82. package/poc/node_modules/node-firebird/.github/workflows/codeql.yml +0 -76
  83. package/poc/node_modules/node-firebird/.github/workflows/node.js.yml +0 -95
  84. package/poc/node_modules/node-firebird/BIGINT_MIGRATION.md +0 -374
  85. package/poc/node_modules/node-firebird/CI_DEBUGGING_GUIDE.md +0 -148
  86. package/poc/node_modules/node-firebird/ENCRYPTION_CALLBACK.md +0 -152
  87. package/poc/node_modules/node-firebird/FIREBIRD_LOG_FEATURE.md +0 -145
  88. package/poc/node_modules/node-firebird/LICENSE +0 -373
  89. package/poc/node_modules/node-firebird/MINIMAL_CHANGES_SUMMARY.md +0 -136
  90. package/poc/node_modules/node-firebird/PR_SUMMARY.md +0 -96
  91. package/poc/node_modules/node-firebird/README.md +0 -794
  92. package/poc/node_modules/node-firebird/ROADMAP.md +0 -223
  93. package/poc/node_modules/node-firebird/SRP_PROTOCOL.md +0 -482
  94. package/poc/node_modules/node-firebird/lib/callback.js +0 -38
  95. package/poc/node_modules/node-firebird/lib/gdscodes.d.ts +0 -1524
  96. package/poc/node_modules/node-firebird/lib/index.d.ts +0 -316
  97. package/poc/node_modules/node-firebird/lib/index.js +0 -128
  98. package/poc/node_modules/node-firebird/lib/pool.js +0 -108
  99. package/poc/node_modules/node-firebird/lib/wire/socket.js +0 -175
  100. package/poc/node_modules/node-firebird/lib/wire/statement.js +0 -48
  101. package/poc/node_modules/node-firebird/package.json +0 -38
  102. package/poc/node_modules/node-firebird/vitest.config.js +0 -24
  103. package/poc/package-lock.json +0 -21
  104. package/poc/package.json +0 -12
  105. package/poc/reproduce-fixed.js +0 -150
  106. package/poc/reproduce.js +0 -133
  107. package/vitest.config.js +0 -27
  108. /package/{poc/node_modules/node-firebird/lib → src}/firebird.msg +0 -0
  109. /package/{poc/node_modules/node-firebird/lib → src}/firebird.msg.json +0 -0
@@ -1,794 +0,0 @@
1
- # Pure JavaScript and Asynchronous Firebird client for Node.js
2
-
3
- ![Firebird Logo](https://firebirdsql.org/file/about/firebird-logo-90.png)
4
-
5
- [![NPM version][npm-version-image]][npm-url] [![NPM downloads][npm-downloads-image]][npm-url] [![Mozilla License][license-image]][license-url]
6
-
7
- [![NPM](https://nodei.co/npm/node-firebird.png?downloads=true&downloadRank=true)](https://nodei.co/npm/node-firebird/)
8
-
9
- [Firebird forum](https://groups.google.com/forum/#!forum/node-firebird) on Google Groups.
10
-
11
- ## Firebird database on social networks
12
-
13
- - [Firebird on Twitter](https://twitter.com/firebirdsql/)
14
- - [Firebird on Facebook](https://www.facebook.com/FirebirdSQL)
15
-
16
- ## Changelog for version v0.2.x
17
-
18
- - added auto-reconnect
19
- - added [sequentially selects](https://github.com/hgourvest/node-firebird/wiki/What-is-sequentially-selects)
20
- - events for connection (attach, detach, row, result, transaction, commit, rollback, error, etc.)
21
- - performance improvements
22
- - supports inserting/updating buffers and streams
23
- - reading blobs (sequentially)
24
- - pooling
25
- - `database.detach()` waits for last command
26
- - better unit-test
27
-
28
- ---
29
-
30
- - [Firebird documentation](https://firebirdsql.org/en/documentation/)
31
- - [Firebird limits and data types](https://firebirdsql.org/en/firebird-technical-specifications/)
32
-
33
- ## Installation
34
-
35
- ```bash
36
- npm install node-firebird
37
- ```
38
-
39
- ## Usage
40
-
41
- ```js
42
- var Firebird = require('node-firebird');
43
- ```
44
-
45
- ### Methods
46
-
47
- - `Firebird.escape(value) -> return {String}` - prevent for SQL Injections
48
- - `Firebird.attach(options, function(err, db))` attach a database
49
- - `Firebird.create(options, function(err, db))` create a database
50
- - `Firebird.attachOrCreate(options, function(err, db))` attach or create database
51
- - `Firebird.pool(max, options) -> return {Object}` create a connection pooling
52
-
53
- ## Connection types
54
-
55
- ### Connection options
56
-
57
- ```js
58
- var options = {};
59
-
60
- options.host = '127.0.0.1';
61
- options.port = 3050;
62
- options.database = 'database.fdb';
63
- options.user = 'SYSDBA';
64
- options.password = 'masterkey';
65
- options.lowercase_keys = false; // set to true to lowercase keys
66
- options.role = null; // default
67
- options.pageSize = 4096; // default when creating database
68
- options.retryConnectionInterval = 1000; // reconnect interval in case of connection drop
69
- options.blobAsText = false; // set to true to get blob as text, only affects blob subtype 1
70
- options.encoding = 'UTF8'; // default encoding for connection is UTF-8
71
- options.wireCompression = false; // set to true to enable firebird compression on the wire (works only on FB >= 3 and compression is enabled on server (WireCompression = true in firebird.conf))
72
- options.wireCrypt = Firebird.WIRE_CRYPT_ENABLE; // default; set to Firebird.WIRE_CRYPT_DISABLE to disable wire encryption (FB >= 3)
73
- options.pluginName = undefined; // optional, auto-negotiated; can be set to Firebird.AUTH_PLUGIN_SRP256, Firebird.AUTH_PLUGIN_SRP, or Firebird.AUTH_PLUGIN_LEGACY
74
- options.dbCryptConfig = undefined; // optional; database encryption key for encrypted databases. Use 'base64:<value>' for base64-encoded keys or plain text
75
- ```
76
-
77
- ### Classic
78
-
79
- ```js
80
- Firebird.attach(options, function (err, db) {
81
- if (err) throw err;
82
-
83
- // db = DATABASE
84
- db.query('SELECT * FROM TABLE', function (err, result) {
85
- // IMPORTANT: close the connection
86
- db.detach();
87
- });
88
- });
89
- ```
90
-
91
- ### Pooling
92
-
93
- ```js
94
- // 5 = the number is count of opened sockets
95
- var pool = Firebird.pool(5, options);
96
-
97
- // Get a free pool
98
- pool.get(function (err, db) {
99
- if (err) throw err;
100
-
101
- // db = DATABASE
102
- db.query('SELECT * FROM TABLE', function (err, result) {
103
- // IMPORTANT: release the pool connection
104
- db.detach();
105
- });
106
- });
107
-
108
- // Destroy pool
109
- pool.destroy();
110
- ```
111
-
112
- ## Database object (db)
113
-
114
- ### Database Methods
115
-
116
- - `db.query(query, [params], function(err, result), options)` - classic query, returns Array of Object
117
- - `db.execute(query, [params], function(err, result), options)` - classic query, returns Array of Array
118
- - `db.sequentially(query, [params], function(row, index), function(err), options)` - sequentially query
119
- - `db.detach(function(err))` detach a database
120
- - `db.transaction(options, function(err, transaction))` create transaction
121
-
122
- ### Transaction options
123
-
124
- ```js
125
- const options = {
126
- autoCommit: false,
127
- autoUndo: true,
128
- isolation: Firebird.ISOLATION_READ_COMMITTED,
129
- ignoreLimbo: false,
130
- readOnly: false,
131
- wait: true,
132
- waitTimeout: 0,
133
- };
134
- ```
135
-
136
- ### Transaction methods
137
-
138
- - `transaction.query(query, [params], function(err, result), options)` - classic query, returns Array of Object
139
- - `transaction.execute(query, [params], function(err, result), options)` - classic query, returns Array of Array
140
- - `transaction.sequentially(query, [params], function(row, index), function(err), options)` - sequentially query
141
- - `transaction.commit(function(err))` commit current transaction
142
- - `transaction.rollback(function(err))` rollback current transaction
143
-
144
- ### Statement options
145
-
146
- ```js
147
- const options = {
148
- timeout: 1000, // Statement timeout in ms, default is 0 (no timeout)
149
- }
150
- ```
151
-
152
- ## Examples
153
-
154
- ### Parametrized Queries
155
-
156
- ### Parameters
157
-
158
- ```js
159
- Firebird.attach(options, function (err, db) {
160
- if (err) throw err;
161
-
162
- // db = DATABASE
163
- db.query(
164
- 'INSERT INTO USERS (ID, ALIAS, CREATED) VALUES(?, ?, ?) RETURNING ID',
165
- [1, "Pe'ter", new Date()],
166
- function (err, result) {
167
- console.log(result[0].id);
168
- db.query(
169
- 'SELECT * FROM USERS WHERE Alias=?',
170
- ['Peter'],
171
- function (err, result) {
172
- console.log(result);
173
- db.detach();
174
- }
175
- );
176
- }
177
- );
178
- });
179
- ```
180
-
181
- ### BLOB (stream)
182
-
183
- ```js
184
- Firebird.attach(options, function (err, db) {
185
- if (err) throw err;
186
-
187
- // db = DATABASE
188
- // INSERT STREAM as BLOB
189
- db.query(
190
- 'INSERT INTO USERS (ID, ALIAS, FILE) VALUES(?, ?, ?)',
191
- [1, 'Peter', fs.createReadStream('/users/image.jpg')],
192
- function (err, result) {
193
- // IMPORTANT: close the connection
194
- db.detach();
195
- }
196
- );
197
- });
198
- ```
199
-
200
- ### BLOB (buffer)
201
-
202
- ```js
203
- Firebird.attach(options, function (err, db) {
204
- if (err) throw err;
205
-
206
- // db = DATABASE
207
- // INSERT BUFFER as BLOB
208
- db.query(
209
- 'INSERT INTO USERS (ID, ALIAS, FILE) VALUES(?, ?, ?)',
210
- [1, 'Peter', fs.readFileSync('/users/image.jpg')],
211
- function (err, result) {
212
- // IMPORTANT: close the connection
213
- db.detach();
214
- }
215
- );
216
- });
217
- ```
218
-
219
- ### Reading Blobs (Asynchronous)
220
-
221
- ```js
222
- Firebird.attach(options, function (err, db) {
223
- if (err) throw err;
224
-
225
- // db = DATABASE
226
- db.query('SELECT ID, ALIAS, USERPICTURE FROM USER', function (err, rows) {
227
- if (err) throw err;
228
-
229
- // first row
230
- rows[0].userpicture(function (err, name, e) {
231
- if (err) throw err;
232
-
233
- // +v0.2.4
234
- // e.pipe(writeStream/Response);
235
-
236
- // e === EventEmitter
237
- e.on('data', function (chunk) {
238
- // reading data
239
- });
240
-
241
- e.on('end', function () {
242
- // end reading
243
- // IMPORTANT: close the connection
244
- db.detach();
245
- });
246
- });
247
- });
248
- });
249
- ```
250
-
251
- ### Reading Multiples Blobs (Asynchronous)
252
-
253
- ```js
254
- Firebird.attach(options, (err, db) => {
255
- if (err) throw err;
256
-
257
- db.transaction(Firebird.ISOLATION_READ_COMMITTED, (err, transaction) => {
258
- if (err) {
259
- throw err;
260
- }
261
-
262
- transaction.query('SELECT FIRST 10 * FROM JOB', (err, result) => {
263
- if (err) {
264
- transaction.rollback();
265
- return;
266
- }
267
-
268
- const arrBlob = [];
269
- for (const item of result) {
270
- const fields = Object.keys(item);
271
- for (const key of fields) {
272
- if (typeof item[key] === 'function') {
273
- item[key] = new Promise((resolve, reject) => {
274
- // the same transaction is used (better performance)
275
- // this is optional
276
- item[key](transaction, (error, name, event, row) => {
277
- if (error) {
278
- return reject(error);
279
- }
280
-
281
- // reading data
282
- let value = '';
283
- event.on('data', (chunk) => {
284
- value += chunk.toString('binary');
285
- });
286
- event.on('end', () => {
287
- resolve({ value, column: name, row });
288
- });
289
- });
290
- });
291
- arrBlob.push(item[key]);
292
- }
293
- }
294
- }
295
-
296
- Promise.all(arrBlob)
297
- .then((blobs) => {
298
- for (const blob of blobs) {
299
- result[blob.row][blob.column] = blob.value;
300
- }
301
-
302
- transaction.commit((err) => {
303
- if (err) {
304
- transaction.rollback();
305
- return;
306
- }
307
-
308
- db.detach();
309
- console.log(result);
310
- });
311
- })
312
- .catch((err) => {
313
- transaction.rollback();
314
- });
315
- });
316
- });
317
- });
318
- ```
319
-
320
- ### Streaming a big data
321
-
322
- ```js
323
- Firebird.attach(options, function (err, db) {
324
- if (err) throw err;
325
-
326
- // db = DATABASE
327
- db.sequentially(
328
- 'SELECT * FROM BIGTABLE',
329
- function (row, index) {
330
- // EXAMPLE
331
- stream.write(JSON.stringify(row));
332
- },
333
- function (err) {
334
- // END
335
- // IMPORTANT: close the connection
336
- db.detach();
337
- }
338
- );
339
- });
340
- ```
341
-
342
- ### Transactions
343
-
344
- **Transaction types:**
345
-
346
- - `Firebird.ISOLATION_READ_UNCOMMITTED`
347
- - `Firebird.ISOLATION_READ_COMMITTED`
348
- - `Firebird.ISOLATION_REPEATABLE_READ`
349
- - `Firebird.ISOLATION_SERIALIZABLE`
350
- - `Firebird.ISOLATION_READ_COMMITTED_READ_ONLY`
351
-
352
- ```js
353
- Firebird.attach(options, function (err, db) {
354
- if (err) throw err;
355
-
356
- // db = DATABASE
357
- db.transaction(
358
- Firebird.ISOLATION_READ_COMMITTED,
359
- function (err, transaction) {
360
- transaction.query(
361
- 'INSERT INTO users VALUE(?,?)',
362
- [1, 'Janko'],
363
- function (err, result) {
364
- if (err) {
365
- transaction.rollback();
366
- return;
367
- }
368
-
369
- transaction.commit(function (err) {
370
- if (err) transaction.rollback();
371
- else db.detach();
372
- });
373
- }
374
- );
375
- }
376
- );
377
- });
378
- ```
379
-
380
- ### Driver Events
381
-
382
- Driver events are synchronous notifications emitted on the `Database` object for connection-level operations. Subscribe with `db.on(eventName, handler)`.
383
-
384
- ```js
385
- Firebird.attach(options, function (err, db) {
386
- if (err) throw err;
387
-
388
- db.on('attach', function () {
389
- // fired once the database is attached
390
- });
391
-
392
- db.on('detach', function (isPoolConnection) {
393
- // isPoolConnection === Boolean
394
- });
395
-
396
- db.on('reconnect', function () {
397
- // fired after the driver reconnects a dropped socket
398
- });
399
-
400
- db.on('error', function (err) {
401
- // connection-level errors (socket errors, closed connection, etc.)
402
- });
403
-
404
- db.on('transaction', function (options) {
405
- // fired when a transaction is started (before server response)
406
- // options === resolved transaction options object
407
- });
408
-
409
- db.on('commit', function () {
410
- // fired when a transaction commit is sent
411
- });
412
-
413
- db.on('rollback', function () {
414
- // fired when a transaction rollback is sent
415
- });
416
-
417
- db.on('query', function (sql) {
418
- // fired with the SQL string when a statement is prepared
419
- });
420
-
421
- db.on('row', function (row, index, isObject) {
422
- // fired for each row decoded during a fetch
423
- // index === Number, isObject === Boolean
424
- });
425
-
426
- db.on('result', function (rows) {
427
- // fired with the full rows array once all rows are fetched
428
- // rows === Array
429
- });
430
-
431
- db.detach();
432
- });
433
- ```
434
-
435
- ### Firebird Database Events (POST_EVENT)
436
-
437
- Firebird database events are **asynchronous** notifications triggered by `POST_EVENT` inside PSQL triggers or stored procedures. They travel over a separate aux connection and are handled through `FbEventManager`.
438
-
439
- > **Note:** Full POST_EVENT reception is not yet implemented. `attachEvent` and `registerEvent` are available, but actual event delivery requires completing the `op_que_events`/`op_event` wire-protocol implementation.
440
-
441
- ```js
442
- Firebird.attach(options, function (err, db) {
443
- if (err) throw err;
444
-
445
- // 1. Open the aux event connection and get a FbEventManager
446
- db.attachEvent(function (err, evtmgr) {
447
- if (err) throw err;
448
-
449
- // 2. Subscribe to one or more named events
450
- evtmgr.registerEvent(['MY_EVENT'], function (err) {
451
- if (err) throw err;
452
-
453
- // 3. Listen for POST_EVENT notifications
454
- evtmgr.on('post_event', function (name, count) {
455
- // name === event name string (e.g. 'MY_EVENT')
456
- // count === cumulative trigger count since last notification
457
- });
458
- });
459
-
460
- // 4. Unsubscribe from events when no longer needed
461
- // evtmgr.unregisterEvent(['MY_EVENT'], function (err) { ... });
462
-
463
- // 5. Release the aux connection when done
464
- // evtmgr.close(function (err) { ... });
465
- });
466
- });
467
- ```
468
-
469
- ### Escaping Query values
470
-
471
- ```js
472
- var sql1 = 'SELECT * FROM TBL_USER WHERE ID>' + Firebird.escape(1);
473
- var sql2 = 'SELECT * FROM TBL_USER WHERE NAME=' + Firebird.escape("Pe'er");
474
- var sql3 =
475
- 'SELECT * FROM TBL_USER WHERE CREATED<=' + Firebird.escape(new Date());
476
- var sql4 = 'SELECT * FROM TBL_USER WHERE NEWSLETTER=' + Firebird.escape(true);
477
-
478
- // or db.escape()
479
-
480
- console.log(sql1);
481
- console.log(sql2);
482
- console.log(sql3);
483
- console.log(sql4);
484
- ```
485
-
486
- ### Using GDS codes
487
-
488
- ```js
489
- var { GDSCode } = require('node-firebird/lib/gdscodes');
490
- /*...*/
491
- db.query(
492
- 'insert into my_table(id, name) values (?, ?)',
493
- [1, 'John Doe'],
494
- function (err) {
495
- if (err.gdscode == GDSCode.UNIQUE_KEY_VIOLATION) {
496
- console.log('constraint name:' + err.gdsparams[0]);
497
- console.log('table name:' + err.gdsparams[0]);
498
- /*...*/
499
- }
500
- /*...*/
501
- }
502
- );
503
- ```
504
-
505
- ### Service Manager functions
506
-
507
- - backup
508
- - restore
509
- - fixproperties
510
- - serverinfo
511
- - database validation
512
- - commit transaction
513
- - rollback transaction
514
- - recover transaction
515
- - database stats
516
- - users infos
517
- - user actions (add modify remove)
518
- - get firebird file log
519
- - tracing
520
-
521
- ```js
522
- // each row : fctname : [params], typeofreturn
523
- var fbsvc = {
524
- "backup" : { [ "options"], "stream" },
525
- "nbackup" : { [ "options"], "stream" },
526
- "restore" : { [ "options"], "stream" },
527
- "nrestore" : { [ "options"], "stream" },
528
- "setDialect": { [ "database","dialect"], "stream" },
529
- "setSweepinterval": { [ "database","sweepinterval"], "stream" },
530
- "setCachebuffer" : { [ "database","nbpagebuffers"], "stream" },
531
- "BringOnline" : { [ "database"], "stream" },
532
- "Shutdown" : { [ "database","shutdown","shutdowndelay","shutdownmode"], "stream" },
533
- "setShadow" : { [ "database","activateshadow"], "stream" },
534
- "setForcewrite" : { [ "database","forcewrite"], "stream" },
535
- "setReservespace" : { [ "database","reservespace"], "stream" },
536
- "setReadonlyMode" : { [ "database"], "stream" },
537
- "setReadwriteMode" : { [ "database"], "stream" },
538
- "validate" : { [ "options"], "stream" },
539
- "commit" : { [ "database", "transactid"], "stream" },
540
- "rollback" : { [ "database", "transactid"], "stream" },
541
- "recover" : { [ "database", "transactid"], "stream" },
542
- "getStats" : { [ "options"], "stream" },
543
- "getLog" : { [ "options"], "stream" },
544
- "getUsers" : { [ "username"], "object" },
545
- "addUser" : { [ "username", "password", "options"], "stream" },
546
- "editUser" : { [ "username", "options"], "stream" },
547
- "removeUser" : { [ "username","rolename"], "stream" },
548
- "getFbserverInfos" : { [ "options", "options"], "object" },
549
- "startTrace" : { [ "options"], "stream" },
550
- "suspendTrace" : { [ "options"], "stream" },
551
- "resumeTrace" : { [ "options"], "stream" },
552
- "stopTrace" : { [ "options"], "stream" },
553
- "getTraceList" : { [ "options"], "stream" },
554
- "hasActionRunning" : { [ "options"], "object"}
555
- }
556
-
557
- ```
558
-
559
- ### Backup Service example
560
-
561
- ```js
562
- const options = {...}; // Classic configuration with manager = true
563
- Firebird.attach(options, function(err, svc) {
564
- if (err)
565
- return;
566
- svc.backup(
567
- {
568
- database:'/DB/MYDB.FDB',
569
- files: [
570
- {
571
- filename:'/DB/MYDB.FBK',
572
- sizefile:'0'
573
- }
574
- ]
575
- },
576
- function(err, data) {
577
- data.on('data', line => console.log(line));
578
- data.on('end', () => svc.detach());
579
- }
580
- );
581
- });
582
- ```
583
-
584
- ### Restore Service example
585
-
586
- ```js
587
- const config = {...}; // Classic configuration with manager = true
588
- const RESTORE_OPTS = {
589
- database: 'database.fdb',
590
- files: ['backup.fbk']
591
- };
592
-
593
- Firebird.attach(config, (err, srv) => {
594
- srv.restore(RESTORE_OPTS, (err, data) => {
595
- data.on('data', () => {});
596
- data.on('end', () =>{
597
- srv.detach();})
598
- });
599
- });
600
- ```
601
-
602
- ### getLog and getFbserverInfos Service examples with use of stream and object return
603
-
604
- ```js
605
- fb.attach(_connection, function (err, svc) {
606
- if (err) return;
607
- // all function that return a stream take two optional parameter
608
- // optread => byline or buffer byline use isc_info_svc_line and buffer use isc_info_svc_to_eof
609
- // buffersize => is the buffer for service manager it can't exceed 8ko (i'm not sure)
610
-
611
- svc.getLog({ optread: 'buffer', buffersize: 2048 }, function (err, data) {
612
- // data is a readablestream that contain the firebird.log file
613
- console.log(err);
614
- data.on('data', function (data) {
615
- console.log(data.toString());
616
- });
617
- data.on('end', function () {
618
- console.log('finish');
619
- });
620
- });
621
-
622
- // an other exemple to use function that return object
623
- svc.getFbserverInfos(
624
- {
625
- dbinfo: true,
626
- fbconfig: true,
627
- svcversion: true,
628
- fbversion: true,
629
- fbimplementation: true,
630
- fbcapatibilities: true,
631
- pathsecuritydb: true,
632
- fbenv: true,
633
- fbenvlock: true,
634
- fbenvmsg: true,
635
- },
636
- {},
637
- function (err, data) {
638
- console.log(err);
639
- console.log(data);
640
- }
641
- );
642
- });
643
- ```
644
-
645
- ### Charset for database connection is always UTF-8
646
-
647
- Node Firebird uses UTF-8 as the default charset. If you want a different one, such as Latin1, you will need to go into the library and modify the default_encoding in the index.js file
648
-
649
- ```js
650
- const default_encoding = 'latin1';
651
- ```
652
-
653
- This is why you should use **Firebird 2.5** server at least.
654
-
655
- ### Firebird 3.0+ Support
656
-
657
- Firebird 3.0 wire protocol versions 14 and 15 are now supported, including:
658
-
659
- - **Srp256 authentication** (SHA-256) — preferred by default, alongside Srp (SHA-1) and Legacy_Auth
660
- - **Wire encryption** (Arc4/RC4) — enabled by default via `wireCrypt`
661
- - **Wire compression** — supported for protocol version 13+ (set `wireCompression: true`)
662
- - **Database encryption callback** — support for encrypted databases via `dbCryptConfig` option
663
-
664
- No server-side configuration changes are required for Firebird 3.0 with default settings.
665
-
666
- ```js
667
- Firebird.attach({
668
- host: '127.0.0.1',
669
- port: 3050,
670
- database: '/path/to/db.fdb',
671
- user: 'SYSDBA',
672
- password: 'masterkey',
673
- wireCrypt: Firebird.WIRE_CRYPT_ENABLE, // default, can set WIRE_CRYPT_DISABLE
674
- pluginName: Firebird.AUTH_PLUGIN_SRP256, // optional, auto-negotiated
675
- }, function(err, db) {
676
- if (err) throw err;
677
- // ...
678
- db.detach();
679
- });
680
- ```
681
-
682
- #### Database Encryption Support
683
-
684
- For encrypted databases, provide the encryption key via the `dbCryptConfig` option:
685
-
686
- ```js
687
- Firebird.attach({
688
- host: '127.0.0.1',
689
- database: '/path/to/encrypted.fdb',
690
- user: 'SYSDBA',
691
- password: 'masterkey',
692
- dbCryptConfig: 'base64:bXlTZWNyZXRLZXkxMjM0NTY=', // base64-encoded key
693
- // or dbCryptConfig: 'myPlainTextKey' // plain text key (UTF-8 encoded)
694
- }, function(err, db) {
695
- if (err) throw err;
696
- // ...
697
- db.detach();
698
- });
699
- ```
700
-
701
- **Notes:**
702
- - The `dbCryptConfig` value can be prefixed with `base64:` for base64-encoded keys
703
- - Plain text values are encoded as UTF-8
704
- - Empty or undefined values send an empty response to the callback
705
- - This feature requires Firebird 3.0.1+ (protocol 14/15) for encrypted databases
706
-
707
- ### Firebird 4.0 and 5.0
708
-
709
- Firebird 4 wire protocol (versions 16 and 17) is now supported with the following features:
710
-
711
- - **Protocol versions 16 and 17** — Full support for Firebird 4.0+ wire protocol
712
- - **DECFLOAT data types** — Support for DECFLOAT(16) and DECFLOAT(34) using IEEE 754 Decimal64 and Decimal128 formats
713
- - **INT128 data type** — Native support for 128-bit integers
714
- - **Extended metadata identifiers** — Support for identifiers up to 63 characters
715
- - **Backward compatibility** — Automatically negotiates the best protocol version with the server
716
-
717
- The driver will automatically negotiate the best protocol version supported by both the client and server. No configuration changes are required for Firebird 4.0 servers.
718
-
719
- ```js
720
- Firebird.attach({
721
- host: '127.0.0.1',
722
- port: 3050,
723
- database: '/path/to/fb4.fdb',
724
- user: 'SYSDBA',
725
- password: 'masterkey',
726
- }, function(err, db) {
727
- if (err) throw err;
728
-
729
- // DECFLOAT and INT128 types are automatically supported
730
- db.query('SELECT CAST(123.456 AS DECFLOAT(16)) AS df16, CAST(9876543210 AS INT128) AS i128 FROM RDB$DATABASE', function(err, result) {
731
- console.log(result); // { df16: 123.456, i128: '9876543210' }
732
- db.detach();
733
- });
734
- });
735
- ```
736
-
737
- **Important Notes:**
738
-
739
- 1. **Statement Timeouts:** Statement timeouts (a Protocol 16 feature) are not yet implemented. This will be added in a future release.
740
-
741
- 2. **DECFLOAT Encoding:** The current DECFLOAT implementation uses a simplified encoding/decoding mechanism and does NOT implement proper IEEE 754 Decimal64/Decimal128 formats. For production use with DECFLOAT types requiring full precision and standards compliance, consider:
742
- - Using a proper IEEE 754 Decimal library (e.g., `decimal128` npm package)
743
- - Contributing a full IEEE 754 implementation to this driver
744
- - Working with DECFLOAT values as strings or Buffers to preserve exact precision
745
-
746
- For legacy Firebird 4 servers with SRP authentication only, use the following configuration in `firebird.conf`:
747
- Firebird 4 wire protocol (versions 16 and 17) is partially supported, including:
748
- - **Time Zone Support**: Native support for `TIME WITH TIME ZONE` and `TIMESTAMP WITH TIME ZONE` (Protocol 16+).
749
- - **INT128 support**: Native support for 128-bit integers.
750
- - **Statement Timeout**: Support for statement-level timeouts.
751
-
752
- #### Using Timezones (FB 4.0+)
753
-
754
- Columns of type `TIMESTAMP WITH TIME ZONE` and `TIME WITH TIME ZONE` are automatically mapped to JavaScript `Date` objects. Values are read as UTC and represented in the local timezone of the Node.js process.
755
-
756
- ```js
757
- // Select timezone columns
758
- db.query('SELECT TS_TZ_COL, T_TZ_COL FROM FB4_TABLE', function(err, result) {
759
- console.log(result[0].ts_tz_col); // JavaScript Date object
760
- });
761
-
762
- // Insert using Date objects
763
- db.query('INSERT INTO FB4_TABLE (TS_TZ_COL) VALUES (?)', [new Date()], function(err) {
764
- // ...
765
- });
766
- ```
767
-
768
- Srp256 authentication and wire encryption are now supported natively,
769
- so you only need the following minimal configuration in `firebird.conf`:
770
-
771
- ```bash
772
- AuthServer = Srp256, Srp
773
- WireCrypt = Enabled
774
- ```
775
-
776
- For more details see:
777
- - [Firebird 3 release notes — new authentication](https://firebirdsql.org/file/documentation/release_notes/html/en/3_0/rnfb30-security-new-authentication.html)
778
- - [Firebird 4 release notes — Srp256](https://firebirdsql.org/file/documentation/release_notes/html/en/4_0/rlsnotes40.html#rnfb40-config-srp256)
779
- - [Firebird 4 release notes — DECFLOAT](https://firebirdsql.org/file/documentation/release_notes/html/en/4_0/rlsnotes40.html#rnfb40-datatype-decfloat)
780
- - [Firebird 4 migration guide — authorization](https://ib-aid.com/download/docs/fb4migrationguide.html#_authorization_with_firebird_2_5_client_library_fbclient_dll)
781
- - [Firebird 5 migration guide — authorization](https://ib-aid.com/download/docs/fb5migrationguide.html#_authorization_from_firebird_2_5_client_libraries)
782
-
783
-
784
- ## Contributors
785
-
786
- - Henri Gourvest, <https://github.com/hgourvest>
787
- - Popa Marius Adrian, <https://github.com/mariuz>
788
- - Peter Širka, <https://github.com/petersirka>
789
-
790
- [license-image]: http://img.shields.io/badge/license-MOZILLA-blue.svg?style=flat
791
- [license-url]: LICENSE
792
- [npm-url]: https://npmjs.org/package/node-firebird
793
- [npm-version-image]: http://img.shields.io/npm/v/node-firebird.svg?style=flat
794
- [npm-downloads-image]: http://img.shields.io/npm/dm/node-firebird.svg?style=flat