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.