Switching Kyvos Repository

Applies to: Kyvos Enterprise  Kyvos Cloud (SaaS on AWS) Kyvos AWS Marketplace

Kyvos Azure Marketplace   Kyvos GCP Marketplace Kyvos Single Node Installation (Kyvos SNI)

The section provides information on the following:

• Important points

• Using Database dump commands

• Switching repository

• From Kyvos 2025.10 onwards, heterogeneous repository types are no longer supported.

• Switching will only be allowed across repository types same as Kyvos Manager. Switching Kyvos repository to a repository type which is not the same as Kyvos Manager is not supported. If you want to change the repository type for Kyvos, first change the repository type for Kyvos Manager.

• You can see the last operation details, including progress status and start time, by clicking the i icon. To view more comprehensive details, simply click the View Details link, which will take you to the Operations page, where you can view the operation information in detail. 

• To avoid semantic model data loss, ensure that before switching ensure property “OBSOLETE_CUBE_PURGE_FREQUENCY“ is set in biserver.properties by increasing the value for it to desired frequency value in which verification that switching worked well can be complete. 

• If the target repository password is different then only for connection testing purposes password can be specified in provided optional input. If not specified explicitly, Kyvos Manager will use the existing password configured in the system for validating the connection. This is not applicable to GCP.

• Before switching the repository ensure that you have data ready in the target Postgres instance to which you are switching.

• Dump import and export can be done using pgdump and psql. However, in case of external to external repository change service on the snapshot offered by the cloud can be used to take snapshot from source Postgres and restore it in destination Postgres.

• Username and Password and database name in target Postgres instance to which switching to is expected to be same as that of current in-use Postgres instance.

• Rollback Scenario: If after an upgrade, the repository is switched then before performing rolling back, ensure it is switched back to the original repository.

• Permissions required in role attached on Kyvos Manager node remains same as that of required for automated deployed in case of external repository thus for switching from external repository to external repository no additional permission is required in the role added on Kyvos Manager node.

• For switching from bundled to an external repository, you need to add permission on the role attached to the Kyvos Manager node so that fetch or external repository details work. If permission is not added to the role, then the Fetch Details will not work. However, you can still proceed ahead by providing those details manually on provided UI inputs.

• If switching to an external repository, then proper network access should be configured.

• The security group must have a role granting access to the port used by external repo from Analytical Server and Kyvos Manager node if it is in the same region and resource group (For Azure Postgres) as that of the cluster.

• Following tags are expected on the external repository:

  • UsedBy - Kyvos

  • ROLE - DATABASE

  • LAYER - Metadata_Storage

• For GCP CloudSQL, the following privileges required while importing dump to external repository:
  GRANT ALL PRIVILEGES ON DATABASE your_database_name TO your_username;
  GRANT new_owner TO current_user WITH SET TRUE;
  GRANT kmdbuser TO postgres WITH SET TRUE;

Before importing, if database is not created automatically, you must manually create database first using create database command

Execute one of the following commands:

The following tables describes the sample commands. This is ONLY for reference.

The following tables describes the sample commands. This is ONLY for reference.

The section provides information on the following:

• Switching from bundled repository to external repository

• Switching from external repository to another external repository

• Switching from an external repository to bundled repository

• Switching to a new bundled repository (recovered state) from the bundled repository (for Disaster Recovery)

• Switching Repository from External PostgreSQL to Installed PostgreSQL

• Switching Repository from Installed PostgreSQL to External PostgreSQL

• Switching from Bundled PostgreSQL 13 to the installed PostgreSQL 16

• Switching from installed PostgreSQL 16 to Bundled PostgreSQL 13

In the case of a cloud environment, you can switch to an external repository. 

1. Export data from bundled Postgres.

2. Import the data exported from step #1 above, in the new Postgres instance (AWS RDS or Azure Postgres) running on the cloud.

3. On the Kyvos Manager, navigate to Utilities > Manage Kyvos Repository.

4. On the page, select the External Repository option (by default, the Bundled Postgres-Server is selected)  

5. Enter details as:

7. Click the Automatically Start or Stop checkbox.

8. Perform repository connection validation using Test Connection link.
   NOTE: In case of any problem with the test connection, you will see an error message. Fix those problems before proceeding with switching the repository.

9. Once the connection is validated successfully, click the Save button. This will configure new Postgres as a repository for Kyvos.

10. Restart the Analytical Server service.

1. Export data from the current configured external Postgres repository (AWS RDS or Azure Postgres) running on the cloud.

2. Import the data exported in above step-1 to the new target external Postgres instance (AWS RDS or Azure Postgres) running on the cloud.

3. On the Kyvos Manager, navigate to Utilities > Manage Kyvos Repository.

4. On the Manage Repository page, provide the details of the external repository you use.

5. Enter details as:

6. Perform repository connection validation using Test Connection link.
   NOTE: In case of any problem with the test connection, you will see an error message. Fix those problems before proceeding with switching the repository.

7. Once the connection is validated successfully, click the Save button. This will configure a new Postgres as a repository for Kyvos.

8. Restart the Analytical Server service.

1. Export data from external Postgres (Azure Postgres or GCP CloudSQL).

2. In an existing cluster, identify the target node for running bundled Postgres and start the Postgres service on that target node.

3. On the navigation bar, click Utilities > Manage Kyvos Repository.

4. On the Manage Kyvos Repository page, select the Bundled Postgres Repository option (by default, Bundled Postgres will be shown selected).

   Open

   

5. Select that cluster node from the dropdown on which the data dump is imported in step #2 above.

6. If needed, select the Restore Database Dump option to restore a dump of the Postgres database.

   1. Locate Dump data from:

      1. Restore data from last backup: Select this option to get the data restored from the last created backup.

      2. Upload data dump file: Select this option to upload a previously saved data dump file.

7. Perform repository connection validation using Test Connection link.
   NOTE: In case of any problem with the test connection, you will see an error message. Fix those problems before proceeding with switching the repository.

8. Once the connection is validated successfully, click the Save button. This will configure new Postgres as a repository for Kyvos.

9. Restart the Analytical Server service.

The following procedure is required in Kyvos Manager node Disaster Recovery case. When the bundled Postgres was configured on Kyvos Manager node.

1. Download data dump from DFS.

2. In an existing cluster, identify the target node for running bundled Postgres and start the Postgres service on that target node, and import that data into that Postgres instance which was downloaded as a dump from DFS in step #1.

3. On the Kyvos Manager, navigate to Utilities > Manage Kyvos Repository.

4. On the Manage Repository page, select the Bundled Postgres Repository option (by default external repository will be shown selected).

5. Provide details for the target External repository.

6. Perform repository connection validation using Test Connection link.
   NOTE: In case of any problem with the test connection, you will see an error message. Fix those problems before proceeding with switching the repository.

7. Once the connection is validated successfully, click the Save button. This will configure new Postgres as a repository for Kyvos.

8. Restart the Analytical Server service.

This document describes the procedure for switching both Kyvos Manager (KM) and Kyvos repositories from an external PostgreSQL instance to an installed PostgreSQL service (version 16). The activity involves stopping Kyvos and Kyvos Manager services, exporting and importing database dumps, updating configurations, and validating the migration.

Step 1: Preparatory Actions

1. Update the passwords for both Kyvos Manager and Kyvos external repositories to match the default passwords used for the installed Kyvos Manager and Kyvos repositories.

2. Install PostgreSQL 16 service: On the Kyvos Manager node, run the ./configure-postgres16.sh command with sudo user to install PostgreSQL 16 using the Kyvos-provided shell script. Ensure that the PostgreSQL service is running at: sudo systemctl status postgresql post installation.

3. Use installed PostgreSQL commands: All PostgreSQL-related commands (for dump export and import) should be executed from the installed PostgreSQL directory.

1. Export database dumps

   • Take separate dumps of the Kyvos Manager and Kyvos databases from the external repository using the pg_dump utility.

   • Use a PostgreSQL version up to 16.9.

   • Do not use version 16.10 or above, as additional manual edits (removal of unsupported \restrict and \unrestrict entries) will be required in the dump files.

   Example command: pg_dump -U <username> -h <external_host> -p <port> -d <database_name> -f <dump_file_path>

2. Import database dumps into installed PostgreSQL

   • Import the KM and Kyvos dumps into the installed PostgreSQL service using the psql command.

   • Always use postgres as the user (-U postgres) during import.
     Example command: psql -U postgres -d <target_database> -f <dump_file_path>
     Note: Any compatibility changes required previously for PostgreSQL 13 are no longer needed, as the installed PostgreSQL version is 16.

3. TLS Configuration (If Applicable): If TLS is enabled in the deployed cluster using the bundled PostgreSQL, perform the following steps:

   1. Copy the certificate files server.crt and server.key from <bundled_pg_base_path>/postgres/data/ to <installed_pg_data_dir> to the data directory of the installed PostgreSQL.

   2. Change ownership using sudo chown postgres:postgres /var/lib/pgsql/data/<file-name>.

   3. Enable SSL in postgresql.conf: ssl=on

   4. Update the following properties in postgresql.conf:

      ssl_cert_file = '<certificate_file_name>' ssl_key_file = '<key_file_name>'

   5. Restart the installed PostgreSQL 16 service after making the above changes.

4. Update KM configuration: In the jdbc.properties file, update the installedRepo=true parameter before starting Kyvos Manager:

   1. Remove or update any repoIdentifier or outdated repository URL entries as per the installed PostgreSQL connection configuration.

   2. Push the following from Kyvos Manager:

      1. KM data snapshot

      2. disaster-recovery.sh snapshot

5. Update symbolic link on cluster nodes

   1. On each cluster node:

      1. Move the existing postgres folder outside the kyvos directory.

      2. Create a soft link inside the kyvos directory pointing to the relocated postgres folder.
         Example command:

      ln -s /path/to/postgres /path/to/kyvos/postgres

6. Step 4: Switch Repository for Kyvos

   1. Using the Kyvos Manager UI, perform the Switch Repository operation for Kyvos.

   2. During this process, Kyvos Manager will automatically update the configuration parameters for Kyvos to point to the installed PostgreSQL repository.

• Start Kyvos Manager and verify that it connects successfully to the installed PostgreSQL repository.

• Start Kyvos cluster services and validate connectivity for both KM and Kyvos repositories.

• Confirm that all repository-dependent functionalities operate as expected.

• Stop all Kyvos services.

• Stop Kyvos Manager.

• Ensure you have access to both installed and external PostgreSQL servers.

• Use pg_dump version 16.9 or lower. (Do not use version 16.10 or higher — remove \restrict and \unrestrict entries if already used.)

• Ensure the KM and Kyvos repository passwords in installed PostgreSQL are the same as those configured in the external PostgreSQL.

Step 1: Switch Kyvos Manager Repository

1. Export KM Repository Dump

   pg_dump -U postgres -h <installed_host> -p <port> -d <kyvos_database> -f <kyvos_dump_path> -or- ./pg_dump -c -C --host=localhost --port=45421 --dbname=delverepo --user=postgres > kyvosdbdump.sql

2. Import Dump to External PostgreSQL

   psql -U postgres -h <external_host> -p <port> -d <km_database> -f <km_dump_path>

3. Update Kyvos Manager Configuration

   1. Open the jdbc.properties file from the Kyvos Manager configuration path.

   2. Update or add the following:

      installedRepo=false repoIdentifier=<external_repo_identifier> jdbc.url=<external_postgres_jdbc_url>

   3. Save the file.

4. Start Kyvos Manager

   1. Start the Kyvos Manager service.

   2. Verify that it connects successfully to the external PostgreSQL repository.

Step 2: Switch Kyvos Repository

1. Export Kyvos Repository Dump

   pg_dump -U postgres -h <installed_host> -p <port> -d <kyvos_database> -f <kyvos_dump_path> -or- ./pg_dump -c -C --host=localhost --port=45421 --dbname=delverepo --user=postgres > kyvosdbdump.sql

2. Import Dump to External PostgreSQL

   psql -U postgres -h <external_host> -p <port> -d <kyvos_database> -f <kyvos_dump_path>

3. Switch Repository for Kyvos (via KM UI)

   • Log in to Kyvos Manager.

   • Go to Configuration → Repository → Switch Repository.

   • Select External Repository.

   • Provide external PostgreSQL connection details.

   • Click Switch Repository.

4. Automatic Configuration Update

   • Kyvos Manager automatically updates Kyvos configuration for external PostgreSQL.

   • No manual edits are required.

Step 3: Post-Switch Activities

1. Stop Installed PostgreSQL Service

   sudo systemctl stop postgresql

2. Push KM Data

   • From Kyvos Manager, push KM data and disaster-recovery.sh snapshots.

3. Verify Connections

   • Ensure both Kyvos and Kyvos Manager are connected to the external PostgreSQL repository.

   • Validate by checking repository-related operations (e.g., connection test, configuration changes).

• Confirm that Kyvos Manager successfully connects to the external PostgreSQL repository.

• Verify that Kyvos services are also connected to the external PostgreSQL repository.

• Check that all repository-related operations (like saving configuration or switching repositories) work correctly.

• Ensure that the installed PostgreSQL service is stopped after the switch.

• Validate that all data and configurations are consistent and no information is missing after migration.

Perform the following manual steps after completing both Kyvos Manager and Kyvos upgrades.

1. Pre-Migration Checks

   1. If Kyvos Manager and Kyvos are using heterogeneous repositories (e.g., one external and one bundled):

      • The component using an external repository must first be moved to a bundled repository.

      • For Kyvos repository, switch the repository to migrate to the bundled repository.

      • For Kyvos Manager repository, perform the migration manually, including updating the jdbc.properties file.

   2. Disable PostgreSQL Component HA (High Availability) by removing all Standby PostgreSQL roles if HA is enabled in the cluster.

   3. Migrate PostgreSQL Role and ensure the PostgreSQL master role is present on the Kyvos Manager node.

   4. Reset Repository Passwords from the Kyvos Manager. Reset both Kyvos Manager repository and Kyvos repository passwords to their default values (if not already set to defaults).

2. Stop Services

   1. Stop cluster services from the Kyvos Manager.

   2. Stop the Kyvos Manager service.

3. Export existing Database Dumps

   1. From the node where the bundled PostgreSQL service is running (default: KM node), export separate database dumps for:

      1. Kyvos Manager database: kmrepo

      2. Kyvos databases: delverepo and usagerepo

4. Install PostgreSQL 16

   1. Stop the bundled PostgreSQL service on the node.

   2. Install PostgreSQL 16 on the same node (default: KM node) by running the installation shell configure-postgres16.sh script. You must execute this script using sudo or root privileges. This script automatically starts the PostgreSQL 16 service. Ensure the bundled PostgreSQL service is stopped before running the installation script and verify that the new PostgreSQL 16 service is running successfully

   3. Verify that the database names, usernames, passwords, and ports for the new PostgreSQL 16 service match those used in the bundled PostgreSQL setup.

5. Import Database Dumps: Import the previously exported kmrepo, delverepo, and usagerepo dumps into the installed PostgreSQL 16 databases.

6. TLS Configuration (If Applicable): If TLS is enabled in the deployed cluster using the bundled PostgreSQL, perform the following steps:

   1. Copy the certificate files server.crt and server.key from <bundled_pg_base_path>/postgres/data/ to <installed_pg_data_dir> to the data directory of the installed PostgreSQL.

   2. Change ownership using sudo chown postgres:postgres /var/lib/pgsql/data/<file-name>.

   3. Enable SSL in postgresql.conf: ssl=on

   4. Update the following properties in postgresql.conf:

      ssl_cert_file = '<certificate_file_name>' ssl_key_file = '<key_file_name>'

   5. Restart the installed PostgreSQL 16 service after making the above changes.

7. Update the Kyvos Manager jdbc.properties file with:

   installedRepo=true repoInstallationDataDirPathPrefix=/var/lib/pgsql

8. On the KM node, modify the file <KYVOS_INSTALL_PATH>/kyvosmanageragent/conf/services/Kyvos.xml In the file, change <type>pid</type> to <type>ps</type> for the PostgreSQL service.

9. Start Kyvos Manager.

10. Update POSTGRESS_INSTALLATION_TYPE=INSTALLED in kyvos-pg-back.sh located at kyvos/postgres/bin (ideally on each node, at least on KM node)

    (Apply on all nodes, at least on the KM node.)

11. Update postgres version as 16.9 in DemoDBRepository.xml

12. Push the following snapshots:

    • BI Connection configuration

    • Kyvos Manager data

    • disaster-recovery.sh

13. Optional: Change Repository Passwords: If required, update the repository passwords for both Kyvos Manager and Kyvos repositories (from their default values set in Step 1) through the Kyvos Manager.

Refer to the Switch Repository Dump section for detailed instructions on compatible dump preparation.

• Remove unsupported parameters such as: LOCALE_PROVIDER = libc

• Import the modified Kyvos Manager and Kyvos database dumps into the respective databases of the bundled PostgreSQL 13 service.

• TLS Configuration (If Applicable): If TLS is enabled in the deployed cluster using the installed PostgreSQL, perform the following steps to reconfigure TLS for the bundled PostgreSQL:

  1. Copy the certificate files server.crt and server.key from <installed_pg_data_dir> to <bundled_pg_base_path>/postgres/data/ to reconfigure TLS for the bundled PostgreSQL:

  2. Change ownership of these files to the Kyvos cluster deployment user using sudo chown <kyvos_user>:<kyvos_user> <file_name>

  3. Enable SSL in the bundled PostgreSQL configuration file (postgresql.conf)

  4. Update the following properties in postgresql.conf:

     ssl_cert_file = '<certificate_file_name>' ssl_key_file = '<key_file_name>'

• Restart the bundled PostgreSQL service after making the above changes.

• Update the Kyvos Manager jdbc.properties file as follows: installedRepo=false

• Ensure all bundled PostgreSQL group-related properties are correctly updated, particularly: homePathBundledRepo=/data/kyvos/app/postgres/

1. On the KM node, update the <KYVOS_INSTALL_PATH>/kyvosmanageragent/conf/services/Kyvos.xml file. In the file, change <type>ps</type> to <type>pid</type> for the PostgreSQL service. If the parameter pidFile is not already present, add it under the PostgreSQL service section:

   <param> <name>pidFile</name> <value>/data/kyvos/app/kyvos/postgres/data/postmaster.pid</value> </param>

   Here, <KYVOS_INSTALL_PATH> is /data/kyvos/app/.

2. Stop the bundled PostgreSQL service if it is already running, to ensure clean configuration reload.

3. Start the Kyvos Manager service.

4. In the kyvos/postgres/bin/kyvos-pg-back.sh file, update the parameter, POSTGRESS_INSTALLATION_TYPE=BUNDLED. Apply on all nodes, or at least on the Kyvos Manager node.

5. In the DemoDBRepository.xml file, update the PostgreSQL version to 13.

6. Push the following snapshots from Kyvos Manager:

   • BI Connection configuration

   • Kyvos Manager data

   • disaster-recovery.sh

7. Post-Migration Step: If required, update the Kyvos Manager repository and Kyvos repository passwords from their default values (set earlier in Step 1) using the Kyvos Manager.