Report position of syntax errors

Author: simolus3

sqlite3/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 - Web: Support `localtime` datetime modifier in SQLite.
 - Introduce topics to dartdoc documentation.
+- Report locations of syntax errors in `SqliteException`.
 
 ## 2.7.2
 

sqlite3/assets/sqlite3.h

@@ -24,6 +24,7 @@ int sqlite3_extended_result_codes(sqlite3 *db, int onoff);
 int sqlite3_extended_errcode(sqlite3 *db);
 sqlite3_char *sqlite3_errmsg(sqlite3 *db);
 sqlite3_char *sqlite3_errstr(int code);
+int sqlite3_error_offset(sqlite3 *db);
 void sqlite3_free(void *ptr);
 
 // Versions

sqlite3/lib/src/exception.dart

@@ -25,6 +25,10 @@ final class SqliteException implements Exception {
   /// code, providing some idea of the cause of the failure.
   int get resultCode => extendedResultCode & 0xFF;
 
+  /// If this error is related to a syntex error in SQL, contains the byte
+  /// offset of the token associated with the error.
+  final int? offset;
+
   /// An informal description of what the `sqlite3` package was attempting to do
   /// when the exception occured, e.g. "preparing a statement",
   /// "opening the database".
@@ -48,6 +52,7 @@ final class SqliteException implements Exception {
     this.causingStatement,
     this.parametersToStatement,
     this.operation,
+    this.offset,
   ]);
 
   @override
@@ -67,7 +72,8 @@ final class SqliteException implements Exception {
     if (causingStatement != null) {
       buffer
         ..writeln()
-        ..write('  Causing statement: ')
+        ..write('  Causing statement')
+        ..write(offset != null ? ' (at position $offset): ' : ': ')
         ..write(causingStatement);
 
       if (parametersToStatement != null) {

sqlite3/lib/src/ffi/bindings.dart

@@ -24,6 +24,7 @@ class BindingsWithLibrary {
   final DynamicLibrary library;
 
   final bool supportsPrepareV3;
+  final bool supportsErrorOffset;
   final bool supportsColumnTableName;
 
   factory BindingsWithLibrary(DynamicLibrary library) {
@@ -50,17 +51,18 @@ class BindingsWithLibrary {
         i++;
       } while (lastOption != null);
     }
+    final supportsErrorOffset = library.providesSymbol('sqlite3_error_offset');
 
     return BindingsWithLibrary._(
-      bindings,
-      library,
-      bindings.sqlite3_libversion_number() >= _firstVersionForV3,
-      hasColumnMetadata,
-    );
+        bindings,
+        library,
+        bindings.sqlite3_libversion_number() >= _firstVersionForV3,
+        hasColumnMetadata,
+        supportsErrorOffset);
   }
 
   BindingsWithLibrary._(this.bindings, this.library, this.supportsPrepareV3,
-      this.supportsColumnTableName);
+      this.supportsColumnTableName, this.supportsErrorOffset);
 }
 
 final class FfiBindings extends RawSqliteBindings {
@@ -434,6 +436,15 @@ final class FfiDatabase extends RawSqliteDatabase {
     return bindings.bindings.sqlite3_extended_errcode(db);
   }
 
+  @override
+  int sqlite3_error_offset() {
+    if (bindings.supportsErrorOffset) {
+      return bindings.bindings.sqlite3_error_offset(db);
+    } else {
+      return -1;
+    }
+  }
+
   @override
   void sqlite3_extended_result_codes(int onoff) {
     bindings.bindings.sqlite3_extended_result_codes(db, onoff);

sqlite3/lib/src/ffi/sqlite3.g.dart

@@ -167,6 +167,20 @@ class Bindings {
   late final _sqlite3_errstr =
       _sqlite3_errstrPtr.asFunction<ffi.Pointer<sqlite3_char> Function(int)>();
 
+  int sqlite3_error_offset(
+    ffi.Pointer<sqlite3> db,
+  ) {
+    return _sqlite3_error_offset(
+      db,
+    );
+  }
+
+  late final _sqlite3_error_offsetPtr =
+      _lookup<ffi.NativeFunction<ffi.Int Function(ffi.Pointer<sqlite3>)>>(
+          'sqlite3_error_offset');
+  late final _sqlite3_error_offset =
+      _sqlite3_error_offsetPtr.asFunction<int Function(ffi.Pointer<sqlite3>)>();
+
   void sqlite3_free(
     ffi.Pointer<ffi.Void> ptr,
   ) {

sqlite3/lib/src/implementation/bindings.dart

@@ -70,6 +70,8 @@ abstract base class RawSqliteDatabase {
   int sqlite3_exec(String sql);
 
   int sqlite3_extended_errcode();
+  int sqlite3_error_offset();
+
   void sqlite3_extended_result_codes(int onoff);
   int sqlite3_close_v2();
   String sqlite3_errmsg();

sqlite3/lib/src/implementation/exception.dart

@@ -13,6 +13,11 @@ SqliteException createExceptionRaw(
   // Getting hold of more explanatory error code as SQLITE_IOERR error group has
   // an extensive list of extended error codes
   final extendedCode = db.sqlite3_extended_errcode();
+  final offset = switch (db.sqlite3_error_offset()) {
+    < 0 => null,
+    final offset => offset,
+  };
+
   return createExceptionFromExtendedCode(
     bindings,
     db,
@@ -21,6 +26,7 @@ SqliteException createExceptionRaw(
     operation: operation,
     previousStatement: previousStatement,
     statementArgs: statementArgs,
+    offset: offset,
   );
 }
 
@@ -32,6 +38,7 @@ SqliteException createExceptionFromExtendedCode(
   String? operation,
   String? previousStatement,
   List<Object?>? statementArgs,
+  int? offset,
 }) {
   // We don't need to free the pointer returned by sqlite3_errmsg: "Memory to
   // hold the error message string is managed internally. The application does
@@ -48,6 +55,7 @@ SqliteException createExceptionFromExtendedCode(
     previousStatement,
     statementArgs,
     operation,
+    offset,
   );
 }
 
@@ -68,10 +76,14 @@ SqliteException createException(
   );
 }
 
-Never throwException(DatabaseImplementation db, int returnCode,
-    {String? operation,
-    String? previousStatement,
-    List<Object?>? statementArgs}) {
+Never throwException(
+  DatabaseImplementation db,
+  int returnCode, {
+  String? operation,
+  String? previousStatement,
+  List<Object?>? statementArgs,
+  int? offset,
+}) {
   throw createException(
     db,
     returnCode,

sqlite3/lib/src/wasm/bindings.dart

@@ -134,6 +134,11 @@ final class WasmDatabase extends RawSqliteDatabase {
     return bindings.sqlite3_extended_errcode(db);
   }
 
+  @override
+  int sqlite3_error_offset() {
+    return bindings.sqlite3_error_offset(db);
+  }
+
   @override
   void sqlite3_extended_result_codes(int onoff) {
     bindings.sqlite3_extended_result_codes(db, onoff);

sqlite3/lib/src/wasm/wasm_interop.dart

@@ -89,7 +89,8 @@ class WasmBindings {
   final JSFunction? _sqlite3_db_config,
       _sqlite3_initialize,
       _commit_hooks,
-      _rollback_hooks;
+      _rollback_hooks,
+      _sqlite3_error_offset;
 
   final Global _sqlite3_temp_directory;
 
@@ -167,6 +168,7 @@ class WasmBindings {
         _sqlite3_stmt_readonly = instance.functions['sqlite3_stmt_readonly']!,
         _sqlite3_db_config = instance.functions['dart_sqlite3_db_config_int'],
         _sqlite3_initialize = instance.functions['sqlite3_initialize'],
+        _sqlite3_error_offset = instance.functions['sqlite3_error_offset'],
         _commit_hooks = instance.functions['dart_sqlite3_commits'],
         _rollback_hooks = instance.functions['dart_sqlite3_rollbacks'],
         _sqlite3_temp_directory = instance.globals['sqlite3_temp_directory']!
@@ -285,6 +287,10 @@ class WasmBindings {
   Pointer sqlite3_errstr(int resultCode) =>
       _sqlite3_errstr.callReturningInt(resultCode.toJS);
 
+  int sqlite3_error_offset(Pointer db) {
+    return _sqlite3_error_offset?.callReturningInt(db.toJS) ?? -1;
+  }
+
   int sqlite3_extended_result_codes(Pointer db, int onoff) {
     return _sqlite3_extended_result_codes.callReturningInt2(
         db.toJS, onoff.toJS);

sqlite3/test/ffi/errors_test.dart

@@ -9,6 +9,9 @@ import 'package:test/test.dart';
 import 'package:test_descriptor/test_descriptor.dart' as d;
 
 void main() {
+  final version = sqlite3.version;
+  final hasErrorOffset = version.versionNumber > 3038000;
+
   test('open read-only exception', () async {
     final path = d.path('read_only_exception.db');
 
@@ -153,5 +156,27 @@ SqliteException(1): message
   Causing statement: SELECT foo;''',
       );
     });
+
+    test(
+      'reports position',
+      () {
+        final db = sqlite3.openInMemory();
+        addTearDown(db.dispose);
+
+        expect(
+          () => db.select('SELECT totally invalid syntax;'),
+          throwsA(isA<SqliteException>()
+              .having(
+                (e) => e.causingStatement,
+                'causingStatement',
+                'SELECT totally invalid syntax;',
+              )
+              .having((e) => e.offset, 'offset', 23)
+              .having((e) => e.toString(), 'toString()',
+                  contains('Causing statement (at position 23): SELECT'))),
+        );
+      },
+      skip: hasErrorOffset ? null : 'Missing sqlite3_error_offset',
+    );
   });
 }

sqlite3/test/wasm/sqlite3_test.dart

@@ -98,6 +98,24 @@ void main() {
           });
         }
       });
+
+      test('can report error location', () {
+        final db = sqlite3.openInMemory();
+        addTearDown(db.dispose);
+
+        expect(
+          () => db.select('SELECT totally invalid syntax;'),
+          throwsA(isA<SqliteException>()
+              .having(
+                (e) => e.causingStatement,
+                'causingStatement',
+                'SELECT totally invalid syntax;',
+              )
+              .having((e) => e.offset, 'offset', 23)
+              .having((e) => e.toString(), 'toString()',
+                  contains('Causing statement (at position 23): SELECT'))),
+        );
+      });
     });
   }