From 0b92e5fcaebf037163c4ed11afb6e13df5a9ed1f Mon Sep 17 00:00:00 2001 From: "j.goderbauer" <j.goderbauer@adito.de> Date: Tue, 2 Oct 2018 14:49:17 +0200 Subject: [PATCH] liquibase-doc --- others/db_changes/readme.adoc | 171 +++++++++++++++++----------------- 1 file changed, 86 insertions(+), 85 deletions(-) diff --git a/others/db_changes/readme.adoc b/others/db_changes/readme.adoc index fe12e5629e..4763f6c404 100644 --- a/others/db_changes/readme.adoc +++ b/others/db_changes/readme.adoc @@ -1,86 +1,87 @@ -liquibase-readme -================ - -== Structure within ADITO -=== in theory - -When using liquibase in an ADITO-System, your project structure _should_ look like this: ----- -PROJECTHOME/others/db_changes/masterChangelog.xml -PROJECTHOME/others/db_changes/struct/ -PROJECTHOME/others/db_changes/data/ -PROJECTHOME/others/db_changes/liquibase.properties ----- - -The file `masterChangelog.xml` contains a list of all changes (well, in fact more like a list of all changelog-files). The structure could look like this: -[source,xml] ----- -<?xml version="1.1" encoding="UTF-8" standalone="no"?> -<databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog" xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.6.xsd"> - <include file="struct/create_org.xml"/> - <include file="data/example_org.xml"/> -</databaseChangeLog> ----- - -TIP: Keep in mind that the header-information can change, visit therefore the liquibase-website: http://www.liquibase.org Specific: the XML-format definition: http://www.liquibase.org/documentation/xml_format.html - -So, thats where all our changes are located - but what about the changes _itself_? -As you can think of, they're stored in files located in the folders `struct` for DDL-stuff like _create_, _alter_ etc. -and `data` for DML-stuff like _insert_, _update_ etc. - -If you want to know what to do add in these files take a look at the official liquibase documentation for futher information how to fill these XML files: http://www.liquibase.org/documentation/index.html - -IMPORTANT: Always remember that you might have to define some rollback-entries. + -This is e.g. not needed for create-entries but for others like insert. - -So, whats about that `liquibase.properties` file? The file is needed to specify some data here, e.g. the driver-name, classpath (of the driver), jdbc-url, etc. -You want to store these information there because otherwise you'd need to specify them on every call of liquibase. Not cool. - -Now you're ready to run commands like `liquibase update` in the `PROJECTHOME/others/db_changes` folder. - -=== in practice - -.Let's say whe want to add a new table `FOOBAR` with some demo-data. We need to: -* create a new file in the struct-folder; e.g. `create_FOOBAR.xml` -* fill the file with changesets that will create a table -* add `include`-tag in the `masterChangelog.xml` for the created file -* create a new file in the data-foler; e.g. `demoData_FOOBAR.xml` -* fill the file with changesets that will insert data into the table and define *rollback-entries* -* add `include`-tag in the `masterChangelog.xml` for the created file -* to apply the changes simply run `liquibase update` - -For example one featurepackage "add contact management" could contain several files itself: ----- - create_org.xml - create_pers.xml - create_relation.xml ----- -On the other hand, several featurepackages cannot be contained in one changelog-file. - - -== How to use it -Normally everything you need is provided by the project-template and the existing files in the git-repository. -Therefore it's easy to use and you can start immediately. - -.Keep in mind: -* run `liquibase update` to apply possible changes after merging something into your repository -* apply modifications on the database always with liquibase; do not write a create-script in SQL. Write some changesets and execute them -* set correct `author`- and `id`-attributes in your changelog-files - - - -== FAQ -[qanda] -What about unicode-columns like `NVARCHAR` or `NCLOB`?:: - Simply define them in your changesets; This is something which is not completely verified: - Maybe columns like `NCLOB` cause problems in some DBMS like _MS SQL Server_ -What if i swtich between branches and want to switch between different database-states?:: - This is something that needs to be defined. Possible ways: rollback or recreate your database entirely -Is it possible to write an update-changeset where I can use a preparedStatement in the where-clause?:: - This needs to be analysed and (the result) added here. - - - ---- - +liquibase-readme +================ + +== Structure within ADITO +=== in theory + +When using liquibase in an ADITO-System, your project structure _should_ look like this: +---- +PROJECTHOME/others/db_changes/masterChangelog.xml +PROJECTHOME/others/db_changes/struct/ +PROJECTHOME/others/db_changes/data/ +PROJECTHOME/others/db_changes/misc/ +PROJECTHOME/others/db_changes/liquibase.properties +---- + +The file `masterChangelog.xml` contains a list of all changes (well, in fact more like a list of all changelog-files). The structure could look like this: +[source,xml] +---- +<?xml version="1.1" encoding="UTF-8" standalone="no"?> +<databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog" xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.6.xsd"> + <include file="struct/create_org.xml"/> + <include file="data/example_org.xml"/> +</databaseChangeLog> +---- + +TIP: Keep in mind that the header-information can change, visit therefore the liquibase-website: http://www.liquibase.org Specific: the XML-format definition: http://www.liquibase.org/documentation/xml_format.html + +So, thats where all our changes are located - but what about the changes _itself_? +As you can think of, they're stored in files located in the folders `struct` for DDL-stuff like _create_, _alter_ etc. +and `data` for DML-stuff like _insert_, _update_ etc. + +If you want to know what to do add in these files take a look at the official liquibase documentation for futher information how to fill these XML files: http://www.liquibase.org/documentation/index.html + +IMPORTANT: Always remember that you might have to define some rollback-entries. + +This is e.g. not needed for create-entries but for others like insert. + +So, whats about that `liquibase.properties` file? The file is needed to specify some data here, e.g. the driver-name, classpath (of the driver), jdbc-url, etc. +You want to store these information there because otherwise you'd need to specify them on every call of liquibase. Not cool. + +Now you're ready to run commands like `liquibase update` in the `PROJECTHOME/others/db_changes` folder. + +=== in practice + +.Let's say whe want to add a new table `FOOBAR` with some demo-data. We need to: +* create a new file in the struct-folder; e.g. `create_FOOBAR.xml` +* fill the file with changesets that will create a table +* add `include`-tag in the `masterChangelog.xml` for the created file +* create a new file in the data-foler; e.g. `demoData_FOOBAR.xml` +* fill the file with changesets that will insert data into the table and define *rollback-entries* +* add `include`-tag in the `masterChangelog.xml` for the created file +* to apply the changes simply run `liquibase update` + +For example one featurepackage "add contact management" could contain several files itself: +---- + create_org.xml + create_pers.xml + create_relation.xml +---- +On the other hand, several featurepackages cannot be contained in one changelog-file. + + +== How to use it +Normally everything you need is provided by the project-template and the existing files in the git-repository. +Therefore it's easy to use and you can start immediately. + +.Keep in mind: +* run `liquibase update` to apply possible changes after merging something into your repository +* apply modifications on the database always with liquibase; do not write a create-script in SQL. Write some changesets and execute them +* set correct `author`- and `id`-attributes in your changelog-files + + + +== FAQ +[qanda] +What about unicode-columns like `NVARCHAR` or `NCLOB`?:: + Simply define them in your changesets; This is something which is not completely verified: + Maybe columns like `NCLOB` cause problems in some DBMS like _MS SQL Server_ +What if i swtich between branches and want to switch between different database-states?:: + This is something that needs to be defined. Possible ways: rollback or recreate your database entirely +Is it possible to write an update-changeset where I can use a preparedStatement in the where-clause?:: + This needs to be analysed and (the result) added here. + + + +--- + ~have~ ~a~ ~nice~ ~day~ ~:-)~ \ No newline at end of file -- GitLab