0
# Constants and Configuration
1

2
SQLite constants for database modes, error codes, version information, and configuration limits. These constants are directly exported from the sqlite3 module and correspond to SQLite's native constants.
3

4
## Capabilities
5

6
### Database Mode Flags
7

8
Constants used when opening database connections to specify access modes and behaviors.
9

10
```javascript { .api }
11
/**
12
 * Open database in read-only mode
13
 * Value: 1
14
 */
15
const OPEN_READONLY: number;
16

17
/**
18
 * Open database in read-write mode
19
 * Value: 2
20
 */
21
const OPEN_READWRITE: number;
22

23
/**
24
 * Create database if it doesn't exist (used with OPEN_READWRITE)
25
 * Value: 4
26
 */
27
const OPEN_CREATE: number;
28

29
/**
30
 * Enable full mutex locking
31
 * Value: 0x00010000
32
 */
33
const OPEN_FULLMUTEX: number;
34

35
/**
36
 * Enable shared cache mode
37
 * Value: 0x00020000
38
 */
39
const OPEN_SHAREDCACHE: number;
40

41
/**
42
 * Enable private cache mode
43
 * Value: 0x00040000
44
 */
45
const OPEN_PRIVATECACHE: number;
46

47
/**
48
 * Interpret filename as URI
49
 * Value: 0x00000040
50
 */
51
const OPEN_URI: number;
52
```
53

54
**Usage Examples:**
55

56
```javascript
57
const sqlite3 = require('sqlite3').verbose();
58

59
// Read-only database
60
const readOnlyDb = new sqlite3.Database('data.db', sqlite3.OPEN_READONLY);
61

62
// Read-write database, create if doesn't exist
63
const readWriteDb = new sqlite3.Database('data.db', 
64
    sqlite3.OPEN_READWRITE | sqlite3.OPEN_CREATE);
65

66
// Database with specific threading mode
67
const threadSafeDb = new sqlite3.Database('data.db', 
68
    sqlite3.OPEN_READWRITE | sqlite3.OPEN_CREATE | sqlite3.OPEN_FULLMUTEX);
69

70
// URI-style filename
71
const uriDb = new sqlite3.Database('file:data.db?cache=shared', 
72
    sqlite3.OPEN_URI | sqlite3.OPEN_READWRITE);
73
```
74

75
### Error Codes
76

77
SQLite result codes that indicate the outcome of database operations.
78

79
```javascript { .api }
80
/**
81
 * Successful result
82
 * Value: 0
83
 */
84
const OK: number;
85

86
/**
87
 * Generic error
88
 * Value: 1
89
 */
90
const ERROR: number;
91

92
/**
93
 * Internal logic error in SQLite
94
 * Value: 2
95
 */
96
const INTERNAL: number;
97

98
/**
99
 * Access permission denied
100
 * Value: 3
101
 */
102
const PERM: number;
103

104
/**
105
 * Callback routine requested an abort
106
 * Value: 4
107
 */
108
const ABORT: number;
109

110
/**
111
 * The database file is locked
112
 * Value: 5
113
 */
114
const BUSY: number;
115

116
/**
117
 * A table in the database is locked
118
 * Value: 6
119
 */
120
const LOCKED: number;
121

122
/**
123
 * A malloc() failed
124
 * Value: 7
125
 */
126
const NOMEM: number;
127

128
/**
129
 * Attempt to write a readonly database
130
 * Value: 8
131
 */
132
const READONLY: number;
133

134
/**
135
 * Operation terminated by sqlite3_interrupt()
136
 * Value: 9
137
 */
138
const INTERRUPT: number;
139

140
/**
141
 * Some kind of disk I/O error occurred
142
 * Value: 10
143
 */
144
const IOERR: number;
145

146
/**
147
 * The database disk image is malformed
148
 * Value: 11
149
 */
150
const CORRUPT: number;
151

152
/**
153
 * Unknown opcode in sqlite3_file_control()
154
 * Value: 12
155
 */
156
const NOTFOUND: number;
157

158
/**
159
 * Insertion failed because database is full
160
 * Value: 13
161
 */
162
const FULL: number;
163

164
/**
165
 * Unable to open the database file
166
 * Value: 14
167
 */
168
const CANTOPEN: number;
169

170
/**
171
 * Database lock protocol error
172
 * Value: 15
173
 */
174
const PROTOCOL: number;
175

176
/**
177
 * Database is empty
178
 * Value: 16
179
 */
180
const EMPTY: number;
181

182
/**
183
 * The database schema changed
184
 * Value: 17
185
 */
186
const SCHEMA: number;
187

188
/**
189
 * String or BLOB exceeds size limit
190
 * Value: 18
191
 */
192
const TOOBIG: number;
193

194
/**
195
 * Abort due to constraint violation
196
 * Value: 19
197
 */
198
const CONSTRAINT: number;
199

200
/**
201
 * Data type mismatch
202
 * Value: 20
203
 */
204
const MISMATCH: number;
205

206
/**
207
 * Library used incorrectly
208
 * Value: 21
209
 */
210
const MISUSE: number;
211

212
/**
213
 * Uses OS features not supported on host
214
 * Value: 22
215
 */
216
const NOLFS: number;
217

218
/**
219
 * Authorization denied
220
 * Value: 23
221
 */
222
const AUTH: number;
223

224
/**
225
 * Auxiliary database format error
226
 * Value: 24
227
 */
228
const FORMAT: number;
229

230
/**
231
 * 2nd parameter to sqlite3_bind out of range
232
 * Value: 25
233
 */
234
const RANGE: number;
235

236
/**
237
 * File opened that is not a database file
238
 * Value: 26
239
 */
240
const NOTADB: number;
241
```
242

243
**Usage Examples:**
244

245
```javascript
246
const sqlite3 = require('sqlite3').verbose();
247
const db = new sqlite3.Database('example.db');
248

249
db.run("INVALID SQL STATEMENT", (err) => {
250
    if (err) {
251
        console.log('Error occurred:', err.message);
252
        console.log('Error code:', err.errno);
253
        
254
        // Check specific error types
255
        switch (err.errno) {
256
            case sqlite3.ERROR:
257
                console.log('Generic SQL error');
258
                break;
259
            case sqlite3.BUSY:
260
                console.log('Database is busy, retry later');
261
                break;
262
            case sqlite3.READONLY:
263
                console.log('Attempted to write to read-only database');
264
                break;
265
            case sqlite3.CONSTRAINT:
266
                console.log('Constraint violation occurred');
267
                break;
268
            default:
269
                console.log('Other error type');
270
        }
271
    }
272
});
273

274
// Error handling in backup operations
275
const backup = db.backup('backup.db');
276
backup.retryErrors = [sqlite3.BUSY, sqlite3.LOCKED];
277
```
278

279
### SQLite Version Information
280

281
Constants providing information about the SQLite version being used.
282

283
```javascript { .api }
284
/**
285
 * SQLite version string (e.g., "3.44.2")
286
 */
287
const VERSION: string;
288

289
/**
290
 * SQLite source ID string
291
 */
292
const SOURCE_ID: string;
293

294
/**
295
 * SQLite version as integer (e.g., 3044002)
296
 */
297
const VERSION_NUMBER: number;
298
```
299

300
**Usage Examples:**
301

302
```javascript
303
const sqlite3 = require('sqlite3').verbose();
304

305
console.log('SQLite Version:', sqlite3.VERSION);
306
console.log('SQLite Version Number:', sqlite3.VERSION_NUMBER);
307
console.log('SQLite Source ID:', sqlite3.SOURCE_ID);
308

309
// Version checking
310
if (sqlite3.VERSION_NUMBER >= 3035000) {
311
    console.log('SQLite version supports RETURNING clause');
312
} else {
313
    console.log('SQLite version does not support RETURNING clause');
314
}
315
```
316

317
### Database Limit Constants
318

319
Constants for configuring SQLite database limits using the `configure()` method.
320

321
```javascript { .api }
322
/**
323
 * Maximum length of a string or BLOB
324
 */
325
const LIMIT_LENGTH: number;
326

327
/**
328
 * Maximum length of an SQL statement
329
 */
330
const LIMIT_SQL_LENGTH: number;
331

332
/**
333
 * Maximum number of columns in a table, index, or view
334
 */
335
const LIMIT_COLUMN: number;
336

337
/**
338
 * Maximum depth of the parse tree
339
 */
340
const LIMIT_EXPR_DEPTH: number;
341

342
/**
343
 * Maximum number of terms in a compound SELECT statement
344
 */
345
const LIMIT_COMPOUND_SELECT: number;
346

347
/**
348
 * Maximum number of instructions in a virtual machine program
349
 */
350
const LIMIT_VDBE_OP: number;
351

352
/**
353
 * Maximum number of arguments on a function
354
 */
355
const LIMIT_FUNCTION_ARG: number;
356

357
/**
358
 * Maximum number of attached databases
359
 */
360
const LIMIT_ATTACHED: number;
361

362
/**
363
 * Maximum length of the pattern argument to the LIKE or GLOB operators
364
 */
365
const LIMIT_LIKE_PATTERN_LENGTH: number;
366

367
/**
368
 * Maximum index number of any parameter in an SQL statement
369
 */
370
const LIMIT_VARIABLE_NUMBER: number;
371

372
/**
373
 * Maximum depth of recursion for triggers
374
 */
375
const LIMIT_TRIGGER_DEPTH: number;
376

377
/**
378
 * Maximum number of auxiliary worker threads
379
 */
380
const LIMIT_WORKER_THREADS: number;
381
```
382

383
**Usage Examples:**
384

385
```javascript
386
const sqlite3 = require('sqlite3').verbose();
387
const db = new sqlite3.Database('example.db');
388

389
// Configure database limits
390
db.configure("limit", sqlite3.LIMIT_SQL_LENGTH, 1000000);  // 1MB SQL limit
391
db.configure("limit", sqlite3.LIMIT_COLUMN, 2000);        // 2000 column limit
392
db.configure("limit", sqlite3.LIMIT_EXPR_DEPTH, 1000);    // Expression depth limit
393

394
// Set busy timeout
395
db.configure("busyTimeout", 30000); // 30 second timeout
396

397
// Check current limits (would require custom implementation)
398
function checkLimits(database) {
399
    console.log('Current database limits:');
400
    console.log('- SQL Length Limit ID:', sqlite3.LIMIT_SQL_LENGTH);
401
    console.log('- Column Limit ID:', sqlite3.LIMIT_COLUMN);
402
    console.log('- Expression Depth Limit ID:', sqlite3.LIMIT_EXPR_DEPTH);
403
}
404

405
checkLimits(db);
406
```
407

408
## Configuration Examples
409

410
### Database Opening with Multiple Flags
411

412
```javascript
413
const sqlite3 = require('sqlite3').verbose();
414

415
// Combine multiple flags using bitwise OR
416
const flags = sqlite3.OPEN_READWRITE | 
417
              sqlite3.OPEN_CREATE | 
418
              sqlite3.OPEN_FULLMUTEX | 
419
              sqlite3.OPEN_SHAREDCACHE;
420

421
const db = new sqlite3.Database('shared.db', flags, (err) => {
422
    if (err) {
423
        console.error('Database open failed:', err.message);
424
    } else {
425
        console.log('Database opened with custom flags');
426
        
427
        // Configure additional settings
428
        db.configure("busyTimeout", 10000);
429
        db.configure("limit", sqlite3.LIMIT_ATTACHED, 10);
430
    }
431
});
432
```
433

434
### Error Code Checking and Handling
435

436
```javascript
437
const sqlite3 = require('sqlite3').verbose();
438
const db = new sqlite3.Database('example.db');
439

440
function handleDatabaseError(err, operation) {
441
    if (!err) return;
442
    
443
    console.log(`Error during ${operation}:`, err.message);
444
    
445
    // Handle specific error codes
446
    switch (err.errno) {
447
        case sqlite3.OK:
448
            console.log('Operation successful');
449
            break;
450
        case sqlite3.BUSY:
451
            console.log('Database busy - consider retry with backoff');
452
            break;
453
        case sqlite3.LOCKED:
454
            console.log('Table locked - transaction may be needed');
455
            break;
456
        case sqlite3.CONSTRAINT:
457
            console.log('Constraint violation - check data integrity');
458
            break;
459
        case sqlite3.CORRUPT:
460
            console.log('Database corruption detected - backup and repair needed');
461
            break;
462
        case sqlite3.READONLY:
463
            console.log('Read-only database - check permissions or mode');
464
            break;
465
        case sqlite3.CANTOPEN:
466
            console.log('Cannot open database - check file path and permissions');
467
            break;
468
        default:
469
            console.log(`Unhandled error code: ${err.errno}`);
470
    }
471
}
472

473
// Usage in database operations
474
db.run("CREATE TABLE test (id INTEGER PRIMARY KEY)", (err) => {
475
    handleDatabaseError(err, 'table creation');
476
});
477

478
db.run("INSERT INTO test (id) VALUES (1)", (err) => {
479
    handleDatabaseError(err, 'insert operation');
480
});
481
```
482

483
### Version-Dependent Feature Usage
484

485
```javascript
486
const sqlite3 = require('sqlite3').verbose();
487

488
function checkSQLiteFeatures() {
489
    console.log(`SQLite Version: ${sqlite3.VERSION}`);
490
    console.log(`Version Number: ${sqlite3.VERSION_NUMBER}`);
491
    
492
    // Check for specific version features
493
    const features = {
494
        'RETURNING clause': sqlite3.VERSION_NUMBER >= 3035000,
495
        'STRICT tables': sqlite3.VERSION_NUMBER >= 3037000,
496
        'UPSERT': sqlite3.VERSION_NUMBER >= 3024000,
497
        'Window functions': sqlite3.VERSION_NUMBER >= 3025000,
498
        'Common Table Expressions': sqlite3.VERSION_NUMBER >= 3008003,
499
        'JSON1 extension': sqlite3.VERSION_NUMBER >= 3038000,
500
    };
501
    
502
    console.log('Available features:');
503
    Object.entries(features).forEach(([feature, available]) => {
504
        console.log(`- ${feature}: ${available ? 'Yes' : 'No'}`);
505
    });
506
    
507
    return features;
508
}
509

510
// Use version checking in application logic
511
const features = checkSQLiteFeatures();
512

513
const db = new sqlite3.Database('example.db');
514

515
if (features['RETURNING clause']) {
516
    db.run("INSERT INTO users (name) VALUES (?) RETURNING id", ["Alice"], function(err) {
517
        if (!err) {
518
            console.log('Used RETURNING clause, new ID:', this.lastID);
519
        }
520
    });
521
} else {
522
    db.run("INSERT INTO users (name) VALUES (?)", ["Alice"], function(err) {
523
        if (!err) {
524
            console.log('Used traditional INSERT, new ID:', this.lastID);
525
        }
526
    });
527
}
528
```