Get Started with Liquibase and YAML

After you install Liquibase, get started with our tutorial and learn how Liquibase works.

With Liquibase, SQL statements [1] are declared as Liquibase changesets [2] in a changelog file [3].

Liquibase [4] then uses the changelog to apply the changesets to target databases [5].

In this tutorial, you will use an example changelog to apply two rounds of updates to an H2 database that is included with the Liquibase installation files.

Applying updates to the database

1. Copy the Liquibase examples directory from the installation directory to another location on your machine.

2. From a command line terminal, enter liquibase init start-h2 to start the example H2 database. The database console opens automatically in a browser on port 9090. The terminal includes the following output:

   ...
   Opening Database Console in Browser...
     Dev Web URL: http://192.168.56.1:8090/frame.jsp?jsessionid=d219f3d2012e078770943ef4c2cd0d11
     Integration Web URL: http://192.168.56.1:8090/frame.jsp?jsessionid=d7ab638787c99dbfe9c8103883bee278

3. Open a new command line terminal and enter the following commands:

cd <your path>/examples/yaml
liquibase update

Liquibase displays the following output:

Running Changeset: example-changelog.yaml::1::your.name
Running Changeset: example-changelog.yaml::2::your.name
Running Changeset: example-changelog.yaml::3::your.name
Liquibase command 'update' was executed successfully.

Understanding changelogs, changesets, and the update command

Liquibase applies the following updates, which are specified as Liquibase changesets in example-changelog.yaml:

- changeSet:
       id:  1
       author:  your.name
       changes:
        - createTable:
             tableName:  person 
             columns:
               - column:
                   name:  id
                   type:  int
                   autoIncrement:  true
                   constraints:
                     primaryKey:  true
                     nullable:  false
               - column:
                   name:  name
                   type:  varchar(50)
- changeSet:  
       id:  2
       author:  your.name
       changes:
        - createTable:
             tableName:  company
             columns:
               - column:
                   name:  id
                   type:  int
                   autoIncrement:  true
                   constraints:
                     primaryKey:  true
                     nullable:  false
               - column:
                   name:  name
                   type:  varchar(50)
- changeSet:
       id:  3
       author:  your.name
       changes:
        - addColumn:
             tableName:  company
             columns:
               - column:
                   name:  country
                   type:  varchar(2)

The author-id value pairs your.name:1 and your.name:2 prevent their respective changesets from accidentally being run multiple times as new changesets are added to the changelog for subsequent updates. For more information, see Changelog.

4. From the database console, confirm that the PERSON and COMPANY tables were added successfully. You may have to click the "Refresh" button to see the changes.

5. Using a text editor, open <your path>/examples/yaml/example-changelog.yaml and add the following changeset to the end of the file:

   Note: When you copy the changeset, put the - changesetattribute at the beginning of a new line without any indentation.

   - changeSet:  
          id:  4
          author:  your.name
          changes:
           - addColumn:
                tableName:  person
                columns:
                  - column:
                      name:  nickname
                      type:  varchar(30)

6. Save and close example-changelog.yaml.

7. Enter the following command:

   liquibase update

   Liquibase displays the following output:

   Running Changeset: example-changelog.yaml::4::your.name
   Liquibase command 'update' was executed successfully.

8. Confirm the update by refreshing the database console and verifying that the NICKNAME column has been added to the PERSON table.

Next steps

1. Introduction to Liquibase – Dive into Liquibase concepts
2. Design Your Liquibase Project – Create a new Liquibase project folder and organize your changelogs
3. Liquibase Database Tutorials – Configure Liquibase to work with your own database
4. How to Apply Your Liquibase Pro License Key – If you use Liquibase Pro, activate your license