Installation

Install#

flutter pub add magic_local_storage
dart run magic:dowel plugin:install magic_local_storage

The barrel, package:magic_local_storage/magic_local_storage.dart, is the only runtime import; everything under src/ is private. The package also ships a Flutter-free package:magic_local_storage/cli.dart for the generators, which the dowel dispatcher loads for you.

Magic core no longer carries the SQLite layer. A model with useLocal => true needs this package: without it the first find, all, save, delete or refresh throws a StateError naming magic_local_storage, see Models.

Requirements#

What the Installer Does#

plugin:install reads the package's install.yaml and makes two edits: it adds DatabaseServiceProvider to the providers list of lib/config/app.dart, and it adds () => databaseConfig to the configFactories of lib/main.dart. No config file is published, because databaseConfig is a getter the package exports.

It then chains local_storage:install, which downloads web/sqlite3.wasm when the project has a web/ folder. Both steps skip work that is already done, so running the installer twice changes nothing.

Register by Hand#

To wire it yourself, register the provider and the config factory in Magic.init:

import 'package:magic/magic.dart';
import 'package:magic_local_storage/magic_local_storage.dart';

Future<void> main() async {
  await Magic.init(
    configFactories: [
      () => databaseConfig,
    ],
    configs: [
      {
        'app': {
          'providers': [
            (app) => DatabaseServiceProvider(app),
          ],
        },
      },
    ],
  );
}

DatabaseServiceProvider is not auto-registered. Its register() binds the DatabaseManager at db and the QueryModelStore at local_model_store; its boot() opens the connection, so the first statement after Magic.init already has one. List the provider before any provider whose boot() runs a query.

Web Setup#

Flutter web loads SQLite from web/sqlite3.wasm. The installer downloads the wasm of the sqlite3 release your project resolved (read from .dart_tool/package_config.json, sqlite3-3.9.1 when it cannot tell) into web/ when the folder exists, and keeps a file that is already there. Add the web target later with flutter create --platforms=web ., then run:

dart run magic:dowel local_storage:install

A failed download prints the curl -L ... -o web/sqlite3.wasm line to run by hand and does not fail the install. The sqlite3 package only works with the specially compiled sqlite3.wasm from its own GitHub releases (a wasm from sql.js and the like does not load), so take the one from the release that matches the sqlite3 version in your pubspec.lock, and replace it when you upgrade that package. dart run magic:dowel local_storage:install --dry-run stages the edits without writing.

Verify#

import 'package:magic/magic.dart';
import 'package:magic_local_storage/magic_local_storage.dart';

void main() {
  // Magic.init(...) has run with the provider and config above.
  print(Magic.bound('db')); // true
  print(Magic.bound('local_model_store')); // true
  print(DB.select('SELECT sqlite_version() AS version').single['version']);
}

If DB throws Database not initialized, DatabaseServiceProvider is missing from providers or Magic.init has not completed.

Related Documentation#

• Configuration: the database config, platforms and the connection.
• Migrations: create your first table.
• Models: persisting a useLocal model.
• Generators: make:migration, make:seeder, make:factory.