From 0da579c5f6905e06185b149e2ba93b742d1520f8 Mon Sep 17 00:00:00 2001 From: Konstantin Krivopustov Date: Wed, 12 Dec 2012 07:00:49 +0000 Subject: [PATCH] Refs #1633 CUBA documentation (dbms) --- doc/content/manual/ru/chapter_deployment.xml | 138 +--------- doc/content/manual/ru/chapter_framework.xml | 258 +++++++++++++++--- doc/content/manual/ru/manual.xml | 66 ++++- .../manual/ru/source/context_mssql.xml | 10 - .../manual/ru/source/context_postgres.xml | 10 - .../manual/ru/source/cuba_dbmstype_mssql.txt | 1 - .../ru/source/cuba_dbmstype_postgres.txt | 1 - .../manual/ru/source/instance1_mssql.txt | 1 - .../manual/ru/source/instance2_mssql.txt | 3 - .../manual/ru/source/instance_mssql.txt | 3 - 10 files changed, 289 insertions(+), 202 deletions(-) delete mode 100644 doc/content/manual/ru/source/context_mssql.xml delete mode 100644 doc/content/manual/ru/source/context_postgres.xml delete mode 100644 doc/content/manual/ru/source/cuba_dbmstype_mssql.txt delete mode 100644 doc/content/manual/ru/source/cuba_dbmstype_postgres.txt delete mode 100644 doc/content/manual/ru/source/instance1_mssql.txt delete mode 100644 doc/content/manual/ru/source/instance2_mssql.txt delete mode 100644 doc/content/manual/ru/source/instance_mssql.txt diff --git a/doc/content/manual/ru/chapter_deployment.xml b/doc/content/manual/ru/chapter_deployment.xml index dc6eb0c54d..335a3dd69c 100644 --- a/doc/content/manual/ru/chapter_deployment.xml +++ b/doc/content/manual/ru/chapter_deployment.xml @@ -19,6 +19,14 @@ Конфигурационный каталог TODO +
+ Рабочий каталог + TODO +
+
+ Каталог скриптов базы данных + TODO +
Варианты запуска Tomcat @@ -29,139 +37,11 @@ TODO
- Интеграция с Active Directory - TODO -
-
- Организация кластера + Отказоустойчивость и балансировка нагрузки TODO
Мониторинг работы приложения TODO
-
- Резервное копирование базы данных - Для резервного копирования базы данных и приложения необходимо: - - - Создать каталог для резервного копирования - - - Создать скрипт в созданном каталоге - - - Для Windows − backup.bat - - - - Для Linux − backup.sh - - - - - - Настроить параметры в скрипте (см. таблицу ниже) в соответствии с Вашей системой - - - Создать файл с паролем - - - Для Windows в файле %APPDATA%\postgresql\pgpass.conf (%APPDATA% − это Application Data пользователя Windows, под которым будет выполняться копирование) должна быть запись вида host:port:databasename:user:password (например, localhost:5432:docflow:root:root) - - - Для Linux нужно создать файл .pgpass в домашней директории пользователя, под которым будет выполняться копирование (например /root) c содержимым, описанным выше, и запретить просмотр и редактирование другим пользователям командой chmod 600 .pgpass - - - - - Сделать скрипт автоисполняемым в зависимости от системы - - - - - - - - - - Параметр - Описание - Значение - - - - - PG_DIR - Путь к папке bin, где установлен PostgreSQL - C:\Program Files\PostgreSQL\8.3\bin (пример) - - - TOMCAT_DIR - Каталог приложения - D:\work\thesis2\tomcat (пример) - - - BACKUP_DIR - Каталог для резервного копирования, который был создан в п.1 - D:\backup (пример) - - - PG_HOST - IP адрес подключения к копируемой базе данных - localhost (по умолчанию) - - - PG_PORT - Порт подключения к копируемой базе данных - 5432 (по умолчанию) - - - DB_NAME - Имя копируемой базы данных - docflow (пример) - - - PG_USER - Пользователь базы данных, под которым выполняется копирование - root (по умолчанию) - - - - - В результате резервного копирования каталог, созданный в п.1, будет иметь следующий вид: - - - backup - - - 2010_09_22 − каталог, созданный скриптом - - - tomcat − копия приложения - - - docflow_2010_09_22.dump − копия базы данных - - - - - ... - - - 2010_09_28 - - - tomcat - - - docflow_2010_10_28.dump - - - - - - - При повторном выполнении скрипта будет создана новая копия базы данных, а в копии приложения будут обновлены файлы. -
diff --git a/doc/content/manual/ru/chapter_framework.xml b/doc/content/manual/ru/chapter_framework.xml index 7e978a5ee7..7517211213 100644 --- a/doc/content/manual/ru/chapter_framework.xml +++ b/doc/content/manual/ru/chapter_framework.xml @@ -2777,6 +2777,21 @@ public class Orders implements OrdersMBean { Следует иметь в виду, что измененные значения для свойств, хранящихся в файлах, не сохраняются, и действуют только до рестарта данного блока. JMX ObjectName: app-core.cuba:type=ConfigStorage, app.cuba:type=ConfigStorage, app-portal.cuba:type=ConfigStorage +
+ PersistenceManagerMBean + PersistenceManagerMBean предоставляет следующие возможности: + + управление механизмом статистики сущностей + + + отображение новых скриптов обновления БД методом findUpdateDatabaseScripts() и запуск обновления методом updateDatabase() + + + запуск произвольных JPQL запросов в контексте Middleware методами jpqlLoadList(), jpqlExecuteUpdate() + + + JMX ObjectName: app-core.cuba:type=PersistenceManager +
ScriptingManagerMBean ScriptingManagerMBean является JMX-фасадом для интерфейса инфраструктуры @@ -2790,7 +2805,7 @@ public class Orders implements OrdersMBean { JMX операции: - runGroovyScript() - выполнить скрипт Groovy и вернуть результат. Для отображения в JMX-интерфейсе результат должен быть типа String. В остальном аналогичен методу Scripting.runGroovyScript(). + runGroovyScript() - выполнить скрипт Groovy в контексте Middleware и вернуть результат. Для отображения в JMX-интерфейсе результат должен быть типа String. В остальном аналогичен методу Scripting.runGroovyScript().
@@ -2983,6 +2998,11 @@ query.setParameter(1, customer); getDelegate() - возвращает экземпляр javax.persistence.Query, предоставляемый реализацией ORM. +
+ Поиск like без учета регистра + Для удобного формирования условия поиска без учета регистра символов и по любой части строки можно использовать префикс (?i) имени параметра запроса, например:select c from sales$Customer c where c.name like :(?i)name + В данном случае ORM переведет значение параметра name в нижний регистр и обрамит символами %, а затем в БД выполнит SQL с условием вида lower(C.NAME) like ? +
Макросы в JPQL Текст JPQL запроса может включать макросы, которые обрабатываются перед выполнением и превращаются в исполняемый JPQL, дополнительно модифицируя набор параметров. @@ -3312,46 +3332,202 @@ public void someServiceMethod() { Таблицу SYS_QUERY_RESULT необходимо периодически чистить от ненужных результатов запросов, оставленных завершенными пользовательскими сессиями. Для этого предназначен метод deleteForInactiveSessions бина QueryResultsManagerAPI. В прикладном проекте с включенным параметром cuba.allowQueryFromSelected - необходимо вызывать этот метод либо из назначенных заданий, либо из стандартного планировщика Spring, например:<task:scheduled-tasks scheduler="scheduler"> - <task:scheduled ref="cuba_QueryResultsManager" method="deleteForInactiveSessions" fixed-rate="600000"/> + необходимо вызывать этот метод либо из назначенных заданий, либо из стандартного планировщика Spring, например:<task:scheduled-tasks scheduler="scheduler"> + <task:scheduled ref="cuba_QueryResultsManager" method="deleteForInactiveSessions" fixed-rate="600000"/> </task:scheduled-tasks>
- Поддерживаемые СУБД - Тип используемой СУБД определяется параметром среднего слоя cuba.dbmsType и настройкой источника данных в Tomcat. - - - PostgreSQL - - Поддерживается всеми проектами платформы: CUBA, Workflow, FTS, Charts, CCPayments, RefApp. - Настройка - Параметр среднего слоя: - - Источник данных в context.xml: - - - - - Microsoft SQL Server - - Поддерживается проектами: CUBA, Workflow, FTS, RefApp. - Настройка - Параметр среднего слоя: - - Источник данных в context.xml: - - В настройках MS SQL надо включить возможность логина для пользователя sa и задать для него пароль из context.xml. Это можно сделать из MS SQL Management Studio, в окне Object Explorer. + Работа с СУБД +
+ Выбор и подключение + Тип используемой СУБД определяется свойством приложения + cuba.dbmsType + и настройкой источника данных. Конфигурационный файл для Tomcat, определяющий источник данных, описан в + + Обратите внимание на применимость СУБД в зависимости от используемых базовых проектов платформы: + + HSQLDB - применяется только для запуска интеграционных тестов платформы, не используется в прикладных проектах + + + PostgreSQL - поддерживается всеми базовыми проектами платформы + + + Microsoft SQL Server - поддерживается базовыми проектами cuba, workflow, fts + + + +
+
+ Создание и обновление БД + Проект CUBA-приложения всегда содержит два набора SQL скриптов: + + Скрипты создания БД - предназначены для создания базы данных с нуля. + Скрипты создания располагаются в каталоге /db/init модуля core. Для каждого типа СУБД, поддерживаемой приложением, создается свой набор скриптов и располагается в подкаталоге с именем, соответствующим значению перечисления DbmsType, например /db/init/postgres. Имена скриптов создания должны иметь вид {optional_prefix}create-db.sql. + + + Скрипты обновления БД - предназначены для поэтапного приведения структуры БД к текущему состоянию модели данных. + Скрипты обновления располагаются в каталоге /db/update модуля core. Для каждого типа СУБД, поддерживаемой приложением, создается свой набор скриптов и располагается в подкаталоге с именем, соответствующим значению перечисления DbmsType, например /db/update/postgres. + Скрипты обновления должны иметь имена, которые при сортировке в алфавитном порядке образуют правильную последовательность их выполнения (обычно это хронологическая последовательность их создания). Поэтому рекомендуется задавать имя скрипта обновления в виде {yymmdd}-{description}.sql, где yy - год, mm - месяц, dd - день, description - краткое описание скрипта. Например 121003-addCodeToCategoryAttribute.sql. + Скрипты обновления можно группировать в подкаталоги, главное чтобы путь к скрипту с учетом подкаталога не нарушал хронологической последовательности. Например, можно создавать подкаталоги по номеру года или по году и месяцу. + + + В развернутом приложении скрипты создания и обновления БД располагаются в специальном каталоге скриптов базы данных, задаваемым свойством приложения + cuba.dbDir + . + Скрипты представляют собой текстовые файлы с набором DDL и DML команд, разделенных символом "^". Символ "^" применяется для того, чтобы можно было применять разделитель ";" в составе сложных команд, например при создании функций или триггеров. Встроенный механизм исполнения скриптов разделяет входной файл на команды по разделителю "^" и выполняет каждую команду в отдельной транзакции. Это означает, что при необходимости можно сгруппировать несколько простых операторов (например insert), разделенных точкой с запятой, и обеспечить выполнение их в одной транзакции. +
+ Создание БД + Базу данных можно создать двумя способами: с помощью скрипта сборки Gradle или на старте приложения путем запуска автоматического обновления. + Скрипт сборки build.gradle содержит задачу createDb, которая создает указанную в параметрах задачи БД и выполняет на ней все SQL скрипты создания (базовых проектов и самого приложения). + + Если база данных по указанному в скрипте сборки URL существует, она полностью удаляется и создается заново. + + Чтобы инициализировать БД механизмом автоматического обновления (например в развернутом приложении при отсутствии скрипта сборки), нужно выполнить следующее: + + включить свойство приложения + cuba.automaticDatabaseUpdate + + + + создать пустую базу данных, соответствующую URL, заданному в описании источника данных в + context.xml + + + + запустить веб-сервер, содержащий блок Middleware. На старте приложения БД будет проинициализирована и сразу же готова к работе. + + +
+
+ Обновление БД + Процесс обновления базы данных заключается в выполнении скриптов обновления, присутствующих в проекте или в каталоге скриптов, которые не зарегистрированы как выполненные в таблице SYS_DB_CHANGELOG. Эти скрипты могут быть выполнены как вручную (используя сторонние инструменты), так и следующими встроенными в систему способами: + + Выполнением задачи updateDb скрипта сборки build.gradle. + + + В работающем приложении: + + на старте Middleware при включенном механизме автоматического обновления + + + после старта вызовом метода updateDatabase() JMX-бина + PersistenceManagerMBean + + + + + +
+
+ Механизм автоматического обновления + Механизм автоматического обновления включается свойством приложения + cuba.automaticDatabaseUpdate + . Он активируется на старте блока Middleware до момента полной инициализации приложения, и действует следующим образом: + + Если в БД отсутствует таблица SEC_USER, то считается, что база данных пуста, и запускается полная инициализация с помощью скриптов создания БД. После выполнения инициализирующих скриптов их имена запоминаются в таблице SYS_DB_CHANGELOG. Кроме того, там же сохраняются имена всех доступных скриптов обновления, без их выполнения. + + + Если в БД имеется таблица SEC_USER, но отсутствует таблица SYS_DB_CHANGELOG (это случай, когда в первый раз запускается описываемый механизм на имеющейся рабочей БД), никакие скрипты не запускаются. Вместо этого создается таблица SYS_DB_CHANGELOG и в ней сохраняются имена всех доступных на данный момент скриптов обновления. + + + Если в БД имеются и таблица SEC_USER и таблица SYS_DB_CHANGELOG, производится запуск скриптов обновления, и их имена запоминаются в таблице SYS_DB_CHANGELOG. Причем запускаются только те скрипты, имен которых не было в таблице SYS_DB_CHANGELOG, т.е. не запускавшиеся ранее. +Последовательность запуска скриптов определяется 2-мя факторами: приоритетом базового проекта (см. содержимое каталога скриптов базы данных: 10-cuba, 20-workflow, ...) и именем файла скрипта (с учетом подкаталогов внутри каталога update) в алфавитном порядке. + + +
+
+
+ Проектирование БД +
+ Соответствие типов данных + В таблице приведено соответствие типов данных, отличающихся для разных СУБД. + + + + + + + + Java + PostgreSQL + MS SQL Server + + + + + UUID + uuid + uniqueidentifier + + + Date + timestamp + datetime + + + Boolean + boolean + tinyint + + + byte[] + bytea + image + + + + +
+
+ Особенности MS SQL Server + Microsoft SQL Server использует кластерные индексы для таблиц. + По умолчанию кластерный индекс создается по первичному ключу таблицы, однако используемые в CUBA-приложении ключи типа UUID плохо подходят для кластерного индекса. Поэтому необходимо для каждой таблицы правильно выбрать и создать кластерный индекс. Поле для кластерного индекса должно быть небольшим и монотонно возрастающим, поэтому ориентировочные правила следующие: + + Для большинства таблиц подходит поле CREATE_TS. При этом записи будут физически располагаться в порядке их создания. + + + Для композитных сущностей, если чтение превалирует над записью, имеет смысл использовать ссылку на владельца. При этом записи будут сгруппированы по владельцам, и их извлечение вместе с владельцем будет происходить быстрее. + + + Для небольших (< 100 записей) редко изменяемых таблиц тип кластерного индекса не важен, можно оставить ID. + + + Для таблиц сущностей, унаследованных по стратегии JOINED, в которых нет поля CREATE_TS, нужно создать его искусственно с параметром default current_tmestamp. + + + Пример:create table SALES_CUSTOMER ( + ID uniqueidentifier not null, + CREATE_TS datetime, + ... + primary key nonclustered (ID) +)^ -Instance − ваш SQL Server. - - Включить сетевую аутентификацию: - - Разрешить доступ по TCP/IP можно из Sql Server Configuration Manager - - - - +create clustered index IDX_SALES_CUSTOMER_CREATE_TS on SALES_CUSTOMER (CREATE_TS)^ + Пример композитной сущности: create table SALES_ITEM ( + ID uniqueidentifier not null, + CREATE_TS datetime, + ... + ORDER_ID uniqueidentifier, + ... + primary key nonclustered (ID), + constraint FK_SALES_ITEM_ORDER foreign key (ORDER_ID) references SALES_ORDER(ID) +)^ + +create clustered index IDX_SALES_ITEM_ORDER on SALES_ITEM (ORDER_ID)^ + Пример унаследованной сущности: create table SALES_DOC ( + CARD_ID uniqueidentifier, + CREATE_TS datetime default current_timestamp, + NUMBER varchar(50), + primary key nonclustered (CARD_ID), + constraint FK_SALES_DOC_CARD foreign key (CARD_ID) references WF_CARD (ID) +)^ + +create clustered index IDX_SALES_DOC_CREATE_TS on SALES_DOC (CREATE_TS)^ + +create index IDX_SALES_DOC_CARD on SALES_DOC (CARD_ID)^ +
+
@@ -8191,18 +8367,14 @@ taskHandler.execute();
Механизмы платформы -
- Обновление базы данных +
+ Выполнение задач по расписанию TODO
Отсылка email TODO
-
- Выполнение задач по расписанию - TODO -
Динамические атрибуты TODO @@ -8211,7 +8383,7 @@ taskHandler.execute(); Пессимистичная блокировка TODO
-
+
Статистика сущностей TODO
diff --git a/doc/content/manual/ru/manual.xml b/doc/content/manual/ru/manual.xml index 353bcdc5b9..e08f2d6e74 100644 --- a/doc/content/manual/ru/manual.xml +++ b/doc/content/manual/ru/manual.xml @@ -111,7 +111,34 @@ Описание конфигурационных файлов
context.xml - TODO + Файл context.xml является дескриптором развертывания приложения на сервере Apache Tomcat. В развернутом приложении этот файл располагается в подкаталоге META-INF каталога веб-приложения или WAR-файла, например tomcat/webapps/app-core/META-INF/context.xml. В проекте файлы данного типа находятся в каталогах /web/META-INF модулей core, web, portal. + Основное предназначение файла для блока Middleware - определить источник данных и поместить его в JNDI под именем, заданным свойством приложения + cuba.dataSourceJndiName + . + Пример определения источника данных для PostgreSQL:<Resource + name="jdbc/CubaDS" + type="javax.sql.DataSource" + maxActive="20" + maxIdle="2" + maxWait="5000" + driverClassName="org.postgresql.Driver" + username="cuba" + password="cuba" + url="jdbc:postgresql://localhost/sales"/> + Пример определения источника данных для Microsoft SQL Server:<Resource + name="jdbc/CubaDS" + type="javax.sql.DataSource" + maxActive="20" + maxIdle="2" + maxWait="5000" + driverClassName="net.sourceforge.jtds.jdbc.Driver" + username="sa" + password="saPass1" + url="jdbc:jtds:sqlserver://localhost/sales"/> + Для всех блоков, являющихся веб-приложениями, данный файл может содержать код, отключающий сериализацию HTTP-сессий:<Manager className="org.apache.catalina.session.PersistentManager" debug="0" distributable="false" + saveOnRestart="false"> + <Store className="org.apache.catalina.session.FileStore"/> +</Manager>
datatypes.xml @@ -123,6 +150,9 @@
persistence.xml + В зависимости от выбранного значения свойства приложения + cuba.dbmsType + автоматически формируются параметры ORM, которые на старте приложения записываются в итоговый файл persistence.xml в рабочем каталоге приложения. TODO
@@ -241,6 +271,15 @@ Используется в блоках Web Client и Middleware. + + cuba.automaticDatabaseUpdate + + Включает режим автоматического обновления базы данных на старте приложения. + Значение по умолчанию: false + Интерфейс: ServerConfig + Используется в блоке Middleware. + + cuba.availableLocales @@ -254,6 +293,31 @@ Используется во всех стандартных блоках. + + cuba.dataSourceJndiName + + Задает имя источника данных в JNDI. + Значение по умолчанию: java:comp/env/jdbc/CubaDS + Используется в блоке Middleware. + + + + cuba.dbDir + + Конфигурационный параметр, задающий расположение каталога скриптов базы данных. + Значение по умолчанию: ${catalina.home}/webapps/${cuba.webContextName}/WEB-INF/db, что означает расположение в подкаталоге WEB-INF/db каталога текущего веб-приложения Tomcat. + Интерфейс: ServerConfig + Используется в блоке Middleware. + + + + cuba.dbmsType + + Задает тип используемой базы данных. Возможные значения соответствуют значениям перечисления DbmsType без учета регистра: hsql, postgres, mssql. + Значение по умолчанию: hsql + Используется в блоке Middleware. + + cuba.defaultQueryTimeoutSec diff --git a/doc/content/manual/ru/source/context_mssql.xml b/doc/content/manual/ru/source/context_mssql.xml deleted file mode 100644 index 297f59bb04..0000000000 --- a/doc/content/manual/ru/source/context_mssql.xml +++ /dev/null @@ -1,10 +0,0 @@ - \ No newline at end of file diff --git a/doc/content/manual/ru/source/context_postgres.xml b/doc/content/manual/ru/source/context_postgres.xml deleted file mode 100644 index 7378152893..0000000000 --- a/doc/content/manual/ru/source/context_postgres.xml +++ /dev/null @@ -1,10 +0,0 @@ - \ No newline at end of file diff --git a/doc/content/manual/ru/source/cuba_dbmstype_mssql.txt b/doc/content/manual/ru/source/cuba_dbmstype_mssql.txt deleted file mode 100644 index 9e3177af7e..0000000000 --- a/doc/content/manual/ru/source/cuba_dbmstype_mssql.txt +++ /dev/null @@ -1 +0,0 @@ -cuba.dbmsType=mssql \ No newline at end of file diff --git a/doc/content/manual/ru/source/cuba_dbmstype_postgres.txt b/doc/content/manual/ru/source/cuba_dbmstype_postgres.txt deleted file mode 100644 index 714dd4ce9c..0000000000 --- a/doc/content/manual/ru/source/cuba_dbmstype_postgres.txt +++ /dev/null @@ -1 +0,0 @@ -cuba.dbmsType=postgres \ No newline at end of file diff --git a/doc/content/manual/ru/source/instance1_mssql.txt b/doc/content/manual/ru/source/instance1_mssql.txt deleted file mode 100644 index 9684ccf550..0000000000 --- a/doc/content/manual/ru/source/instance1_mssql.txt +++ /dev/null @@ -1 +0,0 @@ -Instance -> Properties -> Security (Server authentification: SQL Server and Windows Authentification mode) \ No newline at end of file diff --git a/doc/content/manual/ru/source/instance2_mssql.txt b/doc/content/manual/ru/source/instance2_mssql.txt deleted file mode 100644 index 41985632b8..0000000000 --- a/doc/content/manual/ru/source/instance2_mssql.txt +++ /dev/null @@ -1,3 +0,0 @@ -Sql Server Configuration Manager -> SQL Server Network Configuration -> Protocols for SQLEXPRESS -> TCP/IP -> Properties -General -> Enabled : Yes -IP Addresses -> IP All -> TCP Port : 1433 \ No newline at end of file diff --git a/doc/content/manual/ru/source/instance_mssql.txt b/doc/content/manual/ru/source/instance_mssql.txt deleted file mode 100644 index ca09af5e75..0000000000 --- a/doc/content/manual/ru/source/instance_mssql.txt +++ /dev/null @@ -1,3 +0,0 @@ -Instance -> Security -> Logins -> sa -> Properties -> -General (Задать пароль) -Status (Login: Enabled) \ No newline at end of file