Skip to content
libspiffy

Isar on macOS and iOS

This page shows how to stop Isar databases on macOS and iOS from taking far more disk space than they hold. If your app ships only to Android, Linux or Windows, or uses the PostgreSQL backend, you can skip it.

The problem

Section titled “The problem”

libspiffy 5.0.0, like every 4.x release, stores its event journal, read models and block headers in Isar, through the isar_community package (3.3.2). The published isar_community 3.3.2 native library is built on libmdbx v0.13.8-temp-upstream-fix. On Apple platforms that libmdbx build preallocates the whole new file size past the end of the database file every time the file grows, and never releases it.

The CHANGELOG.md entry for 4.0.0 gives the numbers: a 135 MiB header store held 1.9 GiB on disk, and a full testnet header store about 59 GiB. Every Isar database in the process is affected, not only the one holding headers. A wallet that syncs headers from a CDN on first install grows its header store quickly, so it hits this early.

libmdbx fixed the bug in v0.13.9. isar_community has not released the upgrade yet (isar-community/isar-community#85 and #129).

The fix

Section titled “The fix”

Override both Isar packages with the 3.3.2 build on libmdbx v0.13.12. Add this to your app’s pubspec.yaml:

pubspec.yaml
dependency_overrides:
  isar_community:
    git:
      url: https://github.com/stephanfeb/isar-community.git
      ref: 3.3.2-libmdbx-0.13.12
      path: packages/isar_community
  isar_community_flutter_libs: # Flutter apps only
    git:
      url: https://github.com/stephanfeb/isar-community.git
      ref: 3.3.2-libmdbx-0.13.12
      path: packages/isar_community_flutter_libs

Then run flutter pub get (or dart pub get). libspiffy’s own pubspec.yaml carries the same override for isar_community. Remove the override once isar_community releases the fix.

The normal dependencies stay as the README’s Installation section lists them:

pubspec.yaml
dependencies:
  libspiffy: ^5.0.0
  isar_community: ^3.3.2
  isar_community_flutter_libs: ^3.3.2 # Flutter apps only


dev_dependencies: # only when the app has Isar collections of its own
  isar_community_generator: ^3.3.2
  build_runner: ^2.7.0

Import Isar as package:isar_community/isar.dart.

Space already taken

Section titled “Space already taken”

The fixed binary stops the growth. It does not give back space a database already holds past its end. According to the 4.0.0 changelog entry, you can release it with the database closed by extending the file by one page and truncating it back to its length.

Queries on libspiffy’s collections

Section titled “Queries on libspiffy’s collections”

If your app queries libspiffy’s Isar collections directly, note that 5.0.0 removes four deprecated where clauses. Use the prefixes of the composite indexes instead:

Removed in 5.0.0 Use
AddressEntity: walletIdEqualTo, walletIdNotEqualTo walletIdEqualToAnyPurpose
BitcoinTransactionEntity: statusEqualTo, statusNotEqualTo statusEqualToAnyWalletId

Why Isar is your dependency too

Section titled “Why Isar is your dependency too”

Isar is part of libspiffy’s public API: you can pass your own instance to LibSpiffyActorSystem.initialize(isar:), opened with LibSpiffySchemas.allSchemas. So your app depends on isar_community directly, and the override has to be in your app’s pubspec.yaml. An override in a dependency’s pubspec.yaml has no effect on your build.