====== database ======

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

Данный модуль предназначен для использования другими модулями:
  * [[doc:jroboplc:modules:arcsvr]]
  * [[doc:jroboplc:modules:wessvr]]
  * [[doc:jroboplc:modules:tagscript]]
  

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

<note important>**Внимание!** 

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


<code yaml>
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



</code>


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

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

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

<code yaml>
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'
</code>

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

===== if =====
Формат записи:
<code>
  - if [not] function([args])
</code>

''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 =====
Формат записи:
<code>
  - do sql
</code>

''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