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
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
Make the script privileges executable:
chmod +x backup-restore-dbs.sh
Create a directory to store the backup - for example,
mkdir db-dump
.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.
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
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
Download the following backup script and yaml files required for the script. Save these files to the EC2 instance where SwaggerHub is installed.
Create the resources:
dump-external-mongo.yaml
anddump-external-postgres.yaml
.kubectl apply -f ./dump-external-postgres.yaml kubectl apply -f ./dump-external-mongo.yaml
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
Make the script privileges executable:
chmod +x backup-restore-external-db.sh
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.
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
Download the following backup script and paste it to a machine that can access the cluster:
Make the script privileges executable:
chmod +x backup-restore-external-db.sh
Execute the script:
./backup-restore-external-db.sh dump <NAMESPACE>
Define the following parameters in the script:
<NAMESPACE>
- the existing location of SwaggerHub installation.
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
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
Download the following backup script and yaml files required for the script. Save these files to the EC2 instance where SwaggerHub is installed.
Make the script privileges executable:
chmod +x backup-restore-dbs.sh
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.
Deploy a new sequence in Admin Console, for example, by changing any value in the config.