---
title: 'Project documentation template'
disqus: hackmd
---

Liquibase Quick Start Guide
===

[TOC]

## Introduction
Liquibase is a database change management tool. Great for tracking and reverting changes being rolled over your database.

Liquibase provides a `declarative` and `DBMS-neutral` way to perform `CRUD` operations. We can describe the required changes in `XML`, `YAML`, `Liquibase-specific SQL`, `Groovy DSL` or `JSON` formats (so-called `changeSets` and `changeLog`) which can be applied to any `DBMS`.

### ChangleLog
* `changeSet` describes a specific change to be applied to a database
* `changeLog` handles an order and parameters of execution of multiple `changeSets`

### Tracing changes
Liquibase creates a table `DATABASECHANGELOG` in every database it manages. That table tracking all the applied changes.

## Getting started

### Prerequisites
We consider the following stack:
* JDK 11
* Spring Boot
* Hibernate
* PostgreSQL
* Gradle
* Liquidbase

### Considerations
* Suppose we have `2 databases` to cover with change management: `main` and `security`
* Also we want to run `diff` between the `changeLog` and `database main`
* We want to run `Liquibase commands` over `gradle`

### Configuration
#### `application.properties`

spring.main.datasource.platform=postgres
spring.main.datasource.url=jdbc:postgresql://localhost:5432/main
spring.main.datasource.username=postgres
spring.main.datasource.password=root

spring.security.datasource.platform=postgres
spring.security.datasource.url=jdbc:postgresql://localhost:5432/security
spring.security.datasource.username=postgres
spring.security.datasource.password=root

spring.jpa.show-sql=true

# Deny Hibernate to modify schema
spring.jpa.hibernate.ddl-auto=none

#### `build.gradle`

plugins {
  id 'org.liquibase.gradle' version '2.0.1'
}

repositories {
    mavenLocal()
    mavenCentral()
}

dependencies {
    liquibaseRuntime 'org.liquibase:liquibase-core:3.6.1'
    liquibaseRuntime 'org.postgresql:postgresql' 
    compile 'org.postgresql:postgresql'
}

liquibase {
  activities {
    main {
      changeLogFile 'src/main/db/main.log'
      url project.ext.mainUrl
      username project.ext.mainUsername
      password project.ext.mainPassword
    }
    security {
      changeLogFile 'src/main/db/security.log'
      url project.ext.securityUrl
      username project.ext.securityUsername
      password project.ext.securityPassword
    }
    diffMain {
      changeLogFile 'src/main/db/main.log'
      url project.ext.mainUrl
      username project.ext.mainUsername
      password project.ext.mainPassword
      difftypes 'data'
    }
  }
  runList = project.ext.runList
}

## Examples
### Usage

# Update db
gradle update -PrunList=main -PmainUsername=u -PmainPassword=p -PmainUrl=jdbc:postgresql://localhost:5432/main
gradle update -PrunList='main,security' -PsecurityUrl=jdbc:postgresql://localhost:5432/security -PmainUsername=u -PmainPassword=p -PsecurityUsername=u -PsecurityPassword=p

# Get diff
gradle diff -PrunList=diffMain -PmainUrl=jdbc:postgresql://localhost:5432/main -PmainUsername=u -PmainPassword=p

# Rollback
gradle rollback -PrunList=main -PliquibaseCommandValue='cool_tag_here' -PmainUsername=u -PmainPassword=p -PmainUrl=jdbc:postgresql://localhost:5432/main # you will see where we set that tag in a minute
#gradle rollback -Dliquibase.tag='some_tag'
gradle rollbackCount -PrunList=main -PliquibaseCommandValue=1 -PmainUsername=u -PmainPassword=p -PmainUrl=jdbc:postgresql://localhost:5432/main
gradle rollbackDate -PrunList=main -PliquibaseCommandValue='Jun 03, 2017' -PmainUsername=u -PmainPassword=p -PmainUrl=jdbc:postgresql://localhost:5432/main

### ChangeLog
`src/main/resources/db/main.log`

databaseChangeLog:
  - changeSet:
      id: 1
      author: dev
      changes:
      - sqlFile:
          dbms: postgresql
          encoding: utf8
          path: scripts/1572942263-create-users-and-addresses-schema.sql
          relativeToChangelogFile: true
  - changeSet:
      id: 2
      author: dev
      changes:
      - sqlFile:
          dbms: postgresql
          encoding: utf8
          path: scripts/1572942328-add-user-data-columns.sql
          relativeToChangelogFile: true
      - tagDatabase:
            tag: cool_tag_here #here is our tag we used for rollback earlier
      rollback:
      - sqlFile:
          path: scripts/1572942328-add-user-data-columns.rollback.sql

## Conventions
### Formats
* `changeLog`: YAML
* `changeSet`: SQL
### Paths and naming
* `changeLog`: src/main/resources/db/\${name_of_database}.log
* _i.e._ main.log
* `changeSet`: src/main/resources/db/\${timestamp}-\${some-description}.log
* _i.e._ 1572942328-add-user-data-columns.sql
* `rollback`: src/main/resources/db/\${original-script-name}.rollback.log
* _i.e._ 1572942328-add-user-data-columns.rollback.sql

## References
* [Gradle plugin](https://github.com/liquibase/liquibase-gradle-plugin)
* [Spring Boot and Liquibase](https://www.roytuts.com/evolving-database-using-spring-boot-liquibase/)
* [Spring Boot Liquibase \[RU\]](https://habr.com/ru/post/460377/)
* [Spring Boot Liquibase Gradle Example](https://www.roytuts.com/spring-boot-liquibase-gradle-example/)

###### tags: `liquibase` `gradle` `spring boot`