# database

Добавляет возможность работы с базами данных через JDBC подключение. На текущий момент поддерживаются следующие СУБД:

- Firebird

Данный модуль предназначен для использования другими модулями:

- arcsvr
- wessvr
- script

Данный модуль требует включения в задачу.

Внимание!

Модуль `database` должен работать в одной задаче с использующими его модулями.

    plugin.database:
      enable: on

      module.db:
        enable:      on
        type:        firebird
        dbname:      /home/denis/asutp/promauto/db/fb25/SHPMSC/SHPMSC.FDB
        recon_s:     5
        timeout_s:   10

        host:     localhost
        port:     3050
        user:     sysdba
        password: masterkey

        properties:
          encoding: WIN1251

        startups:
          - dbscr/extra.dbscr.yml:
              schema: mscz4
              table: tbl

          - dbscr/extra.dbscr.yml

        tabletags:
          - table:       modules
            field.id:    idm
            field.name:  name
            field.value: idprod
            access:      rw

          - table:       main
            field.id:    idm
            field.value: wes
            access:      ro

type | - | Тип сервера СУБД. Возможные значения: 'firebird'
dbname | - | Имя базы данный
recon_s | `10` | Интервал переподключения при потере связи
timeout_s | `10` | Тайм-аут подключения и ответа сервера
host | `localhost` | адрес сервера
port |  | порт сервера, значение по умолчанию зависит от типа сервера:
`3050` | firebird
user | - | Имя пользователя на сервере
password | - | Пароль пользователя
properties | - | Дополнительные параметры подключения, специфичные для СУБД
startups | - | Список файлов с dbscr-скриптами, которые будут выполняться при подключении. Дополнительно можно произвольно указать любые параметры, которые будут переданы скрипту.

# tabletags

tabletags - это список отображений значений в базе данных в теги модуля. Одно отображение создается для одного поля одной таблицы. При этом при подключении к базе данных будет создано n тегов для одного отображения, где n - количество записей таблицы с учетом указанного фильтра where. Количество отображений в списке может быть любым.

table | - | Имя таблицы
field.id | id | Имя поля первичного ключа. Возможно использовать только простые ключи, состоящие из одного поля.
field.name | field.id | Имя поля, значения которого будут использоваться для формирования имени тегов. Формат имени тега следующий:
    <table>.<field.value>.<значение поля field.name>
field.value | - | Имя поля чтения/записи значения. Тип поля может быть integer, smallint, bigint, float, double precision, char, varchar
access | - | Ограничение доступа к тегу. Возможные значения rw/ro/wo.
where | - | Условие, добавляемое в select-запрос.

# dbscr

Dbscr - сокращение от «database script», далее по тексту в разделе «скрипт». Скрипт предназначен для работы с содержимым баз данных без написания программного кода. Скрипты содержаться в yaml-файлах, которые могут располагаться:

1. непосредственно на диске
2. в jar-файле плагинов, модули которых используют модуль database

В одном файле допустимо иметь более одного скрипта. Для идентификации начала скрипта имя скрипта содержит префикс `dbscr.`. Пример файла, содержащего два скрипта:

    dbscr.first:

         - if not has_table({schema}, person)
         - do create sequence {schema}SQ_PERSON_ID
         - do create table {schema}PERSON (
                  ID integer not null primary key,
                  ISGROUP smallint default 0,
                  NAME varchar(128),
                  DELETED smallint default 0
                )
         - do create trigger {schema}PERSON_BI active before insert position 0 on {schema}PERSON
                as
                begin
                  if( NEW.ID is NULL) then
                    NEW.ID = next value for {schema}SQ_PERSON_ID;
                end

    dbscr.second:
    #     - if not has_schema(msc)

         - if not has_domain({schema}, dm_myint1)

         - do create domain {schema}dm_myint1 as integer not null

         - if not has_table({schema}, myreader)

         - |
           do create table {schema}myreader (
                 id integer,
                 name varchar(30)
               )
         - |
           do create table {schema}myreader_types (
                 id integer,
                 typename varchar(30)
               )

         - if not has_column({schema}, myreader, info)

         - do alter table {schema}myreader
                add info varchar(30) default 'n/a'

Скрипт - это список действий, которые выполняются в описанной последовательности. Действия подразделяются на условия `if` и команды `do`. Если при выполнении `if` результат положительный, то все последющие `do` будут выполнятся, пока не будет достигнут следующий `if`.

## if

Формат записи:

      - if [not] function([args])

`not` - инверсия результата

`function` - функция проверки. Список доступных функций с параметрами:

- has_schema(<schema>)
- has_domain(<schema>, <domain>)
- has_table(<schema>, <table>)
- has_column(<schema>, <table>, <column>)
- has_constraint(<schema>, <table>, <constraint>)
- has_index(<schema>, <index>)
- has_trigger(<schema>, <trigger>)
- has_procedure(<schema>, <procedure>)
- has_record(<sql>)

## do

Формат записи:

      - do sql

`sql` - один sql-запрос, не возвращающий результат

## параметры скрипта

Скрипту можно передавать параметры, которые в скрипте заключаются в фигурные скобки. Значения параметров задаются в секции `startups` конфигурации модуля, либо в программном коде другого модуля, использующего модуль database.

При загрузке скрипта выполняется поиск и замена всех параметров, включая фигурные скобки, на их значения. Если значение не указано, то используется значение `пустая строка`.

Исключением является параметр `{schema}`, который подставляется вместе с разделителем. Например, `{schema}{table}` со значениями `myschema` и `mytable` для firebird будет преобразовано в `myschema_mytable`, или для postgresql в `myschema.mytable`.

# Команды

Далее `m` обозначает название модуля.

## sql

    m:sql expression

Выполняет произвольный sql-запрос, например:

    db:sql select * from modules

## exec

    m:exec scrfile [prm=val ...]

Выполняет все dbscr-скрипты, содержащиеся в файле `scrfile`, с заданными параметрами. Например:

    db:exec wessvr.debug.yml schema=s1 table=tbl1

# Использование firebird

Для работы с firebird необходимо использовать версию 3.0 и выше. С более ранними версиями тестирование не проводилось.

После установки firebird сервера нужно добавить параметр в файл `firebird.conf`:

    WireCrypt = Enabled

Если при запуске будут ошибки типа:

    PM org.firebirdsql.logging.JulLogger warn
    WARNING: Wire encryption established, but some plugins failed; see other loglines for details

то отключить шифрование совсем:

    WireCrypt = Disabled