Module 14: Local Storage

Two Tools, Two Jobs

Think of it this way: - SharedPreferences is a sticky note on your fridge. Quick to write, quick to read, holds a few simple things. - SQLite is a filing cabinet. Organized, searchable, handles thousands of records with structure and relationships.

SharedPreferences: Key-Value Storage

SharedPreferences stores data as key-value pairs. Keys are strings. Values can be strings, ints, doubles, bools, or string lists. That is it. No nesting, no objects, no queries.

Setup

# pubspec.yaml
dependencies:
  flutter:
    sdk: flutter
  shared_preferences: ^2.2.0

Run flutter pub get.

Basic Operations

import 'package:shared_preferences/shared_preferences.dart';

// Save values
Future<void> saveSettings() async {
  final prefs = await SharedPreferences.getInstance();
  await prefs.setBool('darkMode', true);
  await prefs.setDouble('fontSize', 18.0);
  await prefs.setString('username', 'Campbell');
}

// Read values (with defaults)
Future<void> loadSettings() async {
  final prefs = await SharedPreferences.getInstance();
  final darkMode = prefs.getBool('darkMode') ?? false;
  final fontSize = prefs.getDouble('fontSize') ?? 16.0;
  final username = prefs.getString('username') ?? 'User';
}

// Remove a single key
Future<void> clearUsername() async {
  final prefs = await SharedPreferences.getInstance();
  await prefs.remove('username');
}

// Check if a key exists
Future<bool> hasUsername() async {
  final prefs = await SharedPreferences.getInstance();
  return prefs.containsKey('username');
}

// Remove ALL preferences
Future<void> clearAll() async {
  final prefs = await SharedPreferences.getInstance();
  await prefs.clear();
}

A SettingsService Class

Wrap SharedPreferences in a service class to keep your UI code clean:

class SettingsService {
  Future<void> setDarkMode(bool value) async {
    final prefs = await SharedPreferences.getInstance();
    await prefs.setBool('darkMode', value);
  }

  Future<bool> getDarkMode() async {
    final prefs = await SharedPreferences.getInstance();
    return prefs.getBool('darkMode') ?? false;
  }

  Future<void> setFontSize(double value) async {
    final prefs = await SharedPreferences.getInstance();
    await prefs.setDouble('fontSize', value);
  }

  Future<double> getFontSize() async {
    final prefs = await SharedPreferences.getInstance();
    return prefs.getDouble('fontSize') ?? 16.0;
  }

  Future<void> setUsername(String name) async {
    final prefs = await SharedPreferences.getInstance();
    await prefs.setString('username', name);
  }

  Future<String> getUsername() async {
    final prefs = await SharedPreferences.getInstance();
    return prefs.getString('username') ?? 'User';
  }

  Future<void> clearAllSettings() async {
    final prefs = await SharedPreferences.getInstance();
    await prefs.clear();
  }
}

SQLite: A Real Database on the Device

When your data has structure -- multiple fields, multiple records, the need to search or sort -- SQLite is the right tool. It gives you a full relational database running locally on the device.

Setup

# pubspec.yaml
dependencies:
  flutter:
    sdk: flutter
  sqflite: ^2.3.0
  path: ^1.8.0

Run flutter pub get.

The Database Helper Pattern

Every Flutter SQLite app follows the same structure: a helper class that manages the database connection and exposes CRUD methods.

import 'package:sqflite/sqflite.dart';
import 'package:path/path.dart';

class NoteDatabase {
  static Database? _database;

  Future<Database> get database async {
    if (_database != null) return _database!;
    _database = await _initDatabase();
    return _database!;
  }

  Future<Database> _initDatabase() async {
    final dbPath = await getDatabasesPath();
    final path = join(dbPath, 'notes.db');

    return await openDatabase(
      path,
      version: 1,
      onCreate: (db, version) async {
        await db.execute('''
          CREATE TABLE notes(
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            title TEXT NOT NULL,
            content TEXT NOT NULL,
            createdAt TEXT NOT NULL
          )
        ''');
      },
    );
  }
}

The onCreate callback uses raw SQL. If you have never written SQL, the CREATE TABLE statement defines the shape of your data: - id auto-increments so each note gets a unique number. - TEXT NOT NULL means a required string field. - createdAt is stored as an ISO 8601 string because SQLite does not have a native DateTime type.

Model Classes for the Database

Just like you created model classes for JSON APIs, create them for database records:

class Note {
  final int? id;
  final String title;
  final String content;
  final DateTime createdAt;

  Note({
    this.id,
    required this.title,
    required this.content,
    required this.createdAt,
  });

  // Convert Note to a Map for database insertion
  Map<String, dynamic> toMap() {
    return {
      'id': id,
      'title': title,
      'content': content,
      'createdAt': createdAt.toIso8601String(),
    };
  }

  // Create a Note from a database row
  factory Note.fromMap(Map<String, dynamic> map) {
    return Note(
      id: map['id'],
      title: map['title'],
      content: map['content'],
      createdAt: DateTime.parse(map['createdAt']),
    );
  }

  // Create a copy with some fields changed
  Note copyWith({
    int? id,
    String? title,
    String? content,
    DateTime? createdAt,
  }) {
    return Note(
      id: id ?? this.id,
      title: title ?? this.title,
      content: content ?? this.content,
      createdAt: createdAt ?? this.createdAt,
    );
  }
}

Notice that id is nullable (int?). When you create a new note, you do not know its ID yet -- the database assigns it. Once it is saved, id has a value.

The copyWith method is essential for updates. Instead of mutating a note, you create a new one with the changed fields.

CRUD Operations

With the database helper and model class in place, add the four CRUD operations:

Create

Future<int> insertNote(Note note) async {
  final db = await database;
  return await db.insert('notes', note.toMap());
}

db.insert returns the auto-generated ID of the new row.

Read All

Future<List<Note>> getAllNotes() async {
  final db = await database;
  final maps = await db.query('notes', orderBy: 'createdAt DESC');
  return maps.map((map) => Note.fromMap(map)).toList();
}

db.query returns a List<Map<String, dynamic>>. The orderBy parameter sorts by creation date, newest first.

Read One

Future<Note?> getNote(int id) async {
  final db = await database;
  final maps = await db.query(
    'notes',
    where: 'id = ?',
    whereArgs: [id],
  );
  if (maps.isNotEmpty) {
    return Note.fromMap(maps.first);
  }
  return null;
}

The where and whereArgs pattern prevents SQL injection. Never concatenate user input directly into SQL strings.

Update

Future<int> updateNote(Note note) async {
  final db = await database;
  return await db.update(
    'notes',
    note.toMap(),
    where: 'id = ?',
    whereArgs: [note.id],
  );
}

Delete

Future<int> deleteNote(int id) async {
  final db = await database;
  return await db.delete(
    'notes',
    where: 'id = ?',
    whereArgs: [id],
  );
}

When to Use Which

If you find yourself wanting to store a list of maps in SharedPreferences by serializing to JSON, stop. That is a sign you need SQLite.

There Are No Dumb Questions

Q: Does SharedPreferences encrypt data?

A: No. It stores data in plain text in an XML file (Android) or plist (iOS). Never store passwords, API keys, or sensitive data in SharedPreferences. For secrets, use the flutter_secure_storage package, which uses the device's keychain/keystore.

Q: What happens to the SQLite database when the user uninstalls the app?

A: It is deleted. App storage is tied to the app lifecycle. If the user reinstalls, the database starts fresh.

Q: Can I have multiple tables in one SQLite database?

A: Absolutely. Just add more CREATE TABLE statements in the onCreate callback. Most real apps have several tables.

Q: What if I need to change the database schema later?

A: Increment the version number in openDatabase and provide an onUpgrade callback. That callback receives the old and new version numbers so you can run ALTER TABLE statements to migrate data.

Q: Should I create a new DatabaseHelper instance every time I need it?

A: You can, because the database itself is a singleton (stored in the static _database variable). But a cleaner approach is to make the helper class a singleton too, or use Provider to provide a single instance.

Q: Is sqflite the only option for local databases?

A: No. drift (formerly moor) is a popular alternative that provides a type-safe, reactive query API on top of SQLite. Hive and Isar are NoSQL alternatives. For learning, sqflite teaches you raw SQL skills that transfer everywhere.

Sharpen Your Pencil: Settings Screen

Build a settings screen backed by SharedPreferences.

SettingsService (settings_service.dart)

1. Methods: setDarkMode(bool), getDarkMode() (default false), setFontSize(double), getFontSize() (default 16.0), setUsername(String), getUsername() (default 'User'), clearAllSettings().
2. All methods use SharedPreferences.getInstance().

SettingsScreen (settings_screen.dart)

1. StatefulWidget that loads saved values in initState.
2. A Switch for dark mode, wired to save on change.
3. A Slider for font size (range 12.0 to 24.0), wired to save on change.
4. A TextField for username, wired to save on change.
5. A "Reset Settings" button that calls clearAllSettings() and resets the UI to defaults.

Sharpen Your Pencil: Notes App with SQLite

Build a full notes application with CRUD operations.

Note Model (note_model.dart)

1. Note class with id (int?, nullable), title (String), content (String), createdAt (DateTime).
2. toMap() method (store createdAt as ISO 8601 string).
3. factory Note.fromMap(Map<String, dynamic>) constructor.
4. copyWith() method for immutable updates.

NoteDatabase (note_database.dart)

1. Singleton pattern with static _database field.
2. onCreate creates a notes table with id, title, content, createdAt columns.
3. insertNote(Note) -- returns new id.
4. getAllNotes() -- returns List<Note> ordered by createdAt descending.
5. updateNote(Note) -- updates by id.
6. deleteNote(int id) -- deletes by id.

NotesScreen (notes_screen.dart)

1. StatefulWidget that loads notes on init and after every operation.
2. ListView displaying each note's title and creation date.
3. FloatingActionButton opens a dialog to add a note (title and content fields).
4. Tapping a note opens an edit dialog with pre-filled fields.
5. Swipe-to-delete or delete icon on each note.
6. The list refreshes after every create, update, or delete.

Main App (main.dart)

1. BottomNavigationBar with two tabs: "Notes" and "Settings".
2. Notes tab shows NotesScreen.
3. Settings tab shows SettingsScreen.
4. The dark mode setting controls the app's theme (read the preference in the top-level widget and switch ThemeData accordingly).

Sharpen Your Pencil: Putting It Together

Wire the Notes and Settings screens into a single app:

1. The top-level widget reads the dark mode preference on startup.
2. It passes the appropriate ThemeData to MaterialApp.
3. When the user toggles dark mode in Settings, the theme updates immediately.
4. Notes persist across app restarts because they live in SQLite.
5. Settings persist because they live in SharedPreferences.

📝 Module Quiz

Test what you learned. 45 seconds per question. Passing score is set per module. Your best attempt is saved in your browser so you can track progress -- nothing is sent to a server.

Data That Survives