Работа с базой данных
В 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 и их сопоставление с СУБД