From f6cee5161ed97b99608cd3fdddde8547304c641a Mon Sep 17 00:00:00 2001 From: Jake Newton Date: Tue, 4 Jun 2024 14:39:08 -0500 Subject: [PATCH 1/3] update readme with better formatting and add section on official image --- README.md | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 21507ff4..d1c922c1 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,25 @@ -# Official Liquibase Docker images -[![Docker Auto Build](https://img.shields.io/docker/cloud/automated/liquibase/liquibase)][docker] +## 🚨 Notice: New Official Liquibase Docker Image 🚨 -[docker]: https://hub.docker.com/r/liquibase/liquibase +We are excited to announce that a new Official Liquibase Docker image is now available at [https://hub.docker.com/_/liquibase](https://hub.docker.com/_/liquibase). We recommend all users start using this image for the latest updates and support. -This is the official repository for [Liquibase](https://download.liquibase.org/) images. +### Action Required + +Please update your Dockerfiles and scripts to pull from the new official image: + +```dockerfile +FROM liquibase:latest +``` + +```bash +docker pull liquibase +``` + +In the future, we will stop updating this community liquibase/liquibase Docker image repository. Please transition to the new official image to ensure you continue receiving updates and support. + +# Liquibase Docker images + +This is the community repository for [Liquibase](https://download.liquibase.org/) images. ## BREAKING CHANGE @@ -14,7 +29,7 @@ Support for Snowflake database has been moved from the external extension liquib The following tags are officially supported: -https://hub.docker.com/r/liquibase/liquibase/tags + ### liquibase: From 7be64fd4bc05d182664fae251bbf2bee3367efcc Mon Sep 17 00:00:00 2001 From: Jake Newton Date: Tue, 4 Jun 2024 14:39:48 -0500 Subject: [PATCH 2/3] update readme with better formatting and add section on official image --- README.md | 129 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 66 insertions(+), 63 deletions(-) diff --git a/README.md b/README.md index d1c922c1..9a8f7113 100644 --- a/README.md +++ b/README.md @@ -1,122 +1,129 @@ +# Official Liquibase Docker Images ## 🚨 Notice: New Official Liquibase Docker Image 🚨 -We are excited to announce that a new Official Liquibase Docker image is now available at [https://hub.docker.com/_/liquibase](https://hub.docker.com/_/liquibase). We recommend all users start using this image for the latest updates and support. +We are excited to announce that a new official Liquibase Docker image is now available at [https://hub.docker.com/_/liquibase](https://hub.docker.com/_/liquibase). We recommend all users to start using this image for the latest updates and support. -### Action Required +### 🔧 Action Required Please update your Dockerfiles and scripts to pull from the new official image: +## Dockerfile + ```dockerfile FROM liquibase:latest ``` +## Scripts + ```bash docker pull liquibase ``` -In the future, we will stop updating this community liquibase/liquibase Docker image repository. Please transition to the new official image to ensure you continue receiving updates and support. - -# Liquibase Docker images - -This is the community repository for [Liquibase](https://download.liquibase.org/) images. - -## BREAKING CHANGE +In the future, we will stop updating the community `liquibase/liquibase` Docker image. Transition to the new official image to ensure you continue receiving updates and support. -Support for Snowflake database has been moved from the external extension liquibase-snowflake into the main Liquibase artifact. This means that Snowflake is now included in the main docker image. If you are using the snowflake extension remove it from your lib directory or however you are including it in your project. If you are using the Docker image, use the main v4.12+ as there will no longer be a snowflake separate docker image produced. The latest separate Snowflake image will be v4.11. You need to update your reference to either latest to use the main one that includes Snowflake or the version tag you prefer. +For any questions or support, please visit our [Liquibase Community Forum](https://forum.liquibase.org/). -## Image Flavours +--- -The following tags are officially supported: +This is the community repository for [Liquibase](https://download.liquibase.org/) images. - +## 🚨 BREAKING CHANGE -### liquibase: +Support for Snowflake database has been moved from the external extension liquibase-snowflake into the main Liquibase artifact. This means that Snowflake is now included in the main docker image. If you are using the snowflake extension, remove it from your lib directory or however you are including it in your project. If you are using the Docker image, use the main v4.12+ as there will no longer be a snowflake separate docker image produced. The latest separate Snowflake image will be v4.11. You need to update your reference to either latest to use the main one that includes Snowflake or the version tag you prefer. -This `liquibase:` image is considered the standard choice. If you're uncertain about your specific requirements, it's recommended to opt for this image. It is designed to serve as a disposable container as well as a foundational building block for creating other images. +## 🏷️ Supported Tags -### liquibase:-alpine +The following tags are officially supported and can be found on [Docker Hub](https://hub.docker.com/r/liquibase/liquibase/tags): -The `liquibase:-alpine` image is a slimmed-down version of the Liquibase Docker container (`liquibase:`). It is designed to be lightweight and have a smaller footprint, making it suitable for environments with limited resources or when only the essential functionality is required. This image is built upon the popular [Alpine Linux](https://alpinelinux.org/) project, which can be found in the official Alpine image. Alpine Linux stands out for its significantly smaller size compared to other distribution base images, typically around **5MB**. As a result, it enables the creation of overall slimmer images. +- `liquibase/liquibase:` +- `liquibase/liquibase:-alpine` -If your main concern is minimizing the final image size, this flavor proves to be quite useful. However, it is important to note that certain software may encounter issues depending on their specific `libc` requirements or assumptions. +## 📦 Using the Docker Image -To keep the image size to a minimum, additional tools such as `git` or `bash` are not commonly included in Alpine-based images. Instead, you can utilize this image as a foundation and add the necessary components in your own Dockerfile. +### 🏷️ Standard Image -#### Extending liquibase:-alpine +The `liquibase/liquibase:` image is the standard choice. Use it as a disposable container or a foundational building block for other images. -To extend the functionality of the `liquibase:-alpine` image and include additional tools that are not included by default. Examples are provided in the [examples](/examples) directory as `Dockerfile.alpine.`. +For examples of extending the standard image, see the [standard image examples](https://github.com/liquibase/docker/tree/main/examples). -## Changelog File +### 🏷️ Alpine Image -The docker image has a /liquibase/changelog volume in which the directory containing the root of your changelog tree can be mounted. Your `--changeLogFile` argument should list paths relative to this. +The `liquibase/liquibase:-alpine` image is a lightweight version designed for environments with limited resources. It is built on Alpine Linux and has a smaller footprint. -The /liquibase/changelog volume can also be used for commands that write output, such as `generateChangeLog`. Note that in this case (where liquibase should write a new file) you need to specify the absolute path to the changelog, i.e. prefix the path with `/liquibase/changelog/`. +For examples of extending the alpine image, see the [alpine image examples](https://github.com/liquibase/docker/tree/main/examples). -### Changelog File Example +### 📄 Using the Changelog File -If you have a local `c:\projects\my-project\src\main\resources\com\example\changelogs\root.changelog.xml` file, you would run `docker run --rm -v c:\projects\my-project\src\main\resources:/liquibase/changelog liquibase/liquibase --changeLogFile=changelog/com/example/changelogs/root.changelog.xml update` +Mount your changelog directory to the `/liquibase/changelog` volume and use relative paths for the `--changeLogFile` argument. -To generate a new changelog file at this location, run `docker run --rm -v c:\projects\my-project\src\main\resources:/liquibase/changelog liquibase/liquibase --changeLogFile=changelog/com/example/changelogs/root.changelog.xml generateChangeLog` +#### Example -## Configuration File +```shell +docker run --rm -v /path/to/changelog:/liquibase/changelog liquibase/liquibase --changeLogFile=changelog.xml update +``` -If you would like to use a "default file" to specify arguments rather than passing them on the command line, include it in your changelog volume mount and reference it. +### ⚙️ Using a Configuration File -If specifying a custom liquibase.properties file, make sure you include `searchPath=/liquibase/changelog` so Liquibase will continue to look for your changelog files there. +To use a default configuration file, mount it in your changelog volume and reference it with the `--defaultsFile` argument. -### Configuration File Example +#### Example -If you have a local `c:\projects\my-project\src\main\resources\liquibase.properties` file, you would run `docker run --rm -v c:\projects\my-project\src\main\resources:/liquibase/changelog liquibase/liquibase --defaultsFile=liquibase.properties update` +```shell +docker run --rm -v /path/to/changelog:/liquibase/changelog liquibase/liquibase --defaultsFile=liquibase.properties update +``` -## Drivers and Extensions +### 📚 Including Drivers and Extensions -The Liquibase docker container ships with drivers for many popular databases. If your driver is not included or if you have an extension, you can mount a local directory containing the jars to `/liquibase/lib`. +Mount a local directory containing additional jars to `/liquibase/lib`. -### Driver and Extensions Example +#### Example -If you have a local `c:\projects\my-project\lib\my-driver.jar` file, `docker run --rm -v c:\projects\my-project\src\main\resources:/liquibase/changelog -v c:\projects\my-project\lib:/liquibase/lib liquibase/liquibase update` +```shell +docker run --rm -v /path/to/changelog:/liquibase/changelog -v /path/to/lib:/liquibase/lib liquibase/liquibase update +``` -### Notice for MySQL Users +### 🔍 MySQL Users -Due to licensing restrictions for the MySQL driver, this container does not ship with the MySQL driver installed. Two options exist for loading this driver: 1. Create a new container from the `liquibase/liquibase` image. 2. Load this driver during runtime via an environment variable. +Due to licensing restrictions, the MySQL driver is not included. Add it either by extending the image or during runtime via an environment variable. -### New Container Example +#### Extending the Image -Dockerfile +Dockerfile: ```dockerfile -FROM liquibase/liquibase +FROM liquibase RUN lpm add mysql --global ``` -Build +Build: ```shell -docker build . -t liquibase/liquibase-mysql +docker build . -t liquibase-mysql ``` -### Runtime Example +#### Runtime ```shell docker run -e INSTALL_MYSQL=true liquibase/liquibase update ``` -## Complete Examples +## 🛠️ Complete Example -### Specify everything via arguments +Here is a complete example using environment variables and a properties file: -`docker run --rm -v :/liquibase/changelog liquibase/liquibase --url="jdbc:sqlserver://:1433;database=;" --changeLogFile=com/example/changelog.xml --username= --password= --liquibaseProLicenseKey="" update` +### Environment Variables Example -Using with [Liquibase Pro Environment Variables](https://docs.liquibase.com/concepts/basic/liquibase-environment-variables.html) example: -`docker run --env LIQUIBASE_COMMAND_USERNAME --env LIQUIBASE_COMMAND_PASSWORD --env LIQUIBASE_COMMAND_URL --env LIQUIBASE_PRO_LICENSE_KEY --env LIQUIBASE_COMMAND_CHANGELOG_FILE --rm -v /changelogs:/liquibase/changelog liquibase/liquibase --log-level=info update` +```shell +docker run --env LIQUIBASE_COMMAND_USERNAME --env LIQUIBASE_COMMAND_PASSWORD --env LIQUIBASE_COMMAND_URL --env LIQUIBASE_PRO_LICENSE_KEY --env LIQUIBASE_COMMAND_CHANGELOG_FILE --rm -v /path/to/changelog:/liquibase/changelog liquibase/liquibase --log-level=info update +``` -### Using a properties file +### Properties File Example -*liquibase.docker.properties file:* +`liquibase.docker.properties` file: -```dockerfile +```properties searchPath: /liquibase/changelog url: jdbc:postgresql://:5432/?currentSchema= changeLogFile: changelog.xml @@ -125,13 +132,13 @@ password: liquibaseProLicenseKey= ``` -*CLI:* +CLI: -`docker run --rm -v :/liquibase/changelog liquibase/liquibase --defaultsFile=liquibase.docker.properties update` -or -`docker run --rm -v :/liquibase/changelog liquibase/liquibase --defaultsFile=liquibase.docker.properties --changeLogFile=changelog.xml generateChangeLog` (the argument `--changeLogFile` wins against the defaultsFile) +```shell +docker run --rm -v /path/to/changelog:/liquibase/changelog liquibase/liquibase --defaultsFile=liquibase.docker.properties update +``` -### Example JDBC Urls +## 🔗 Example JDBC URLs - MS SQL Server: `jdbc:sqlserver://:1433;database=` - PostgreSQL: `jdbc:postgresql://:5432/?currentSchema=` @@ -139,11 +146,7 @@ or - MariaDB: `jdbc:mariadb://:3306/` - DB2: `jdbc:db2://:50000/` - Snowflake: `jdbc:snowflake:///?db=&schema=` -- Sybase `jdbc:jtds:sybase://:/` +- Sybase: `jdbc:jtds:sybase://:/` - SQLite: `jdbc:sqlite:/tmp/.db` -Note: If the database IP refers to a locally running docker container then one needs to specify host networking like `docker run --network=host -rm -v ...` - -### Adding Native Executors - -The recommended path for adding native executors/binaries such as Oracle SQL*Plus, Microsoft SQLCMD, Postgres PSQL, or the AWS CLI is to extend the liquibase/liquibase Dockerfile. Examples are provided in the [Examples](https://github.com/liquibase/docker/tree/main/examples) Directory. +For more details, visit our [Liquibase Documentation](https://docs.liquibase.com/). \ No newline at end of file From e58a5021213f4a11fcb753dfa7d48ad3d3b808c1 Mon Sep 17 00:00:00 2001 From: Jake Newton Date: Tue, 4 Jun 2024 14:48:31 -0500 Subject: [PATCH 3/3] update readme with better formatting and add section on official image --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9a8f7113..04210f2b 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ ## 🚨 Notice: New Official Liquibase Docker Image 🚨 -We are excited to announce that a new official Liquibase Docker image is now available at [https://hub.docker.com/_/liquibase](https://hub.docker.com/_/liquibase). We recommend all users to start using this image for the latest updates and support. +We are excited to announce that a new official Liquibase Docker image is now available at [https://hub.docker.com/_/liquibase](https://hub.docker.com/_/liquibase) starting with liquibase 4.27.0 and newer. We recommend all users to start using this image for the latest updates and support. Any versions prior to 4.27.0 will only be available on the existing `liquibase/liquibase` community image. ### 🔧 Action Required @@ -149,4 +149,4 @@ docker run --rm -v /path/to/changelog:/liquibase/changelog liquibase/liquibase - - Sybase: `jdbc:jtds:sybase://:/` - SQLite: `jdbc:sqlite:/tmp/.db` -For more details, visit our [Liquibase Documentation](https://docs.liquibase.com/). \ No newline at end of file +For more details, visit our [Liquibase Documentation](https://docs.liquibase.com/).