tarsier_local_storage 1.0.5

A simple and flexible library for managing SQLite databases in Dart and Flutter applications.

Tarsier Local Storage

Documentation • Issues • Example • License • Pub.dev

A simple and flexible library for managing SQLite databases in Dart and Flutter applications. It simplifies database operations with reusable abstractions for tables and models, making it easy to build scalable and maintainable applications.

✨ Features

• Easy Database Management: Initialize and manage SQLite databases effortlessly.
• Dynamic Tables: Define table schemas dynamically with support for CRUD operations.
• Model Mapping: Seamlessly map database rows to model objects.
• Cross-Platform: Supports Android, iOS, Windows, Linux, and more.
• Backup & Restore: provides a simple and efficient way to backup and restore database.

🚀 Getting Started

Add the package to your pubspec.yaml:

dependencies:
  tarsier_local_storage: ^1.0.5

Run the following command:

flutter pub get

📒 Usage

• Define a Model

  Create a class that extends BaseTableModel to represent a database entity:

import 'package:tarsier_local_storage/tarsier_local_storage.dart';

class User extends BaseTableModel {
  final int? id;
  final String name;
  final DateTime createdAt;

  User({
    this.id,
    required this.name,
    required this.createdAt,
  });

  factory User.fromMap(Map<String, dynamic> map) {
    return User(
      id: map['id'] as int?,
      name: map['name'] as String,
      createdAt: DateTime.parse(map['created_at'] as String),
    );
  }

  @override
  Map<String, dynamic> toMap() {
    return {
      'id': id,
      'name': name,
      'created_at': createdAt.toIso8601String(),
    };
  }

  static const String tableName = 'users';

  static Map<String, String> get schema => {
        'id': 'INTEGER PRIMARY KEY',
        'name': 'TEXT',
        'created_at': 'TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP',
      };
}

• Define a Table

  Create a table class by extending BaseTable:

import 'package:tarsier_local_storage/tarsier_local_storage.dart';

import 'user_model.dart';

class UserTable extends BaseTable<User> {
  UserTable()
      : super(
          tableName: User.tableName,
          schema: User.schema,
          fromMap: (map) => User.fromMap(map),
          toMap: (user) => user.toMap(),
        );
}

• Initialize the Database

  Initialize the database and pass the table definitions:

void main() async {
  await TarsierLocalStorage().init('app.db', [
    UserTable(), // Table class extended by BaseTable
    ...          // Add more table class here
  ]);

  final userTable = UserTable();

  // Add a new user
  await userTable.createObject(User(id: 1, name: 'John Doe'));
  // Or using Map on creating new user
  await userTable.create({
    'id' : 1,
    'name' : 'John Doe',
  });

  // Retrieve all users
  final users = await userTable.all();
  for (var user in users) { 
    print(user.name);
  }
}

• Backup and Restore Functionality

This package provides a simple and efficient way to backup and restore an SQLite database in a Flutter application. It supports saving backups in a custom file format and optionally compressing them into .zip archives for storage efficiency.

• ✅ Backup SQLite database to a specified directory
• ✅ Restore database from a backup file (supports .zip and uncompressed files)
• ✅ Supports progress tracking with callback functions
• ✅ Efficient file handling with proper error management
• ✅ Uses archive package for ZIP compression

1️⃣ Backup the Database

await storage.backup(
  backupDirectory: '/storage/emulated/0/backup',
  archive: true, // Set to false if you don't want ZIP compression
  extension: '.bk', // Custom file extension
  onStatusChanged: (status) => print('Backup Status: $status'),
);

2️⃣ Restore the Database

await storage.restore(
  backupPath: '/storage/emulated/0/backup/data.dbbk.zip',
  onStatusChanged: (status) => print('Restore Status: $status'),
);

3️⃣ Enum Status Callbacks

The backup and restore methods provide status updates via callbacks:

🔹 BackupStatus Enum

• creatingBackupDirectory → Creating backup directory
• writingBackupFile → Copying database file
• creatingArchive → Compressing to ZIP (if enabled)
• completed → Backup completed successfully
• failed → Backup failed

🔹 RestoreStatus Enum

• readingBackupFile → Reading backup file
• decodingArchive → Extracting ZIP contents (if applicable)
• restoringDatabase → Copying file to database location
• completed → Restore completed successfully
• failed → Restore failed

4️⃣ Error Handling

If the database file is missing or a backup file is corrupted, an exception will be thrown:

try {
  await storage.backup(backupDirectory: '/backup');
} catch (e) {
  print('Backup failed: $e');
}

📝 Notes

• Ensure your app has read/write storage permissions if saving to external directories.
• If using ZIP compression, the .zip file will replace the uncompressed backup.

📸 Example Screenshots

Home Screen	Notes Screen	Users Screen	Products Screen	Categories Screen

🎖️ License

This project is licensed under the MIT License. See the LICENSE file for details.

🐞 Contributing

Contributions are welcome! Please submit a pull request or file an issue for any bugs or feature requests on GitHub.