bitrix-best-practice-sql

Original：🇺🇸 English

Translated

Use for Bitrix SQL and ORM patterns raw SQL or Connection queries, DataManager maps or field definitions, Objectify objects or collections, ORM queries or filters, ORM writes or batch persistence. Use when designing, reviewing, or implementing DB reads, writes, schema, or data access code.

3installs

Sourcebitrix-tools/best-practice

Added on2026-08-19

NPX Install

npx skill4agent add bitrix-tools/best-practice bitrix-best-practice-sql

SKILL.md Content

View Translation Comparison →

Bitrix Best Practice SQL

Скилл помогает понять, какие нужно использовать SQL/DB best practices. Используй его только для задач, где есть работа с базой данных: схема, SQL-запросы, ORM-модели, выборки, запись, миграции данных, индексы, транзакции или другие DB-boundary решения.

Как использовать

Определи, действительно ли задача затрагивает SQL, ORM или хранение данных.
Выдели конкретную DB-область задачи: чтение, запись, схема, миграция, производительность, консистентность или безопасность запроса.
Открой только те rule-файлы, которые напрямую относятся к этой DB-области.
Сначала следуй более строгим правилам репозитория и ограничениям модуля.
Предпочитай framework-native и Bitrix-native паттерны работы с данными вместо самодельных SQL- и storage-абстракций.

Выбор rule-файла

Когда читать

rules/query-execution.md

Читай

rules/query-execution.md

, если задача затрагивает хотя бы одну из этих областей:

Bitrix\Main\Application::getConnection()

,

Bitrix\Main\DB\Connection

или

getSqlHelper()

;

query()

,

queryScalar()

,

queryExecute()

,

add()

,

addMulti()

или

Bitrix\Main\DB\Result

;

```
Bitrix\Main\DB\SqlExpression
```
, placeholders
```
?s
```
,
```
?i
```
,
```
?f
```
,
```
?#
```
,
```
?@
```
или ручную сборку SQL из частей;

SqlHelper::quote()

,

forSql()

,

prepareInsert()

,

prepareUpdate()

,

convertToDb*()

или

getTopSql()

;

замену legacy
```
$DB
```
/
```
CDatabase
```
на D7 DB API;
выбор между raw SQL через
```
Connection
```
и более высокоуровневым framework-native DB path.

Когда читать

rules/orm-datamanager-map.md

Читай

rules/orm-datamanager-map.md

, если задача затрагивает хотя бы одну из этих областей:

класс

*Table extends Bitrix\Main\ORM\Data\DataManager

;

getTableName()

,

getConnectionName()

,

getMap()

,

getUfId()

,

postInitialize()

или

setDefaultScope()

;

описание полей через
```
Bitrix\Main\ORM\Fields\Field
```
и наследников вместо legacy array map;
```
Reference
```
,
```
OneToMany
```
,
```
ManyToMany
```
,
```
configureJoinType()
```
,
```
configureCascade*Policy()
```
именно на уровне декларации сущности;
primary key, autocomplete, validators, save/fetch modifiers, title и default values в entity map;
выбор между typed field objects и старым массивом в
```
getMap()
```
.

Когда читать

rules/orm-objectify.md

Читай

rules/orm-objectify.md

, если задача затрагивает хотя бы одну из этих областей:

Bitrix\Main\ORM\Objectify\EntityObject

,

Collection

,

createObject()

,

createCollection()

,

wakeUpObject()

или

wakeUpCollection()

;

get()

,

require()

,

remindActual()

,

fill()

,

isFilled()

,

isChanged()

,

collectValues()

;

работу с relation graph через
```
addTo()
```
,
```
removeFrom()
```
,
```
removeAll()
```
или collection lifecycle;

Collection::walk()

,

filter()

,

find()

,

merge()

,

hasByPrimary()

или

getByPrimary()

;

выбор между Objectify-объектами и массивами результата;
object state (
```
RAW
```
,
```
ACTUAL
```
,
```
CHANGED
```
,
```
DELETED
```
) и in-memory поведение ORM.

Когда читать

rules/orm-query-filter.md

Читай

rules/orm-query-filter.md

, если задача затрагивает хотя бы одну из этих областей:

DataManager::query()

,

getList()

,

getRow()

,

getByPrimary()

или

getCount()

;

Bitrix\Main\ORM\Query\Query

,

Query::filter()

,

ConditionTree

,

where*

,

having*

,

logic()

или nested filters;

```
fetchObject()
```
,
```
fetchCollection()
```
,
```
fetch()
```
,
```
fetchAll()
```
и выбор между object fetch и массивами;

runtime fields,

registerRuntimeField()

,

Query::expr()

,

ExpressionField

в query-path;

```
buildFilterSql()
```
,
```
disableDataDoubling()
```
, private fields, aggregation/object-fetch restrictions;
выбор между modern query builder и legacy filter array.

Когда читать

rules/orm-persistence-write.md

Читай

rules/orm-persistence-write.md

, если задача затрагивает хотя бы одну из этих областей:

DataManager::add()

,

update()

,

delete()

,

addMulti()

,

updateMulti()

или object/collection

save()

;

DeleteByFilterTrait::deleteByFilter()

,

MergeTrait::merge()

или low-level ORM write helpers;

Bitrix\Main\ORM\Data\AddStrategy

,

InsertIgnore

,

Merge

,

MergeByDefaultTrait

,

InsertIgnoreByDefaultTrait

,

AddMergeTrait

или

AddInsertIgnoreTrait

;

выбор между обычной ORM-записью, batch-операцией, merge/upsert и delete-by-filter;
события ORM при записи,
```
ignoreEvents
```
, cache cleanup и caveats batch persistence;
массовая запись или обновление нескольких строк через ORM lifecycle.

bitrix-best-practice-sql

NPX Install

Tags

SKILL.md Content

Bitrix Best Practice SQL

Как использовать

Выбор rule-файла

Когда читать
`rules/query-execution.md`

Когда читать
`rules/orm-datamanager-map.md`

Когда читать
`rules/orm-objectify.md`

Когда читать
`rules/orm-query-filter.md`

Когда читать
`rules/orm-persistence-write.md`