doc (718927de) · Commits · lib / unicaen / BddAdmin

doc/architecture.md

0 → 100644

+212 −0

Original line number	Diff line number	Diff line
		# Architecture

		## SGBDs concernés

		BddAdmin est actuellement capable de gérer deux SGBD : Oracle & POstgresql.
		Un driver Mysql a été débuté, mais il ne permet que de requêter sans gérer de DDL.

		Chaque SGBD a sont propre driver.
		Le répertoire des drivers est [src/Driver](../src/Driver).

		En configuration, le nom du répertoire du driver sera utilisé pour spécifier quel driver utiliser :

		* Oracle
		* Postgresql
		* Mysql

		Tous les drivers implémentent l'interface [DriverInterface](../src/Driver/DriverInterface.php).

		Les drivers ne peuvent pas être appelés directement. Ils seront utilisés par [Bdd](../src/Bdd.php) pour se connecter &
		faire des requêtes.

		## Types d'objets gérés

		Les types d'objets suivant sont gérés par BddAdmin :

		\| Constante \| Valeur \| Description \|
		\|-----------------------------------------------\|------------------------\|-------------------------------------\|
		\| `Unicaen\BddAdmin\Ddl\Ddl:TABLE` \| `'table'` \| Tables \|
		\| `Unicaen\BddAdmin\Ddl\Ddl:VIEW` \| `'view'` \| Vues \|
		\| `Unicaen\BddAdmin\Ddl\Ddl:SEQUENCE` \| `'sequence'` \| Séquences \|
		\| `Unicaen\BddAdmin\Ddl\Ddl:MATERIALIZED_VIEW` \| `'materialized-view'` \| Vues matérialisées \|
		\| `Unicaen\BddAdmin\Ddl\Ddl:PRIMARY_CONSTRAINT` \| `'primary-constraint'` \| Contraintes de clé primaire \|
		\| `Unicaen\BddAdmin\Ddl\Ddl:FUNCTION` \| `'function'` \| Fonctions \|
		\| `Unicaen\BddAdmin\Ddl\Ddl:PROCEDURE` \| `'procedure'` \| Procédures \|
		\| `Unicaen\BddAdmin\Ddl\Ddl:PACKAGE` \| `'package'` \| Packages (Oracle uniquement) \|
		\| `Unicaen\BddAdmin\Ddl\Ddl:REF_CONSTRAINT` \| `'ref-constraint'` \| Contraintes de clés étrangères \|
		\| `Unicaen\BddAdmin\Ddl\Ddl:INDEX` \| `'index'` \| Indexs \|
		\| `Unicaen\BddAdmin\Ddl\Ddl:UNIQUE_CONSTRAINT` \| `'unique-constraint'` \| Contraintes d'unicité \|
		\| `Unicaen\BddAdmin\Ddl\Ddl:TRIGGER` \| `'trigger'` \| Triggers \|
		\| `Unicaen\BddAdmin\Ddl\Ddl:SCHEMA` \| `'schema'` \| Schémas (Postgresql uniquement) \|

		## Objet Bdd

		Un objet de classe [Bdd](../src/Bdd.php) doit être instancié ou bien récupéré.

		Il s'agit de l'objet "point d'entrée" de BddAdmin, celui par lequel tout va transiter (configuration, etc).

		[Bdd](../src/Bdd.php) se charge de distribuer aux autres parties de la biliothèque les directives de configuration
		nécessaires.

		C'est aussi par lui que nous pourrons récupérer les autres objets afin de les exploiter.

		Bdd permet de :
		- gérer les options de configuration de tout BddAdmin (fournies à l'instanciation)
		- gère la connexion à la base de données courante
		- exécuter des requêtes SQL (`exec`, `queryCollect`, `execQueries`, `select`, `selectSingle`, `selectOne`, `selectEtch`)
		- faire des transactions (`beginTransaction`, `commitTransaction`, `rollbackTransaction`)
		- accéder à la gestion d'une table en particulier (`getTable(string $name): Table`), voir ci-dessous
		- accéder aux managers (voir ci-dessous)
		- gérer les DDL : récupération de configurations DDL, création de DDL (`getFiltersForUpdateBdd`, `getFiltersForUpdateDdl`, `getNewDdl`, `getDdl`, `getRefDdl`)
		- réaliser des opérations avancées sur ou à partir de la DDL (coeur de métier) : création/modification/suppression différentielles d'objets à partir de la DDL (`create`, `alter`, `drop`)
		- réaliser les opérations de haut niveau, sur toute la base de données : vidage, installation, mise à jour complète, mise à jour des seules données (`clear`, `install`, `update`, `updateData`)
		- générer la DDL à partir de la base de données (`updateDdl`)
		- générer un jeu de données à partir des données présentes en base (`makeData`)
		- générer des différentiels mettant en valeurs les écarts DDL/BDD : (`diff`,`diffDdl`)
		- exécuter des opérations de maintenance/mise à niveau supplémentaires : (`majSequences`,`refreshMaterializedViews`,`compilerTout`)
		- faires des opérations de copie de bases de données : (`copy`, `copyTo`)
		- faire des opérations de sauvegarde/restauration de bases de données (`save`, `load`)
		- accéder au gestionnaire de données [DataManager](donnees.md) (`$bdd->data()`)
		- accéder au gestionnaire de scripts de migrations [MigrationManager](migrations.md) (`$bdd->migration()`)

		Vous trouverez plus d'infos sur l'API de BDd [ici](bdd.md)

		## Table

		Pour accéder à une Table, il faut lancer :

		```php

		/** @var \Unicaen\BddAdmin\Bdd $bdd */
		/** @var \Unicaen\BddAdmin\Table $table */

		$table = $bdd->getTable('ma_table');
		```

		La classe Table permet de :

		- récupérer la DDL de la table (`getDdl`, `getDdlFromFile`)
		- savoir si ses données sont historisables, synchronisables ou pas (`hasHistorique`, `hasImport`)
		- récupérer des données typées en PHP (`select`)
		- faire des opérations de copie, sauvegarde, restauration (`copy`, `save`, `load`)
		- récupérer la valeur du dernier ID inséré, en se basant sur la séquence associée (`getLastInsertId`)
		- faire des opérations de modification de données (`insert`, `update`, `delete`, `truncate`)
		- faire des opération de synchronisation des données en masse (`merge`), sorte de rsync pour un jeu de données
		- récupérer simplement des infos (`hasId`, `hasSequence`, `hasColumn`)
		- gérer l'historisation en récupérant la liste des dcolonnes gérant l'historique & d'historiser un ensemble de lignes (`getHistoColumns`, `histoWhere`)

		Le `merge` est particulièrement important : il est utilisé par le DataManager pour mettre à jour le jeu de données de la bdd.

		## Managers

		Chaque type d'objet a son propre Manager, qui implémente [ManagerInterface](../src/Manager/ManagerInterface.php).

		Les managers, par type d'objet, sont implémentés dans chaque driver.
		Un Driver n'est pas obligé de gérer tous les managers.

		`$bdd->managerList()` retourne la liste des managers disponibles (dépend du driver utilisé).

		[DriverInterface:getDdlClass](../src/Driver/DriverInterface.php) permet de lister les managers disponibles pour le
		driver voulu, et retourne la classe correspondante.

		Les opérations suivantes pourront être gérées par les managers:

		\| Fonction \| Descriptif \| Données attendues \|
		\|-----------------------------------------------------------------------------------\|------------------------------------------------------\|---------------------------------------------------------------------------------------------------------------------------\|
		\| `get(string\\|array\\|null $includes = null, string\\|array\\|null $excludes = null)` \| Liste des objets, retourne un array de Ddl \| array de [DdlFilter](../src/Ddl/DdlFilter) permettant de filtrer ce que l'on veut obtenir, par exclusion ou par sélection \|
		\| `exists(string $name)` \| Détermine si l'objet existe ou non, retourne un bool \| Nom de l'objet \|
		\| `create(array $data)` \| Crée un nouvel objet \| array représentant la DDL de l'objet \|
		\| `drop(array\\|string $name)` \| Supprime un objet selon sa définition ou son nom \| Nom ou Ddl de l'objet \|
		\| `alter(array $old, array $new)` \| Modifie un objet \| array représentant l'ancienne DDL & la nouvelle DDL \|
		\| `rename(string $oldName, array\\| string $new)` \| Renomage d'un objet \| à partir de son ancien nom, on donne un nouveau nom en chaine ou on fournit sa DDL complète \|
		\| `prepareRenameCompare(array $data)` \| \| \|

		Ces opérations seront ensuite appelées pour mettre à jour vos bases de données.

		Les managers sont accessibles en passant par [Bdd](../src/Bdd.php) :

		\| Méthode \| Type de retour \| Description \|
		\|-------------------------\|-------------------------------------\|---------------------------------------------------------------------------------------\|
		\| `manager(string $name)` \| `ManagerInterface` \| Retourne le manager dont le nom est le type d'objet souhaité (types listés ci-dessus) \|
		\| `schema` \| `SchemaManagerInterface` \| Manager des schémas \|
		\| `index` \| `IndexManagerInterface` \| Manager des indexs \|
		\| `materializedView` \| `MaterializedViewManagerInteface` \| Manager des vues matérialisées \|
		\| `procedure` \| `ProcedureManagerInteface` \| Manager des procédures \|
		\| `function` \| `FunctionManagerInteface` \| Manager des fonctions \|
		\| `package` \| `PackageManagerInteface` \| Manager des packages \|
		\| `primaryConstraint` \| `PrimaryConstraintManagerInterface` \| Manager des contraintes de clés primaires \|
		\| `refConstraint` \| `RefConstraintManagerInterface` \| Manager des contraintes de clés étrangères \|
		\| `sequence` \| `SequenceManagerInterface` \| Manager des séquences \|
		\| `table` \| `TableManagerInterface` \| Manager des tables \|
		\| `trigger` \| `TriggerManagerInterface` \| Manager des triggers \|
		\| `uniqueConstraint` \| `UniqueConstraintManagerInterface` \| Manager des contraintes d'unicité \|
		\| `view` \| `ViewManagerInterface` \| Manager des vues \|

		L'accès aux managers sera réservé aux opérations avancées, l'objectif de BddAdmin étant de faire cela par lui-même.


		## DDL

		L'objet [Unicaen\BddAdmin\Ddl\Ddl](../src/Ddl/Ddl.php) permet d'efectuer toutes les opérations nécessaires sur une DDL.

		La DDL peut aussi bien prevenir du système de fichiers, que de l'analyse de la base de données.

		La plupart du temps, une seule DDL sera manipulée : celle de la base de données courante déclarée en configuration.

		`$bdd->getDdl()` permet de récupérer la DDL calculée depuis la base de données courante.

		`$bdd->getRefDdl()` permet de récupérer la DDL déclarée dans le système de fichiers, en tenant compte des options de configuration transmises à Bdd.



		## DataManager

		Le DataManager va servir à gérer les données.
		Il permet :
		- de créer un jeu de données à partir de la bas de données (il est ainsi possible de créer plusieurs jeux de données)
		- de charger un jeu de données dnas la base de données

		Il est accesible via l'objet $bdd :

		```php

		/** @var \Unicaen\BddAdmin\Bdd $bdd */
		/** @var \Unicaen\BddAdmin\Data\DataManager $dm */

		$dm = $bdd->data();

		```

		Des règles de gestion permettent de préciser les sources à utiliser, qui peuvent être :
		- des array PHP
		- un fichier
		- un répertoire comportant des fichiers dont chacun d'entre eux correspond à une table
		- des classes avec pour chaque table à charger une méthode portant le même nom

		Le DataManager va utiliser le Table->merge pour agir sur la base de données.
		L'opération est donc différentielle et idempotente.

		Plusieurs jeux de donnée pourront être chargés successivement.

		Des règles de gestion permettent de préciser, par table et par colonne, si la modification doit être faite ou non,
		par ligne si la ligne doit être supprimée/modifiée/historisée/restaurée/supprimée, etc.

		Ces règles permettent aussi, via des transformateurs, de calculer des ID à partir de requêtes afin de ne pas avoi à les fournir.
		Ceci permet de ne travailler qu'avec des codes ou des données persistentes, les ID étant générés avec des séquences la plupart du temps.

		Enfin, dans certain cas des opétation "custom" sont possibles.

		La documentation du format de configuration du DataManager est décrite [ici](configs/data-config.md).

		## MigrationManager


		## Logger



		## Commandes

		Des commandes en console permettent de lancer un certain nombre d'opérations en utilisant BddAdmin.

		La liste complète est disponible [ici](doc.md).
		No newline at end of file

doc/configs/data-config.md

0 → 100644

+1 −0

Original line number	Diff line number	Diff line
		# Schéma de configuration du DataManager
		No newline at end of file

doc/configs/ddl-filter.md

0 → 100644

+2 −0

Original line number	Diff line number	Diff line
		# Schéma de DDLFilters

doc/configs/merge.md

0 → 100644

+2 −0

Original line number	Diff line number	Diff line
		# Schéma de configuration du merge

doc/doc.md

+9 −2

Original line number	Diff line number	Diff line
		# Documentation

		[Architecture](architecture.md)

		## Configuration (WIP)

		- [Filtres](filtres.md)
		- [Options de configuration](options.md)


		## Commandes console

		### Opérations globales
		@@ -30,7 +31,8 @@
		### Autres commandes

		- [test-migration](console/test-migration.md) : Permet de tester le bon fonctionnement des scripts de migration
		- [update-sequences](console/update-sequences.md) : Met à jour les séquences afin que leur valeur courante ne soit pas déjà utilisée
		- [update-sequences](console/update-sequences.md) : Met à jour les séquences afin que leur valeur courante ne soit
		pas déjà utilisée

		## API (WIP)

		@@ -45,6 +47,11 @@
		- [Copies, sauvegardes, restaurations](copies-sauvegardes-restaurations.md)
		- [Logger](logger.md)

		## Formats de configuration

		- [DataManager](configs/data-config.md)
		- [DdlFilter](configs/ddl-filter.md)
		- [Merge](configs/merge.md)

		## Outils