bitrix-database

直接访问数据库

基准：main 23.0+ · 已验证：main 26.800.0

优先使用 ORM（bitrix-orm）：query()、批量写入、合并、deleteByFilter。如需执行 upsert、窗口函数/CTE、复杂报表、使用额外连接或更改架构，则改用 SQL。

任务	阅读
connections 配置、额外数据库、字符集、连接后钩子、命名锁	rules/connections.md
query*、add/addMulti、SqlHelper、占位符、upsert、事务	rules/queries.md
DDL 构建器、表/索引更改、SqlTracker	rules/ddl-debug.md

不可违反的规则

• 每个值都必须通过 SqlExpression 占位符或 SqlHelper（forSql、convertToDb*）传入 SQL。query()/queryExecute() 的 $binds 参数不是预处理语句。
• 来自输入的标识符：先使用白名单，再使用 quote() / ?#。
• 原始写入会跳过 ORM 事件和缓存：之后调用 XxxTable::cleanCache()。
• 仅使用可移植 SQL：使用 SqlHelper 函数，不用反引号、ENGINE、UNSIGNED（bitrix-postgresql）。
• 每个事务使用一个连接；事务应尽量简短。