flutter_easy_db #

A secure, easy-to-use encrypted local database for Flutter with two modes:

1. EasyDbNoSql — Isar-style document database (schema-free, simple put/get/query)
2. EasyDbSql — Drift-style relational database (typed tables, joins, foreign keys, migrations)

Both use AES-256 encryption for secure data at rest.

Installation #

dependencies:
  flutter_easy_db: ^1.0.0

EasyDbNoSql (Isar-style) #

Schema-free document store. No table definitions needed.

final db = await EasyDbNoSql.open(
  EasyDbConfig(
    dbName: 'my_app',
    encryptionKey: 'my-32-character-secret-key!!!!!', // exactly 32 chars
  ),
);

final users = db.collection('users');

// Insert
await users.put({'name': 'Alice', 'age': 30});

// Query
final results = await users.query()
  .where('age', isGreaterThan: 25)
  .where('name', contains: 'li')
  .sortBy('age', descending: true)
  .limit(10)
  .find();

// Watch (reactive)
users.watch().listen((docs) => print('Changed!'));

await db.close();

NoSQL API #

EasyDbSql (Drift-style) #

Typed relational tables with schemas, foreign keys, joins, and migrations.

// Define schemas
final usersSchema = EasyTableSchema(
  name: 'users',
  columns: [
    EasyColumn(name: 'id', type: ColumnType.integer, isPrimaryKey: true, autoIncrement: true),
    EasyColumn(name: 'name', type: ColumnType.text),
    EasyColumn(name: 'email', type: ColumnType.text, isUnique: true),
    EasyColumn(name: 'age', type: ColumnType.integer),
  ],
);

final postsSchema = EasyTableSchema(
  name: 'posts',
  columns: [
    EasyColumn(name: 'id', type: ColumnType.integer, isPrimaryKey: true, autoIncrement: true),
    EasyColumn(name: 'title', type: ColumnType.text),
    EasyColumn(name: 'user_id', type: ColumnType.integer,
      foreignKey: ForeignKey(referenceTable: 'users', referenceColumn: 'id'),
    ),
  ],
);

// Open
final db = await EasyDbSql.open(
  EasyDbConfig(dbName: 'my_app', encryptionKey: 'my-32-character-secret-key!!!!!'),
  tables: [usersSchema, postsSchema],
);

// Get table — optionally encrypt specific columns
final users = db.table('users', encryptedColumns: ['email']);

// Insert
final userId = await users.insert({'name': 'Alice', 'email': 'alice@example.com', 'age': 30});

// Select with WHERE
final results = await users.select()
  .where('age > ?', [25])
  .orderBy('name ASC')
  .limit(10)
  .run();

// JOIN
final joined = await users.select(columns: ['users.name', 'posts.title'])
  .join('posts', on: 'users.id = posts.user_id')
  .run();

// Update / Delete
await users.update({'age': 31}, where: 'name = ?', whereArgs: ['Alice']);
await users.delete(where: 'name = ?', whereArgs: ['Bob']);

await db.close();

SQL API #

SELECT Query Builder #

table.select(columns: ['name', 'age'])
  .where('age > ?', [18])
  .join('posts', on: 'users.id = posts.user_id')
  .leftJoin('comments', on: 'posts.id = comments.post_id')
  .orderBy('name ASC')
  .limit(20)
  .offset(10)
  .run();       // List<Map<String, dynamic>>
  .runFirst();  // Map<String, dynamic>?

Security #

• AES-256-CBC encryption with SHA-256 key derivation
• NoSQL: entire document encrypted as one blob
• SQL: choose which columns to encrypt (e.g. email, phone)
• Each encryption uses a unique random IV (prevents pattern analysis)
• Key never stored on disk
• Pass null for encryptionKey to disable (dev mode)

Architecture #

┌─────────────────────────────────────────────┐
│             Your Flutter App                │
├──────────────────┬──────────────────────────┤
│  EasyDbNoSql     │  EasyDbSql              │
│  (Isar-style)    │  (Drift-style)          │
│  put/get/query   │  insert/select/join     │
├──────────────────┴──────────────────────────┤
│         AES-256 Encryption Layer            │
├─────────────────────────────────────────────┤
│              SQLite (sqflite)               │
└─────────────────────────────────────────────┘

License #

MIT