Upgrading SlashDB 1.8.x to 2.0.x

Important

Before upgrading, make sure you have a valid license key for version 2.0.x
SlashDB 2.0.x supports Python v3.9 - 3.12

Note

If you have set the SlashDB INI parameter slashdb_env to a custom directory, replace any instances of /etc/slashdb in this document with the custom directory.

General Upgrade Notes

Configuration Files Permissions

Files in the /etc/slashdb folder should have the following permissions:

[root@8fc37589d913 /]# ls -l /etc/slashdb/
total 48
-rw-rw---- 1 root    slashdb 2349 Jul 22 11:23 auth.cfg
-rw-rw---- 1 slashdb slashdb  382 Jul 22 11:23 databases.cfg
-rw-rw---- 1 slashdb slashdb  468 Jul 22 11:23 license.key
-rw-r--r-- 1 root    root    4927 Jul 22 11:23 nginx.conf
-rw-rw---- 1 slashdb slashdb 4661 Jul 22 11:23 querydefs.cfg
-rw-r--r-- 1 slashdb slashdb    0 Jul 22 11:23 regular-initial
drwxr-xr-x 2 root    root    4096 Aug 23 12:48 sites-available
drwxr-xr-x 2 root    root    4096 Jul 22 11:23 sites-enabled
-rw-rw---- 1 root    slashdb 6055 Jul 22 11:23 slashdb.ini
-rw-rw---- 1 slashdb slashdb  474 Jul 22 11:23 users.cfg

RPM / DEB Packages

You have two options to perform the upgrade:

Installing Over an Existing Installation

can be faster for upgrading existing hosts
manual edits of certain configuration files may be required

Installing On a New System

Important

If you choose this option, you will need to copy the config files from the existing installation.

best for creating a new "golden image" or new client instance
avoids stale components or application files whose locations might have changed
reduces downtime
does not affect production if any issues are encountered during the installation

Installing Over Existing Installation

1. Obtain and install the latest RPM/DEB on the system

Important

Before you start, create a snapshot image of the existing instance in case something goes wrong and the instance needs to be restored quickly.

Download the 2.0.x installer package:

RPM https://downloads.slashdb.com/versions/2.0.1/slashdb-2.0.1.x86_64.rpm
DEB https://downloads.slashdb.com/versions/2.0.1/slashdb_2.0.1_amd64.deb

Info

These links are for SlashDB v2.0.1. If you need another version, replace the version number in the link with the specific version you want to download.

Red Hat Linux/RPM upgrade

cd /tmp
wget https://downloads.slashdb.com/versions/2.0.1/slashdb-2.0.1.x86_64.rpm
sudo su
yum upgrade ./slashdb-2.0.1.x86_64.rpm

Ubuntu/Debian/DEB upgrade

cd /tmp
wget https://downloads.slashdb.com/versions/2.0.1/slashdb_2.0.1_amd64.deb
sudo su
apt-get --only-upgrade install ./slashdb_2.0.1_amd64.deb

Important

The following database connectors are no longer part of the core package and now need to be installed separately:
IBM DB2, Microsoft SQL Server, Oracle, MariaDB, MySQL, PostgreSQL and SQLCipher.

See Database Connectors for installation instructions.

Info

You will need to install and configure an Oracle client for your system, following these steps:

2. Review and update the slashdb.ini file as needed, as well as any other config files that were customized

Immediately after upgrading with the 2.0.x package, SlashDB will automatically start and use the existing configuration files from the v1.8.x instance.

The new instance will be in initial setup mode, which requires visiting the web UI and going through the Welcome wizard:

providing license details
(Depending on the configuration, you might need to first select the "Development" license and then upload the production license throug the license page.)
accepting terms & conditions
setting the admin password

Note

Alternatively, this can be done in the backend. After upgrading with the new package:

remove the file /etc/slashdb/regular-initial
enter a valid license in the file /etc/slashdb/license.key. You can find the original license that was used in the 1.8.x deployment in a file with a datetime stamp in it e.g. license-202208241610.key.

These configuration files are automatically updated:

/etc/slashdb/databases.cfg
/etc/slashdb/querydefs.cfg
/etc/slashdb/auth.cfg

Important

To update the users.cfg file, you'll need to run this command once:

/opt/slashdb/bin/slashdb_tools hash-api-keys /etc/slashdb/slashdb.ini

This will hash all user API keys.

Important

These configuration files may require manual review and editing:

/etc/slashdb/slashdb.ini
/etc/slashdb/nginx.conf
files in /etc/slashdb/sites-available and /etc/slashdb/sites-enabled

They may be different in the newer version and won't be updated automatically. For these files, if a corresponding file with the suffix .rpmnew exists, it must be compared using a tool like sdiff and any differences resolved manually.

See the Config File Changes Since Last Version section for more info.

If changes were made to any of the configuration files, restart the SlashDB service:

systemctl restart slashdb

Installing On New System

1. Create backups of the SlashDB configuration files from the old system

On the existing SlashDB 1.8.x instance:

Create backups of the SlashDB configuration and sites directories:

cp /etc/slashdb ~/backups/v1.8.x/etc/slashdb
cp /var/lib/slashdb ~/backup/v1.8.x/var/lib/slashdb/sites

Transfer these backups to the new system

2. Obtain and install the latest RPM/DEB on the new system

On the new system:

perform normal installation of the v2.0.x package as per the documentation
install and configure an Oracle client, following these steps:
- Oracle for Red Hat or Oracle Linux
- Oracle for Debian or Ubuntu

3. Overwrite the new system's SlashDB configuration files with the backups from the old system

Transfer and replace some of the configuration files:

make a local backup of the configuration files of the new installation:
```
cp -r /etc/slashdb ~/backups/clean-v2.0.x
```
This will be needed to resolve differences between v1.8.x and v2.0.x in some of the configuration files.
remove the SlashDB configuration directory /etc/slashdb on the new machine:
```
rm -r /etc/slashdb
```
Copy the 1.8.x instance backups to the /etc/slashdb and /var/lib/slashdb directories
```
cp ~/backups/v1.8.x/etc/slashdb /etc/slashdb    
cp ~/backup/v1.8.x/var/lib/slashdb/sites /var/lib/slashdb
```
Warning

Don’t copy or overwrite folders /var/lib/slashdb/www and /var/lib/slashdb/templates. These contain web UI files and must match the installed version.
update /etc/slashdb/license.key with a valid 2.0.x license

These configuration files are automatically updated:

/etc/slashdb/databases.cfg
/etc/slashdb/querydefs.cfg
/etc/slashdb/auth.cfg

Important

To update the users.cfg file, you'll need to run this command once:

/opt/slashdb/bin/slashdb_tools hash-api-keys /etc/slashdb/slashdb.ini

This will hash all user API keys.

4. Review and update the slashdb.ini file as needed, as well as any other config files that were customized

Important

The configuration files below may require manual review and editing:

/etc/slashdb/slashdb.ini
/etc/slashdb/nginx.conf and
files in /etc/slashdb/sites-available and /et/slashdb/sites-enabled

These files may be different in the newer version and won't be updated automatically. They must be compared with files in ~/backups/clean-v1.8.x using a tool like sdiff and any differences resolved manually.

See the Config File Changes Since Last Version section for more info.

5. Reassign the IP address/hostname to the new system and shut down the old one

resassign IP address/hostname to the new system
restart the SlashDB service:

systemctl restart slashdb

Docker

To migrate a SlashDB 1.8.x Docker container to SlashDB 2.0.x, the simplest approach is to move the Docker volumes containing configuration data and logs from the 1.8.x container to the new 2.0.x container.

The SlashDB Docker containers include volumes for /etc/slashdb and /var/log/slashdb.

1. Obtain the latest SlashDB Docker image and config file bundle

First, download the SlashDB 2.0.x Docker image:

docker pull slashdb/slashdb

Next, download the default SlashDB configuration files and create a directory for logs

wget -c https://downloads.slashdb.com/versions/2.0.1/default-slashdb-configs_2.0.1.zip
unzip ./default-slashdb-configs_2.0.1.zip
mkdir slashdb-log

In your current directory you should have the zip file, and two directories named slashdb and slashdb-log.

Important

There are a few changes in the SlashDB 1.8.x INI that you may want to keep. If so, make a reference copy of the slashdb/slashdb.ini file before proceeding.

2. Copy existing configuration files from the old Docker container to the new one

Your existing 1.8.x container should have been configured on installation to store its configuration and logs in two directories named slashdb and slashdb-log.

Locate these directories, and copy their contents to the newly created slashdb and slashdb-log directories, respectively.

3. Review and update the slashdb.ini file as needed, as well as any other config files that were customized

Note

If you made a reference copy of the slashdb/slashdb.ini file for the 1.8.x container, copy the changes you want from the reference file to slashdb/slashdb.ini file. You may want to use a tool like sdiff to resolve any differences.

See Config File Changes Since Last Version for more info.

Important

To update the users.cfg file, you'll need to run this command once inside the 2.0.x Docker container:

/opt/slashdb/bin/slashdb_tools hash-api-keys /etc/slashdb/slashdb.ini

This will hash all user API keys.

Important

You can now update the slashdb/license.key file for the 1.8.x container with a valid 2.0.x license using a text editor.

If you want to upload a new license via the GUI, navigate to the 2.0.x SlashDB GUI in a browser to upload a license file after the container is running.

4. Launch the new container

Start the SlashDB 2.0.x container:

docker run -d -p 8080:80 -v $(pwd)/slashdb:/etc/slashdb  -v $(pwd)slashdb-log:/var/log/slashdb slashdb/slashdb

Your previous SlashDB configuration should be present on the 2.0.x container.

See the Docker Volumes documentation for more information about Docker volumes.

VMWare/VirtualBox/HyperV

1. Obtain and launch the latest virtual appliance

Download the latest virtual appliance:

https://downloads.slashdb.com/versions/2.0.1/slashdb-2.0.1.ova

Install the appliance using the virtual machine management software for your virtual environment.

2. Copy the SlashDB configuration files from the old appliance to the new one

Launch the SlashDB 1.8.x appliance if it is not running, and create backups of /etc/slashdb/ and /var/log/slashdb from a shell:

systemctl stop slashdb
tar cvf etc_slashdb.tar /etc/slashdb
tar cvf var_log_slashdb.tar /var/log/slashdb

Launch the SlashDB 2.0.x appliance if it is not running. You may need to update the network settings first to configure the appliance for your hardware/network environment.

Important

There are a few changes in the SlashDB 1.8.x INI that you may want to keep. If so, make a reference copy of the /etc/slashdb/slashdb.ini file on the 1.8.x appliance before proceeding.

Copy the tar backup files from the 1.8.x appliance to the 2.0.x appliance using SCP, FTP, a shared network resource, USB, etc.

Using SCP to copy the tar files from the 1.8.x appliance (default password for root on the SlashDB 2.0.x appliance is slashdb):

scp etc_slashdb.tar root@<slashdb_17x_appliance_hostname_ip>:
scp var_log_slashdb.tar root@<slashdb_17x_appliance_hostname_ip>:

Open a shell on the 2.0.x appliance. The tar files will be in the /root folder. You'll need to install the tar utility to extract them:

yum install tar

Extract the backups to their target directories:

cd /etc && tar xvf /root/etc_slashdb.tar --strip 1
cd /var/log && tar xvf /root/var_log_slashdb.tar --strip 1

3. Review and update the slashdb.ini file as needed, as well as any other config files that were customized

Important

To update the users.cfg file, you'll need to run this command once:

/opt/slashdb/bin/slashdb_tools hash-api-keys /etc/slashdb/slashdb.ini

This will hash all user API keys.

Note

If you made a reference copy of the /etc/slashdb/slashdb.ini file on the 2.0.x appliance, copy the changes you want from the reference file to the /etc/slashdb/slashdb.ini file. You may want to use a tool like sdiff to resolve any differences.

See Config File Changes Since Last Version for more details.

Restart the SlashDB process:

systemctl restart slashdb-app

4. Reassign the IP address/hostname to the new appliance and shut down the old one

You can now update the /etc/slashdb/license.key file on the 2.0.x appliance with a valid 2.0.x license using a text editor, or navigate to the 2.0.x SlashDB GUI in a browser to upload a license file.

Amazon AWS/Microsoft Azure

Upgrades for Amazon AWS/Microsoft Azure deployments follow a process similar to upgrading virtual appliances. Once the new instance is deployed, you can reassign the IP address/hostname of the old deployment to the new one.

1. Launch the new instance from AWS/Azure Marketplace following normal installation instructions

2. Copy and reconcile the SlashDB configuration files from the existing instance to the new one

From the SlashDB 1.8.x container, create backups of the configuration:

systemctl stop slashdb
tar cvf etc_slashdb.tar /etc/slashdb
tar cvf var_log_slashdb.tar /var/log/slashdb

Important

There are a few changes in the SlashDB 1.8.x INI that you may want to keep. If so, make a reference copy of the /etc/slashdb/slashdb.ini file after launching the AWS/Azure SlashDB 1.8.x container.

Copy the tar backup files from the 1.8.x container to the 2.0.x container using SCP, FTP, or a shared network resource.

Using SCP to copy the tar files from the 1.8.x container:

scp etc_slashdb.tar root@<slashdb_17x_container_hostname_ip>:
scp var_log_slashdb.tar root@<slashdb_17x_container_hostname_ip>:

Open a shell on the 2.0.x container. The tar files will be in the /root folder.

Extract the backups to their target directories:

cd /etc && tar xvf /root/etc_slashdb.tar --strip 1
cd /var/log && tar xvf /root/var_log_slashdb.tar --strip 1

Important

To update the users.cfg file, you'll need to run this command once:

/opt/slashdb/bin/slashdb_tools hash-api-keys /etc/slashdb/slashdb.ini

This will hash all user API keys.

3. Reassign the IP address/hostname to the new instance and shut down the old one

Note

If you made a reference copy of the /etc/slashdb/slashdb.ini file on the 1.8.x container, copy the changes you want from the reference file to the /etc/slashdb/slashdb.ini file. You may want to use a tool like sdiff to resolve any differences. See Config File Changes Since Last Version for more details.

Finally, restart the SlashDB process:

systemctl restart slashdb-app

Config File Changes Since Last Version

Info

The changes below refer to the /etc/slashdb/slashdb.ini file. See all the INI Settings here.

Additions

Date and Time Format

date_format

time_format

datetime_format

Parameters that control how date and time strings are formatted. See the Date and Time Format INI documentation for more details.

Request Status

request_status_ok_lifetime

request_status_err_lifetime

INI settings that control how long requests will appear on the Request Status page.

Changes

userdef_enforce_privilege_hierarchy - default value is now True

Subtractions

None