Work with an external database

Mikhail Serov

ADCM supports operations with external databases. In particular, PostgreSQL databases are supported.

IMPORTANT
A standalone PostgreSQL database is recommended for use in the product environment.

Configuration

The prerequisites to use the external PostgreSQL database are:

  • The user, the database, and the user password must be created (DATABASE_USERNAME, DATABASE_NAME, DATABASE_USER_PASSWORD in the example below).

  • The user must be the owner of the external PostgreSQL database.

CREATE USER <DATABASE_USERNAME> with encrypted password '<DATABASE_USER_PASSWORD>';
CREATE DATABASE <DATABASE_NAME> OWNER <DATABASE_USERNAME>;

Example of running ADCM with the PostgreSQL database:

$ sudo docker run -d --restart=always -p 8000:8000 -v /opt/adcm:/adcm/data -e DB_HOST="10.92.40.190" -e DB_PORT="5432" -e DB_USER="admin" -e DB_NAME="postgres" -e DB_PASS="admin" --name adcm hub.arenadata.io/adcm/adcm:<version> -e DB_OPTIONS="<DATABASE_OPTIONS>"

where <version> is a desired ADCM image version in one of the following formats:

  • <major>.<minor>.<patch> — if you need a specific ADCM patch. For example, 2.0.0.

  • <major>.<minor> — if you need the last patch within the selected ADCM version. For example, 2.0.

You can use DB_OPTIONS to establish an SSL connection to the database. For more information about the parameters available for the DB_OPTIONS variable, see the Installation article.

Prepare the SSL certificate and secret key files and place them into <data_volume>/conf/ssl/. Then, list the DB_OPTIONS parameters in JSON format:

DB_OPTIONS='{"sslmode": "verify-full", "sslcert": "/adcm/data/conf/ssl/client.crt", "sslkey": "/adcm/data/conf/ssl/client.key", "sslrootcert": "/adcm/data/conf/ssl/server.crt"}'
IMPORTANT

  • latest was used for earlier versions of ADCM and is no longer supported starting from version 2.0.0.

  • Before ADCM 2.0.0, the following format was used for versioning: YYYY.MM.DD.HH.

Use -v /opt/adcm:/adcm/data:Z for SELinux.

Migration

IMPORTANT

  • Starting with version 2.7.0, ADCM no longer supports SQLite.

  • ADCM migration feature is available up to version 2.6.0 inclusively and not supported for ADCM versions 2.7.0 and higher.

  • Migration must be performed within a single version of ADCM.

ADCM includes tools for data migration from SQlite to PostgreSQL. This functionality is supported from the version 2023.03.27.20 onwards. The functionality is useful if you have upgraded ADCM to the newest version and want to start using PostgreSQL.

To migrate from a source SQlite database to a target PostgreSQL database, you must fully prepare the target PostgreSQL database first.

After you have updated the ADCM docker container to the newest version, you can migrate from SQLite to PostgreSQL via the following commands:

  1. Dump the SQLite database to a file:

    $ docker exec -it adcm /adcm/python/manage.py dumpdata --natural-foreign --natural-primary -o /adcm/data/var/data.json

    where -o specifies the file path.

    Essentially, this command requests all data from the SQlite database, then creates a JSON representation of that data, and places it to the specified file system location as a data.json file.

  2. Stop the ADCM container:

    $ docker stop adcm
$ docker rm adcm

  3. Start the ADCM container in MIGRATION_MODE:

    $ docker run -d --restart=always -p 8000:8000 -v /opt/adcm:/adcm/data
-e DB_HOST="<DATABASE_HOSTNAME_OR_IP_ADDRESS>" -e DB_PORT="<DATABASE_TCP_PORT>"
-e DB_USER="<DATABASE_USERNAME>" -e DB_NAME="<DATABASE_NAME>"
-e DB_PASS="<DATABASE_USER_PASSWORD>" -e MIGRATION_MODE=1
--name adcm hub.arenadata.io/adcm/adcm:<version>

    where <version> is a desired ADCM image version in one of the following formats:

    • <major>.<minor>.<patch> — if you need a specific ADCM patch. For example, 2.0.0.

    • <major>.<minor> — if you need the last patch within the selected ADCM version. For example, 2.0.

    IMPORTANT

    • latest was used for earlier versions of ADCM and is no longer supported starting from version 2.0.0.

    • Before ADCM 2.0.0, the following format was used for versioning: YYYY.MM.DD.HH.

    For SELinux, use -v /opt/adcm:/adcm/data:Z.

    Starting the ADCM container like this, you obtain an empty ADCM instance that has not yet been filled with data.

  4. Load the data from a file to the PostgreSQL database:

    $ docker exec -it adcm /adcm/python/manage.py loaddata /adcm/data/var/data.json

  5. Stop the ADCM container:

    $ docker stop adcm
$ docker rm adcm

  6. Start the ADCM container:

    $ docker run -d --restart=always -p 8000:8000 -v /opt/adcm:/adcm/data
-e DB_HOST="<DATABASE_HOSTNAME_OR_IP_ADDRESS>" -e DB_PORT="<DATABASE_TCP_PORT>"
-e DB_USER="<DATABASE_USERNAME>" -e DB_NAME="<DATABASE_NAME>"
-e DB_PASS="<DATABASE_USER_PASSWORD>" -e MIGRATION_MODE=0
--name adcm hub.arenadata.io/adcm/adcm:<version>
Found a mistake? Seleсt text and press Ctrl+Enter to report it