lightdiver / satori Goto Github PK

Introduction
=============
Минималистическая среда интеграции встраиваемого кода для построения
приложений на основании простых соглашений (Comp Actn Form)

Requirements
=============
1. [musthave] 
   Git - распределённая система управления версиями файлов 
   http://ru.wikipedia.org/?oldid=22211681 (инфо)
   http://code.google.com/p/msysgit/ (инсталл)  

2.
   
Getting Started
================
1. Установить переменные проекта.
   Для этого скопировать и сохранить service\cfg\setvars_scripts.git как
   service\cfg\setvars_scripts.cmd (занесен в .gitignore).
   Прописать свои значения. 

2. Banzai!

Структура проекта
==================
service - создание схем, часто выполняемые команды Git
       /cfg - файлы конфигурации
source - файлы исходных текстов проекта
documentation - файлы документирования кода 

Генерировать SSH ключ рекомендуется для passphrase = '', 
чтобы не вводить его каждый раз при общении с сервером Git

Надо помнить, что последние версии Git клонируют файлы с точкой как скрытые.
Такие файлы могут не быть включенными программой создания интсталляторов в дистрибутив.
Рекомендуется не именовать файлы названиями, содержащими лидирующую точку.

GIT
===================
Именование веток:
master         - основная (релизная) ветка
PRLS_NNN.NN    - основная ветка разработки (по умолчанию все работы идут в ней) [ где NNN.NN версия разрабатываемого релиза/патча]
                 настраивается в cfg/setvars_scripts.cmd. Параметры с этого файла используются другими cmd-файлами. 
<base>_dev_all - ветка разработки (при необходимости) 
  например, oracle_dev_all
=================================================!!!====================================
******Внимание! Нужно всегда понимать в какой, в данный момент, ветке ведутся работы!***
=================================================!!!====================================

Разработка БД
===================
* Всі обмеження мають місце доти доки це не заважає продуктивності роботи БД (777999)
--- Деякі нюанси пов'язані з JDBC
>>> Postgres більш суворий до змінних в частині автоматичного приведення типів. 
Тому якщо змінна в Java String str_integer, а в Postgres функція має, наприклад, вхідну змінну numeric(в Oracle number), то
CallableStatement.setString(1, str_integer); призвиде до SQLException, але вже відпрацює, якщо зробити так: cs.setInt(1, Integer.parseInt(str_integer));
З Oracle проблем в цьому не виникне.
JDBC Postgres ще чутлівіше до параметрів які вертаються з бази. 
Так, наприклад, якщо в Postgres Foo(OUT NUMERIC), то в Java потрібно його реєструвати як 
CallableStatement.registerOutParameter(1, Types.NUMERIC);
і якщо очікується що там int, то потрібно буде костомізувати для подальшої роботи bigDecimal.intValue()

Postgres   Oracle
---------------------------------
NUMERIC    NUMBER                 (INTEGER не використовувати(див. 777999))  

===================
1. Регистр
  ВНИМАНИЕ! ВСЕГДА И ВЕЗДЕ ДЛЯ SQL(DDL/DML) ПРИМЕНЯЕТСЯ ВЕРХНИЙ РЕГИСТР! *
2. Параметры базы данных
  TODO: описать параметры подключения, кодовую странцу и пр..
3. Именование объектов базы данных
  ! Внимание длина имен не должна превышать 32 символов
  Database Objects             Naming Pattern
  --------------------------   -----------------------------
  Sequences                    -  [NAME]_SEQ
  Triggers                     -  [TABLE_NAME]$[A[IUD] | B[IUD]] , где (A)After;B(Before);(I)Insert;(U)Update;(D)Delete
  Roles                        -  ROL_[NAME]
  Users                        -  [NAME] 

  3.а Именование переменных 
      Входящие переменные  i_[NAME]
      Исходящие переменные o_[NAME]  
      Переменные в ХП      v_[NAME]
      При объявлении переменных в ХП тип выставлять с помощью конструкции %TYPE 
      При объявлении переменных в функциях тип выставлять БЕЗ конструкции %TYPE в Postgres (их автоматом преобразует)
      

3. Порядок создания и выполнения скриптов БД

  File Name                    Meaning
  --------------------------   -----------------------------
  TODO

4. ОСОБЕННОСТИ
  - имена для таблиц выбираются из множества слов английского языка (кроме слов
    аборигенов и если нет аналогов – тогда транслитерация английскими буквами)

  - значения для первичных ключей по умолчанию генерируются в триггере
    перед вставкой следующим кодом:

   :NEW.ID := NVL(:NEW.ID, SEQ_PRIMARY.NEXTVAL); 		(Oracle)
  			  NEXTVAL('SEQ_PRIMARY')		 (Postgres)

  - использование NULL для значения полей не рекомендуется

  - имена для полей выбираются из множества слов английского языка (кроме слов
    аборигенов и если нет аналогов – тогда транслитерация английскими буквами)

  - порядок определения полей в таблице должен иметь логическое основание,
    а также строгую структуру следующего вида:
      CREATE TABLE DEMO_TABLE (
      <первичный ключ>,
      <список внешних ключей по логике связей таблицы>,
      <список значимых полей таблицы, сгруппированных в логическом порядке>
      <список вычисляемых в триггерах полей в логическом порядке>
      );

  - ограничения на таблицу определяются отдельно от метаданных таблицы через
    конструкцию ALTER TABLE.

  - при составлении запросов каждая таблица должна иметь алиас,
    алиас для таблиц всегда один, кроме исключительного случая,
    когда  таблица участвует в запросе дважды - в этом случае к ним
    добавляется цифра (например TN1 и TN2)

  - все соединения формулируются только через конструкцию JOIN, в порядке
    увелечения количества данных в соединяемых таблицах
  
  - каждый объект PL/SQL должен содержать заголовок в котором должно быть(см. документацию по plsqldoc):
        краткое описание объекта,
        входные параметры
        выходящие параметры
        ошибки гененрируемые объектом
        автор
        дата создание

5. Для облегчения переноса функций с одной БД в другую (Oracle <=> Postgres)
   - использовать CASE вместо DECODE
   - 
6. Для минимизации зависимости кода Java от подключаемой БД
   - Запрещено создавать функции, если есть возвращаемые параметры OUT - это процедура. Procedure(IN i_var1, OUT i_var2, OUT i_var3) (относиться к Oracle). 

7. ОГРАНИЧЕНИЯ
  З А П Р Е Щ Е Н Ы к использованию

  - имена объектов, требующие обрамления в двойные кавычки
  - вычисляемые поля (если надо, рассчитываем значения в триггерах или процедурах/функциях, помещая
    их в обычные физические поля)
  - смешение явных и неявных соединений в одном запросе
  - сложные мысли и кривые руки