跨平台开发 / 系统课时
创建 SQLite 数据库和表
创建 SQLite 数据库和表
Flutter 应用需要保存可查询、可更新的结构化数据时,可以把数据放进 SQLite。本节用 sqflite 创建本地数据库,定义一张带主键和基础约束的任务表,并通过一次查询确认数据库与表都已经初始化成功。
学习目标
- 使用
openDatabase创建并打开应用数据库 - 在
onCreate中定义字段、主键和非空约束 - 查询 SQLite 元数据,验证数据表是否真正创建成功
准备 SQLite 依赖
Flutter 本身没有直接提供 SQLite API,移动端项目通常使用 sqflite,并用 path 处理数据库文件路径。在项目目录执行:
flutter pub add sqflite path预期输出
Resolving dependencies...
Got dependencies!具体依赖版本可能随执行时间和现有项目约束而不同,因此不需要依赖终端中出现固定版本号。
创建数据库和表
数据库初始化通常集中放在一个数据库类中,避免页面组件重复处理路径、版本号和建表 SQL。下面示例创建 app.db,并在第一次打开数据库时建立 tasks 表。
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 是否存在。下面代码可以放到临时调试入口中执行:
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);
}预期输出
[{name: tasks}]如果得到空列表,说明当前打开的数据库中没有这张表。常见原因是修改了 onCreate 中的 SQL,却仍然使用已经创建过的旧数据库文件;开发阶段可以删除应用数据后重新运行,正式应用则应该提升数据库版本并通过迁移逻辑修改表结构。
数据库版本不是表版本
openDatabase 的 version 表示整个数据库的结构版本,而不是某一张表的版本。应用发布后新增字段或创建新表时,不应直接修改 onCreate 后期待旧用户自动获得变化,而应提高版本号并在 onUpgrade 中执行迁移。
例如数据库从版本 1 升到版本 2 时,可以新增字段:
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 字段。实际项目应把数据库创建和迁移逻辑统一维护,避免不同入口定义出不一致的表结构。