name: "flutter-db" description: "Local database and persistence selection for Flutter including SharedPreferences, SecureStorage, Hive, and Drift. Use when implementing offline storage, encrypted data persistence, or choosing between key-value and relational local databases." metadata: last_modified: "2026-03-12 11:18:17 (GMT+8)"
Database Architecture Guide (Flutter)
Goal
Implement robust, scalable, and secure local persistence strategies for Flutter applications. This skill ensures developers choose the optimal storage engine—balancing simple key-value settings, encrypted sensitive data, high-performance NoSQL object stores, and complex relational databases.
Process
🚀 High-Level Workflow
Selecting the right persistence layer depends on data sensitivity, complexity, and relationship depth.
Phase 1: Key-Value Persistence (Simple & Secure)
Use lightweight stores for settings and sensitive credentials.
- Shared Preferences Guide - Non-sensitive settings and flags using static wrappers.
- Secure Storage Guide - Encrypted storage for tokens and passwords.
Phase 2: High-Performance Object Storage (NoSQL)
For local-first apps requiring fast read/write of large datasets without complex relations.
- Hive CE (Synchronous NoSQL) - Blazing fast object store for local caching and offline data.
Phase 3: Complex Relational Schemas (SQL)
For apps requiring strict data integrity, transactions, and complex queries.
- Drift (Reactive SQL) - Type-safe relational database built on top of SQLite.
📚 Documentation Library
Refer to these specialized resources to implement your chosen persistence strategy:
- 🗄️ Database Architecture Overview
- ⚙️ Shared Preferences
- 🔐 Secure Storage (Encrypted)
- 🐝 Hive CE Best Practices
- 🐘 Drift (SQL) Best Practices
Constraints
- Type Safety: Prohibit raw
dynamicdata access. Always use generated classes (Drift) or typed static wrappers (SharedPreferences/SecureStorage). - Sensitivity Awareness: Force use of
Secure Storagefor any tokens, passwords, or PII. Never store sensitive data in SharedPreferences or unencrypted Hive boxes. - Singleton Access: Access storage instances via DI (Riverpod) or strictly defined static classes to prevent key fragmentation.
- Performance Balance: Use NoSQL (Hive) for high-frequency reads and SQL (Drift) for complex relationships. Don't over-engineer simple apps with SQL.