Running Your First Update

Once you have set up your workspace using the Liquibase installer files, you can run your first command.

The first Liquibase command you will use is the liquibase update command. This command applies any changes in your changelog that have not been run to your database.

Update the database

To run your first update:

• Open a command-line or Terminal app.
• Navigate to your ...examples/sql directory or ...examples/xml directory.
• In your command prompt run liquibase update.

You should see a message saying Update has been successful.

Check your developer console page

Next, refresh your developer database console page.

You should now see the following tables added to the object view:

• COMPANY
• DATABASECHANGELOG
• DATABASECHANGELOGLOCK
• PERSON

By running liquibase update, your database now matches the desired database state as defined by the changelog script.

The DATABASECHANGELOG and DATABASECHANGELOGLOCK tables are liquibase-metadata tables, the COMPANY and PERSON tables were created by the changelog.

Open your changelog file

Now, open the com/example/sample.changelog.xml or com/example/sample.changelog.sql file in your favorite text editor.

In each file, you can see how changes were defined as a series of changesets. Each changeset is uniquely identified by the id and authorfields. Liquibase uses these fields to track what changes have been run and what has not.

When you run the update command, Liquibase evaluates which changesets have not been run against your target database and runs them.

Add new changesets

Running the update command updates your developer database so that it matches the defined state. Now that they match, you can start adding additional changes with changesets.

In this example, you will add a new changeset to create a “works for” column in the “PERSONS” table.

To add this changeset, open the sample changelog file in your existing editor, and add one of the following to then END of the file:

XML changelog example code

<changeSet id="3" author="your.name">
    <addColumn tableName="person">
        <column name="worksfor_company_id" type="int"/>
    </addColumn>
</changeSet>

<changeSet id="4" author="your.name">
    <addForeignKeyConstraint constraintName="fk_person_worksfor"
         baseTableName="person" baseColumnNames="worksfor_company_id" referencedTableName="company" referencedColumnNames="id"/>
</changeSet>

SQL changelog example code

--changeset your.name:4
ALTER TABLE person ADD worksfor_company_id INT;

--changeset your.name:5
ALTER TABLE person ADD CONSTRAINT fk_person_worksfor FOREIGN KEY (worksfor_company_id) REFERENCES company(id);

 

Note: It’s a best practice to wrap every statement in its own changeset block.

Now, run liquibase update again and refresh your database console. You will see the new column on the PERSON table.

Promote changes

Now that you have added a new changeset and the database has the desired structure, you are ready to apply the changes to your integration database.

In a typical workflow, you would commit your changelog to version control and/or build an artifact containing it, however, for this tutorial you will run it directly against another database.

To apply the changes to the integration database run:

liquibase --url=jdbc:h2:tcp://localhost:9090/mem:integration update

By passing along the --url parameter, you override the URL value specified in the liquibase.properties file, but still use all the other parameters in the file.

After running update against the integration database, you should now see the COMPANY and PERSON tables in your integration web console.