
Saving Game Progress in Flutter: shared_preferences vs Hive vs Isar vs SQLite
How to store Flutter game save data without losing player progress: shared_preferences, Hive, Isar and SQLite compared, with schema versioning.
Published on 13 min
On this page
You open your inbox on a Sunday morning to find an email from a frustrated player. After updating your sudoku game yesterday, their 214-day streak vanished, and the puzzle they were halfway through solving reset to a blank grid.
When you inspect the code, the cause becomes clear. The save file had no schema version. The new release expected an updated data structure, so the loader quietly returned null when encountering unexpected fields. From a technical standpoint, the player’s progress was never erased from disk; the new build simply could not read it. For the player, however, that distinction makes no difference: months of daily play are gone.
Managing game state in Flutter (often searched as flutter game save data) seems simple until an update corrupts real player records. In this guide, we evaluate the four most popular storage options in Flutter: shared_preferences, Hive, Isar, and SQLite. We will cover what belongs in a save file, what to leave out, and how to implement a versioned save envelope with forward-only migrations for puzzle game saves. All examples use pure Dart so you can run and test them directly in DartPad.
Why saving progress is a core feature, not just plumbing
Most tutorials treat persistence as a quick chore between building the board and releasing the game. Players, however, treat it as a fundamental promise. Puzzle games like sudoku depend on continuity: a half-solved grid from the morning commute, an unbroken daily streak, and statistics tracked over months of play. If an update corrupts that record, loyal players feel let down. Instead of starting over from scratch, they simply uninstall the app.
Save reliability directly protects player retention. When players know they can close the game at any moment without losing progress, they return more often. If leaving mid-puzzle feels risky, they stop opening the app for short sessions. A solid, predictable save system is one of the most effective retention features you can build.
The four storage contenders in Flutter
Almost every Flutter application relies on one of four storage solutions. Each tool was designed for specific use cases and brings distinct trade-offs.
shared_preferences is the official key-value plugin from the Flutter team. It wraps platform stores: NSUserDefaults on iOS and macOS, Android SharedPreferences or DataStore Preferences, and key-value stores on other platforms. It holds primitive types like int, double, bool, String, and List<String>. Since version 2.3.0, it offers two newer APIs, SharedPreferencesAsync and SharedPreferencesWithCache, while the legacy SharedPreferences class waits for deprecation. It is ideal for audio volume, selected themes, and feature flags, but not for your main save file.
Hive is a pure Dart key-value store inspired by Bitcask. You open typed or dynamic boxes and read values synchronously from memory-mapped structures, which makes reads fast. The original author handed the package to the community, and the actively maintained line continues under the hive_ce fork. Hive is a great match for small to medium casual puzzle games that need fast access to structured data.
Isar is an advanced NoSQL database by the creator of Hive, with fast queries, indexes, object links, and ACID transactions. Version 3 is stable and widely used. Version 4 has been in development for a long time, and progress has slowed down. Before choosing it for a new project, review the Isar repository on GitHub to see if its release pace fits your needs.
SQLite, accessed through the sqflite plugin or the drift layer, is the relational standard. It is ACID-compliant, battle-tested for decades, and supports WAL mode for fast concurrent reads. It scales from a single settings row to thousands of completed sudoku puzzles with full move histories. The trade-off is setup: you must write schemas, queries, and migrations.
Quick comparison
| Storage Option | Setup Complexity | Read / Write Speed | Sweet Spot | Best Fit |
|---|---|---|---|---|
| shared_preferences | Trivial | Fast for small keys | A few KB of settings | Volume controls, theme flags, onboarding |
| Hive | Low | Very fast in-memory reads | Up to a few MB per box | Main save file for a casual puzzle game |
| Isar | Medium | Fast with indexed queries | MBs to tens of MBs | Complex models with filters and links |
| SQLite (sqflite / drift) | Medium to High | Fast, ACID, WAL | Any size with indexes | Move histories, detailed stats, multiple entities |

A useful rule: design for your worst-case data size, not the average session. A single sudoku save is tiny. An archive of two thousand completed puzzles with per-cell timestamps is not. Pick a tool that remains fast and reliable at your worst case.
What to save, and what to leave behind
The fastest save code is the code that runs least often. Before picking a library, decide what deserves space on disk.
Save:
- Board state. For a sudoku game: the puzzle identifier, the initial givens (or the seed to generate them), player entries, pencil marks, and the move counter. Store elapsed time as accumulated milliseconds (
elapsedMs) rather than an activeDateTime, so the timer survives app restarts and timezone changes. - Settings. Sound volume, haptics, theme selection, and difficulty preferences.
- Statistics and streaks. Total wins, average times, best scores, and the current streak with the date of the last qualifying win. Date anchors make streaks verifiable, whereas a bare number like
streak = 12leaves you with no recovery path if data is questioned. - State flags. Flags for completing the tutorial or displaying the rating prompt.
Do not save:
- Derived data. Sudoku candidates can be recomputed from board entries in microseconds. Caching them in the save file adds bytes and creates schema migration headaches.
- UI state. Scroll positions, open dialogs, and animation phases. Rebuild them when the screen loads; they are not game progress.
- Snapshots on every move. Autosave at sensible checkpoints: after a batch of entries, on pause, or when the app goes to the background. A 9x9 board with pencil marks takes under a kilobyte as JSON, but writing to disk on every tap creates useless I/O load.
- Unverified device clocks. Device clocks are easily changed by users. Use local time for display in the UI, but rely on monotonic timers or server timestamps for game logic and daily streaks.
A sudoku board state shows this pattern. Everything here is either a given, player input, or an accumulated counter. The snippet is pure Dart and can be tested in DartPad:
class SudokuSave {
SudokuSave({
required this.puzzleSeed,
required this.entries,
required this.pencilMarks,
required this.elapsedMs,
required this.hintsUsed,
});
factory SudokuSave.fresh(String seed) => SudokuSave(
puzzleSeed: seed,
entries: List.filled(81, 0),
pencilMarks: const {},
elapsedMs: 0,
hintsUsed: 0,
);
final String puzzleSeed; // Givens regenerate from the seed.
final List<int> entries; // 81 cells, 0 means empty.
final Map<int, Set<int>> pencilMarks;
final int elapsedMs; // Accumulated time in milliseconds.
final int hintsUsed;
Map<String, Object?> toJson() => {
'puzzleSeed': puzzleSeed,
'entries': entries,
'pencilMarks': {
for (final e in pencilMarks.entries)
'${e.key}': e.value.toList(),
},
'elapsedMs': elapsedMs,
'hintsUsed': hintsUsed,
};
}
The save envelope: one pattern that prevents most disasters
Regardless of your storage choice, wrap your save payload in an envelope from day one. Three metadata fields solve most persistence bugs: a schema version, a UTC timestamp, and a device identifier. This snippet is pure Dart. Paste it into DartPad and it runs:
class SaveEnvelope {
SaveEnvelope({
required this.schemaVersion,
required this.savedAtUtc,
required this.deviceId,
required this.payload,
});
static const int currentVersion = 1;
final int schemaVersion;
final DateTime savedAtUtc;
final String deviceId;
final Map<String, Object?> payload;
Map<String, Object?> toJson() => {
'schemaVersion': schemaVersion,
'savedAtUtc': savedAtUtc.toIso8601String(),
'deviceId': deviceId,
'payload': payload,
};
static SaveEnvelope? fromJson(Map<String, Object?> json) {
final version = json['schemaVersion'];
if (version is! int || version > currentVersion) {
// Either corrupted, or written by a newer build. Do not guess.
return null;
}
final savedAt = DateTime.tryParse('${json['savedAtUtc']}');
if (savedAt == null) return null;
final payload = json['payload'];
if (payload is! Map<String, Object?>) return null;
return SaveEnvelope(
schemaVersion: version,
savedAtUtc: savedAt,
deviceId: '${json['deviceId']}',
payload: payload,
);
}
}
Notice the guard condition in fromJson: a save file with a version newer than the running app is rejected rather than parsed. This prevents an older build from mangling a newer save format. You can then prompt the player to update the app, instead of crashing on unexpected fields.
Version your schema from day one, then migrate forward only
Migrations should be small, single-purpose functions that each upgrade the schema by exactly one step. Avoid writing a single large converter. Instead, chain your steps so upgrading from version 0 to version 2 runs step 0 to 1, followed by step 1 to 2 in sequence:
Map<String, Object?> migrateSave(Map<String, Object?> raw) {
var version = raw['schemaVersion'];
if (version is! int) return raw; // Legacy file with no version: treat as v0.
var data = raw;
while (version < SaveEnvelope.currentVersion) {
data = switch (version) {
0 => _v0ToV1(data),
1 => _v1ToV2(data),
_ => data,
};
version = data['schemaVersion'] as int;
}
return data;
}
Map<String, Object?> _v0ToV1(Map<String, Object?> data) => {
...data,
'schemaVersion': 1,
'deviceId': data['deviceId'] ?? 'legacy-device',
};
Map<String, Object?> _v1ToV2(Map<String, Object?> data) => {
...data,
'schemaVersion': 2,
'savedAtUtc': data['savedAtUtc'] ??
DateTime.fromMillisecondsSinceEpoch(0, isUtc: true)
.toIso8601String(),
};
Three habits keep migrations safe in production:
- Additive updates beat rewrites. Prefer adding new fields with default values over renaming or deleting keys. Older code can safely ignore extra keys, while missing an expected key almost always causes errors.
- Test migrations with real save files. Keep a sample save file from each past version in your test suite. Writing synthetic test data by hand often hides edge cases.
- Write atomically. When writing to disk, save to a temporary file, flush the buffer, and rename over the target file. If the device powers off mid-write, you keep either the clean old file or the clean new one, never a corrupt partial write. SQLite gives you this through transactions; with raw files, you handle it yourself.

Five failure modes that bite mobile developers
1. shared_preferences does not guarantee immediate disk writes. The package docs state plainly that data may be written to disk asynchronously, with no guarantee that writes survive if the process exits right after the call. Never use it for critical game progress. Losing a sound preference is harmless; losing a 200-day sudoku streak loses a player. On Android, use the newer SharedPreferencesAsync API, which saves through DataStore Preferences rather than the legacy XML file.
2. Android’s apply() has a tail-latency trap. Android’s apply() returns right away and writes in the background, but the disk flush is deferred. On some devices, deferred flushes run during the app’s next cold start, adding to startup delay. A few simple flags hide this, but hundreds of writes per session will slow things down.
3. Hive benchmark speeds reflect memory cache. Hive benchmarks often measure reads from an open box mapped into RAM. That is the normal way to use Hive, but it tells you little about cold starts or sustained disk write speeds. Plan for cold launch times, because that is what players see after an update. Keep maintenance in mind as well: the original package has slowed down, while the hive_ce fork continues active maintenance.
4. Isar’s release timeline is a dependency risk. Isar 4 has been in development for a long time, so teams must track the repository closely. A database in a game is a multi-year choice. Check the Isar repository on GitHub and its issue tracker before committing. Keep your data models separated from the storage layer so you can switch tools if needed.
5. JSON serialization on the UI isolate drops frames. Running jsonEncode on a large save file executes on Flutter’s main UI thread, which also renders your animations. Encoding large states on every move can stutter gameplay on older phones. Move heavy serialization to a worker isolate using compute(), or save only at natural checkpoints. The Flutter persistence cookbook covers the basics of background processing.
Preparing for cloud sync before you build it
You do not need a backend on day one. You just need a save format that will not fight you when cloud sync arrives.
The save envelope pattern gives you a head start. These practices keep future sync simple:
- Always store
schemaVersion,deviceId, andsavedAtUtc. Conflict resolution depends on metadata. Without a version number, you cannot merge across app updates. Without timestamps, you cannot order changes. Without a device id, you cannot debug sync issues. - Use field-level merges over whole-file overwrites. If a player solves a sudoku puzzle offline on a tablet and later uses a hint on their phone, a whole-file overwrite discards one of those actions. Merging field by field preserves both the solved puzzle and the used hint.
- Keep saves within cloud size limits. Cloud save slots on platforms like Google Play Games Services have size limits (often 3 MB per slot). That is plenty of space for puzzle data, provided you avoid storing raw images or logs in the save. Keeping saves lean prevents quota problems.
- Use server timestamps for authoritative ordering. Device clocks can be inaccurate or manipulated by users. Keep
savedAtUtcfor UI display and diagnostics, but use server timestamps to order conflicting sync writes. - Make sync safe for local history. A first sync must never wipe out an existing local history without confirmation. When saves diverge, merging records or asking the player to choose is far safer than silently replacing local data.

Recommended setups for a sudoku game
Selecting the right storage setup depends on your data needs:
- The pragmatic default.
SharedPreferencesAsyncfor settings,hive_cefor the main save envelope. Two lightweight libraries, simple to test, with sub-millisecond cold starts. - The stats collector.
drifton top of SQLite. When you want per-puzzle history, filtered statistics, and data exports, a relational schema with queries pays for itself quickly. - The minimalist. If the game has settings and one save slot, a single versioned JSON file via
path_providerwith atomic rename is all you need. Do not add a database unless your feature set demands it.
Final checklist before you ship
Before publishing a game update, verify that your save setup meets these checks:
- Every save payload carries
schemaVersion,savedAtUtc, anddeviceId. - The loader rejects saves newer than the app instead of guessing.
- Writes are atomic (temp file plus rename, or a database transaction).
- Settings live in
shared_preferences, while progress lives in a durable store. - Sample save files from past versions are included in the test suite.
- Serialization runs off the UI thread or at checkpoints.
- You tested save performance under worst-case data sizes.
Saving progress is rarely the most exciting system to build, but it is the one players remember when it fails. Build it simple, build it versioned, and your sudoku app can preserve player streaks for years to come.
Keep reading
Polydocu - a sudoku adventure
Nine digits, an expedition through the jungle, Poly the parrot, and no artificial roadblocks. Join the waitlist and we will notify you when the game launches.
One email at launch, no spam.




