The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

Using Liquibase

Liquibase is an open source tool for database schema change management.

Quarkus provides first class support for using Liquibase as will be explained in this guide.

Solução

Recomendamos que siga as instruções nas seções seguintes e crie a aplicação passo a passo. No entanto, você pode ir diretamente para o exemplo completo.

Clone o repositório Git: git clone https://github.com/quarkusio/quarkus-quickstarts.git, ou baixe um arquivo.

The solution is located in the liquibase-quickstart directory.

Setting up support for Liquibase

To start using Liquibase with your project, you just need to:

  • add your changeLog to the src/main/resources/db/changeLog.xml file as you usually do with Liquibase

  • activate the migrate-at-start option to migrate the schema automatically or inject the Liquibase object and run your migration as you normally do.

In your pom.xml, add the following dependencies:

  • the Liquibase extension

  • sua extensão de driver JDBC ( quarkus-jdbc-postgresql , quarkus-jdbc-h2 , quarkus-jdbc-mariadb , …​)

pom.xml
<!-- Liquibase specific dependencies -->
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-liquibase</artifactId>
</dependency>

<!-- JDBC driver dependencies -->
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-jdbc-postgresql</artifactId>
</dependency>
build.gradle
// Liquibase specific dependencies
implementation("io.quarkus:quarkus-liquibase")

// JDBC driver dependencies
implementation("io.quarkus:quarkus-jdbc-postgresql")

Liquibase support relies on the Quarkus datasource config. It can be customized for the default datasource as well as for every named datasource. First, you need to add the datasource config to the application.properties file in order to allow Liquibase to manage the schema.

A seguir, um exemplo do arquivo application.properties :

# configure your datasource
quarkus.datasource.db-kind=postgresql
quarkus.datasource.username=sarah
quarkus.datasource.password=connor
quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/mydatabase

# Liquibase minimal config properties
quarkus.liquibase.migrate-at-start=true

# Liquibase optional config properties
# quarkus.liquibase.change-log=db/changeLog.xml
# quarkus.liquibase.validate-on-migrate=true
# quarkus.liquibase.clean-at-start=false
# quarkus.liquibase.database-change-log-lock-table-name=DATABASECHANGELOGLOCK
# quarkus.liquibase.database-change-log-table-name=DATABASECHANGELOG
# quarkus.liquibase.contexts=Context1,Context2
# quarkus.liquibase.labels=Label1,Label2
# quarkus.liquibase.default-catalog-name=DefaultCatalog
# quarkus.liquibase.default-schema-name=DefaultSchema
# quarkus.liquibase.liquibase-catalog-name=liquibaseCatalog
# quarkus.liquibase.liquibase-schema-name=liquibaseSchema
# quarkus.liquibase.liquibase-tablespace-name=liquibaseSpace

Add a changeLog file to the default folder following the Liquibase naming conventions: src/main/resources/db/changeLog.xml The yaml, json, xml and sql changeLog file formats are also supported.

<?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
    https://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd
    http://www.liquibase.org/xml/ns/dbchangelog
    https://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd">

    <changeSet author="quarkus" id="1">
        <createTable tableName="quarkus">
            <column name="ID" type="VARCHAR(255)">
                <constraints nullable="false"/>
            </column>
            <column name="NAME" type="VARCHAR(255)"/>
        </createTable>
    </changeSet>
</databaseChangeLog>

Now you can start your application and Quarkus will run the Liquibase’s update method according to your config:

import io.quarkus.liquibase.LiquibaseFactory; (1)

@ApplicationScoped
public class MigrationService {
    // You can Inject the object if you want to use it manually
    @Inject
    LiquibaseFactory liquibaseFactory; (2)

    public void checkMigration() {
        // Get the list of liquibase change set statuses
        try (Liquibase liquibase = liquibaseFactory.createLiquibase()) {
            List<ChangeSetStatus> status = liquibase.getChangeSetStatuses(liquibaseFactory.createContexts(), liquibaseFactory.createLabels());
        }
    }
}
1 The Quarkus extension provides a factory to initialize a Liquibase instance
2 Inject the Quarkus liquibase factory if you want to use the liquibase methods directly

Datasources Múltiplos

Liquibase can be configured for multiple datasources. The Liquibase properties are prefixed exactly the same way as the named datasources, for example:

quarkus.datasource.db-kind=h2
quarkus.datasource.username=username-default
quarkus.datasource.jdbc.url=jdbc:h2:tcp://localhost/mem:default
quarkus.datasource.jdbc.max-size=13

quarkus.datasource.users.db-kind=h2
quarkus.datasource.users.username=username1
quarkus.datasource.users.jdbc.url=jdbc:h2:tcp://localhost/mem:users
quarkus.datasource.users.jdbc.max-size=11

quarkus.datasource.inventory.db-kind=h2
quarkus.datasource.inventory.username=username2
quarkus.datasource.inventory.jdbc.url=jdbc:h2:tcp://localhost/mem:inventory
quarkus.datasource.inventory.jdbc.max-size=12

# Liquibase configuration for the default datasource
quarkus.liquibase.schemas=DEFAULT_TEST_SCHEMA
quarkus.liquibase.change-log=db/changeLog.xml
quarkus.liquibase.migrate-at-start=true

# Liquibase configuration for the "users" datasource
quarkus.liquibase.users.schemas=USERS_TEST_SCHEMA
quarkus.liquibase.users.change-log=db/users.xml
quarkus.liquibase.users.migrate-at-start=true

# Liquibase configuration for the "inventory" datasource
quarkus.liquibase.inventory.schemas=INVENTORY_TEST_SCHEMA
quarkus.liquibase.inventory.change-log=db/inventory.xml
quarkus.liquibase.inventory.migrate-at-start=true

Notice there’s an extra bit in the key. The syntax is as follows: quarkus.liquibase.[optional name.][datasource property].

Without configuration, Liquibase is set up for every datasource using the default settings.

Using the Liquibase object

In case you are interested in using the Liquibase object directly, you can inject it as follows:

If you enabled the quarkus.liquibase.migrate-at-start property, by the time you use the Liquibase instance, Quarkus will already have run the migrate operation.
import io.quarkus.liquibase.LiquibaseFactory;

@ApplicationScoped
public class MigrationService {
    // You can Inject the object if you want to use it manually
    @Inject
    LiquibaseFactory liquibaseFactory; (1)

    @Inject
    @LiquibaseDataSource("inventory") (2)
    LiquibaseFactory liquibaseFactoryForInventory;

    @Inject
    @Named("liquibase_users") (3)
    LiquibaseFactory liquibaseFactoryForUsers;

    public void checkMigration() {
        // Use the liquibase instance manually
        try (Liquibase liquibase = liquibaseFactory.createLiquibase()) {
            liquibase.dropAll(); (4)
            liquibase.validate();
            liquibase.update(liquibaseFactory.createContexts(), liquibaseFactory.createLabels());
            // Get the list of liquibase change set statuses
            List<ChangeSetStatus> status = liquibase.getChangeSetStatuses(liquibaseFactory.createContexts(), liquibaseFactory.createLabels()); (5)
        }
    }
}
1 Inject the LiquibaseFactory object
2 Inject Liquibase for named datasources using the Quarkus LiquibaseDataSource qualifier
3 Inject Liquibase for named datasources
4 Use the Liquibase instance directly
5 List of applied or not applied liquibase ChangeSets

Liquibase on Kubernetes

Sometimes, it’s helpful not to execute Liquibase initialization on each application startup. One such example is when deploying on Kubernetes, where it doesn’t make sense to execute Liquibase on every single replica. Instead it’s desirable to execute it once and then start the actual application without Liquibase. To support this use case, when generating manifests for Kubernetes the generated manifests contain a Kubernetes initialization Job for Liquibase. The Job performs initialization and the actual Pod, will starts once the Job is successfully completed.

Desabilitando

O recurso é habilitado por padrão e pode ser desativado globalmente, usando:

quarkus.kubernetes.init-task-defaults.enabled=false

ou no OpenShift:

quarkus.openshift.init-task-defaults.enabled=false

Usando uma imagem personalizada que controla a espera pelo Job

Para alterar a imagem wait-for que, por padrão, é groundnuty/k8s-wait-for:no-root-v1.7 , você pode usar:

quarkus.kubernetes.init-task-defaults.wait-for-container.image=my/wait-for-image:1.0

ou no OpenShift:

quarkus.openshift.init-task-defaults.wait-for-container.image=my/wait-for-image:1.0

Observação : Neste contexto, globalmente significa for all extensions that support init task externalization .

Referência de configuração

Propriedade de Configuração Fixa no Momento da Compilação - Todas as outras propriedades de configuração podem ser sobrepostas em tempo de execução.

Configuration property

Tipo

Padrão

The liquibase change log file. All included change log files in this file are scanned and add to the projects.

Environment variable: QUARKUS_LIQUIBASE_CHANGE_LOG

Show more

string

db/changeLog.xml

The search path for DirectoryResourceAccessor

Environment variable: QUARKUS_LIQUIBASE_SEARCH_PATH

Show more

list of string

Flag to enable / disable Liquibase.

Environment variable: QUARKUS_LIQUIBASE_ENABLED

Show more

boolean

true

true to execute Liquibase automatically when the application starts, false otherwise.

Environment variable: QUARKUS_LIQUIBASE_MIGRATE_AT_START

Show more

boolean

false

true to validate the applied changes against the available ones, false otherwise. It is only used if migration-at-start is true

Environment variable: QUARKUS_LIQUIBASE_VALIDATE_ON_MIGRATE

Show more

boolean

true

true to execute Liquibase clean command automatically when the application starts, false otherwise.

Environment variable: QUARKUS_LIQUIBASE_CLEAN_AT_START

Show more

boolean

false

Comma-separated case-sensitive list of ChangeSet contexts to execute for liquibase.

Environment variable: QUARKUS_LIQUIBASE_CONTEXTS

Show more

list of string

Comma-separated case-sensitive list of expressions defining labeled ChangeSet to execute for liquibase.

Environment variable: QUARKUS_LIQUIBASE_LABELS

Show more

list of string

Map of parameters that can be used inside Liquibase changeLog files.

Environment variable: QUARKUS_LIQUIBASE_CHANGE_LOG_PARAMETERS__PARAMETER_NAME_

Show more

Map<String,String>

The liquibase change log lock table name. Name of table to use for tracking concurrent Liquibase usage.

Environment variable: QUARKUS_LIQUIBASE_DATABASE_CHANGE_LOG_LOCK_TABLE_NAME

Show more

string

DATABASECHANGELOGLOCK

The liquibase change log table name. Name of table to use for tracking change history.

Environment variable: QUARKUS_LIQUIBASE_DATABASE_CHANGE_LOG_TABLE_NAME

Show more

string

DATABASECHANGELOG

The name of Liquibase’s default catalog.

Environment variable: QUARKUS_LIQUIBASE_DEFAULT_CATALOG_NAME

Show more

string

The name of Liquibase’s default schema. Overwrites the default schema name (returned by the RDBMS) with a different database schema.

Environment variable: QUARKUS_LIQUIBASE_DEFAULT_SCHEMA_NAME

Show more

string

The username that Liquibase uses to connect to the database. If no specific username is configured, falls back to the datasource username and password.

Environment variable: QUARKUS_LIQUIBASE_USERNAME

Show more

string

The password that Liquibase uses to connect to the database. If no specific password is configured, falls back to the datasource username and password.

Environment variable: QUARKUS_LIQUIBASE_PASSWORD

Show more

string

The name of the catalog with the liquibase tables.

Environment variable: QUARKUS_LIQUIBASE_LIQUIBASE_CATALOG_NAME

Show more

string

The name of the schema with the liquibase tables.

Environment variable: QUARKUS_LIQUIBASE_LIQUIBASE_SCHEMA_NAME

Show more

string

The name of the tablespace where the -LOG and -LOCK tables will be created (if they do not exist yet).

Environment variable: QUARKUS_LIQUIBASE_LIQUIBASE_TABLESPACE_NAME

Show more

string

Allows duplicated changeset identifiers without failing Liquibase execution.

Environment variable: QUARKUS_LIQUIBASE_ALLOW_DUPLICATED_CHANGESET_IDENTIFIERS

Show more

boolean

Named datasources

Tipo

Padrão

The liquibase change log file. All included change log files in this file are scanned and add to the projects.

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__CHANGE_LOG

Show more

string

db/changeLog.xml

The search path for DirectoryResourceAccessor

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__SEARCH_PATH

Show more

list of string

true to execute Liquibase automatically when the application starts, false otherwise.

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__MIGRATE_AT_START

Show more

boolean

false

true to validate the applied changes against the available ones, false otherwise. It is only used if migration-at-start is true

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__VALIDATE_ON_MIGRATE

Show more

boolean

true

true to execute Liquibase clean command automatically when the application starts, false otherwise.

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__CLEAN_AT_START

Show more

boolean

false

Comma-separated case-sensitive list of ChangeSet contexts to execute for liquibase.

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__CONTEXTS

Show more

list of string

Comma-separated case-sensitive list of expressions defining labeled ChangeSet to execute for liquibase.

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__LABELS

Show more

list of string

Map of parameters that can be used inside Liquibase changeLog files.

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__CHANGE_LOG_PARAMETERS__PARAMETER_NAME_

Show more

Map<String,String>

The liquibase change log lock table name. Name of table to use for tracking concurrent Liquibase usage.

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__DATABASE_CHANGE_LOG_LOCK_TABLE_NAME

Show more

string

DATABASECHANGELOGLOCK

The liquibase change log table name. Name of table to use for tracking change history.

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__DATABASE_CHANGE_LOG_TABLE_NAME

Show more

string

DATABASECHANGELOG

The name of Liquibase’s default catalog.

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__DEFAULT_CATALOG_NAME

Show more

string

The name of Liquibase’s default schema. Overwrites the default schema name (returned by the RDBMS) with a different database schema.

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__DEFAULT_SCHEMA_NAME

Show more

string

The username that Liquibase uses to connect to the database. If no specific username is configured, falls back to the datasource username and password.

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__USERNAME

Show more

string

The password that Liquibase uses to connect to the database. If no specific password is configured, falls back to the datasource username and password.

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__PASSWORD

Show more

string

The name of the catalog with the liquibase tables.

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__LIQUIBASE_CATALOG_NAME

Show more

string

The name of the schema with the liquibase tables.

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__LIQUIBASE_SCHEMA_NAME

Show more

string

The name of the tablespace where the -LOG and -LOCK tables will be created (if they do not exist yet).

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__LIQUIBASE_TABLESPACE_NAME

Show more

string

Allows duplicated changeset identifiers without failing Liquibase execution.

Environment variable: QUARKUS_LIQUIBASE__DATASOURCE_NAME__ALLOW_DUPLICATED_CHANGESET_IDENTIFIERS

Show more

boolean

Conteúdo Relacionado