flutter_local_db

A high-performance cross-platform local database for Dart and Flutter applications using Rust + LMDB via FFI.

pub package License: MIT

flutter_local_db

Features

  • High-performance: LMDB backend with Rust implementation
  • Rust-powered: Memory-safe native performance
  • Cross-platform: Android, iOS, macOS, Linux, Windows
  • Android 15+ Compatible: Full support for 16 KB page size requirements
  • Simple API: Key-value interface with CRUD operations
  • Type-safe: Result-based error handling
  • Easy to use: Single file, zero configuration

Installation

Add to your pubspec.yaml:

dependencies:
  flutter_local_db: ^1.4.0

Usage

import 'package:flutter_local_db/flutter_local_db.dart';

void main() async {
  // Initialize the database
  await LocalDB.init('my_database');

  // Create a record
  final result = await LocalDB.Post('user_1', {
    'name': 'John Doe',
    'email': 'john@example.com',
    'age': 30
  });

  result.when(
    ok: (model) => print('Created: ${model.id}'),
    err: (error) => print('Error: $error'),
  );

  // Get a record
  final getResult = await LocalDB.GetById('user_1');
  final user = getResult.unwrapOr(null);
  print('User: $user');

  // Update a record
  await LocalDB.Put('user_1', {
    'name': 'Jane Doe',
    'email': 'jane@example.com',
    'age': 25
  });

  // Get all records
  final allResult = await LocalDB.GetAll();
  allResult.when(
    ok: (models) => print('Total records: ${models.length}'),
    err: (error) => print('Error: $error'),
  );

  // Delete a record
  await LocalDB.Delete('user_1');

  // Clear all data
  await LocalDB.ClearData();

  // Close database (optional)
  await LocalDB.close();
}

Platform Support

Platform Status Architecture
Android Supported arm64-v8a, armeabi-v7a, x86, x86_64
iOS Supported arm64
macOS Supported arm64, x86_64
Linux Supported x86_64
Windows Supported x86_64

Android 15+ Compatibility

This package fully supports Android 15's 16 KB page size requirement. Native libraries are compiled with proper ELF alignment to ensure compatibility with all Android versions.

Platform Setup

This package uses FFI to load native Rust libraries. The required binaries are included.

Android: The Flutter plugin automatically includes the native libraries for all architectures. No additional setup required.

iOS: The iOS plugin includes the static library via Cocoapods. No additional setup required.

Desktop: Desktop platforms (macOS, Linux, Windows) automatically include the native libraries via their respective build systems. No additional setup required.

API Reference

Result Type

All database operations return LocalDbResult<T, E> for type-safe error handling:

result.when(
  ok: (value) => handleSuccess(value),
  err: (error) => handleError(error),
);

// Or use convenience methods
final value = result.unwrapOr(defaultValue);
final maybeValue = result.okOrNull;

Error Handling

Errors are typed for better handling:

result.when(
  ok: (model) => print('Success: $model'),
  err: (error) {
    switch (error.type) {
      case LocalDbErrorType.notFound:
        print('Record not found');
        break;
      case LocalDbErrorType.validation:
        print('Invalid key: ${error.message}');
        break;
      case LocalDbErrorType.database:
        print('Database error: ${error.message}');
        break;
    }
  },
);

Performance

  • Fast: Direct FFI calls to optimized Rust code
  • Memory efficient: LMDB memory-mapped storage
  • Minimal overhead: Single file, no complex abstractions
  • Production ready: Used in multiple production applications

Limitations

  • Data must be JSON-serializable
  • IDs must follow the format requirements
  • Platform-specific limitations may apply
  • Currently no support for complex queries or indexing
  • No automatic migration system

Native Library

This package uses offline_first_core, a Rust library built on LMDB (Lightning Memory-Mapped Database) - the same database engine used by Bitcoin Core and OpenLDAP.

Contributing

Contributions are welcome! The project uses a dual-language architecture:

  • Flutter/Dart for the high-level API and FFI bridge
  • Rust for the core database operations

Please ensure you have both Rust and Flutter development environments set up before contributing.

License

MIT License - see LICENSE

Author

Made with Rust + Flutter by JhonaCode

Libraries

flutter_local_db