SQLite 数据库

SQLite 是一个轻量级的嵌入式关系型数据库，无需单独的服务进程，整个数据库以单个文件形式存储，适合在脚本中持久化保存结构化数据。

说明：SQLite 模块内部通过 Android 的 SQLiteOpenHelper 打开数据库，数据库文件位于应用的私有目录，仅当前应用可访问。

sqlite.open(name[, version[, desc[, size]]])

新增于：Hamibot 1.7.3

打开（不存在则创建）一个数据库，返回数据库对象。

参数

名称	类型	描述
name	string	数据库名称
version	number	数据库版本号，默认为 1
desc	string	数据库描述，默认为 null（当前保留，暂未使用）
size	number	预分配大小，默认为 0（当前保留，暂未使用）

返回值

类型	描述
Database	数据库对象，见下方各方法

示例

var db = sqlite.open('demo.db');
log('数据库路径：', db.path());
db.close();
hamibot.exit();

db.exec(sql[, args])

新增于：Hamibot 1.7.3

执行一条 SQL 语句。

根据 SQL 的首个关键字决定行为：

• INSERT / REPLACE：执行插入，返回 1，同时可通过 db.lastInsertRowId() 获取新记录的 ID；
• UPDATE / DELETE：返回受影响的行数；
• 其它语句（如 CREATE TABLE、DROP TABLE、ALTER TABLE 等）：返回 0。

参数

名称	类型	描述
sql	string	要执行的 SQL 语句，可使用 ? 作为参数占位符
args	Array | null	参数占位符对应的值数组，默认为 null。值会按位置依次绑定到 ? 占位符

返回值

类型	描述
number	见上方说明（1 或受影响行数或 0）

示例

var db = sqlite.open('demo.db');

// 建表，返回值 0
db.exec(
  'CREATE TABLE IF NOT EXISTS user(id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER)'
);

// 插入，返回值 1
db.exec('INSERT INTO user(name, age) VALUES(?, ?)', ['alice', 18]);
log('新记录 ID：', db.lastInsertRowId()); // => 1

// 更新，返回受影响行数
var affected = db.exec('UPDATE user SET age = ? WHERE name = ?', [20, 'alice']);
log('受影响行数：', affected); // => 1

// 删除，返回受影响行数
db.exec('DELETE FROM user WHERE name = ?', ['alice']);

db.close();
hamibot.exit();

db.query(sql[, args])

新增于：Hamibot 1.7.3

执行查询语句，返回结果集。

结果集中每一行为一个对象，键为列名，值为该列的值。列值的类型映射如下：

SQLite 类型	JavaScript 类型
TEXT	string
INTEGER	number
REAL/FLOAT	number
BLOB	byte[]
NULL	null

参数

名称	类型	描述
sql	string	查询语句，可使用 ? 作为参数占位符
args	Array | null	参数占位符对应的值数组，默认为 null

返回值

类型	描述
Array<Object>	查询结果，无结果时为空数组

示例

var db = sqlite.open('demo.db');
db.exec('INSERT INTO user(name, age) VALUES(?, ?)', ['alice', 18]);
db.exec('INSERT INTO user(name, age) VALUES(?, ?)', ['bob', 20]);

var rows = db.query('SELECT * FROM user WHERE age > ?', [0]);
log(rows); // => [{ id: 1, name: 'alice', age: 18 }, { id: 2, name: 'bob', age: 20 }]

db.close();
hamibot.exit();

注意：绑定到 query 的参数会被转换为字符串后再交给底层执行，请避免编写依赖参数类型的查询条件。

db.queryOne(sql[, args])

新增于：Hamibot 1.7.3

执行查询语句并返回第一行结果。

参数

名称	类型	描述
sql	string	查询语句，可使用 ? 作为参数占位符
args	Array | null	参数占位符对应的值数组，默认为 null

返回值

类型	描述
Object | null	第一行结果，无结果时 null

示例

var db = sqlite.open('demo.db');
db.exec('INSERT INTO user(name, age) VALUES(?, ?)', ['alice', 18]);

var row = db.queryOne('SELECT * FROM user WHERE name = ?', ['alice']);
log(row); // => { id: 1, name: 'alice', age: 18 }

db.close();
hamibot.exit();

db.lastInsertRowId()

新增于：Hamibot 1.7.3

获取最近一次 INSERT / REPLACE 产生的新记录 ID。

返回值

类型	描述
number	新记录的 rowId

示例

var db = sqlite.open('demo.db');
db.exec('INSERT INTO user(name, age) VALUES(?, ?)', ['alice', 18]);
log('新记录 ID：', db.lastInsertRowId()); // => 1
db.close();
hamibot.exit();

db.version()

新增于：Hamibot 1.7.3

获取数据库当前的版本号。

返回值

类型	描述
number	数据库版本

db.path()

新增于：Hamibot 1.7.3

获取数据库文件的路径。

返回值

类型	描述
string	数据库文件的完整路径

db.isOpen()

新增于：Hamibot 1.7.3

判断数据库是否处于打开状态。

返回值

类型	描述
boolean	打开返回 true，关闭返回 false

示例

var db = sqlite.open('demo.db');
log(db.isOpen()); // => true
db.close();
log(db.isOpen()); // => false
hamibot.exit();

db.transaction(callback)

新增于：Hamibot 1.7.3

在事务中执行一段操作。回调执行完毕会自动提交；若回调中抛出异常，则事务自动回滚，并将异常向上抛出。

参数

名称	类型	描述
callback	function	事务回调，参数为一个事务对象，具有 exec / query / queryOne

示例

var db = sqlite.open('demo.db');
db.exec(
  'CREATE TABLE IF NOT EXISTS account(id INTEGER PRIMARY KEY, balance INTEGER)'
);
db.exec('INSERT INTO account(id, balance) VALUES(?, ?)', [1, 100]);
db.exec('INSERT INTO account(id, balance) VALUES(?, ?)', [2, 50]);

// 转账：任一语句失败则全部回滚
db.transaction(function (tx) {
  tx.exec('UPDATE account SET balance = balance - ? WHERE id = ?', [30, 1]);
  tx.exec('UPDATE account SET balance = balance + ? WHERE id = ?', [30, 2]);
});

log(db.query('SELECT * FROM account')); // => [{ id: 1, balance: 70 }, { id: 2, balance: 80 }]

db.close();
hamibot.exit();

db.readTransaction(callback)

新增于：Hamibot 1.7.3

在只读事务中执行一段操作，参数与 db.transaction(callback) 相同。适用于只做查询的场景。

db.close()

新增于：Hamibot 1.7.3

关闭数据库。关闭后再次调用该数据库的方法会抛出异常。脚本退出时，所有已打开但未关闭的数据库会被自动关闭。

示例

var db = sqlite.open('demo.db');
db.close();
// db.exec('SELECT 1'); // 抛出异常：database has been closed
hamibot.exit();

sqlite.remove(name)

新增于：Hamibot 1.7.3

删除指定的数据库。删除前会先关闭当前脚本中已打开的、同名的数据库。

参数

名称	类型	描述
name	string	要删除的数据库名称

返回值

类型	描述
boolean	删除成功返回 true

示例

var db = sqlite.open('demo.db');
db.exec('CREATE TABLE IF NOT EXISTS t(id INTEGER)');
db.close();

log(sqlite.remove('demo.db')); // => true
hamibot.exit();