Update version to 1.3.0

Author: graknol

README.md

@@ -18,6 +18,7 @@ The foundation of the ecosystem. It provides all the core functionality for sche
 - **Type-Safe Queries**: Build complex SQL queries with type safety and autocompletion.
 - **Streaming Queries**: Create reactive queries that automatically emit new results when underlying data changes.
 - **Conflict-Free Sync**: Built-in support for data synchronization using a Hybrid Logical Clock (HLC) to ensure conflict-free, last-write-wins data merging.
+- **Graceful Error Handling**: Robust constraint violation handling during bulk operations with configurable strategies.
 - **File Management**: Integrated support for attaching and managing files linked to database records.
 
 ### 📱 Flutter Integration (`declarative_sqlite_flutter`)
@@ -48,12 +49,12 @@ To get started, add the necessary packages to your `pubspec.yaml`:
 dependencies:
   flutter:
     sdk: flutter
-  declarative_sqlite: ^1.0.2
-  declarative_sqlite_flutter: ^1.0.2
+  declarative_sqlite: ^1.3.0
+  declarative_sqlite_flutter: ^1.3.0
 
 dev_dependencies:
   build_runner: ^2.4.10
-  declarative_sqlite_generator: ^1.0.2
+  declarative_sqlite_generator: ^1.3.0
 ```
 
 For a detailed guide, please refer to our [**official documentation**](https://graknol.github.io/declarative_sqlite/).

declarative_sqlite/CHANGELOG.md

@@ -1,3 +1,28 @@
+## 1.3.0
+
+### Features
+- **Constraint Violation Handling in bulkLoad**: Added graceful constraint violation handling with `ConstraintViolationStrategy`
+  - `throwException` (default): Maintains existing behavior - throws on constraint violations
+  - `skip`: Silently skips problematic rows and continues processing valid ones
+  - Comprehensive constraint detection for unique, primary key, check, foreign key, and NOT NULL violations
+  - Detailed logging for monitoring and debugging constraint violation events
+- **Fixed Unique Constraint Generation**: Resolved issue where unique keys weren't properly creating `CREATE UNIQUE INDEX` statements
+  - Unique constraints now generate proper SQL: `CREATE UNIQUE INDEX uniq_table_column ON table (column)`
+  - Improved migration script generation to handle both regular indexes and unique constraints
+
+### Developer Experience
+- Enhanced bulkLoad method for server synchronization scenarios
+- Better error handling and logging for constraint violations
+- Safer bulk loading operations with granular control over error handling
+
+### Bug Fixes
+- Fixed missing unique constraint generation in schema migration scripts
+- Improved constraint violation detection and categorization
+
+### Documentation
+- Updated bulkLoad method documentation with constraint violation handling examples
+- Enhanced migration guide with unique constraint best practices
+
 ## 1.2.0
 
 ### Features

declarative_sqlite/lib/declarative_sqlite.dart

@@ -29,8 +29,12 @@ export 'src/record_map_factory_registry.dart';
 export 'src/files/filesystem_file_repository.dart';
 
 // Schema classes
-export 'src/schema/db_table.dart';
 export 'src/schema/schema.dart';
+export 'src/schema/db_table.dart';
+export 'src/schema/db_view.dart';
+export 'src/schema/db_column.dart';
+export 'src/schema/db_key.dart';
+export 'src/schema/live_schema.dart';
 
 // Streaming queries
 export 'src/streaming/query_dependency_analyzer.dart';

declarative_sqlite/lib/src/declarative_database.dart

@@ -26,6 +26,15 @@ import 'sync/hlc.dart';
 import 'sync/dirty_row_store.dart';
 import 'sync/dirty_row.dart';
 
+/// Strategy for handling constraint violations during bulk load operations
+enum ConstraintViolationStrategy {
+  /// Throw the original exception (default behavior)
+  throwException,
+  
+  /// Silently skip the problematic row and continue processing
+  skip,
+}
+
 /// A declarative SQLite database.
 class DeclarativeDatabase {
   /// The underlying sqflite database.
@@ -1085,8 +1094,23 @@ class DeclarativeDatabase {
   ///
   /// Rows processed by this method are NOT marked as dirty, as they represent
   /// data coming from the server rather than local changes to be synchronized.
+  ///
+  /// ## Constraint Violation Handling
+  ///
+  /// The [onConstraintViolation] parameter controls how constraint violations
+  /// are handled when they occur:
+  ///
+  /// - `ConstraintViolationStrategy.throwException` (default): Throws the original exception
+  /// - `ConstraintViolationStrategy.skip`: Silently skips the problematic row
+  ///
+  /// The `skip` strategy is useful when loading data from a server where some
+  /// rows might conflict with local data, and you want to preserve existing
+  /// local data while still loading non-conflicting rows.
   Future<void> bulkLoad(
-      String tableName, List<Map<String, Object?>> rows) async {
+    String tableName,
+    List<Map<String, Object?>> rows, {
+    ConstraintViolationStrategy onConstraintViolation = ConstraintViolationStrategy.throwException,
+  }) async {
     final tableDef = _getTableDefinition(tableName);
     final pkColumns = tableDef.keys
         .where((k) => k.isPrimary)
@@ -1144,17 +1168,45 @@ class DeclarativeDatabase {
         }
 
         if (valuesToUpdate.isNotEmpty) {
-          await _update(
-            tableName,
-            valuesToUpdate,
-            now,
-            where: 'system_id = ?',
-            whereArgs: [systemId],
-          );
+          try {
+            await _update(
+              tableName,
+              valuesToUpdate,
+              now,
+              where: 'system_id = ?',
+              whereArgs: [systemId],
+            );
+          } catch (e) {
+            if (_isConstraintViolation(e)) {
+              await _handleConstraintViolation(
+                onConstraintViolation,
+                e,
+                tableName,
+                'UPDATE',
+                row,
+              );
+            } else {
+              rethrow;
+            }
+          }
         }
       } else {
         // INSERT logic - mark as server origin
-        await _insertFromServer(tableName, row, hlcClock.now());
+        try {
+          await _insertFromServer(tableName, row, hlcClock.now());
+        } catch (e) {
+          if (_isConstraintViolation(e)) {
+            await _handleConstraintViolation(
+              onConstraintViolation,
+              e,
+              tableName,
+              'INSERT',
+              row,
+            );
+          } else {
+            rethrow;
+          }
+        }
       }
     }
 
@@ -1171,6 +1223,41 @@ class DeclarativeDatabase {
     }
     return await dirtyRowStore!.getAll();
   }
+
+  /// Checks if an exception is a constraint violation
+  bool _isConstraintViolation(dynamic exception) {
+    final errorMessage = exception.toString().toLowerCase();
+    return errorMessage.contains('constraint') ||
+           errorMessage.contains('unique') ||
+           errorMessage.contains('primary key') ||
+           errorMessage.contains('foreign key') ||
+           errorMessage.contains('check constraint') ||
+           errorMessage.contains('not null constraint') ||
+           errorMessage.contains('sqlite_constraint');
+  }
+
+  /// Handles constraint violations based on the specified strategy
+  Future<void> _handleConstraintViolation(
+    ConstraintViolationStrategy strategy,
+    dynamic exception,
+    String tableName,
+    String operation,
+    Map<String, Object?> row,
+  ) async {
+    switch (strategy) {
+      case ConstraintViolationStrategy.throwException:
+        throw exception;
+
+      case ConstraintViolationStrategy.skip:
+        // Log the skip and continue silently
+        developer.log(
+          '⚠️ Skipping row due to constraint violation in $operation on table $tableName: ${exception.toString()}',
+          name: 'BulkLoadConstraintViolation',
+          level: 900, // WARNING level
+        );
+        return;
+    }
+  }
 }
 
 // Static helper methods for settings

declarative_sqlite/lib/src/migration/generate_migration_scripts.dart

@@ -83,10 +83,17 @@ List<String> _generateCreateTableScripts(CreateTable change) {
   scripts.add(_generateCreateTableScript(change));
 
   final indexKeys = table.keys.where((k) => k.type == KeyType.indexed);
+  final uniqueKeys = table.keys.where((k) => k.type == KeyType.unique);
+  
   if (indexKeys.isNotEmpty) {
     developer.log('    📊 Creating ${indexKeys.length} indexes for table ${table.name}', name: 'Migration');
   }
 
+  if (uniqueKeys.isNotEmpty) {
+    developer.log('    📊 Creating ${uniqueKeys.length} unique constraints for table ${table.name}', name: 'Migration');
+  }
+  
+  // Create regular indexes
   for (final key in indexKeys) {
     var indexName = 'idx_${table.name}_${key.columns.join('_')}';
     if (indexName.length > 62) {
@@ -101,6 +108,21 @@ List<String> _generateCreateTableScripts(CreateTable change) {
         'CREATE INDEX $indexName ON ${table.name} (${key.columns.join(', ')});');
   }
 
+  // Create unique indexes
+  for (final key in uniqueKeys) {
+    var indexName = 'uniq_${table.name}_${key.columns.join('_')}';
+    if (indexName.length > 62) {
+      final hash =
+          sha1.convert(utf8.encode(indexName)).toString().substring(0, 10);
+      indexName = 'uniq_${table.name}_$hash';
+      developer.log('      • Unique index name truncated: $indexName (${key.columns.join(', ')})', name: 'Migration');
+    } else {
+      developer.log('      • Unique index: $indexName (${key.columns.join(', ')})', name: 'Migration');
+    }
+    scripts.add(
+        'CREATE UNIQUE INDEX $indexName ON ${table.name} (${key.columns.join(', ')});');
+  }
+  
   return scripts;
 }
 

declarative_sqlite/pubspec.yaml

@@ -1,6 +1,6 @@
 name: declarative_sqlite
 description: A dart package for declaratively creating SQLite tables and automatically migrating them.
-version: 1.2.0
+version: 1.3.0
 repository: https://github.com/graknol/declarative_sqlite
 
 environment:

declarative_sqlite/test/bulk_load_constraint_test.dart

@@ -0,0 +1,120 @@
+import 'package:declarative_sqlite/declarative_sqlite.dart';
+import 'package:sqflite_common_ffi/sqflite_ffi.dart';
+import 'package:test/test.dart';
+
+void main() {
+  sqfliteFfiInit();
+
+  late DeclarativeDatabase database;
+
+  setUp(() async {
+    sqfliteFfiInit();
+    
+    final schema = SchemaBuilder()
+        .table('users', (table) {
+          table.guid('id').notNull('default-id');
+          table.text('name').notNull('Default Name');
+          table.text('email').notNull('[email protected]');
+          table.key(['id']).primary();
+          table.key(['email']).unique(); // This will cause constraint violations
+        })
+        .build();
+
+    database = await DeclarativeDatabase.open(
+      ':memory:',
+      databaseFactory: databaseFactoryFfi,
+      schema: schema,
+      fileRepository: FilesystemFileRepository('temp_test'),
+    );
+  });
+
+  tearDown(() async {
+    await database.close();
+  });
+
+  group('Bulk Load Constraint Violation Handling', () {
+    test('throwException strategy throws on constraint violation', () async {
+      // Insert initial data
+      await database.insert('users', {
+        'id': 'user-1',
+        'name': 'John Doe',
+        'email': '[email protected]',
+      });
+
+      // Try to bulk load data with duplicate email (should throw)
+      expect(() async {
+        await database.bulkLoad(
+          'users',
+          [
+            {
+              'system_id': 'unique-server-user-1', // Different system_id to force INSERT
+              'id': 'user-2',
+              'name': 'Jane Doe',
+              'email': '[email protected]', // Duplicate email
+            }
+          ],
+          onConstraintViolation: ConstraintViolationStrategy.throwException,
+        );
+      }, throwsException);
+    });
+
+    test('skip strategy silently skips constraint violations', () async {
+      // Insert initial data
+      await database.insert('users', {
+        'id': 'user-1',
+        'name': 'John Doe',
+        'email': '[email protected]',
+      });
+
+      // Bulk load data with duplicate email (should skip silently)
+      await database.bulkLoad(
+        'users',
+        [
+          {
+            'system_id': 'unique-server-user-2', // Different system_id to force INSERT
+            'id': 'user-2',
+            'name': 'Jane Doe',
+            'email': '[email protected]', // Duplicate email - should be skipped
+          },
+          {
+            'system_id': 'unique-server-user-3', // Different system_id to force INSERT
+            'id': 'user-3',
+            'name': 'Bob Smith',
+            'email': '[email protected]', // Valid email - should work
+          }
+        ],
+        onConstraintViolation: ConstraintViolationStrategy.skip,
+      );
+
+      // Verify that only the valid row was inserted
+      final users = await database.queryMaps((q) => q.from('users'));
+      expect(users.length, equals(2)); // Original + 1 valid new row
+      
+      final emails = users.map((u) => u['email']).toList();
+      expect(emails, contains('[email protected]'));
+      expect(emails, contains('[email protected]'));
+      expect(emails, isNot(contains('[email protected]'))); // Jane should be skipped
+    });
+
+    test('default behavior is to throw exceptions', () async {
+      // Insert initial data
+      await database.insert('users', {
+        'id': 'user-1',
+        'name': 'John Doe',
+        'email': '[email protected]',
+      });
+
+      // Try to bulk load data with duplicate email (should throw by default)
+      expect(() async {
+        await database.bulkLoad('users', [
+          {
+            'system_id': 'unique-server-user-4', // Different system_id to force INSERT
+            'id': 'user-2',
+            'name': 'Jane Doe',
+            'email': '[email protected]', // Duplicate email
+          }
+        ]);
+      }, throwsException);
+    });
+  });
+}

declarative_sqlite_flutter/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 1.3.0
+
+### Updates
+- Updated to use declarative_sqlite ^1.3.0
+- Enhanced compatibility with new constraint violation handling features
+- Improved data safety when working with server synchronization and constraint violations in Flutter widgets
+- Fixed the `recreateDatabase` parameter not getting passed from the `DatabaseProvider` widget to the `DeclarativeDatabase.open(...)` call
+
 ## 1.2.0
 
 ### Updates

declarative_sqlite_flutter/lib/src/database_provider.dart

@@ -164,6 +164,7 @@ class _DatabaseProviderState extends State<DatabaseProvider> {
             'files',
           ),
         ),
+        recreateDatabase: widget.recreateDatabase,
       );
       setState(() {
         _database = db;