Expand documentation comments a bit

drift/lib/src/dsl/columns.dart

@@ -46,6 +46,13 @@ abstract class Column<T> extends Expression<T> {
 typedef IntColumn = Column<int?>;
 
 /// A column that stores BigInt values.
+///
+/// In a database, this is the exact same thing as an [IntColumn]. However,
+/// unlike an [IntColumn], the resulting value is mapped to a [BigInt] in Dart.
+/// As sqlite3 only supports 64-big integers (the same range that an [int] in
+/// Dart can represent), there is no need to use an [Int64Column] for native
+/// apps. For Dart compiled to JavaScript though, it may be beneficial to use
+/// [BigInt]s to avoid loosing precision for values larger than 2⁵².
 typedef Int64Column = Column<BigInt?>;
 
 /// A column that stores boolean values. Booleans will be stored as an integer

drift/lib/src/dsl/table.dart

@@ -98,23 +98,38 @@ abstract class Table extends HasResultSet {
   List<String> get customConstraints => [];
 
   /// Use this as the body of a getter to declare a column that holds integers.
-  /// Caution! Compiled to web [int] can only hold maximum of 52 bits! To
-  /// store values higher than this, use [int64()] instead.
+  ///
   /// Example (inside the body of a table class):
   /// ```
   /// IntColumn get id => integer().autoIncrement()();
   /// ```
+  ///
+  /// In sqlite3, an integer column stores 64-big integers. This column maps
+  /// values to an [int] in Dart, which works well on native platforms. On the
+  /// web, be aware that [int]s are [double]s internally which means that only
+  /// integers smaller than 2⁵² can safely be stored.
+  /// If you need web support __and__ a column that potential stores integers
+  /// larger than what fits into 52 bits, consider using a [int64] column
+  /// instead. That column stores the same value in a database, but makes drift
+  /// report the values as a [BigInt] in Dart.
+
   @protected
   ColumnBuilder<int> integer() => _isGenerated();
 
-  /// Use this as the body of a getter to declare a column that holds web-safe
-  /// 64-bit integer. Although this is a BigInt type, the database can only
-  /// hold a maximum of 64 bits. Trying to store a value that exceeds this will
-  /// case an exception.
-  /// Example (inside the body of a table class):
-  /// ```
-  /// Int64Column get int64Number => int64()();
-  /// ```
+  /// Use this as the body of a getter to declare a column that holds a 64-big
+  /// integer as a [BigInt].
+  ///
+  /// The main purpose of this column is to support large integers for web apps
+  /// compiled to JavaScript, where using an [int] does not reliably work for
+  /// numbers larger than 2⁵².
+  /// It stores the exact same data as an [integer] column (and supports the
+  /// same options), but instructs drift to generate a data class with a
+  /// [BigInt] field and a database conversion aware of large intergers.
+  ///
+  /// __Note__: The use of [int64] is only necessary for apps that need to work
+  /// on the web __and__ use columns that are likely to store values larger than
+  /// 2⁵². In all other cases, using [integer] directly is much more efficient
+  /// and recommended.
   @protected
   ColumnBuilder<BigInt> int64() => _isGenerated();
 

drift/pubspec.yaml

@@ -15,7 +15,7 @@ dependencies:
   js: ^0.6.3
   meta: ^1.3.0
   stream_channel: ^2.1.0
-  sqlite3: ^1.7.0
+  sqlite3: ^1.7.1
 
 dev_dependencies:
   build_test: ^2.0.0
@@ -36,8 +36,3 @@ dependency_overrides:
     path: ../drift_dev
   sqlparser:
     path: ../sqlparser
-  sqlite3:
-    git:
-      url: https://github.com/simolus3/sqlite3.dart
-      ref: main
-      path: sqlite3

sqlparser/lib/src/analysis/types/data.dart

@@ -101,7 +101,8 @@ class IsDateTime extends TypeHint {
   const IsDateTime();
 }
 
-/// Type hint to mark that this type will contain a date time value.
+/// A type hint to mark that this type might contain a large integer that should
+/// be mapped to Dart as a [BigInt].
 class IsBigInt extends TypeHint {
   const IsBigInt();
 }