bun:sqlite: count byteOffset from the start of the SQL text in run and exec

docs/runtime/sql.mdx

@@ -1138,7 +1138,7 @@ try {
     // SQLite-specific error
     console.log(error.code); // SQLite error code (e.g., "SQLITE_CONSTRAINT")
     console.log(error.errno); // SQLite error number
-    console.log(error.byteOffset); // Byte offset in SQL statement (if available)
+    console.log(error.byteOffset); // UTF-8 byte offset in the query text (-1 or undefined if not known)
   } else if (error instanceof SQL.SQLError) {
     // Generic SQL error (base class)
     console.log(error.message);

packages/bun-types/sql.d.ts

@@ -158,6 +158,14 @@ declare module "bun" {
     class SQLiteError extends SQLError {
       public readonly code: string;
       public readonly errno: number;
+      /**
+       * The UTF-8 byte offset of the token that the error refers to, counted
+       * from the start of the query text. `-1` if the error refers to no
+       * token, or if the offset is not known.
+       *
+       * Not set on errors that Bun raises without SQLite, such as
+       * `ERR_SQLITE_CONNECTION_CLOSED`.
+       */
       public readonly byteOffset?: number | undefined;
 
       constructor(message: string, options: { code: string; errno: number; byteOffset?: number | undefined });

packages/bun-types/sqlite.d.ts

@@ -1293,9 +1293,14 @@ declare module "bun:sqlite" {
     code?: string;
 
     /**
-     * The UTF-8 byte offset of the sqlite3 query that failed, if known
+     * The UTF-8 byte offset of the token that the error refers to, counted
+     * from the start of the SQL string that was passed. `-1` if the error
+     * refers to no token, or if the offset is not known.
      *
-     * This corresponds to `sqlite3_error_offset`.
+     * {@link Database.run} counts from the start of the whole string, also
+     * when the statement that failed is not the first one.
+     *
+     * The offset comes from `sqlite3_error_offset`.
      *
      * @since v1.0.21
      */

src/jsc/bindings/sqlite/JSSQLStatement.cpp

@@ -376,11 +376,14 @@ JSC_DECLARE_CUSTOM_GETTER(jsSqlStatementGetColumnDeclaredTypes);
 JSC_DECLARE_CUSTOM_GETTER(jsSqlStatementGetSafeIntegers);
 JSC_DECLARE_CUSTOM_SETTER(jsSqlStatementSetSafeIntegers);
 
-static JSValue createSQLiteError(JSC::JSGlobalObject* globalObject, sqlite3* db)
+static JSValue createSQLiteError(JSC::JSGlobalObject* globalObject, sqlite3* db, int64_t byteOffsetBase = 0)
 {
     auto& vm = JSC::getVM(globalObject);
     int code = sqlite3_extended_errcode(db);
-    int byteOffset = sqlite3_error_offset(db);
+    int64_t byteOffset = sqlite3_error_offset(db);
+    // SQLite counts the offset from the pointer that sqlite3_prepare_v3 received.
+    if (byteOffset >= 0)
+        byteOffset += byteOffsetBase;
 
     const char* msg = sqlite3_errmsg(db);
     // Error messages can echo identifiers/values from the query, which SQLite does
@@ -1526,8 +1529,9 @@ JSC_DEFINE_HOST_FUNCTION(jsSQLStatementExecuteFunction, (JSC::JSGlobalObject * l
     auto utf8 = Bun::UTF8View::tryCreate(lexicalGlobalObject, scope, sqlString);
     RETURN_IF_EXCEPTION(scope, {});
 
-    const char* sqlStringHead = utf8->span().data();
-    const char* end = utf8->span().data() + utf8->span().size();
+    const char* const sqlStringStart = utf8->span().data();
+    const char* sqlStringHead = sqlStringStart;
+    const char* end = sqlStringStart + utf8->span().size();
 
     bool didSetBindings = false;
     bool didExecuteAny = false;
@@ -1561,8 +1565,10 @@ JSC_DEFINE_HOST_FUNCTION(jsSQLStatementExecuteFunction, (JSC::JSGlobalObject * l
 
         rc = sqlite3_prepare_v3(db, sqlStringHead, end - sqlStringHead, 0, &sql.stmt, &tail);
 
-        if (rc != SQLITE_OK)
-            break;
+        if (rc != SQLITE_OK) {
+            throwException(lexicalGlobalObject, scope, createSQLiteError(lexicalGlobalObject, db, sqlStringHead - sqlStringStart));
+            return {};
+        }
 
         if (!sql.stmt) {
             // Empty statement. Stop if sqlite3_prepare_v3 made no progress
@@ -1608,6 +1614,7 @@ JSC_DEFINE_HOST_FUNCTION(jsSQLStatementExecuteFunction, (JSC::JSGlobalObject * l
     }
 
     if (rc != SQLITE_OK && rc != SQLITE_DONE) [[unlikely]] {
+        // sqlite3_step failed. sqlStringHead is past that statement, so it is no base for the offset.
         throwException(lexicalGlobalObject, scope, createSQLiteError(lexicalGlobalObject, db));
         return {};
     }

test/js/bun/sqlite/sqlite.test.js

@@ -1286,6 +1286,73 @@ it("syntax error sets the byteOffset", () => {
   }
 });
 
+// The system SQLite of macOS before 13 has no sqlite3_error_offset. Bun reports -1 there.
+const hasErrorOffset = !(isMacOS && !isMacOSVersionAtLeast(13));
+
+// sqlite3_error_offset counts from the pointer that sqlite3_prepare_v3 received. run() and exec() prepare each
+// statement from where the one before it ended, after the blanks and `;` that bun skips, so the offset of the
+// statement in the text has to be added.
+it.each(["run", "exec"])("%s() counts byteOffset from the start of the SQL text", method => {
+  const byteOffsetOf = (sql, how = method) => {
+    using db = new Database(":memory:");
+    db.run("CREATE TABLE users (id, name)");
+    try {
+      db[how](sql);
+    } catch (e) {
+      return e.byteOffset;
+    }
+    return "no error";
+  };
+  // The UTF-8 byte index of the token that the error names.
+  const at = (sql, token) => (hasErrorOffset ? Buffer.from(sql).indexOf(token) : -1);
+
+  // The first statement of the text fails. prepare() compiles it from the start of the text and agrees.
+  const first = [
+    ["SELECT nmae FROM users", "nmae"],
+    ["\n    SELECT nmae FROM users", "nmae"],
+    [" !", "!"],
+    [";;; SELECT nmae FROM users", "nmae"],
+    ["-- comment\nSELECT nmae FROM users", "nmae"],
+    ["/* comment */ SELECT nmae FROM users", "nmae"],
+    ["\n\t SELECT 'abc", "'abc"],
+  ];
+  expect(first.map(([sql]) => ({ sql, byteOffset: byteOffsetOf(sql), prepare: byteOffsetOf(sql, "prepare") }))).toEqual(
+    first.map(([sql, token]) => ({ sql, byteOffset: at(sql, token), prepare: at(sql, token) })),
+  );
+
+  // A later statement fails. The offset counts the statements, blanks, comments and non-ASCII text before it.
+  const later = [
+    ["DELETE FROM users; SELECT nmae FROM users", "nmae"],
+    ["DELETE FROM users; DELETE FROM users; SELECT nmae FROM users", "nmae"],
+    ["DELETE FROM users; -- comment\n SELECT nmae FROM users", "nmae"],
+    ["SELECT 'é😀'; SELECT nmae FROM users", "nmae"],
+    ["SELECT ';'; SELECT nmae FROM users", "nmae"],
+    ["CREATE TRIGGER t AFTER INSERT ON users BEGIN DELETE FROM users; END; SELECT nmae FROM users", "nmae"],
+    ["SELECT 1; SELECT * FROM users!!", "!!"],
+    ["SELECT 1; !!", "!!"],
+    ["SELECT 1; SELECT 'abc", "'abc"],
+    // SQLite rejects a vertical tab. Bun skips it in front of a statement.
+    ["\vSELECT nmae FROM users", "nmae"],
+  ];
+  expect(later.map(([sql]) => ({ sql, byteOffset: byteOffsetOf(sql) }))).toEqual(
+    later.map(([sql, token]) => ({ sql, byteOffset: at(sql, token) })),
+  );
+
+  // An error that names no token has no offset, wherever its statement is. The last one fails in sqlite3_step.
+  const noToken = [
+    "SELECT 1;\n\n  SELECT * FROM nope",
+    "SELECT 1; SELECT (",
+    "\n  INSERT INTO users VALUES (1, 2, 3)",
+    "SELECT 1;\n  SELECT abs(-9223372036854775808)",
+  ];
+  expect(noToken.map(sql => ({ sql, byteOffset: byteOffsetOf(sql) }))).toEqual(
+    noToken.map(sql => ({ sql, byteOffset: -1 })),
+  );
+
+  // An error that does not come from SQLite has no byteOffset property.
+  expect(byteOffsetOf(" ; ")).toBeUndefined();
+});
+
 it("Missing DB throws SQLITE_CANTOPEN", () => {
   try {
     new Database("./definitely/not/found");

test/js/sql/sqlite-sql.test.ts

@@ -1,7 +1,7 @@
 import { randomUUIDv7, SQL } from "bun";
 import { Database } from "bun:sqlite";
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, mock, test } from "bun:test";
-import { isDebug, tempDir } from "harness";
+import { isDebug, isMacOS, isMacOSVersionAtLeast, tempDir } from "harness";
 import { existsSync } from "node:fs";
 import { rm, stat } from "node:fs/promises";
 import { join } from "node:path";
@@ -2063,6 +2063,53 @@ describe("Error handling", () => {
       expect((err as Error).message).toContain("FOREIGN KEY");
     }
   });
+
+  test("byteOffset counts from the start of the query text", async () => {
+    await sql`CREATE TABLE offsets (id, name)`;
+    // The system SQLite of macOS before 13 has no sqlite3_error_offset. Bun reports -1 there.
+    const hasErrorOffset = !(isMacOS && !isMacOSVersionAtLeast(13));
+    const at = (text: string, token: string) => (hasErrorOffset ? Buffer.from(text).indexOf(token) : -1);
+    const byteOffsetOf = async (query: PromiseLike<unknown>) => {
+      try {
+        await query;
+      } catch (error: any) {
+        return error.byteOffset;
+      }
+      return "no error";
+    };
+
+    // The adapter sends text with no SELECT, PRAGMA, WITH, EXPLAIN or RETURNING token to Database.run, which
+    // prepares one statement at a time.
+    const indented = "\n      DELETE FROM offsets WHERE nmae = 1";
+    const second = "DELETE FROM offsets WHERE name = 'é'; DELETE FROM offsets WHERE nmae = 1";
+    // Text with such a token goes to Database.prepare, which compiles the first statement from the start.
+    const select = "\n      SELECT nmae FROM offsets";
+    using dir = tempDir("sqlite-sql-offsets", { "statements.sql": second });
+
+    expect({
+      tagged: await byteOffsetOf(sql`
+      DELETE FROM offsets WHERE nmae = 1`),
+      unsafe: await byteOffsetOf(sql.unsafe(second)),
+      file: await byteOffsetOf(sql.file(join(String(dir), "statements.sql"))),
+      transaction: await byteOffsetOf(sql.begin(tx => tx.unsafe(second))),
+      select: await byteOffsetOf(sql.unsafe(select)),
+    }).toEqual({
+      tagged: at(indented, "nmae"),
+      unsafe: at(second, "nmae"),
+      file: at(second, "nmae"),
+      transaction: at(second, "nmae"),
+      select: at(select, "nmae"),
+    });
+
+    // An error that Bun raises without SQLite has no byteOffset property.
+    const closed = new SQL("sqlite://:memory:");
+    await closed.close();
+    const error = await closed`SELECT 1`.catch(e => e);
+    expect({ code: error.code, hasByteOffset: "byteOffset" in error }).toEqual({
+      code: "ERR_SQLITE_CONNECTION_CLOSED",
+      hasByteOffset: false,
+    });
+  });
 });
 
 describe("Connection management", () => {