Liquibase Extension for OpenSearch

This Liquibase extension supports managing migrations for OpenSearch.

Tip

If you wish to use Spring Boot you should be using liquibase-opensearch-spring-boot-starter instead of using this directly.

Usage

With the Liquibase CLI

To use this with the Liquibase CLI follow these steps:

1. Download & install the Liquibase CLI
2. Download the fat jar of liquibase-opensearch
3. Put the fat jar in the lib folder of the CLI
4. Use the CLI and prefix the URL of OpenSearch with opensearch: (e.g. opensearch:http://localhost:9200)

In a Java Project

To use this in your java project, add a dependency to org.liquibase.ext:liquibase-opensearch.

This supports a single liquibase change type called httpRequest which executes the given request against OpenSearch. A simple example changelog might look like this:

databaseChangeLog:
  - changeSet:
      id: 1
      author: test
      comment: this creates the index testindex and stores a document in it
      changes:
        - httpRequest:
            method: PUT
            path: /testindex
            body: >
              {
                "mappings": {
                  "properties": {
                    "testfield": {
                      "type": "text"
                    }
                  }
                }
              }
        - httpRequest:
            method: PUT
            path: /testindex/_doc/testdoc
            body: >
              {
                "testfield": "foo"
              }

OpenSearch Connection

New Connection From Liquibase

The standard liquibase integration supports only connections with either HTTP or HTTPS with valid TLS certificates and either no authentication or basic authentication (username/password). To use this you have to prepend the URL(s) of OpenSearch with opensearch: so that Liquibase can identify it as an OpenSearch connection:

void main() {
    final var url = "opensearch:http://localhost:9200";
    final var username = "...";
    final var password = "...";

    final var changeLogFile = "path/to/changelog.yaml";

    // let Liquibase instantiate the connection
    final var database = (OpenSearchLiquibaseDatabase) DatabaseFactory.getInstance().openDatabase(url, username, password, null, null);

    // execute the migration
    new CommandScope(UpdateCommandStep.COMMAND_NAME)
            .addArgumentValue(DbUrlConnectionArgumentsCommandStep.DATABASE_ARG, database)
            .addArgumentValue(UpdateCommandStep.CHANGELOG_FILE_ARG, changeLogFile)
            .execute();
}

This also supports multiple URLs for OpenSearch, in which case you can specify them in a comma-separated manner. Note that they all must be for the same OpenSearch cluster, otherwise you'll have undefined behaviour! Example: opensearch:http://localhost:9200,http://localhost:9201,http://localhost:9202

Custom OpenSearchClient

If you wish to use any other form of authentication or have special requirements for the connection (e.g. not validate the TLS certificates) you have to construct your own OpenSearchClient and pass that to OpenSearchConnection. See CustomOpenSearchClientLiquibaseIT for a full example.

void main() {
    final var changeLogFile = "path/to/changelog.yaml";

    final var connection = new OpenSearchConnection(openSearchClient);
    ConnectionServiceFactory.getInstance().register(connection);
    final var database = new OpenSearchLiquibaseDatabase(connection);
    DatabaseFactory.getInstance().register(database);

    // execute the migration
    new CommandScope(UpdateCommandStep.COMMAND_NAME)
            .addArgumentValue(DbUrlConnectionArgumentsCommandStep.DATABASE_ARG, database)
            .addArgumentValue(UpdateCommandStep.CHANGELOG_FILE_ARG, changeLogFile)
            .execute();
}

OpenSearch Compatibility

liquibase-opensearch is currently compatible with OpenSearch 2.x and 3.x.

Versioning

This project adheres to Semantic Versioning.

Changelog

For the changelog please see the dedicated CHANGELOG.md.

License

This project is licensed under the Apache License Version 2.0 - see the LICENSE file for details.