flutter_local_db #

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

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.3.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': '[email protected]',
    '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': '[email protected]',
    '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 #

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