How to save data locally in Flutter

You will need a Flutter development environment set up, and should have some basic knowledge of Flutter.

Introduction

It’s a rare app that doesn’t need to store some sort of data, whether it’s remembering the last article read, the user’s email address, or the night mode setting. Both Android and iOS give us several options for how to save data locally. Flutter makes these options available to us, too. Specifically, we’ll learn how to save data using the following methods:

Shared preferences
SQLite database
Text file

We’ll look at each one of these and go through some easy examples to help us understand them.

Prerequisites

I’m assuming that you:

Have the Flutter development environment set up (This tutorial was tested with Flutter 1.0.)
Know the way around your IDE (I’m using Android Studio, but VSCode and IntelliJ are fine, too.)
Have experience creating a basic Flutter app (If not see First steps with Flutter parts one, two, and three.)

Beyond that there is very little that you need to know for this lesson. I’ll give you cut-and-paste code blocks for you to try out. From there you’ll be able to experiment and adapt them to your own needs.

Setup

Start a new Flutter project. I’m calling mine flutter_saving_data.

Saving to shared preferences

When you have small amounts of data that you want to persist across app runs, you can use Flutter’s shared_preferences plugin to save that data. Here are some examples of things you might save using shared preferences:

User selected color theme
Whether night mode is enabled
Preferred app language

Some data may not have been explicitly chosen by the user, but is still important to save. For example:

Last scroll position
Current tab
Time length already played in an audio or video file

Any customization that makes the user do less work the next time they use your app is a good candidate for shared preferences. When you want to save larger amounts of data, though, you should consider using a database.

Since shared preferences saves app related settings and defaults, the system erases that data when the user uninstalls your app. So if there are settings that should persist across installs or devices, then you should consider saving to the cloud.

In Flutter, we’ll use a plugin that is a wrapper around the same underlying functionality in Android and iOS. Android calls it SharedPreferences while iOS calls it NSUserDefaults. Like Android, Flutter also calls it SharedPreferences.

The following steps will get you set up using SharedPreferences.

Dependency

Open your pubspec.yaml file and in the dependencies section add the line shared_preferences: ^0.4.3 like this:

    dependencies:
      flutter:
        sdk: flutter
      shared_preferences: ^0.4.3

This tutorial is using version 0.4.3. You can find the most recent version on pub.

Note: Do you understand the meaning of the ^ caret before the version number? Based on semantic versioning, this allows the dependency to automatically update to the latest version as long as that version does not contain breaking changes to whatever version number you specified. See this post for more details.

You might have also seen the any keyword used, as in shared_preferences: any. It’s better not to do this, though, since it would allow automatic updates with changes that could break your app.

Minimal example

Let’s make a simple app to read and save data with SharedPreferences.

flutter-local-data-buttons

There are two buttons. One button will read from SharedPreferences. The other button will write to it. In order to keep the UI as simple as possible we will log the output using print(). In Android Studio be sure to have the Run tab selected so that you can see the output.

Replace the code in your main.dart file with the following:

    import 'package:flutter/material.dart';
    import 'package:shared_preferences/shared_preferences.dart';
    
    void main() => runApp(MyApp());
    
    class MyApp extends StatelessWidget {
      @override
      Widget build(BuildContext context) {
        return MaterialApp(
          theme: ThemeData(primarySwatch: Colors.blue),
          home: MyHomePage(),
        );
      }
    }
    
    class MyHomePage extends StatelessWidget {
      @override
      Widget build(BuildContext context) {
        return Scaffold(
          appBar: AppBar(
            title: Text('Saving data'),
          ),
          body: Row(
            //mainAxisAlignment: MainAxisAlignment.center,
            children: <Widget>[
              Padding(
                padding: const EdgeInsets.all(8.0),
                child: RaisedButton(
                  child: Text('Read'),
                  onPressed: () {
                    _read();
                  },
                ),
              ),
              Padding(
                padding: const EdgeInsets.all(8.0),
                child: RaisedButton(
                  child: Text('Save'),
                  onPressed: () {
                    _save();
                  },
                ),
              ),
            ],
          ),
        );
      }
      
      // Replace these two methods in the examples that follow
      
      _read() async {
        final prefs = await SharedPreferences.getInstance();
        final key = 'my_int_key';
        final value = prefs.getInt(key) ?? 0;
        print('read: $value');
      }
      
      _save() async {
        final prefs = await SharedPreferences.getInstance();
        final key = 'my_int_key';
        final value = 42;
        prefs.setInt(key, value);
        print('saved $value');
      }
    }

In this minimal app setup, we are going to save an integer to shared preferences. Because I am trying to make the app as simple as possible, I hard coded the integer 42 as the value to save. In a production app we would get this value from somewhere else, for example, from a text field or a scroll position or a preferred font size. See First steps with Flutter: Responding to user input for some examples of how to get user input.

Run the app and press the Read button. We are trying to read a value that has never been set, so you should see the following output:

    read: 0

Now press the Save button. This will save the integer 42 to shared preferences. Then press the Read button again. You should see the following output:

    saved: 42
    read: 42

Even if you close the app and restart it the read value should still be 42.

Explanation

Let’s take a look at the code in the _read() method from above:

    _read() async {
      final prefs = await SharedPreferences.getInstance();
      final key = 'my_int_key';
      final value = prefs.getInt(key) ?? 0;
      print('read: $value');
    }

Notes:

Any read/write to data storage can be expensive so you have to do it in an async method and await the shared preference instance before trying to read from it.
Shared preferences use key-value pairs to save data. To get a saved integer we use the getInt() method and pass in our key to look up.
The ?? double question mark operator means “if null”, so if the key that we are looking up doesn’t exist, then we will use the default value after the ??, in this case 0.

In the _save() method above we use setInt() to save an integer value for a particular key string.

    prefs.setInt(key, value);

The SharedPreferences types that you can save are:

int
double
bool
string
stringList

You can see examples of these here. Play around with the code above to save some of the other types.

Saving to a database

For large amounts of data SharedPreferences is not a good option. Here are some examples of the kind of data I am talking about:

Names and addresses
A word frequency list
High scores

In iOS we would use Core Data and in Android we would use SQLite to store that kind of data. Because of the complexities of dealing with Core Data, when I was developing iOS apps I ended up ignoring Core Data and just using an SQLite plugin. This greatly simplified cross platform development. Flutter takes this to a whole new level by allowing us to effectively ignore the entire platform.

In Flutter we can interact with an SQLite database through a plugin called SQFlite. To set it up we will apply the following points:

We will keep the database management code in a database helper class. Doing so will help to isolate the plugin from the rest of the app. That way in the future if there are updates to the plugin, or if we want to use a different plugin, we will only have to update this one class. (If we wanted to further apply the principles of clean architecture, we could define an interface for the database helper class to implement. That way the rest of the app could just use the interface and know nothing about the helper class. We won’t do that today, though.)
The database helper will be a singleton class and it will maintain a single app-wide global reference to the database, which it will keep open. This will prevent the concurrency issues and memory leaks that can occur when multiple database connections are open at the same time and not closed properly.
We will also create a data model class that will mirror a row in the database. Creating such a class isn’t strictly necessary for teaching you how to use SQFlite, but it greatly simplifies passing data around. The class will also include some convenience methods for converting the data to and from a Map object, which SQFlite uses to interact with the database. (Note that this data model class is different than the concept of an Entity in clean architecture theory. It’s just a convenient way to pass around related data.)

So here is a summary of what we will be doing:

Add the dependency
Make a data model class
Make a database helper class
Use the above classes to read and save data in our app

For our minimal example below, we will use a simple database schema. Each row in the database table will have three columns:

id
word
frequency

In a full app you could use these to record the frequency of every word in a book or article.

Dependencies

Open your pubspec.yaml file and in the dependencies section add the following two lines:

      sqflite: ^1.0.0
      path_provider: ^0.4.1

The version numbers above were tested for this tutorial, but you can find the current versions at sqflite and path_provider. We will use the path provider plugin to give us the data directory where we can store the database in Android and iOS. In Android this maps to the AppData directory, and in iOS to NSDocumentsDirectory.

Database helpers file

Create a new Dart file called database_helpers.dart. Dart allows us to put multiple classes in the same file (also known as a library), so we are going to put both our data model class and our database helper class in here.

Paste the following code into the database_helpers.dart file. This is a modification of and expansion on the documentation.

    import 'dart:io';
    import 'package:path/path.dart';
    import 'package:sqflite/sqflite.dart';
    import 'package:path_provider/path_provider.dart';
    
    // database table and column names
    final String tableWords = 'words';
    final String columnId = '_id';
    final String columnWord = 'word';
    final String columnFrequency = 'frequency';
    
    // data model class
    class Word {
    
      int id;
      String word;
      int frequency;
      
      Word();
      
      // convenience constructor to create a Word object
      Word.fromMap(Map<String, dynamic> map) {
        id = map[columnId];
        word = map[columnWord];
        frequency = map[columnFrequency];
      }
      
      // convenience method to create a Map from this Word object
      Map<String, dynamic> toMap() {
        var map = <String, dynamic>{
          columnWord: word,
          columnFrequency: frequency
        };
        if (id != null) {
          map[columnId] = id;
        }
        return map;
      }
    }
    
    // singleton class to manage the database
    class DatabaseHelper {
    
      // This is the actual database filename that is saved in the docs directory.
      static final _databaseName = "MyDatabase.db";
      // Increment this version when you need to change the schema.
      static final _databaseVersion = 1;
      
      // Make this a singleton class.
      DatabaseHelper._privateConstructor();
      static final DatabaseHelper instance = DatabaseHelper._privateConstructor();
      
      // Only allow a single open connection to the database.
      static Database _database;
      Future<Database> get database async {
        if (_database != null) return _database;
        _database = await _initDatabase();
        return _database;
      }
      
      // open the database
      _initDatabase() async {
        // The path_provider plugin gets the right directory for Android or iOS.
        Directory documentsDirectory = await getApplicationDocumentsDirectory();
        String path = join(documentsDirectory.path, _databaseName);
        // Open the database. Can also add an onUpdate callback parameter.
        return await openDatabase(path,
            version: _databaseVersion,
            onCreate: _onCreate);
      }
      
      // SQL string to create the database 
      Future _onCreate(Database db, int version) async {
        await db.execute('''
              CREATE TABLE $tableWords (
                $columnId INTEGER PRIMARY KEY,
                $columnWord TEXT NOT NULL,
                $columnFrequency INTEGER NOT NULL
              )
              ''');
      }
      
      // Database helper methods:
      
      Future<int> insert(Word word) async {
        Database db = await database;
        int id = await db.insert(tableWords, word.toMap());
        return id;
      }
      
      Future<Word> queryWord(int id) async {
        Database db = await database;
        List<Map> maps = await db.query(tableWords,
            columns: [columnId, columnWord, columnFrequency],
            where: '$columnId = ?',
            whereArgs: [id]);
        if (maps.length > 0) {
          return Word.fromMap(maps.first);
        }
        return null;
      }
      
      // TODO: queryAllWords()
      // TODO: delete(int id)
      // TODO: update(Word word)
    }

Use the database

Now open the main.dart file. We are going to use the same UI layout from the SharedPreferences example.

flutter-local-data-buttons

To keep this as simple as possible, we will be saving a hard coded word hello with a hard coded word frequency of 15 to the database. This is what we would save in a real app if we counted the word “hello” occurring 15 times in a text passage.

Replace the _read() method with

      _read() async {
        DatabaseHelper helper = DatabaseHelper.instance;
        int rowId = 1;
        Word word = await helper.queryWord(rowId);
        if (word == null) {
          print('read row $rowId: empty');
        } else {
          print('read row $rowId: ${word.word} ${word.frequency}');
        }
      }

And replace the _save() method with

      _save() async {
        Word word = Word();
        word.word = 'hello';
        word.frequency = 15;
        DatabaseHelper helper = DatabaseHelper.instance;
        int id = await helper.insert(word);
        print('inserted row: $id');
      }

You will need to import the package that you created above with the database helper and data model class.

    // I called my project `flutter_saving_data`. If you called yours something
    // different then adjust the import location.
    import 'package:flutter_saving_data/database_helpers.dart';

Run the app (I had to do a full stop and restart). First press the Read button, which will try to query row 1. We haven’t inserted a row yet, though, so you should see the following output:

    read row 1: empty

Now press the Save button to insert a row whose word column is hello and whose frequency column is 15. Then press the Read button again to query row 1. You should see

    inserted row: 1
    read row 1: hello 15

Congratulations! You have written to and read from a database.

Challenge

Continuing to press the Save button will insert more rows. The row ID will be auto-incremented. Try changing the word and frequency of the inserted row. Then change the rowId in the _read() method to query other rows.
Modify the app so that when you press the Read button it will list all of the rows in the database. Hint: db.query(tableWords) returns a list of every row as a Map.
Modify the app so that when you press the Save button it will either update or delete an existing row. See the documentation for help.

Saving to a file

Not all data fits well in a database. Sometimes the easiest way to store it is in a file. Here are some examples of when you might want to save data in a file:

Exporting database content as a csv file
Creating a log file
Converting a canvas bitmap to a png file

In the minimal example below we will save a string to a text file and then read it back again.

Dependency

You should have already added the path_provider dependency to your pubspec.yaml file when you did the last section. But in case you came directly here, you can add it now:

      path_provider: ^0.4.1

Minimal example

The UI is still the same as before.

flutter-local-data-buttons

When we press the Save button it will save some text to a file. When we press the Read button it will read the text file.

Use the same main.dart file that we had above, but replace the _read() and _save() methods with the code below.

      _read() async {
        try {
          final directory = await getApplicationDocumentsDirectory();
          final file = File('${directory.path}/my_file.txt');
          String text = await file.readAsString();
          print(text);
        } catch (e) {
          print("Couldn't read file");
        }
      }
      
      _save() async {
        final directory = await getApplicationDocumentsDirectory();
        final file = File('${directory.path}/my_file.txt');
        final text = 'Hello World!';
        await file.writeAsString(text);
        print('saved');
      }

You will have to add the following two imports:

    import 'dart:io';
    import 'package:path_provider/path_provider.dart';

Restart the app and press the Read button. The file doesn’t exist yet so you should see:

    Couldn't read file

Now press the Save button. This will create a file and save the hardcoded string Hello World! to it. Then press the Read button again. You should see the following output:

    saved
    Hello World!

Great! We were able to read and write a text file. The File class also has writeAsBytes() and readAsBytes() methods for non-text files.

Conclusion

In this tutorial, we learned three different ways to save data locally. For small amounts of discrete data, shared preferences is a good option. If you have a long list of data items, though, a database is a better choice. In other situations, saving data in a file makes more sense. All of these are local storage options. If the app is uninstalled then the user will lose this data. To prevent data loss, you could use a cloud storage API to backup user data online. This has the added benefit of being able to sync data across devices. However, it also makes you responsible for protecting users’ private data. But cloud storage is a lesson for a different day. For now continue to hone your skills at storing data locally.

The source code for this tutorial is available on GitHub. (If you got stuck on the database challenge, you can find the answers there, too.)

Android Flutter iOS

14 February 2019

by Suragch