bitrix-best-practice-sql

Bitrix Best Practice SQL

The skill helps you understand which SQL/DB best practices should be used. Use it only for tasks that involve working with a database: schema, SQL queries, ORM models, selects, writes, data migrations, indexes, transactions, or other DB-boundary decisions.

How to use

1. Determine whether the task actually involves SQL, ORM, or data storage.
2. Identify the specific DB area of the task: read, write, schema, migration, performance, consistency, or query security.
3. Open only those rule files that directly relate to this DB area.
4. First follow the stricter repository rules and module constraints.
5. Prefer framework-native and Bitrix-native data access patterns over homemade SQL and storage abstractions.

Choosing a rule file

When to read query-execution.md

Read query-execution.mdif the task involves at least one of these areas:

• Bitrix\Main\Application::getConnection(), Bitrix\Main\DB\Connection or getSqlHelper();
• query(), queryScalar(), queryExecute(), add(), addMulti() or Bitrix\Main\DB\Result;
• Bitrix\Main\DB\SqlExpression, placeholders ?s, ?i, ?f, ?#, ?@ or manually assembling SQL from parts;
• SqlHelper::quote(), forSql(), prepareInsert(), prepareUpdate(), convertToDb*() or getTopSql();
• replacing legacy $DB / CDatabase with the D7 DB API;
• choosing between raw SQL via Connection and a higher-level framework-native DB path.

When to read orm-datamanager-map.md

Read orm-datamanager-map.mdif the task involves at least one of these areas:

• class *Table extends Bitrix\Main\ORM\Data\DataManager;
• getTableName(), getConnectionName(), getMap(), getUfId(), postInitialize() or setDefaultScope();
• describing fields via Bitrix\Main\ORM\Fields\Field and its descendants instead of a legacy array map;
• Reference, OneToMany, ManyToMany, configureJoinType(), configureCascade*Policy() specifically at the entity declaration level;
• primary key, autocomplete, validators, save/fetch modifiers, title и default values в entity map;
• choosing between typed field objects and the old array in getMap().

When to read orm-objectify.md

Read orm-objectify.mdif the task involves at least one of these areas:

• Bitrix\Main\ORM\Objectify\EntityObject, Collection, createObject(), createCollection(), wakeUpObject() or wakeUpCollection();
• get(), require(), remindActual(), fill(), isFilled(), isChanged(), collectValues();
• working with the relation graph via addTo(), removeFrom(), removeAll() or collection lifecycle;
• Collection::walk(), filter(), find(), merge(), hasByPrimary() or getByPrimary();
• choosing between Objectify objects and result arrays;
• object state (RAW, ACTUAL, CHANGED, DELETED) and in-memory ORM behavior.

When to read orm-query-filter.md

Read orm-query-filter.mdif the task involves at least one of these areas:

• DataManager::query(), getList(), getRow(), getByPrimary() or getCount();
• Bitrix\Main\ORM\Query\Query, Query::filter(), ConditionTree, where*, having*, logic() or nested filters;
• fetchObject(), fetchCollection(), fetch(), fetchAll() and choosing between object fetch and arrays;
• runtime fields, registerRuntimeField(), Query::expr(), ExpressionField в query-path;
• buildFilterSql(), disableDataDoubling(), private fields, aggregation/object-fetch restrictions;
• choice between modern query builder and legacy filter array.

When to read orm-persistence-write.md

Read orm-persistence-write.md, if the task touches at least one of these areas:

• DataManager::add(), update(), delete(), addMulti(), updateMulti() or object/collection save();
• DeleteByFilterTrait::deleteByFilter(), MergeTrait::merge() or low-level ORM write helpers;
• Bitrix\Main\ORM\Data\AddStrategy, InsertIgnore, Merge, MergeByDefaultTrait, InsertIgnoreByDefaultTrait, AddMergeTrait or AddInsertIgnoreTrait;
• choice between regular ORM write, batch operation, merge/upsert and delete-by-filter;
• ORM events on write, ignoreEvents, cache cleanup и caveats batch persistence;
• bulk write or update of multiple rows through ORM lifecycle.