Sqflite Darwin Setup

sqflite_darwin: iOS and macOS implementation of sqflite

sqflite_darwin is the endorsed iOS/macOS implementation of the sqflite federated plugin (one shared Objective-C source tree, sharedDarwinSource: true). Adding sqflite pulls it in automatically (default_package: sqflite_darwin for both ios and macos); SqfliteDarwin.registerWith() installs the method channel DatabaseFactory as databaseFactory before main(). It links the system SQLite through a bundled, renamed copy of FMDB (SqfliteDarwin* classes), so the SQLite version depends on the OS version.

# pubspec.yaml (normal case): nothing darwin specific
dependencies:
  sqflite:

Guidelines

• Add sqflite_darwin explicitly only when the app does not depend on sqflite (for example it codes against package:sqflite_common and ships iOS/macOS only). Registration is automatic; then use databaseFactory / openDatabase from package:sqflite_common/sqflite.dart.
• Requirements: iOS 12.0+, macOS 10.14+ (podspec and Package.swift), Flutter >= 3.44 / Dart >= 3.12. Both CocoaPods (sqflite_darwin.podspec) and Swift Package Manager are supported; the privacy manifest (PrivacyInfo.xcprivacy) is bundled as a resource.
• No FMDB pod is needed or used; remove any pod 'FMDB' line from the app Podfile left over from sqflite < 2.3.2 (Module 'FMDB' not found). After upgrading run flutter clean and delete ios/Podfile.lock / macos/Podfile.lock.
• getDatabasesPath() returns the app Documents directory. Prefer path_provider (getLibraryDirectory() on iOS, or the application support directory) for data the user should not see in Files/iCloud backups. A relative path is resolved under Documents.
• The plugin creates the parent directory of a read-write database on open; a read-only open (SQLITE_OPEN_READONLY) does not, and fails on the first access if the file is not a SQLite database (corruption is not auto repaired or deleted, unlike Android read-write opens).
• deleteDatabase(path) also removes the -wal, -shm and -journal files; use it rather than File.delete.
• DatabaseException.getResultCode() yields the primary SQLite result code (for example 19 for a constraint violation) on iOS/macOS, the extended code on Android/ffi; write checks that accept both or use isUniqueConstraintError() and friends.
• Background isolate while the device is locked (push notification, background fetch): files created in protected folders are unreadable. Create the database inside a folder made with SqfliteDarwin.createUnprotectedFolder(parent, name) (from package:sqflite/sqflite.dart, NSFileProtectionNone), only for non-sensitive data.
• Method channel results on macOS are posted back on the main thread; all SQL still runs on a background queue per database.
• App Store ITMS-91065 Missing signature when the app embeds sqflite.framework via add-to-app frameworks: sign the xcframework with codesign --timestamp -v -f --sign "<identity>" sqflite.xcframework.
• Build failures on old projects: enforce IPHONEOS_DEPLOYMENT_TARGET (>= 12.0) in the Podfile post_install, keep use_frameworks! in the Runner target, or recreate the ios/ folder with flutter create ..

Examples

iOS/macOS-only app on the pure Dart API

dependencies:
  flutter:
    sdk: flutter
  sqflite_common:
  sqflite_darwin:

import 'package:path/path.dart';
import 'package:path_provider/path_provider.dart';
import 'package:sqflite_common/sqflite.dart';

Future<Database> openAppDb() async {
  // databaseFactory was registered by SqfliteDarwin.registerWith().
  final dir = await getLibraryDirectory();
  return openDatabase(
    join(dir.path, 'app.db'),
    version: 1,
    onCreate: (db, _) =>
        db.execute('CREATE TABLE Item (id INTEGER PRIMARY KEY, name TEXT)'),
  );
}

Database readable while the device is locked (needs package:sqflite)

import 'dart:io';

import 'package:path/path.dart';
import 'package:sqflite/sqflite.dart';

Future<Database> openUnprotectedDb() async {
  final databasesPath = await getDatabasesPath();
  var dir = databasesPath;
  if (Platform.isIOS) {
    dir = join(databasesPath, 'unprotected');
    if (!Directory(dir).existsSync()) {
      await SqfliteDarwin.createUnprotectedFolder(databasesPath, 'unprotected');
    }
  }
  return openDatabase(join(dir, 'notifications.db'), version: 1,
      onCreate: (db, _) => db.execute('CREATE TABLE Event (id INTEGER PRIMARY KEY)'));
}

Podfile post_install for deployment target issues

post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
    target.build_configurations.each do |config|
      config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '12.0'
    end
  end
end

Common mistakes

• Keeping pod 'FMDB' in the Podfile or expecting FMDB symbols; sqflite bundles its own renamed copy.
• Storing user databases in Documents (getDatabasesPath()) when they should not be exposed or backed up; use path_provider.
• Comparing getResultCode() to Android extended codes only.
• Opening from a background isolate on a locked device without an unprotected folder (DatabaseException(open_failed)).

More

App-level API: the sqflite package skills (sqflite-open-database, sqflite-crud-and-transactions, sqflite-testing-and-platforms). Other implementation: sqflite_android. Interface: sqflite_platform_interface.