Skip to content

Changes

Page history
Update Migrations authored by Henry Page's avatar Henry Page
Hide whitespace changes
Inline Side-by-side
Migrations.md
View page @ 41521dfd
When an application is already deployed and changes to the database are necessary, a migration needs to be written. This can be done as follows.
When an application is already deployed and changes to the database are necessary, a migration needs to be written. This can be done as follows.
### Setup Liquibase:
1. Install [Liquibase](https://docs.liquibase.com/start/install/home.html)
1. Install [Liquibase](https://docs.liquibase.com/start/install/home.html)
2. Copy the `liquibase.template.properties` file in the root directory (if it isn't available in your project, head to the Queue or TAM repository and copy it from there).
3. Paste the copy into the root directory and rename it to `liquibase.properties`.
4. Check the `build.gradle.kts` file and find the `h2Version` variable. In the `classpath` variable, replace `VERSION` with the version as it appears in the variable.
5. Check the following path in your file explorer: `$HOME\.gradle\caches\modules-2\files-2.1\com.h2database\h2\VERSION` and find the folder containing a `.jar` file. Replace `HASH` in the `classpath` variable with the name of this folder.
* If you can't find `modules-2` in the `.gradle/caches` folder, then check the [Gradle Docs](https://docs.gradle.org/current/userguide/directory_layout.html) and replace `modules-2` with the folder labeled `Shared caches (e.g. for artifacts of dependencies)`.
* Alternatively, you can opt to install the `.jar` file using the relevant version of H2 available on [Maven Central](https://mvnrepository.com/artifact/com.h2database/h2). When executing the migration process (see below), include an extra `--classpath` flag, specifying the file path to the installed `.jar` file.
* (**EASIER**) Alternatively, you can opt to install the `.jar` file using the relevant version of H2 available on [Maven Central](https://mvnrepository.com/artifact/com.h2database/h2). When executing the migration process (see below), include an extra `--classpath` flag, specifying the file path to the installed `.jar` file.
6. On a new line add the variable `changeSetAuthor` and set it equal to your GitLab username (usually your NetID).
Another option is to obtain `h2.jar` and `liquibase.zip` from another developer (or from the `.gradle` folder). Then add Liquibase to your path and put the jar under `/usr/local/apps/h2`.
### Create migrations:
0. Make sure your `spring.datasource` in the `application.yaml` has `username: sa` and `password: `
1. Switch to the `dev` branch.
2. Make sure the `application.yaml` file has `url: jdbc:h2:file:./testdb-old;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE;DATABASE_TO_UPPER=false;` in the `datasource` section.
3. Run the project normally, there should now be some `.db` files in the root directory.
4. Stop the project.
5. Switch back to your branch.
6. Make sure the `application.yaml` file has `url: jdbc:h2:file:./testdb-new;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE;DATABASE_TO_UPPER=false;` in the `datasource` section.
7. Run the project normally.
8. Now run this command: `liquibase --changelogFile=new.yaml diff-changelog`, there should now be a file called `new.yaml` in the root directory.
9. If you encounter errors during this step, check the `liquibase.properties` file for instructions.
10. Now copy your changes from `new.yaml` to the bottom of `migrations.yaml`. Double check whether the generated changelog makes sense. Sometimes, you might need to add default values or change column types.
11. Make sure to delete the `new.yaml` file before preforming more migrations.
1. Make sure your `spring.datasource` in the `application.yaml` has `username: sa` and `password:`
2. Switch to the `dev` branch.
3. Make sure the `application.yaml` file has `url: jdbc:h2:file:./testdb-old;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE;DATABASE_TO_UPPER=false;` in the `datasource` section.
4. Run the project normally, there should now be some `.db` files in the root directory.
5. Stop the project.
6. Switch back to your branch.
7. Make sure the `application.yaml` file has `url: jdbc:h2:file:./testdb-new;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE;DATABASE_TO_UPPER=false;` in the `datasource` section.
8. Run the project normally.
9. Now run this command: `liquibase --changelogFile=new.yaml diff-changelog`, there should now be a file called `new.yaml` in the root directory.
10. If you encounter errors during this step, check the `liquibase.properties` file for instructions.
11. Now copy your changes from `new.yaml` to the bottom of `migrations.yaml`. Double check whether the generated changelog makes sense. Sometimes, you might need to add default values or change column types.
12. Make sure to delete the `new.yaml` file before preforming more migrations.
Alternatively you can generate a changelog with the following script:
```
PROJ_DIR=$1
RESOURCES_DIR=$PROJ_DIR/src/main/resources
......@@ -50,9 +51,11 @@ liquibase \
## Common Errors
### No Changelog Generated
Liquibase may display a message indicating successful generation of the changelog, but in reality, no changelog exists. This issue is likely due to incorrect url and referenceUrl configurations for your H2 traces. Consider using absolute paths instead of relative paths.
### Incompatible H2 Version
```
Caused by: org.h2.mvstore.MVStoreException: The write format 2 is smaller than the supported format 3 [2.2.224/5]
at org.h2.mvstore.DataUtils.newMVStoreException(DataUtils.java:996) ~[h2-2.2.224.jar:2.2.224]
......@@ -66,4 +69,4 @@ Caused by: org.h2.mvstore.MVStoreException: The write format 2 is smaller than t
... 35 common frames omitted
```
This means the traces that were produced are written using an older version of the H2 driver that is not supported by a newer version of liquibase. Either downgrade your liquibase version or write the traces using a newer version of H2.
This means the traces that were produced are written using an older version of the H2 driver that is not supported by a newer version of liquibase. Either downgrade your liquibase version or write the traces using a newer version of H2.
\ No newline at end of file