跨平台开发 / 系统课时

创建 SQLite 数据库和表

创建 SQLite 数据库和表

Flutter 应用需要保存可查询、可更新的结构化数据时,可以把数据放进 SQLite。本节用 sqflite 创建本地数据库,定义一张带主键和基础约束的任务表,并通过一次查询确认数据库与表都已经初始化成功。

学习目标

  • 使用 openDatabase 创建并打开应用数据库
  • 在 onCreate 中定义字段、主键和非空约束
  • 查询 SQLite 元数据,验证数据表是否真正创建成功

准备 SQLite 依赖

Flutter 本身没有直接提供 SQLite API,移动端项目通常使用 sqflite,并用 path 处理数据库文件路径。在项目目录执行:

bash
flutter pub add sqflite path

预期输出

text
Resolving dependencies...
Got dependencies!

具体依赖版本可能随执行时间和现有项目约束而不同,因此不需要依赖终端中出现固定版本号。

创建数据库和表

数据库初始化通常集中放在一个数据库类中,避免页面组件重复处理路径、版本号和建表 SQL。下面示例创建 app.db,并在第一次打开数据库时建立 tasks 表。

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

class AppDatabase {
  AppDatabase._();

  static final AppDatabase instance = AppDatabase._();
  Database? _database;

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

    final basePath = await getDatabasesPath();
    final dbPath = join(basePath, 'app.db');

    _database = await openDatabase(
      dbPath,
      version: 1,
      onCreate: (db, version) async {
        // 主键使用 SQLite 自增整数,标题不允许为空。
        await db.execute('''
          CREATE TABLE tasks (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            title TEXT NOT NULL,
            is_done INTEGER NOT NULL DEFAULT 0,
            created_at INTEGER NOT NULL
          )
        ''');
      },
    );

    return _database!;
  }
}

这里的 id 由 SQLite 自动生成;title 和 created_at 使用 NOT NULL 阻止缺少关键数据的记录写入;SQLite 没有独立的布尔存储类型,因此示例用整数 0 和 1 表示任务状态。

onCreate 只会在数据库文件首次创建时执行。已经存在版本为 1 的数据库再次打开时,不会重复执行建表语句,因此不要把每次启动都必须执行的逻辑放在这里。

验证数据表

可以查询 SQLite 自带的 sqlite_master 元数据表确认 tasks 是否存在。下面代码可以放到临时调试入口中执行:

dart
Future<void> verifyDatabase() async {
  final db = await AppDatabase.instance.database;
  final rows = await db.rawQuery(
    "SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?",
    ['tasks'],
  );

  print(rows);
}

预期输出

text
[{name: tasks}]

如果得到空列表,说明当前打开的数据库中没有这张表。常见原因是修改了 onCreate 中的 SQL,却仍然使用已经创建过的旧数据库文件;开发阶段可以删除应用数据后重新运行,正式应用则应该提升数据库版本并通过迁移逻辑修改表结构。

数据库版本不是表版本

openDatabase 的 version 表示整个数据库的结构版本,而不是某一张表的版本。应用发布后新增字段或创建新表时,不应直接修改 onCreate 后期待旧用户自动获得变化,而应提高版本号并在 onUpgrade 中执行迁移。

例如数据库从版本 1 升到版本 2 时,可以新增字段:

dart
final database = await openDatabase(
  dbPath,
  version: 2,
  onCreate: (db, version) async {
    await db.execute('''
      CREATE TABLE tasks (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        title TEXT NOT NULL,
        is_done INTEGER NOT NULL DEFAULT 0,
        created_at INTEGER NOT NULL,
        note TEXT
      )
    ''');
  },
  onUpgrade: (db, oldVersion, newVersion) async {
    if (oldVersion < 2) {
      await db.execute('ALTER TABLE tasks ADD COLUMN note TEXT');
    }
  },
);

这是片段示例,依赖前文已经计算出的 dbPath。生效后,新安装用户通过 onCreate 直接获得完整结构,旧版本用户则通过 onUpgrade 增加 note 字段。实际项目应把数据库创建和迁移逻辑统一维护,避免不同入口定义出不一致的表结构。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

创建 SQLite 数据库和表

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通