Работа с базой данных

В be5 доступ к БД осуществляется на двух уровнях:

Уровень Класс Когда использовать
Модельный (CRUD) DatabaseModel / EntityModel Записи сущностей (таблиц) по метаданным: вставка, чтение, обновление, удаление. SQL не пишется — генерируется из метаданных, автоматически добавляются служебные колонки (who_inserted, modified_date, is_deleted, ...)
Raw SQL DbService Произвольные SQL-запросы: агрегации, подзапросы, join-ы, работа с конкретными строками результата (QRec), транзакции, доступ к соединению

Оба класса доступны в операциях как инжектированные поля database и db (см. operations-back.md, раздел OperationSupport).

DatabaseModel

DatabaseModel (be5/database-model/.../databasemodel/DatabaseModel.java) — фасад модельного доступа к БД. Сам SQL не выполняет: по имени сущности возвращает EntityModel<T> — типизированный CRUD-обёртку над таблицей сущности.

Методы

Метод Описание
<T> EntityModel<T> getEntity(String entityName) Возвращает EntityModel для сущности. Имя ищется в метаданных (Meta.getEntity)
<T> EntityModel<T> getAt(String entityName) То же, что getEntity; зарегистрирован Groovy-мета-класс, поэтому в Groovy работает database["entityName"]

Тип параметра T — тип первичного ключа сущности (обычно Long или String).

EntityModel

EntityModel<T> (be5/database-model/.../databasemodel/EntityModel.java) — CRUD-операции над таблицей сущности. Ошибки — EntityModelException. Классы не синхронизированы.

Вставка:

Метод Описание
<R> R add(Map<String, ?> values) Вставить запись, вернуть сгенерированный id
<R> R add(DynamicPropertySet dps) То же, значения из DPS
<R> List<R> addAll(Collection<Map<String, ?>> c) Пакетная вставка, вернуть список id

Чтение:

Метод Описание
@Nullable RecordModel<T> get(T id) Запись по первичному ключу (null, если нет)
@Nullable RecordModel<T> getBy(Map<String, ?> conditions) Запись по условию
@Nullable RecordModel<T> getColumns(List<String> columns, T id) Запись по PK, только указанные колонки
@Nullable RecordModel<T> getColumnsBy(List<String> columns, Map<String, ?> conditions) То же по условию
DynamicPropertySet getPropertySet(Map<String, ?> conditions) Запись «сырым» DPS (без обёртки RecordModel)
List<RecordModel<T>> toList() / toList(Map<String, ?> conditions) Все записи (или по условию)
RecordModel<T>[] toArray() / toArray(Map<String, ?> conditions) То же, массивом

Обновление:

Метод Описание
int set(T id, String propertyName, Object value) Обновить одно поле по PK
int set(T id, Map<String, ?> values) / set(T id, DynamicPropertySet values) Обновить поля по PK
int setIds(T[] ids, Map<String, ?> values) / setIds(T[] ids, DynamicPropertySet values) Обновить несколько записей по списку PK (bulk)
int setBy(Map<String, ?> values, Map<String, ?> conditions) / setBy(DynamicPropertySet, Map) Обновить по условию

Удаление:

Метод Описание
int remove(T id) / int remove(T[] ids) Удалить по PK
int removeBy(Map<String, ?> conditions) Удалить по условию
int removeWhereColumnIn(String columnName, T[] ids) Удалить где колонка IN (...)
int removeAll() Удалить все записи

Подсчёт и проверки:

Метод Описание
long count() / long count(Map<String, ?> values) Число строк (по условию)
boolean isEmpty() Пуста ли таблица
boolean contains(Map<String, ?> conditions) / containsAll(Collection<Map<String, ?>> c) Найдётся ли запись(и) по условию

Метаданные:

Метод Описание
String getEntityName() Имя сущности
String getPrimaryKeyName() Имя колонки первичного ключа
Entity getEntity() Объект метаданных сущности

RecordModel

RecordModel<T> — результат get(...)/toList(...). Это DynamicPropertySet (см. attributes.md) со специальными методами:

Метод Описание
T getPrimaryKey() Значение первичного ключа
int update(String propertyName, Object value) / update(Map<String, ?> values) Обновить запись в БД (через EntityModel) и обновить локальную копию
int remove() Удалить запись из БД

Прямой setValue(...) на RecordModel запрещён (IllegalAccessError) — записывайте только через EntityModel.set(...).

Служебные колонки

DatabaseModel автоматически поддерживает служебные колонки сущности (через ColumnsHelper): created_date, modified_date, who_inserted, who_modified, ip_inserted, ip_modified, is_deleted. При add/set/remove значения подставляются сами (текущий пользователь, время, IP), is_deleted становится yes при remove (soft delete), если колонка есть в сущности.

Примеры

// Java — вставка
Long id = database.getEntity("documents").add(
        ImmutableMap.of("title", "Отчёт", "status", "new"));

// Java — чтение и обновление
RecordModel<String> rec = database.<String>getEntity("user_roles").get("admin");
rec.update("role", "Administrator");
database.<String>getEntity("user_roles").set("admin", "role", "Viewer");

// Java — пакетное обновление и удаление по условию
database.getEntity("user_roles").setIds(
        new String[] {"a", "b"}, ImmutableMap.of("role", "Administrator"));
database.getEntity("user_roles")
        .removeBy(Collections.singletonMap("user_name", "obsolete"));

// Java — подсчёт
long total = database.getEntity("documents").count(
        ImmutableMap.of("status", "open"));
// Groovy — в операции
def entity = database.getEntity(info.entityName)
def id = entity.add([title: title, category: category])

// Groovy — доступ через [] (мета-класс)
def rec = database["user_roles"]["admin"]
def users = database["users"].toList()

DbService

DbService (be5/database/.../database/DbService.java, реализация DbServiceImpl) — сервис raw SQL: выполнение произвольных запросов с параметрами, маппинг результатов, транзакции. SQL перед выполнением транслируется под конкретный DBMS (format(sql), реализация через DbmsTransformer).

Выборка: скаляры

Метод Описание
T one(String sql, Object... params) Первая колонка первой строки (скаляр)
Long getLong(String sql, Object... params) / String getString(...) / Integer getInteger(...) То же, с типизацией
long countFrom(String sql, Object... params) Оборачивает в SELECT COUNT(1) FROM (sql)
List<T> scalarList(String sql, Object... params) / List<Long> scalarLongList(...) Список скаляров первой колонки
Long[] longArray(String sql, Object... params) / String[] stringArray(...) То же, массивами

Выборка: QRec

Метод Описание
QRec record(String sql) / record(String sql, String cacheName) Первая строка как QRec (null, если пусто); вариант с кэшированием
List<QRec> list(String sql) / list(String sql, String cacheName) Все строки как QRec
QRec recordWithParams(String sql, Object... params) / List<QRec> listWithParams(String sql, Object... params) Те же методы с параметрами ?

Выборка: произвольная маппинг

Метод Описание
T query(String sql, ResultSetHandler<T> rsh, Object... params) Маппинг через Commons-DBUtils ResultSetHandler (например, BeanHandler)
T select(String sql, ResultSetParser<T> parser, Object... params) Одна строка через функциональный ResultSetParser
List<T> list(String sql, ResultSetParser<T> parser, Object... params) Все строки через ResultSetParser
List<T> list(AstStart astStart, ResultSetParser<T> parser, Object... params) То же, запрос задаётся AST-строителем (com.developmentontheedge.sql)

Изменение

Метод Описание
int update(String sql, Object... params) / updateRaw(...) INSERT/UPDATE/DELETE, вернуть число затронутых строк
T insert(String sql, Object... params) / insertRaw(...) INSERT, вернуть сгенерированный ключ
T executeRaw(String sql, ResultSetHandler<T> rsh, Object... params) DML с обработчиком результата

Транзакции и соединение

Метод Описание
T execute(SqlExecutor<T> executor) Доступ к Connection (каллбек T run(Connection))
T inTransaction(TransactionExecutor<T> executor) Выполнить блок в транзакции, вернуть результат
void useTransaction(TransactionExecutorVoid executor) То же, без результата
boolean isInTransaction() Внутри ли текущая нить транзакции
String format(String sql) / format(AstStart astStart) Только трансляция SQL под DBMS, без выполнения

Транзакции также можно объявить аннотацией @Transactional (метод или класс) — интерцептор (TransactionInterceptor) в DatabaseModule обработает её. Исключения при SQL-ошибках — RuntimeSqlException (unchecked).

QRec

QRec (be5/database/.../database/QRec.java) — строка результата SQL, наследуется от DynamicPropertySetSupport (то есть это DPS: getValue("col"), hasProperty("col"), …). Плюс типизированные доступы к первой колонке и по имени:

Метод Описание
Object getValue() Значение первой колонки
String getString() / Integer getInt() / Long getLong() / Date getDate() Первая колонка, типизированно
String getString(String name) / int getInt(String name) / long getLong(String name) / Date getDate(String name) Колонка по имени
InputStream getBinaryStream() / getBinaryStream(String name) BLOB-значение как поток

Примеры

// Скаляр
String password = db.oneString("SELECT user_pass FROM users WHERE user_name = ?", username);
long total = db.countFrom("SELECT * FROM documents WHERE status = ?", "open");

// Строки как QRec
QRec person = db.recordWithParams("SELECT * FROM persons WHERE name = ?", "user2");
String name = person.getString("name");
long id = person.getLong();

List<QRec> rows = db.listWithParams(
        "SELECT id, title FROM documents WHERE created_date > ?", since);
for (QRec r : rows) {
    System.out.println(r.getLong("id") + " " + r.getString("title"));
}

// Произвольный маппинг в бин
TestPerson p = db.query("SELECT * FROM persons WHERE name = ?",
        new BeanHandler<>(TestPerson.class), "user2");

// Вставка / обновление
Long newId = db.insert("INSERT INTO persons (name, password) VALUES (?, ?)", "user", "pass");
int affected = db.update("UPDATE persons SET password = ? WHERE name = ?", "new", "user");
// Groovy — транзакция
db.inTransaction {
    db.update("UPDATE accounts SET balance = balance - ? WHERE id = ?", amount, from)
    db.update("UPDATE accounts SET balance = balance + ? WHERE id = ?", amount, to)
}

Сравнение: модельный доступ vs raw SQL

Критерий DatabaseModel DbService
SQL Не пишется — генерируется из метаданных Пишется вручную
Служебные колонки Подставляются автоматически Только вручную
Soft delete remove → is_deleted = yes Ручной UPDATE/DELETE
Связи сущностей Через метаданные (COLLECTION и т.п.) Через JOIN в SQL
Агрегации / подзапросы Ограниченно (count, toList) Полный SQL
Типизация результата RecordModel<T> / DynamicPropertySet QRec, скаляры, бин-маппинг
Кэширование — list(sql, cacheName), record(sql, cacheName)

Правило выбора: CRUD по записям сущности — database.getEntity(...); всё остальное (сложные выборки, агрегации, администрирование) — db.

Вспомогательные классы

Класс Модуль Назначение
SqlHelper database-model Построение INSERT/UPDATE/DELETE SQL из мап: insert(table, values), update(table, conditions, values), updateIn(table, col, ids, values), delete(table, conditions)
ColumnsHelper database-model Служебные колонки: addInsertSpecialColumns, withUpdateSpecialColumns, addDeleteSpecialValues, checkDpsColumns
DpsUtils database-model Утилиты над DPS: setValues(dps, map/dps), getTagName, toLinkedHashMap и др.
ConnectionService database Управление соединениями: getConnection, beginTransaction/endTransaction/rollbackTransaction, inTransaction
DataSourceService database getDataSource, getDbms (тип СУБД), getConnectionUrl
@Transactional database Аннотация для декларативных транзакций (интерцептор)
RuntimeSqlException database Unchecked-обёртка ошибок SQL

Ссылки

  • operations-back.md — поля database и db в OperationSupport, примеры операций

  • attributes.md — DynamicPropertySet (QRec и RecordModel наследуются от него)

  • db.rst — типы колонок be5 и их сопоставление с СУБД