数据查询Fetch
可使用的方法有:get(),first(),value(),column(),find(),chunk()
查询多条数据get() 或many()
get($type), 如果$type为true时,不执行查询,直接返回构建的sql语句
// 获取多条记录
Db::table('test')->get();
// 生成SQL: "SELECT * FROM test"
// 获取指定字段的多条记录
Db::select('title')->table('pages')->where('id', 17)->get();
// 生成SQL: "SELECT title FROM pages WHERE id='17'"
// 获取指定字段的多条记录
Db::select('username')->table('users')->where('status', 1)->get();
// 生成SQL: "SELECT username FROM users WHERE status='1'"获取单条数据 First()或 one() 别名
成功返回一维数据,失败返回null
$user = Db::table('users')->where('status', 1)->first();
// 结果:单个用户对象或数组获取单一字段 Value
成功返回字段值对应的数值,失败返回null, 这个方法可以从一条数据中获取到单一字段的值
// 获取单个字段的值
$username = Db::table('users')->where('id', 1)->value('username');
// 结果:字符串 "admin"按字段提取列数据column
获取单列数据:
// 获取所有用户名
$usernames = Db::table('users')->column('username');
// 结果: ['admin', 'user1', 'user2', ...]构建键值对:
// 获取用户ID到邮箱的映射
$emails = Db::table('users')->column('email', 'id');
// 结果: [1 => 'admin@example.com', 2 => 'user1@example.com', ...]用于选择框:
// 获取分类下拉框选项
$categories = Db::table('categories')->column('name', 'id');
// 在视图中使用
foreach ($categories as $id => $name) {
echo "{$name}";
}快速按主键查询find
方法有find(),findMany()
find($id) 通过主键查找单条记录,返回记录数组或 null
find($id, $key, true) 查找记录,找不到抛异常 ,返回记录数组
findMany($ids,$key) 通过主键数组查找多条记录 ,返回记录数组
findOrFail($id,$key) *已过时,使用 find($id, 'id', true)*,返回记录数组
基本用法
// 通过主键查找单条记录(默认找不到返回 null)
$user = $db->table('users')->find(1);
// 找不到会抛出异常(新方式)
try {
$user = $db->table('users')->find(999, 'id', true); // 第三个参数控制是否抛异常
} catch (Exception $e) {
echo "用户不存在";
}
// 兼容旧方式(已标记为过时)
try {
$user = $db->table('users')->findOrFail(999);
} catch (Exception $e) {
echo "用户不存在";
}
// 批量查找多条记录
$users = $db->table('users')->findMany([1, 2, 3, 4, 5]);
// 使用自定义主键字段
$user = $db->table('users')->find('admin@example.com', 'email');
// 自定义主键 + 抛异常
$user = $db->table('users')->find('admin@example.com', 'email', true);与传统方式对比
// 传统方式
$user = $db->table('users')->where('id', 1)->first();
$users = $db->table('users')->in('id', [1,2,3])->get();
// 使用 find 方法(更简洁)
$user = $db->table('users')->find(1);
$users = $db->table('users')->findMany([1,2,3]);限制条数与偏移limit() / offset()
limit() 只接受行数一个参数:->limit(10) 生成 LIMIT 10,取前 10 条。要跳过前面的记录,链式加 offset():->limit(10)->offset(20) 生成 LIMIT 10 OFFSET 20。
// 取前 10 条
$articles = Db::table('articles')->limit(10)->get();
// 跳过前 20 条,再取 10 条
$articles = Db::table('articles')->limit(10)->offset(20)->get();
// 分页用 page($page, $perPage),页码从 1 开始
$articles = Db::table('articles')->page(3, 10)->get();分页场景直接写 page($page, $perPage) 更省事,它内部就是 limit($perPage) 加 offset(($page - 1) * $perPage)。
limit() 不接受第二个参数。旧写法 limit($a, $b) 会直接抛出 InvalidArgumentException,不会静默降级。
还有两点容易踩:limit(0) 是「取 0 条」,返回空集,不是「不限制」;只写 offset() 而不写 limit() 时,框架会自动补上 LIMIT 18446744073709551615,因为 MySQL 不支持单独的 OFFSET。
分块遍历chunk()
chunk($count, $callback, $column = null),用于大数据量遍历:每批取 $count 行交给回调处理,再按推进列(默认主键 id)从上一批的最大值继续往后取,直到取完。每批只驻留 $count 行数据,内存占用与总行数无关。成功返回累计处理的行数。
参数说明:
$count每批行数,必须大于 0$callback回调函数,签名为function (array $rows),返回false可提前终止遍历$column推进列,默认id,需为唯一且可排序的列(通常是自增主键)
基本用法:
// 分批处理 5 万条订单,每批 1000 行
$total = Db::table('orders')->where('status', 1)->chunk(1000, function ($rows) {
foreach ($rows as $row) {
// 处理每一行数据……
}
});
echo "共处理 {$total} 行";回调返回 false 提前终止:
Db::table('logs')->chunk(500, function ($rows) {
foreach ($rows as $row) {
if ($row['level'] === 'error') {
return false; // 不再取下一批,遍历到此结束
}
}
});自定义推进列(表没有 id 列时):
Db::table('user_stats')->chunk(200, function ($rows) {
// ...
}, 'user_id');边遍历边写库:
// 按主键推进,遍历过程中更新或删除已处理的行不会漏行、不会重复
Db::table('users')->where('synced', 0)->chunk(1000, function ($rows) {
foreach ($rows as $row) {
Db::table('users')->where('id', $row['id'])->update(['synced' => 1]);
}
});在模型上使用(自动带上软删除范围):
$userModel = $this->model('User');
$userModel->where('status', 1)->chunk(1000, function ($rows) {
// 已软删除的记录不会被遍历到
});与事务配合,任意一批出错即整体回滚:
Db::transaction(function () {
Db::table('orders')->where('status', 1)->chunk(1000, function ($rows) {
foreach ($rows as $row) {
// 任意一步抛异常,整个事务回滚
}
});
});事务的完整用法(嵌套事务、inTransaction()、手动模式等)见 事务操作及维护。
注意事项:
- 不要用
limit/offset循环翻页来遍历全表:遍历过程中一旦有行被删除或插入,偏移量就会错位,导致已处理的行被跳过。chunk() 按推进列取值(WHERE id > 上一批最大值)推进,不受数据变动影响。 - 推进列必须唯一且可排序,默认主键
id;列名写错、或结果集里取不到该列时都会直接抛出异常,不会陷入死循环。 - 每批的
order / limit / offset由 chunk() 内部接管(按推进列 ASC + LIMIT $count),调用方不需要也不应再设置。 - chunk() 是「分批查询」,遍历过程中可以安全地写库或开启事务;而游标(unbuffered 流式读取)在同一连接上边读边写会报错,边读边写的场景请用 chunk()。
- chunk() 自身不包事务。需要「整批失败整体回滚」时把它放进
Db::transaction(function () { ... })里;但事务会持有锁,超大数据量建议每批单独提交。
和分页的关系
chunk() 和分页解决的不是同一个问题,但两者的推进方式同源:chunk() 内部用的 WHERE 推进列 > 上一批最大值 ORDER BY 推进列 ASC LIMIT $count,把「页码」换成「上一页最后一行的主键值」,就是游标分页(keyset pagination)。
按需求选:
- 要页码、要总数、能跳页(后台列表页)→
Db::table('t')->page($page, $perPage)取数据,或Model::paginate()一次拿到数据与total / total_pages / current_page / has_more,再用Pagination渲染页码。 - 只要「下一页」、翻得很深(无限滚动、导出)→ 游标分页,前端传上一页最后一条的主键(如
?last_id=xxx),不要传页码。代价是拿不到总数、不能跳页。 - 要遍历全表做处理(刷数据、导报表)→ chunk(),它没有「页」的概念,只有「批」。
为什么深翻页别用 OFFSET:LIMIT 10 OFFSET 19000 要先扫描并丢弃前 19000 行,读取行数随页码线性增长;游标写法恒定只读 10 行。2 万行实测:OFFSET 19000 读取 19010 行,游标读取 10 行。
分页的完整用法见 分页类,模型层的 paginate() 见 模型。
获取查询次数queryCount
返回查询的数据条数.
// 执行一系列查询操作
$db = Db::table('users')->where('status', 1)->get();
$articles = Db::table('articles')->limit(10)->get();
$category = Db::table('categories')->where('id', 5)->first();
// 获取已执行的查询总数
$count = Db::queryCount();
echo "执行的查询总数: " . $count; // 输出: 执行的查询总数: 3影响行数numRows()
返回数据影响条数.
// 查询示例
$users = Db::table('users')->where('status', 1)->get();
$affectedRows = Db::numRows();
echo "查询影响的行数: " . $affectedRows; // 例如: 查询影响的行数: 5
// 更新示例
Db::table('articles')->where('category_id', 3)->update(['status' => 0]);
$updatedRows = Db::numRows();
echo "更新影响的行数: " . $updatedRows; // 例如: 更新影响的行数: 8
// 删除示例
Db::table('comments')->where('post_id', 10)->delete();
$deletedRows = Db::numRows();
echo "删除影响的行数: " . $deletedRows; // 例如: 删除影响的行数: 12最新插入的id号insertId()
插入后读取最后插入的主键值。推荐直接用 insertGetId() 拿主键;insertId() 记录的是「最近一次插入」的状态,之后的任何查询都可能覆盖它。
// 推荐:插入的同时拿到主键
$newArticleId = Db::table('articles')->insertGetId([
'title' => '新文章标题',
'content' => '文章内容',
'created_at' => date('Y-m-d H:i:s')
]);
echo "新插入文章的ID: " . $newArticleId; // 例如: 25
// 也可以插入后立刻读
Db::table('articles')->insert($data);
$newArticleId = Db::insertId();插入类型、返回值语义与批量插入的注意事项,见 插入数据。
链式构建的注意事项
Db::table() 返回的是共享的查询构建器,不是每次新建的对象。查询一执行完,构建状态(where、limit、order、绑定值等)就会自动清空,只保留结果状态(insertId()、numRows()、getQuery())。由此有三条约束。
1. 不要跨查询复用同一个构建器
$q = Db::table('tools')->where('status', 1); // 尚未执行
$a = $q->where('cat_id', 1)->get(); // 执行完,构建状态已被清空
$b = $q->where('cat_id', 2)->get(); // ⚠ 不是「status 条件丢了」,而是整条链作废
// 会生成 SELECT * FROM ...,直接报错
// 正确做法:需要复用条件就重建两次查询
$a = Db::table('tools')->where('status', 1)->where('cat_id', 1)->get();
$b = Db::table('tools')->where('status', 1)->where('cat_id', 2)->get();2. 不要留下没有执行的链
只写了 table()/where() 却漏掉执行器(get()、first()、count()、update()、delete() 等),这条链会在下一次 table() 时被直接丢弃,不会报错。它不会再污染下一次查询,但也不会替你执行:
Db::table('tools')->where('id', 999); // 漏了执行器
$rows = Db::table('logs')->get(); // 正常查 logs,上一条链被丢弃(不会带上 id=999)
// 想让这条链执行,就补上执行器
Db::table('tools')->where('id', 999)->get();3. 嵌套子查询是禁区
同一条表达式里调用两次 Db::table(),内层求值会清掉外层的表名,外层查询直接报错。需要子查询时,先把内层结果算出来:
// ⚠ 不要这样写
Db::table('tools')->where('id', Db::table('logs')->count())->get();
// 正确做法:先取内层结果
$n = Db::table('logs')->count();
Db::table('tools')->where('id', $n)->get();字段和条件可以写在 table() 之前(如 Db::select('title')->table('pages')),但这类链必须紧跟 table() 并执行,不要留成「只有 where、没有表名」的悬空条件——它无法与下一条链区分,仍会串过去。
如果完全没指定表名就执行(例如 Db::where('id', 1)->get()),会直接抛 LogicException 并提示「未指定查询表名」,不会等到 MySQL 报 1064。
只想取 SQL 不执行:用 getSql(),它返回一个快照并立即清空当前构建状态,因此不会影响后续查询。写法是「先 getSql(),再链执行器」——getSql() 必须在执行器之前,因为「执不执行」要在执行前决定。
// 只出 SQL,不写库
$sql = Db::table('articles')->getSql()->insert($data);
$sql = Db::table('articles')->getSql()->insert($data, 'REPLACE'); // 指定插入类型
$sql = Db::table('articles')->getSql()->where('id', 1)->update(['title' => 'x']);返回值是快照对象,不是字符串:getSql() 返回 SqlSnapshot(DbCore 的子类),必须再链一个执行器才拿到 SQL 字符串。可用的是全部「会产出 SQL」的执行器:
- 查询:
get()first()value()column(),以及find()many()one()等包装方法 - 聚合:
count()max()min()sum()avg() - 写入:
insert()insertGetId()update()delete()invert()inc()dec()touch() - 表维护:
truncate()drop()repair()optimize()analyze()check()checksum()
只写 getSql() 就 echo 或拼字符串不会报致命错误,而是输出一段以 -- 开头的提示文本(SQL 注释形式),提醒还没链执行器。
旧写法已移除:get(true)、first(true)、update($data, true)、delete(true) 这类「第二个参数传 true 只返回 SQL」的写法已删除,调用会抛 InvalidArgumentException 并提示改用 getSql()。之所以要主动抛异常:PHP 对用户函数的多余实参是静默忽略的,只删参数不拦的话,update($data, true) 会从「不执行」变成「真的写库」。
取 SQL 不写日志:getSql() 链不产生执行日志,Db::lastQuery() 取不到它——后者只记录真正执行过的语句。日志受配置 database.log_sql(0 关闭 / 1 只记写操作 / 2 全部记录,默认 2)与 log_sql_max(默认 1000 条,超出丢弃最旧)控制。
WHERE 条件与 OR 分组
多个 where() / orWhere() 之间是纯字符串拼接(用 AND / OR 连接),框架不会自动加括号。SQL 里 AND 的优先级高于 OR,所以只要一段条件里含 OR,它后面的 AND 就会被吃掉。
// ⚠ 错误:以为条件是「三个 LIKE 命中之一 且 status=1」
Db::table('users')
->where('name LIKE ? OR url LIKE ? OR email LIKE ?', [$kw, $kw, $kw])
->where('status', 1)
->getSql()->get();
// 生成: WHERE name LIKE '%a%' OR url LIKE '%a%' OR email LIKE '%a%' AND status = 1
// 实际语义: name LIKE .. OR url LIKE .. OR (email LIKE .. AND status = 1)
// → status=0 的记录也会被带出来
// ✅ 正确:OR 段自己加括号
Db::table('users')
->where('(name LIKE ? OR url LIKE ? OR email LIKE ?)', [$kw, $kw, $kw])
->where('status', 1)
->getSql()->get();
// 生成: WHERE (name LIKE '%a%' OR url LIKE '%a%' OR email LIKE '%a%') AND status = 1三条可用的分组写法:
- 模板里手写括号:
where('(a = ? OR b = ?)', [$x, $y]),最直白,适用于任意复杂条件。 |/&特殊字段语法:where('name|url', $kw)生成(name = ? OR url = ?),where('id&status', 1)生成(id = ? AND status = ?),框架自动加括号;但只支持等值匹配,不能配LIKE。grouped()闭包:
Db::table('users')
->grouped(function ($q) use ($kw) {
$q->where('name', 'like', $kw)
->orWhere('url', 'like', $kw);
})
->where('status', 1)
->get();
// 生成: WHERE (name LIKE '%a%' OR url LIKE '%a%') AND status = 1为什么框架不默认加括号:where('id=? AND status=?', [1, 1]) 这类模板会被整体包成 (id=? AND status=?),所有 getSql() 输出与 SQL 日志文本都会变;而且确实有人靠 SQL 优先级写 a OR b AND c。需要分组就显式写出来——这与 Laravel、ThinkPHP 的行为一致。
三条容易踩的边界:
whereRaw('a = 1 OR b = 2')同样不分组,后面再接where()一样会被OR吃掉,需要时自己包括号。grouped()的闭包里必须至少加一个条件。闭包内一个条件都没加时(例如可选筛选参数全为空),当前实现仍会补上右括号,生成WHERE ) AND ...的语法错误 SQL;可选条件请在闭包外先判断。- 数组条件的第 4 个元素(如
where([['a', '=', $x, 'OR'], ['b', '=', $y, 'OR']]))目前不生效,片段之间一律按外层逻辑连接(默认AND),且不会报错。要 OR 请用grouped()或手写括号。