diff --git a/drift/lib/src/dsl/columns.dart b/drift/lib/src/dsl/columns.dart index 93ac0ce6..348bf401 100644 --- a/drift/lib/src/dsl/columns.dart +++ b/drift/lib/src/dsl/columns.dart @@ -46,6 +46,13 @@ abstract class Column extends Expression { typedef IntColumn = Column; /// 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; /// A column that stores boolean values. Booleans will be stored as an integer diff --git a/drift/lib/src/dsl/table.dart b/drift/lib/src/dsl/table.dart index 60e74ee2..be47cba0 100644 --- a/drift/lib/src/dsl/table.dart +++ b/drift/lib/src/dsl/table.dart @@ -98,23 +98,38 @@ abstract class Table extends HasResultSet { List 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 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 int64() => _isGenerated(); diff --git a/drift/pubspec.yaml b/drift/pubspec.yaml index 5e600d99..9949ef68 100644 --- a/drift/pubspec.yaml +++ b/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 diff --git a/sqlparser/lib/src/analysis/types/data.dart b/sqlparser/lib/src/analysis/types/data.dart index 6cade55c..41f0a480 100644 --- a/sqlparser/lib/src/analysis/types/data.dart +++ b/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(); }