Commit 6aa78c62 authored by Bertrand Gauthier's avatar Bertrand Gauthier
Browse files

Mise à jour de la doc de création d'une bdd pour SyGAL

parent 0a9e7134
Loading
Loading
Loading
Loading
+47 −27
Changes for bin/database/README.md: 47 added lines, 27 removed lines.
Original line number Diff line number Diff line
# Base de données : génération de la doc d'installation
Génération de la doc et des scripts SQL de création d'une bdd pour SyGAL
========================================================================

Ce README s'adresse au développeur souhaitant générer les scripts de création d'une base de données PostgreSQL
toute neuve. 
Ce README s'adresse au développeur souhaitant générer la doc et les scripts de création d'une base de données 
PostgreSQL pour ESUP-SyGAL. 

Cette génération se fait *à partir d'une base de données PostgreSQL modèle existante* à laquelle on se connecte.

Génération des fichiers
-----------------------

## Génération des fichiers
### Principe

Le script shell [`./build_db_install_files.sh`](build_db_install_files.sh) génère dans un répertoire de votre choix :

  - un répertoire [`sql/`](sql) contenant un ensemble de scripts SQL ordonnés :
    - [01_create_db_user.sql`](sql/01_create_db_user.sql)
    - [02_create_schema.sql`](sql/02_create_schema.sql)
    - [03_insert_bootstrap_data.sql`](sql/03_insert_bootstrap_data.sql)
    - [04_insert_data.sql`](sql/04_insert_data.sql)
    - [05_prepare_data.sql`](sql/05_prepare_data.sql)
    - [06_create_constraints.sql`](sql/06_create_constraints.sql)
    - [07_create_comue.sql.dist`](sql/07_create_comue.sql.dist)
    - [08_init.sql.dist`](sql/08_init.sql.dist)
    - [09_create_fixture.sql.dist`](sql/09_create_fixture.sql.dist)
  - un répertoire `sql/` contenant un ensemble de scripts SQL ordonnés :
    - `01_create_db_user.sql`
    - `02_create_schema.sql`
    - `03_insert_bootstrap_data.sql`
    - `04_insert_data.sql`
    - `05_prepare_data.sql`
    - `06_create_constraints.sql`
    - `07_create_comue.sql`
    - `08_init.sql`
    - `09_create_fixture.sql`
      
  - un script bash et un fichier de config pour "préparer" les scripts SQL ayant l'extension `.sql.dist` :    
    - [`build_db_files.conf.dist`](build_db_files.conf.dist)
    - [`build_db_files.sh`](build_db_files.sh)
    - `build_db_files.conf.dist`
    - `build_db_files.sh`
    
  - un fichier expliquant comment procéder pour créer une base de données à l'aide de tous ces scripts :
    - [`README.md`](README.md)
    - `README.md`

Ce script [`./build_db_install_files.sh`](build_db_install_files.sh) :
Ce script `./build_db_install_files.sh` :
  - se base sur les fichers `.template.*` situés dans le répertoire [`src/`](src) ;
  - charge le fichier de config [`./conf/build_db_install_files.conf`](confuild_db_install_files.conf)
    dans lequel sont spécifiés les paramètres de génération.

Le script prend en argument le chemin d'un fichier de config et le chemin du répertoire où doivent être générés 
les fichiers.
Le script prend en argument :
  - le chemin d'un fichier de config ;
  - le chemin du répertoire où doivent être générés les fichiers.

La façon de procéder pour créer une base de données à partir des fichiers générés est expliquée dans le fichier
`README.md` (lui aussi généré).

### Exemple

Voici un exemple pour générer les fichiers de création d'une base de données...
  - dans le répertoire destination `/tmp/build`,
  - à partir de la base modèle `sygal` (spécifiée par les variables d'env `PGDATABASE`, etc.),
  - qui permettront de créer une base et un utilisateur spécifiés dans le fichier de config 
  - qui permettront de créer la base et l'utilisateur spécifiés dans le fichier de config 
    `./build_db_install_files.conf ` :

```bash
PGHOST='localhost' PGPORT=54322 PGDATABASE='sygal' PGUSER='ad_sygal' PGPASSWORD='xxxxxx' \
./build_db_install_files.sh -c ./conf/build_db_install_files.conf -o /tmp/build
PGHOST='localhost' \
PGPORT=54322 \
PGDATABASE='sygal' \
PGUSER='ad_sygal' \
PGPASSWORD='xxxxxx' \
./build_db_install_files.sh \
-c ./conf/build_db_install_files.conf \
-o /tmp/build
```

La façon de procéder pour créer une base de données à partir des fichiers générés est expliquée dans le fichier 
`README.md` (lui aussi généré).

Mise à jour de la documentation à partir des fichiers générés
-------------------------------------------------------------

Diff avec la doc actuelle, exemple :

## Mise à jour éventuelle de la doc
```bash
meld /tmp/build/ ../../doc/database/
```

Copier les fichiers générés vers le répertoire contenant la documentation :
Copier les fichiers générés vers le répertoire contenant la documentation, exemple :

```bash
cp -r /tmp/build/* ../../doc/database/
+5 −2
Changes for bin/database/build_db_install_files.sh: 5 added lines, 2 removed lines.
Original line number Diff line number Diff line
@@ -135,8 +135,9 @@ mkdir -p $OUTPUT_DIR/sql
#
# db and user
#
OUTPUT_FILE=$OUTPUT_DIR/sql/01_$NAME_CREATE_DB_USER.sql
OUTPUT_FILE=$OUTPUT_DIR/sql/admin/01_$NAME_CREATE_DB_USER.sql
SRC_SCRIPT=$THIS_DIR/src/sql/$NAME_CREATE_DB_USER.template.sql
mkdir $OUTPUT_DIR/sql/admin
cp $SRC_SCRIPT $OUTPUT_FILE
injectConfParamsInScript $OUTPUT_FILE
echo "> $OUTPUT_FILE"
@@ -145,7 +146,7 @@ echo "> $OUTPUT_FILE"
# schema objects
#
OUTPUT_FILE=$OUTPUT_DIR/sql/02_$NAME_CREATE_SCHEMA.sql
pg_dump --section=pre-data --schema-only --exclude-table 'MV_INDICATEUR*' >$OUTPUT_FILE
pg_dump --section=pre-data --schema-only --exclude-table 'MV_INDICATEUR*' --exclude-table '*_SAV' >$OUTPUT_FILE
replacePgDatabaseAndUserInScript $OUTPUT_FILE
#prepareScript $OUTPUT_FILE
echo "> $OUTPUT_FILE"
@@ -206,3 +207,5 @@ OUTPUT_FILE=$OUTPUT_DIR/sql/09_$NAME_CREATE_FIXTURE.sql.dist
SRC_SCRIPT=$THIS_DIR/src/sql/$NAME_CREATE_FIXTURE.template.sql
cp $SRC_SCRIPT $OUTPUT_FILE
echo "> $OUTPUT_FILE"

echo 'Terminé.'
+2 −2
Changes for bin/database/conf/build_db_install_files.conf: 2 added lines, 2 removed lines.
Original line number Diff line number Diff line
@@ -4,5 +4,5 @@
#===========================================#

#========= Base de données à créer =========#
DBNAME='sygal'                              # Nom de la database que les scripts créeront
DBUSER='ad_sygal'                           # Nom du user que les scripts créeront
DBNAME=':dbname' # Nom de la database que les scripts créeront
DBUSER=':dbuser' # Nom du user que les scripts créeront
+55 −35
Changes for bin/database/src/README.template.md: 55 added lines, 35 removed lines.
Original line number Diff line number Diff line
@@ -4,19 +4,19 @@ Création d'une base de données pour ESUP-SyGAL
Les fichiers fournis permettant de créer une base de données pour ESUP-SyGAL sont :

- d'une part, le fichier de config et le script bash de construction :
    - [`build_db_files.conf.dist`](build_db_files.conf.dist) (à adpater puis à renommer en `.conf`)
    - [`build_db_files.conf.dist`](build_db_files.conf.dist) (à adpater et à renommer en `.conf`)
    - [`build_db_files.sh`](build_db_files.sh)
    
- d'autre part, les scripts SQL situés dans le répertoire [`sql/`](sql) :
    - [`01_create_db_user.sql`](sql/01_create_db_user.sql)
    - [`admin/01_create_db_user.sql`](sql/admin/01_create_db_user.sql)
    - [`02_create_schema.sql`](sql/02_create_schema.sql)
    - [`03_insert_bootstrap_data.sql`](sql/03_insert_bootstrap_data.sql)
    - [`04_insert_data.sql`](sql/04_insert_data.sql)
    - [`05_prepare_data.sql`](sql/05_prepare_data.sql)
    - [`06_create_constraints.sql`](sql/06_create_constraints.sql)
    - [`07_create_comue.sql.dist`](sql/07_create_comue.sql.dist) (à "préparer" avec le script) 
    - [`08_init.sql.dist`](sql/08_init.sql.dist) (idem)
    - [`09_create_fixture.sql.dist`](sql/09_create_fixture.sql.dist) (idem)
    - [`07_create_comue.sql.dist`](sql/07_create_comue.sql.dist)
    - [`08_init.sql.dist`](sql/08_init.sql.dist)
    - [`09_create_fixture.sql.dist`](sql/09_create_fixture.sql.dist)
    

## Case départ
@@ -55,55 +55,64 @@ Une fois le script bash exécuté, vous devriez vous retrouver avec 3 scripts SQ
À présent, tout est prêt pour lancer la création de la base de données.


## Création de la base de données `{DBNAME}` et de l'utilisateur `{DBUSER}`
## Adresse du serveur de base de données

- Lancer le script [`01_create_db_user.sql`](sql/01_create_db_user.sql) *en étant connecté en tant que 
  super-utilisateur*, exemple :
- Adaptez et exportez les 2 variables d'environnement suivantes :

```bash
ON_ERROR_STOP=1 \
export \
PGHOST=localhost \
PGPORT=5432 \
PGDATABASE=postgres \
PGUSER=postgres \
PGPASSWORD=admin \
psql -f sql/01_create_db_user.sql
PGPORT=5432
```

Ce 1er script SQL crée la base de données `{DBNAME}` et l'utilisateur `{DBUSER}`. 

**Attention, l'utilisateur est créé avec un mot de passe par défaut** donc vous devez le modifier en faisant un 
truc du genre :
## Nom de la base de données SyGAL à créer, de l'utilisateur et de son mot de passe

- Adaptez et exportez les 3 variables d'environnement suivantes :

```bash
PGHOST=localhost \
PGPORT=5432 \
PGDATABASE=postgres \
PGUSER=postgres \
PGPASSWORD=admin \
psql -c "alter user {DBUSER} with encrypted password 'VRAI_MOT_DE_PASSE'"
export \
SYGAL_DB='sygal' \
SYGAL_USER='ad_sygal' \
SYGAL_PASSWORD='xxxxxxxxx'
```


## Création des objets et insertion des données de fonctionnement
## Création de la base de données et de l'utilisateur

*Les scripts suivants doivent être lancés en étant connecté à la base `{DBNAME}` avec le user `{DBUSER}`
créés à l'étape précédente (et non plus avec l'utilisateur `postgres`).*
- Dans les lignes de commande suivantes, renseignez correctement les variables d'environnement `PG*` permettant 
  de se connecter au serveur Postgres en tant que super-utilisateur puis lancez-les :

Pour cela, exportez les variables d'environnement PostgreSQL comme suit :
```bash
export \
ON_ERROR_STOP=1 \
PGHOST=localhost \
PGPORT=5432 \
PGDATABASE={DBNAME} \
PGUSER={DBUSER} \
PGPASSWORD=VRAI_MOT_DE_PASSE
PGDATABASE=postgres \
PGUSER=postgres \
PGPASSWORD=admin

psql \
  -v "dbname=${SYGAL_DB}" \
  -v "dbuser=${SYGAL_USER}" \
  -v "dbpassword='${SYGAL_PASSWORD}'" \
  -f sql/admin/01_create_db_user.sql
```

Lancez ensuite *dans l'ordre* chacun des scripts suivants :

## Création des objets et insertion des données de fonctionnement

*Les scripts suivants sont lancés en étant connecté à la base SyGAL avec l'utilisateur SyGAL
créés à l'étape précédente (et non plus avec le super-utilisateur).*

- Lancez les lignes de commande suivantes :

```bash
psql -f sql/02_create_schema.sql && \
export \
ON_ERROR_STOP=1 \
PGDATABASE=${SYGAL_DB} \
PGUSER=${SYGAL_USER} \
PGPASSWORD=${SYGAL_PASSWORD}

psql -v "dbuser=${SYGAL_USER}" -f sql/02_create_schema.sql && \
psql -f sql/03_insert_bootstrap_data.sql && \
psql -f sql/04_insert_data.sql && \
psql -f sql/05_prepare_data.sql && \
@@ -113,8 +122,19 @@ psql -f sql/08_init.sql && \
psql -f sql/09_create_fixture.sql
```

Par précaution, effacez éventuellement les variables d'environnement PostgreSQL :
Par précaution, effacez éventuellement les variables d'environnement exportées :

```bash
unset ON_ERROR_STOP PGHOST PGPORT PGDATABASE PGUSER PGPASSWORD # précaution
```

## Si besoin

- Suppression de la base de données !!

```bash
PGDATABASE=postgres \
PGUSER=postgres \
PGPASSWORD=admin \
psql -c "drop database ${SYGAL_DB}"
```
+3 −3
Changes for bin/database/src/sql/create_db_user.template.sql: 3 added lines, 3 removed lines.
Original line number Diff line number Diff line
@@ -3,8 +3,8 @@
--

-- Databases
create database {DBNAME} with ENCODING = 'UTF-8';
create database :dbname with ENCODING = 'UTF-8';
-- Users
create user {DBUSER} with encrypted password 'MOT_DE_PASSE_PAR_DEFAUT' NOSUPERUSER NOCREATEDB;
create user :dbuser with encrypted password :dbpassword NOSUPERUSER NOCREATEDB;
-- Grants
grant all privileges on database {DBNAME} to {DBUSER};
grant all privileges on database :dbname to :dbuser;
Loading