bitrix-best-practice-sql

Bitrix Best Practice SQL

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

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

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

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

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

Читай 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.

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

Читай 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().

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

Читай 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.

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

Читай 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.

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

Читай 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.

Когда читать transactions.md

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

• Connection::startTransaction(), commitTransaction() или rollbackTransaction();
• вложенные транзакции, savepoint, баланс уровней или TransactionException;
• фиксацию и откат нескольких SQL/ORM-операций в одном соединении;
• различия transaction API MySQL, PostgreSQL, MSSQL и Oracle.