本地数据库 Sqlite

Sqlite 在本地用 SQLite 存结构化数据。和键值型的 Storage 不同：适合多行记录、条件查询、计数等场景。

写入时不必先建表。 insert / update 会根据对象字段自动创建表；表已存在但缺字段时会自动 ALTER TABLE 补列。每张表默认带自增主键 id。

javascript

let db = Sqlite.create('myApp');
db.insert('users', { name: 'tom', age: 18, active: true });
let rows = db.find('users', { name: 'tom' });
console.log(rows[0].age);

不调用 create 时，直接 Sqlite.insert(...) 走默认库 deekeScript.db。

方法	作用
`create(name)`	打开/创建指定库，返回实例
`insert(table, data)`	插入一行（自动建表/补列）
`update(table, data, where, options?)`	按条件更新；无 where 须带 limit
`delete(table, where, options?)`	按条件删除；无 where 须带 limit
`find(table, where?, options?)`	查询多行；支持 limit/offset/orderBy
`findOne(table, where?, options?)`	查询第一行
`count(table, where?)`	计数
`sum` / `avg` / `max` / `min`	列聚合
`group(table, spec)`	分组聚合
`clear(table)`	清空表数据（保留表）
`drop(table)`	删除整张表
`tables()`	列出所有表名
`exists(table)`	表是否存在
`query(sql, args?)`	原始 SELECT，返回行数组
`scalar(sql, args?)`	查询第一行第一列（适合 COUNT）
`exec(sql, args?)`	执行 SQL；SELECT 会自动走 query
`close()`	关闭连接
`getName()`	当前库文件名

create(name)

参数：

name {string} 数据库名。可省略 .db 后缀

返回： {object} 该库的 Sqlite 实例

javascript

let db = Sqlite.create('orders');

insert(table, data)

参数：

table {string} 表名（字母数字下划线，不能以数字开头）
data {object} 行数据。键为列名，值为字段值；对象/数组会存成 JSON 字符串

返回： {number} 新行 id；失败为 -1

表不存在时按字段自动创建；已有表缺列时自动补列。布尔存为 0/1，数字按整数/浮点推断类型。

javascript

let id = db.insert('users', {
    name: 'tom',
    age: 18,
    active: true,
    tags: ['a', 'b']
});
console.log(id);

update(table, data, where, options?)

参数：

table {string} 表名
data {object} 要更新的字段
where {object} 条件（多键为 AND）。可传 {}，但此时必须带 options.limit
options {object} 可选：limit、offset、orderBy

返回： {number} 影响行数；失败为 -1

javascript

db.update('users', { age: 20 }, { name: 'tom' });

// 不限条件，只改最新 1 条
db.update('user', { status: 0 }, {}, { limit: 1, orderBy: 'id DESC' });

delete(table, where, options?)

参数：

table {string} 表名
where {object} 条件。可传 {} 表示不限条件，但此时必须带 options.limit（防误删全表；清空请用 clear）
options {object} 可选：limit、offset、orderBy

返回： {number} 影响行数；失败为 -1

javascript

db.delete('users', { id: 1 });

// 不限条件，删最新 1 条
db.delete('user', {}, { limit: 1, orderBy: 'id DESC' });

// 删除某条件下最早（id 最小）的 1 条
db.delete('logs', { type: 'error' }, { limit: 1, orderBy: 'id ASC' });

// 删除最新的 3 条
db.delete('logs', { type: 'error' }, { limit: 3, orderBy: 'id DESC' });

find(table, where?, options?)

参数：

table {string} 表名
where {object} 可选。不传或空对象则查全部；也可只传 options（仅含 limit/offset/orderBy）
options {object} 可选：
- limit {number} 最多返回行数
- offset {number} 跳过行数
- orderBy {string | string[]} 如 'id DESC'、'id desc, age asc'、['id DESC', 'age ASC']

返回： {Array} 行对象数组；表不存在时为 []

javascript

let all = db.find('users');
let list = db.find('users', { active: true });
console.log(list[0].name);

// 分页（orderBy 大小写均可，支持多列）
let page = db.find('user', {}, {
    limit: 10,
    offset: 10,
    orderBy: 'id desc, age asc'
});
// 或
page = db.find('user', {}, {
    limit: 10,
    offset: 10,
    orderBy: ['id DESC', 'age ASC']
});

// 无 where，直接 options
let latest = db.find('logs', { limit: 5, orderBy: 'id DESC' });

findOne(table, where?, options?)

参数：

table {string} 表名
where {object} 可选。不传或 {} 表示不限条件；也可只传 options
options {object} 可选：orderBy、offset（limit 固定为 1）

返回： {object | null} 第一行；没有则 null

javascript

let user = db.findOne('users', { name: 'tom' });
if (user) {
    console.log(user.id, user.age);
}

// 整表最新一条
let latest = db.findOne('user', { orderBy: 'id DESC' });
// 或
latest = db.findOne('user', {}, { orderBy: 'id DESC' });

// 条件下最早一条
let first = db.findOne('logs', { type: 'error' }, { orderBy: 'id ASC' });

count(table, where?)

参数：

table {string} 表名
where {object} 可选

返回： {number} 行数

javascript

let total = db.count('users');
let activeCount = db.count('users', { active: true });

sum / avg / max / min

参数：

table {string} 表名
column {string} 列名
where {object} 可选条件

返回：

sum / avg：{number}，无数据为 0
max / min：{number | string | null}，无数据为 null

javascript

db.sum('orders', 'amount');
db.sum('orders', 'amount', { status: 'paid' });
db.avg('orders', 'amount', { status: 'paid' });
db.max('orders', 'amount');
db.min('orders', 'id', { type: 'a' });

group(table, spec)

参数：

table {string} 表名
spec {object}：
- by {string | string[]} 必填，分组列
- count {boolean} 为 true 时统计行数，结果字段 count
- sum / avg / max / min {string} 聚合列名，结果字段同名
- where {object} 可选过滤
- orderBy / limit / offset 可选

返回： {Array} 每组一行

javascript

let rows = db.group('orders', {
    by: 'status',
    count: true,
    sum: 'amount',
    where: { year: 2024 },
    orderBy: 'sum DESC',
    limit: 20
});
// [{ status: 'paid', count: 5, sum: 1200 }, ...]

db.group('orders', { by: ['city', 'status'], count: true, avg: 'amount' });

更复杂的聚合（HAVING、一次对多列 sum 等）用 query：

javascript

db.query('SELECT status, SUM(amount) AS total FROM orders GROUP BY status HAVING total > ?', [100]);

clear(table)

参数： table {string} 表名

返回： {boolean} 是否成功

清空表内全部行，保留表结构。

javascript

db.clear('users');

drop(table)

参数： table {string} 表名

返回： {boolean} 是否成功

删除整张表。

javascript

db.drop('users');

tables()

返回： {string[]} 当前库中的表名列表

javascript

console.log(db.tables());

exists(table)

参数： table {string} 表名

返回： {boolean} 表是否存在

javascript

if (db.exists('users')) {
    console.log(db.count('users'));
}

query(sql, args?)

参数：

sql {string} SELECT 语句，可用 ? 占位符
args {Array} 可选，绑定参数

返回： {Array} 行对象数组

适合复杂查询（排序、分页、联表、聚合等）。

javascript

let rows = db.query('SELECT * FROM users WHERE age > ? ORDER BY id DESC LIMIT ?', [18, 10]);

// 计数（推荐加别名）
let countRows = db.query('SELECT COUNT(1) AS c FROM user WHERE id > ?', [12]);
console.log(countRows[0].c);

scalar(sql, args?)

参数： 同 query

返回： 第一行第一列的值；无数据为 null

适合 COUNT / SUM 等单值：

javascript

let n = db.scalar('SELECT COUNT(1) FROM user WHERE id > ?', [12]);
console.log(n);

exec(sql, args?)

参数：

sql {string} SQL
args {Array} 可选

返回：

查询类 SQL（SELECT 等）：自动改走 query，返回行数组（单值更推荐 scalar）
其它（INSERT / UPDATE / DELETE / DDL）：{boolean}

javascript

db.exec('CREATE INDEX IF NOT EXISTS idx_users_name ON users(name)');
db.exec('DELETE FROM user WHERE id < ?', [10]);

// 下面也能用，但建议改成 scalar / query
let rows = db.exec('SELECT COUNT(1) AS c FROM user WHERE id > ?', [12]);
console.log(rows[0].c);

close()

关闭当前数据库连接。之后再读写会自动重新打开。

javascript

db.close();

注意

表名、列名只能包含字母、数字、下划线，且不能以数字开头。
update / delete 无 where（{}）时必须带 options.limit，避免误改/误删全表；清空用 clear。
find / findOne / count / sum / avg / max / min / group 的 where 可为空，表示不限条件。
复杂 SQL（联表、聚合）继续用 query / exec。
对象/数组字段存成 JSON 字符串，读回后需 JSON.parse。
布尔条件查询时用 true/false（内部按 1/0 匹配）。
与 Storage 独立：键值配置继续用 Storage，多行业务数据用 Sqlite。

组件

本地数据库 Sqlite

create(name)

insert(table, data)

update(table, data, where, options?)

delete(table, where, options?)

find(table, where?, options?)

findOne(table, where?, options?)

count(table, where?)

sum / avg / max / min

group(table, spec)

clear(table)

drop(table)

tables()

exists(table)

query(sql, args?)

scalar(sql, args?)

exec(sql, args?)

close()

注意

相关

本地数据库 Sqlite ​

create(name) ​

insert(table, data) ​

update(table, data, where, options?) ​

delete(table, where, options?) ​

find(table, where?, options?) ​

findOne(table, where?, options?) ​

count(table, where?) ​

sum / avg / max / min ​

group(table, spec) ​

clear(table) ​

drop(table) ​

tables() ​

exists(table) ​

query(sql, args?) ​

scalar(sql, args?) ​

exec(sql, args?) ​

close() ​

注意 ​

相关 ​

本地数据库 Sqlite

create(name)

insert(table, data)

update(table, data, where, options?)

delete(table, where, options?)

find(table, where?, options?)

findOne(table, where?, options?)

count(table, where?)

sum / avg / max / min

group(table, spec)

clear(table)

drop(table)

tables()

exists(table)

query(sql, args?)

scalar(sql, args?)

exec(sql, args?)

close()

注意

相关