Multi-Process Access

• On Apple platforms, app and system extensions, such as home screen widgets, run in an independent process.
• On desktop platforms, users can launch your app multiple times. Each instance runs in a separate process.

​

Multi-Process Considerations

1. Sync coordination: When you call connect() on a PowerSync database, the new connection replaces earlier connections. This replacement does not work if a database is opened multiple times in one or multiple processes. Calling connect() from multiple processes is not safe and typically causes duplicate downloads.
2. SQLite locks: When two processes try to write to the same database file, SQLite waits for a timeout and then returns a SQLITE_BUSY error code. Within a single process, PowerSync SDKs use internal locks to serialize writes, so this error does not occur. PowerSync SDKs do not provide equivalent locks across processes.
3. Missing updates: PowerSync SDKs provide methods to watch for changes in a database. watch() methods use these change notifications to re-run queries, and the SDKs use them to invoke your upload callback after local writes. The notifications come from SQLite update hooks, which do not report writes from other processes.

​

Solutions

​

Single-Process Apps

​

Limited Second-Process Access

​

Full Multi-Process Access

import 'dart:io';

import 'package:path/path.dart' as p;
import 'package:path_provider/path_provider.dart';
import 'package:powersync/native.dart';
import 'package:powersync/powersync.dart';
import 'package:sqlite_async/sqlite_async.dart';

final class MultiProcessPlatform extends PowerSyncPlatform {
  final FileMutex _syncMutex;
  final FileMutex _crudMutex;

  MultiProcessPlatform(Directory lockDirectory)
      : _syncMutex = FileMutex(lockDirectory, 'ps-sync.lock'),
        _crudMutex = FileMutex(lockDirectory, 'ps-crud.lock');

  @override
  Mutex namedMutex(String identifier) {
    if (identifier.endsWith('-sync')) {
      return _syncMutex;
    } else if (identifier.endsWith('-crud')) {
      return _crudMutex;
    } else {
      throw UnsupportedError('Unknown mutex id $identifier');
    }
  }
}

Future<PowerSyncDatabase> openDatabase() async {
  final supportDir = await getApplicationSupportDirectory();
  final lockDir = await getTemporaryDirectory();
  await lockDir.create(recursive: true);

  final db = PowerSyncDatabase(
    schema: schema,
    path: p.join(supportDir.path, 'app.db'),
    platform: MultiProcessPlatform(lockDir),
  );
  await db.initialize();
  return db;
}