Migration of Databases: Internal to External and External to Internal

Restoring a Backup on a New Instance

Important

When restoring a backup on a new instance, follow these steps to avoid errors and ensure proper functionality.

Address IP Configuration Issues

  • During restoration, the new instance may retain the IP address of the original instance.

  • If AutoMocking is enabled, update the IP address to match the new instance. Use the Maintenance Operations bulk-replace feature to ensure the new IP address matches the required settings for your environment.

Log Out Users Before Backup and Restore

  • Ensure all users log out before starting the backup or restore process.

  • If users remain logged in, they may encounter a TOKEN_UNKNOWN error and lose access to SwaggerHub.

  • To resolve this issue, users should clear their cookies and site data, and then log in again.

Match Product Versions

  • Restore backups only to the same version of SwaggerHub they were created on.

Maintain File Naming and Structure

  • Do not rename the  .tar files generated during backup.

  • Place all required files in the target directory without modifying their names. The restore script relies on these file names and their locations.

Use the Same Search Type

  • The search type on the new instance must match the search type used on the original instance. If they differ, the  registry-api will return a 500 status code.

Run Scripts with Correct Permissions

  • Depending on your environment, execute scripts as sudo or use an account with the required permissions.

Test Procedures Before Production

  • Test the backup and restore process in a non-production environment before applying it to production.

Handle External Database Configurations

  • If you use an external database, modify the backup-restore-external-db.sh script to accommodate your database's specifics.

  • SwaggerHub does not provide support for external database configurations.

Migration from an internal to external database

In order to migrate from an internal database to an external one, you need to first create a backup. Store it outside the SwaggerHub installation environment for retrieval after a critical failure.

After creating the internal database backup, follow the process of restoring it to an external database.

Create a backup of internal MongoDB and Postgres databases

  1. Download the following backup script and paste it to a machine that can access the cluster(s): https://maintenance.sonp.swaggerhub.com/backup-restore-dbs.sh

  2. Make the script privileges executable:

    chmod +x backup-restore-dbs.sh
  3. Create a directory to store the backup - for example, mkdir db-dump.

  4. Execute the script:

    ./backup-restore-dbs.sh dump <NAMESPACE> <PATH>

    The following parameters need to be defined in the script:

    • <NAMESPACE> - the existing location of SwaggerHub installation.

    • <PATH> - the intended location of the backup.

  5. Download the backup files from the remote server to your local machine.

    scp -rp -i ~/.ssh/key [email protected]:/home/ubuntu/db-dump/mongodb-dump.tar.gz ~/path/on/local/machine
    scp -rp -i ~/.ssh/key [email protected]:/home/ubuntu/db-dump/postgresql-dump.tar.gz ~/path/on/local/machine

Restore the backup of an internal database to an external one

  1. Transfer the backup files from your local machine to the remote server. For example:

    scp -rp -i ~/.ssh/key ./mongodb-dump.tar.gz [email protected]:/home/ubuntu
    scp -rp -i ~/.ssh/key ./postgresql-dump.tar.gz [email protected]:/home/ubuntu
  2. Download the following backup script and yaml files required for the script. Save these files to the EC2 instance where SwaggerHub is installed.

  3. Create the resources: dump-external-mongo.yaml and dump-external-postgres.yaml.

    kubectl apply -f ./dump-external-postgres.yaml
    kubectl apply -f ./dump-external-mongo.yaml
  4. Copy Mongo and Postgres backups to external Mongo and Postgres pods:

    kubectl cp mongodb-dump.tar.gz default/dump-external-mongodb:/bitnami/mongodb
    kubectl cp postgresql-dump.tar.gz default/dump-external-postgres:/bitnami/postgresql
  5. Make the script privileges executable:

    chmod +x backup-restore-external-db.sh
  6. Execute the script:

    ./backup-restore-external-db.sh restore <NAMESPACE>

    The following parameter needs to be defined in the script:

    • <NAMESPACE> - the existing location of SwaggerHub installation.

  7. Deploy a new sequence in Admin Console, for example, by changing any value in the config.

Migration from an external to internal database

To migrate from an external database to an internal one, you need to create a backup of the external database and then follow the process of restoring it to an internal database.

Create a backup of external MongoDB and Postgres databases

  1. Download the following backup script and paste it to a machine that can access the cluster:

  2. Make the script privileges executable:

    chmod +x backup-restore-external-db.sh
  3. Execute the script:

    ./backup-restore-external-db.sh dump <NAMESPACE>

    Define the following parameters in the script:

    • <NAMESPACE> - the existing location of SwaggerHub installation.

  4. Download the file backup files from the remote server to the local machine.

    scp -rp -i ~/.ssh/key [email protected]:/path/mongodb-dump.tar.gz ~/path/on/local/machine
    scp -rp -i ~/.ssh/key [email protected]:/path/postgresql-dump.tar.gz ~/path/on/local/machine

Restore the backup of an external database onto an internal one

  1. Transfer the backup files from the local machine to the remote server:

    scp -rp -i ~/.ssh/key ./postgresql-dump.tar.gz [email protected]:/home/ubuntu
    scp -rp -i ~/.ssh/key ./mongodb-dump.tar.gz [email protected]:/home/ubuntu
  2. Download the following backup script and yaml files required for the script. Save these files to the EC2 instance where SwaggerHub is installed.

  3. Make the script privileges executable:

    chmod +x backup-restore-dbs.sh
  4. Execute the script:

    ./backup-restore-dbs.sh restore <NAMESPACE> <PATH>

    Define the following parameters in the script:

    • <NAMESPACE> - the existing location of SwaggerHub installation.

    • <PATH> - the intended location of the backup.

  5. Deploy a new sequence in Admin Console, for example, by changing any value in the config.

Publication date: