Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -75,9 +75,10 @@ BITCODE_FILES = out/sqlite3.o out/extension-functions.o

OUTPUT_WRAPPER_FILES = src/shell-pre.js src/shell-post.js

SOURCE_API_FILES = src/api.js
SOURCE_API_FILES = out/constants.js src/api.js

EMFLAGS_PRE_JS_FILES = \
--pre-js out/constants.js \
--pre-js src/api.js

MODULE_API_JSON_FILES = src/exported_functions.json src/exported_runtime_methods.json src/incoming_module_api.json
Expand Down Expand Up @@ -189,6 +190,12 @@ out/sqlite3.o: sqlite-src/$(SQLITE_AMALGAMATION) Makefile
# Generate llvm bitcode
$(EMCC) $(SQLITE_COMPILATION_FLAGS) -c sqlite-src/$(SQLITE_AMALGAMATION)/sqlite3.c -o $@

# SQLite's integer constants, as the C preprocessor reads the header of the SQLite being compiled
out/constants.js: sqlite-src/$(SQLITE_AMALGAMATION) scripts/constants.cjs
mkdir -p out
$(EMCC) -E -dM -x c sqlite-src/$(SQLITE_AMALGAMATION)/sqlite3.h | node scripts/constants.cjs sqlite-src/$(SQLITE_AMALGAMATION)/sqlite3.h > $@.tmp
mv $@.tmp $@

# Since the extension-functions.c includes other headers in the sqlite_amalgamation, we declare that this depends on more than just extension-functions.c
out/extension-functions.o: sqlite-src/$(SQLITE_AMALGAMATION) src/legacy-functions.c Makefile
mkdir -p out
Expand Down
52 changes: 52 additions & 0 deletions scripts/constants.cjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
"use strict";

// Writes every integer constant sqlite3.h defines, and the names of its result
// codes, as a script the build runs before src/api.js.
// Usage: emcc -E -dM -x c sqlite3.h | node scripts/constants.cjs sqlite3.h
// The macros come from the C preprocessor on stdin; the header itself is read
// only for the comments that mark where its primary result codes are.
const fs = require("node:fs");
const process = require("node:process");

const macros = Object.fromEntries(
[...fs.readFileSync(0, "utf8").matchAll(/^#define (SQLITE_\w+) (.+)$/gm)]
.map(([, name, expr]) => [name, expr])
);

const constants = {};
function get(name) {
if (name in constants) return constants[name];
const expr = macros[name].replace(/\bSQLITE_\w+\b/g, (n) => `(${get(n)})`);
// Integer arithmetic alone: anything else (a string, a cast, a function)
// is not a constant JavaScript can hold.
if (!/^(?:0[xX][\da-fA-F]+|[\s\d()|&^~<>+*/-])*$/.test(expr)) throw new Error(`${name} is not an integer`);
const value = Function(`return (${expr})`)();
if (!Number.isSafeInteger(value)) throw new Error(`${name} is not an integer`);
constants[name] = value;
return value;
}
for (const name of Object.keys(macros)) {
try {
get(name);
} catch {
// Not an integer constant.
}
}

// The primary result codes are between sqlite3.h's beginning-of-error-codes
// and end-of-error-codes comments, and each extended one is defined as a
// primary one with a byte above it.
const header = fs.readFileSync(process.argv[2], "utf8");
const block = /\/\* beginning-of-error-codes \*\/([\s\S]*?)\/\* end-of-error-codes \*\//.exec(header);
if (!block) throw new Error("no error codes found in " + process.argv[2]);
const primary = new Set([...block[1].matchAll(/^#define (SQLITE_\w+)/gm)].map(([, name]) => name));
const resultCodes = Object.keys(constants).filter((name) => {
if (primary.has(name)) return true;
const base = /^\(\s*(SQLITE_\w+)\s*\|/.exec(macros[name]);
return base !== null && primary.has(base[1]);
});
if (!resultCodes.includes("SQLITE_CONSTRAINT_UNIQUE")) throw new Error("no extended result codes found");

process.stdout.write("// Generated from sqlite3.h by scripts/constants.cjs.\n"
+ `var SQLITE_CONSTANTS = ${JSON.stringify(constants, null, 4)};\n`
+ `var SQLITE_RESULT_CODES = ${JSON.stringify(resultCodes, null, 4)};\n`);
70 changes: 64 additions & 6 deletions src/api.js
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
/* global
FS
SQLITE_CONSTANTS
SQLITE_RESULT_CODES
HEAP8
Module
_malloc
Expand All @@ -23,6 +25,27 @@
* @typedef {{Database:Database, Statement:Statement}} SqlJs
* @property {Database} Database A class that represents an SQLite database
* @property {Statement} Statement The prepared statement class
* @property {Object<string, number>} constants Every integer constant of
* SQLite's C API, by name, such as `SQLITE_CONSTRAINT_UNIQUE`
*/

/**
* An error SQLite returned, thrown as an `Error` whose message is SQLite's.
* Its `code` and `errcode` say which error it was, so it can be told apart
* without reading the message.
* @typedef {Error} SqliteError
* @property {string} code The name of SQLite's extended result code, such as
* `"SQLITE_CONSTRAINT_UNIQUE"`
* @property {number} errcode The number of that code, such as `2067`, which
* is `SQL.constants.SQLITE_CONSTRAINT_UNIQUE`
* @example
* try {
* db.run("INSERT INTO users (email) VALUES ('a@example.com')");
* } catch (e) {
* if (e.code === "SQLITE_CONSTRAINT_UNIQUE") {
* // the email is taken
* }
* }
*/

/**
Expand Down Expand Up @@ -80,6 +103,11 @@ Module["onRuntimeInitialized"] = function onRuntimeInitialized() {
var SQLITE_INSERT = 18;
var SQLITE_UPDATE = 23;
var SQLITE_DELETE = 9;
// var - The name of each result code, primary and extended, by number
var resultCodeNames = {};
SQLITE_RESULT_CODES.forEach(function nameResultCode(name) {
resultCodeNames[SQLITE_CONSTANTS[name]] = name;
});
// var - cwrap function
var sqlite3_open = cwrap("sqlite3_open", "number", ["string", "number"]);
var sqlite3_close_v2 = cwrap("sqlite3_close_v2", "number", ["number"]);
Expand Down Expand Up @@ -139,6 +167,11 @@ Module["onRuntimeInitialized"] = function onRuntimeInitialized() {
);
var sqlite3_step = cwrap("sqlite3_step", "number", ["number"]);
var sqlite3_errmsg = cwrap("sqlite3_errmsg", "string", ["number"]);
var sqlite3_extended_errcode = cwrap(
"sqlite3_extended_errcode",
"number",
["number"]
);
var sqlite3_column_count = cwrap(
"sqlite3_column_count",
"number",
Expand Down Expand Up @@ -340,7 +373,8 @@ Module["onRuntimeInitialized"] = function onRuntimeInitialized() {

* @param {Statement.BindParams} values The values to bind
* @return {boolean} true if it worked
* @throws {String} SQLite Error
* @throws {SqliteError} If SQLite fails to bind a value
* @throws {String} If the statement was freed
*/
Statement.prototype.bind = function bind(values) {
if (!this.stmt) {
Expand All @@ -358,7 +392,8 @@ Module["onRuntimeInitialized"] = function onRuntimeInitialized() {
that can be retrieved with {@link Statement.get}.

@return {boolean} true if a row of result available
@throws {String} SQLite Error
@throws {SqliteError} If SQLite fails to run the statement
@throws {String} If the statement was freed
*/
Statement.prototype.step = function step() {
if (!this.stmt) {
Expand Down Expand Up @@ -438,6 +473,7 @@ Module["onRuntimeInitialized"] = function onRuntimeInitialized() {
<caption>Enable BigInt support</caption>
var stmt = db.prepare("SELECT * FROM test");
while (stmt.step()) console.log(stmt.get(null, {useBigInt: true}));
@throws {SqliteError} If SQLite fails to bind or to run the statement
*/
Statement.prototype.get = function get(params, config) {
config = config || {};
Expand Down Expand Up @@ -504,6 +540,7 @@ Module["onRuntimeInitialized"] = function onRuntimeInitialized() {
stmt.step(); // Execute the statement
console.log(stmt.getAsObject());
// Will print {nbr:5, data: Uint8Array([1,2,3]), null_value:null}
@throws {SqliteError} If SQLite fails to bind or to run the statement
*/
Statement.prototype.getAsObject = function getAsObject(params, config) {
var values = this.get(params, config);
Expand Down Expand Up @@ -540,6 +577,7 @@ Module["onRuntimeInitialized"] = function onRuntimeInitialized() {
Bind the values, execute the statement, ignoring the rows it returns,
and resets it
@param {Statement.BindParams} [values] Value to bind to the statement
@throws {SqliteError} If SQLite fails to bind or to run the statement
*/
Statement.prototype.run = function run(values) {
if (values != null) {
Expand Down Expand Up @@ -763,7 +801,8 @@ Module["onRuntimeInitialized"] = function onRuntimeInitialized() {

/** Prepare the next available SQL statement
@return {StatementIterator.StatementIteratorResult}
@throws {String} SQLite error or invalid iterator error
@throws {SqliteError} If SQLite fails to prepare the next statement
@throws {String} If the iterator is no longer valid
*/
StatementIterator.prototype.next = function next() {
if (this.sqlPtr === null) {
Expand Down Expand Up @@ -853,6 +892,7 @@ Module["onRuntimeInitialized"] = function onRuntimeInitialized() {
* one stored in the byte array passed in first argument
* @param {Array<number>} data An array of bytes representing
* an SQLite database file
* @throws {SqliteError} If SQLite cannot open the database
*/
function Database(data) {
this.filename = "dbfile_" + (0xffffffff * Math.random() >>> 0);
Expand Down Expand Up @@ -885,6 +925,7 @@ Module["onRuntimeInitialized"] = function onRuntimeInitialized() {
);

@return {Database} The database object (useful for method chaining)
@throws {SqliteError} If SQLite fails to prepare or to run the SQL
*/
Database.prototype.run = function run(sql, params) {
if (!this.db) {
Expand Down Expand Up @@ -975,6 +1016,7 @@ Module["onRuntimeInitialized"] = function onRuntimeInitialized() {
you **cannot** provide an sql string that contains several statements
(separated by `;`). This limitation does not apply to params as an object.
* @return {Array<Database.QueryExecResult>} The results of each statement
* @throws {SqliteError} If SQLite fails to prepare or to run the SQL
*/
Database.prototype.exec = function exec(sql, params, config) {
if (!this.db) {
Expand Down Expand Up @@ -1051,6 +1093,7 @@ Module["onRuntimeInitialized"] = function onRuntimeInitialized() {
db.each("SELECT name,age FROM users WHERE age >= $majority", {$majority:18},
function (row){console.log(row.name + " is a grown-up.")}
);
@throws {SqliteError} If SQLite fails to prepare or to run the SQL
*/
// eslint-disable-next-line max-len
Database.prototype.each = function each(sql, params, callback, done, config) {
Expand Down Expand Up @@ -1079,7 +1122,7 @@ Module["onRuntimeInitialized"] = function onRuntimeInitialized() {
(`?`, `:VVV`, `:AAA`, `@AAA`)
@param {Statement.BindParams} [params] values to bind to placeholders
@return {Statement} the resulting statement
@throws {String} SQLite error
@throws {SqliteError} If SQLite fails to prepare the SQL
*/
Database.prototype.prepare = function prepare(sql, params) {
var sqlPtr = stringToNewUTF8(sql);
Expand Down Expand Up @@ -1235,6 +1278,7 @@ Module["onRuntimeInitialized"] = function onRuntimeInitialized() {
*
* Databases **must** be closed when you're finished with them, or the
* memory consumption will grow forever
* @throws {SqliteError} If SQLite cannot close the database
*/
Database.prototype.close = function close() {
// do nothing if db is null or already closed
Expand All @@ -1258,16 +1302,27 @@ Module["onRuntimeInitialized"] = function onRuntimeInitialized() {
};

/** Analyze a result code, return null if no error occured, and throw
an error with a descriptive message otherwise
an error with a descriptive message otherwise. The error's `code` is the
name of SQLite's extended result code (such as
`"SQLITE_CONSTRAINT_UNIQUE"`), and its `errcode` is that code's number.
@nodoc
*/
Database.prototype.handleError = function handleError(returnCode) {
var errmsg;
var errcode;
var err;
if (returnCode === SQLITE_OK) {
return null;
}
errmsg = sqlite3_errmsg(this.db);
throw new Error(errmsg);
errcode = sqlite3_extended_errcode(this.db);
if ((errcode & 0xff) !== (returnCode & 0xff)) {
errcode = returnCode;
}
err = new Error(errmsg);
err["code"] = resultCodeNames[errcode];
err["errcode"] = errcode;
throw err;
};

/** Returns the number of changed rows (modified, inserted or deleted)
Expand Down Expand Up @@ -1372,6 +1427,7 @@ Module["onRuntimeInitialized"] = function onRuntimeInitialized() {
SQL statements.
@param {function(any)} func the actual function to be executed.
@return {Database} The database object. Useful for method chaining
@throws {SqliteError} If SQLite refuses to register the function
*/
Database.prototype.create_function = function create_function(
name,
Expand Down Expand Up @@ -1439,6 +1495,7 @@ Module["onRuntimeInitialized"] = function onRuntimeInitialized() {
will be used as the final value.
@return {Database} The database object. Useful for method chaining
@template T
@throws {SqliteError} If SQLite refuses to register the function
*/
Database.prototype.create_aggregate = function create_aggregate(
name,
Expand Down Expand Up @@ -1717,4 +1774,5 @@ Module["onRuntimeInitialized"] = function onRuntimeInitialized() {

// export Database to Module
Module["Database"] = Database;
Module["constants"] = Object.freeze(SQLITE_CONSTANTS);
};
1 change: 1 addition & 0 deletions src/exported_functions.json
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
"_sqlite3_exec",
"_sqlite3_free",
"_sqlite3_errmsg",
"_sqlite3_extended_errcode",
"_sqlite3_changes",
"_sqlite3_prepare_v2",
"_sqlite3_sql",
Expand Down
59 changes: 59 additions & 0 deletions test/test_errors.js
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,65 @@ exports.test = function(sql, assert) {
assert.throws(function(){
stmt.run([3]);
}, "Statements shouldn't be able to execute after the database is closed");

// Errors carry SQLite's extended result code, by name and by number
var codeOf = function(fn) {
try {
fn();
} catch (e) {
return [e.code, e.errcode];
}
assert.fail("Expected an error");
};
db = new sql.Database();
db.run("PRAGMA foreign_keys = ON");
db.run("CREATE TABLE parent (id INTEGER PRIMARY KEY)");
db.run("CREATE TABLE child (id INTEGER PRIMARY KEY," +
" parent INTEGER REFERENCES parent(id), name TEXT NOT NULL UNIQUE," +
" age INTEGER CHECK (age >= 0))");
db.run("INSERT INTO child (id, name) VALUES (1, 'a')");

assert.deepEqual(codeOf(function() {
db.run("INSERT INTO child (id, name) VALUES (1, 'b')");
}), ["SQLITE_CONSTRAINT_PRIMARYKEY", 1555], "A primary key violation");
assert.deepEqual(codeOf(function() {
db.run("INSERT INTO child (name) VALUES ('a')");
}), ["SQLITE_CONSTRAINT_UNIQUE", 2067], "A unique violation");
assert.deepEqual(codeOf(function() {
db.run("INSERT INTO child (name) VALUES (NULL)");
}), ["SQLITE_CONSTRAINT_NOTNULL", 1299], "A not null violation");
assert.deepEqual(codeOf(function() {
db.run("INSERT INTO child (name, age) VALUES ('c', -1)");
}), ["SQLITE_CONSTRAINT_CHECK", 275], "A check violation");
assert.deepEqual(codeOf(function() {
db.run("INSERT INTO child (name, parent) VALUES ('d', 9)");
}), ["SQLITE_CONSTRAINT_FOREIGNKEY", 787], "A foreign key violation");
var err = null;
try {
db.run("INSERT INTO child (name) VALUES ('a')");
} catch (e) {
err = e;
}
assert.strictEqual(err.errcode, sql.constants.SQLITE_CONSTRAINT_UNIQUE,
"An error's code is one of the module's constants");
assert.strictEqual(sql.constants.SQLITE_OPEN_READWRITE, 2,
"The module has SQLite's other constants too");
assert.deepEqual(codeOf(function() {
db.exec("SELEC 1");
}), ["SQLITE_ERROR", 1], "A syntax error");
assert.deepEqual(codeOf(function() {
db.prepare("SELECT ?").bind([1, 2]);
}), ["SQLITE_RANGE", 25], "Binding too many parameters");
var insert = db.prepare("INSERT INTO child (name) VALUES (?)");
assert.deepEqual(codeOf(function() {
insert.run(["a"]);
}), ["SQLITE_CONSTRAINT_UNIQUE", 2067], "A failing prepared statement");
insert.free();
db.close();

assert.deepEqual(codeOf(function() {
new sql.Database([1, 2, 3]).exec("SELECT * FROM sqlite_master");
}), ["SQLITE_NOTADB", 26], "Opening something that is not a database");
};

if (module == require.main) {
Expand Down
Loading