Flutter SQLite

E o Hive?

Além do Flutter SQLite, havia também o Hive como opção. Ele é um banco de dados local, NoSQL e escrito em Dart, o que parece o casamento perfeito.

Porém, existem alguns riscos que não gostaria de correr naquele momento. Além disso, o Hive é menos popular que o SQLite, então a comunidade e o material de apoio são menores.

Se você ainda está decidindo entre as opções de gerenciamento de estado e arquitetura do app, vale ler também o artigo Flutter: por onde começar.

Guardando o script em constantes

Eu armazeno sempre esses códigos SQL em constantes no código. Assim, evito mudanças em tempo de execução e possíveis erros de digitação espalhados pelo projeto.

Para este caso específico, criei uma constante chamada CREATE_CONTACTS_TABLE_SCRIPT com o conteúdo como String. Também recomendo guardar o nome do banco e da tabela em constantes, como DATABASE_NAME e TABLE_NAME.

const String DATABASE_NAME = "contacts.db";
const String TABLE_NAME = "contacts";

// Script executado apenas na criação do banco
const String CREATE_CONTACTS_TABLE_SCRIPT =
    "CREATE TABLE contacts(id INTEGER PRIMARY KEY, name TEXT, email TEXT, phone TEXT, image TEXT, addressLine1 TEXT, addressLine2 TEXT, latLng TEXT)";

O nome contacts.db é apenas um exemplo. O importante é que o mesmo valor seja usado em todos os pontos que abrem o banco.

Abrindo o banco com openDatabase

Neste caso, vou criar um método privado e assíncrono chamado _getDatabase(), que nos retorna o banco de dados pronto para uso. Caso o banco ainda não exista, vamos pedir ao SQLite que o crie usando o script que definimos anteriormente.

Note que a criação ou abertura do banco é um processo que pode demorar. Por isso, o retorno é um Future.

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

Future<Database> _getDatabase() async {
  return openDatabase(
    // Monta o caminho completo do arquivo do banco
    join(await getDatabasesPath(), DATABASE_NAME),
    onCreate: (db, version) {
      // Executado apenas quando o arquivo ainda não existe
      return db.execute(CREATE_CONTACTS_TABLE_SCRIPT);
    },
    version: 1,
  );
}

O método getDatabasesPath recupera o caminho padrão para bancos de dados no dispositivo. Em seguida, o join do pacote path une esse caminho ao nome do arquivo.

Caso o arquivo não seja encontrado, o sqflite dispara o callback onCreate. Dentro dele, executamos o script SQL guardado na constante CREATE_CONTACTS_TABLE_SCRIPT.

Versão do banco e migrações

O parâmetro version é o que permite evoluir o esquema com o tempo. Quando você aumenta esse número em uma nova versão do app, o sqflite chama o callback onUpgrade, onde você pode adicionar colunas ou criar tabelas novas.

Segundo a documentação do pacote, tanto o onCreate quanto o onUpgrade rodam dentro de uma transação. Ou seja, se algo falhar no meio do script, nada fica pela metade.

A documentação também recomenda manter uma única instância do banco aberta durante a vida do app. Com isso, você evita o custo de abrir o arquivo repetidas vezes, então vale guardar o Database em uma variável depois da primeira chamada.

Preparando o modelo

Antes de prosseguir, precisamos de um modelo de dados. Isso pode, e deve, ser feito pelos models da aplicação.

O sqflite sempre recebe e retorna um Map<String, dynamic>. Por isso, é uma boa ideia deixar o modelo preparado para ser convertido de e para essa estrutura, com um método toMap e um construtor fromMap.

class ContactModel {
  int id = 0;
  String name = "";
  String email = "";
  String phone = "";
  String image = "assets/images/profile-picture.png";
  String addressLine1 = "";
  String addressLine2 = "";
  String latLng = "";

  ContactModel({
    this.id,
    this.name,
    this.email,
    this.phone,
    this.image,
    this.addressLine1,
    this.addressLine2,
    this.latLng,
  });

  // Converte um registro do banco em modelo
  ContactModel.fromMap(Map<String, dynamic> map) {
    id = map['id'];
    name = map['name'];
    email = map['email'];
    phone = map['phone'];
    image = map['image'];
    addressLine1 = map['addressLine1'];
    addressLine2 = map['addressLine2'];
    latLng = map['latLng'];
  }

  // Converte o modelo no formato esperado pelo sqflite
  Map<String, dynamic> toMap() {
    return {
      'id': id,
      'name': name,
      'phone': phone,
      'email': email,
      'image': image,
      'addressLine1': addressLine1,
      'addressLine2': addressLine2,
      'latLng': latLng,
    };
  }
}

As chaves do mapa precisam ter exatamente os mesmos nomes das colunas da tabela. Caso contrário, o sqflite tenta gravar em uma coluna que não existe e lança uma exceção.

Esse código segue a sintaxe do Dart da época do curso, antes do null safety. Em projetos com Dart 2.12 ou superior, os parâmetros opcionais precisam de valores padrão ou de tipos anuláveis, como int?.

Salvando um registro no Flutter SQLite

No sqflite, o método db.insert faz a inserção de um novo registro. Nele, precisamos informar a tabela e o item que desejamos incluir.

Lembre-se de que esse item precisa estar no formato Map<String, dynamic>. Então, convertemos o modelo usando o método toMap() criado anteriormente.

Para exemplificar, criei um método chamado create, que recebe um modelo e o insere no banco de dados.

Future create(ContactModel model) async {
  try {
    final Database db = await _getDatabase();

    await db.insert(
      TABLE_NAME,
      model.toMap(),
    );
  } catch (ex) {
    // Registra o erro sem derrubar o app
    print(ex);
    return;
  }
}

Note que executamos tudo dentro de um try/catch, pois podem ocorrer erros de execução ou de disco aqui. É bom sempre ficar prevenido.

Primeiro, recuperamos o banco com await _getDatabase(). Em seguida, o db.insert persiste o modelo na tabela definida pela constante TABLE_NAME.

O insert também aceita o parâmetro conflictAlgorithm. Com ConflictAlgorithm.replace, por exemplo, um registro com o mesmo id é substituído em vez de gerar erro de chave duplicada.

Lendo os registros

Para a leitura no Flutter SQLite, usamos o método query, enviando como parâmetro o nome da tabela de onde queremos buscar os resultados. Ele também aceita filtros, ordenação e limite, como where, orderBy e limit.

Esse método retorna um List<Map<String, dynamic>>. Embora você possa devolver essa mesma lista para a interface, é comum retornarmos uma lista tipada, ou seja, um List<ContactModel>.

Dessa forma, temos o método getContacts(), que busca os contatos, converte o resultado para uma lista tipada e o devolve.

Future<List<ContactModel>> getContacts() async {
  try {
    final Database db = await _getDatabase();
    final List<Map<String, dynamic>> maps = await db.query(TABLE_NAME);

    // Converte cada mapa em um ContactModel
    return List.generate(
      maps.length,
      (i) {
        return ContactModel.fromMap(maps[i]);
      },
    );
  } catch (ex) {
    print(ex);
    return new List<ContactModel>();
  }
}

Note que usamos o List.generate para percorrer os mapas e gerar uma nova lista do tipo List<ContactModel>. Em caso de erro, devolvemos uma lista vazia, assim a tela não quebra por falta de dados.

Como o retorno é um Future, a interface costuma consumir esse método com um FutureBuilder. Dessa forma, o widget mostra um indicador de carregamento enquanto a consulta não termina.

Update e delete no Flutter SQLite

Neste momento, você já deve ter pego a ideia de como o Flutter SQLite trabalha. Basicamente, abrimos o banco e pedimos para uma instrução ser executada com base no nosso modelo.

Para o update e o delete, precisamos de um parâmetro adicional, que é o id do contato. Isso é feito com as propriedades where e whereArgs.

await db.update(
  TABLE_NAME,
  model.toMap(),
  // O ? será substituído pelo valor de whereArgs
  where: "id = ?",
  whereArgs: [model.id],
);

Na propriedade where, escrevemos o filtro em SQL, usando um ? onde queremos um parâmetro. Em seguida, o whereArgs substitui cada ? pelos valores informados.

É importante lembrar que essa substituição ocorre na ordem. Ou seja, o primeiro ? recebe o primeiro valor da lista, e assim por diante.

O último método, o delete, chama a função db.delete() da mesma forma que fizemos no update, inclusive informando o id.

await db.delete(
  TABLE_NAME,
  where: "id = ?",
  whereArgs: [id],
);

Tanto o update quanto o delete retornam a quantidade de linhas afetadas. Com isso, você consegue saber se o registro realmente existia antes da operação.