Appendix B. Use the Ringtail Database Utility

This appendix explains how to install, configure, and use the Ringtail Database Utility.

Caution: If a previous version of the Ringtail Database Utility exists, you must uninstall it before installing the newer version. If you install the newer version of the utility and try upgrading databases without uninstalling the previous version, the databases will be upgraded to the older version. To identify the version of the utility, use the Windows Add or Remove Programs (or equivalent) function to list the installed version.
‎
‎Also, if the SQL component referenced in the installation procedure is already installed, you must install a newer SQL component, if available. SQL components are version specific. 

About the Ringtail Database Utility

The Ringtail Database Utility manages the creation and upgrades of Ringtail databases. You can connect the utility to any SQL Server to work with databases on that server.

Note: Ensure all databases are at the current compatibility level of your SQL Server, or at least 100. For the SQL Server version requirements, see the Nuix Discover 10.15 - Hardware and System Requirements.

From within this utility, you can perform a batch upgrade of multiple databases. You also use the utility to create a portal, case, RPF, temp (rs_tempdb) databases, and to create the NIST table in rs_tempdb.

Use the Ringtail Database Utility to do the following:

View details of the current SQL component installed on the database server. For more information, see Connect to the database server.

Upgrade portal and case databases. For more information, see Upgrade databases.

Create new databases for the portal. For more information, see Create new databases.

Authentication

The Ringtail Database Utility uses either SQL Authentication or the default Windows authentication to connect to the SQL Server.

To use Windows authentication, you must be a Windows system administrator on the target database server, with Database Creation and Bulk Update access.

To use SQL Authentication, you must have system administrator (SA) equivalent access.

Prerequisites

The Ringtail Database Utility requires the Ringtail SQL component, Ringtail9-SQLComponent_<latest version>.exe, to be installed on the database server. Download the latest versions of the installation files from the Nuix Discover Quarterly Releases page on the Nuix download site, https://download.nuix.com/. To find out about the latest versions, contact Nuix Support.

Database administrator permissions

For a database user to create cases, they must be a member of the System Administrator (SA) server role. The SQL Server Database Service account must have read permissions to the target scripts directory.

Installation

Install the Ringtail Database Utility on a computer that is in the same domain as the database server. To install the utility, you must log in as a domain administrator, through Windows authentication on the SQL Server.

For information about installing the Ringtail Database Utility, see Install the Ringtail Database Utility.

Connect to the database server

When you launch the Ringtail Database Utility, you start by connecting to the computer on which the existing SQL Server database server resides. The Ringtail Database Utility is session-based, so you remain connected to the database server for the duration of the database upgrade or database creation. When you close the utility, it saves these connections. When you next launch the utility, it reconnects to the saved connections. You can connect to one database or to multiple database servers.

Warning: If you close the Ringtail Database Utility before completing the database upgrade, the database may become corrupt and require a rollback to an earlier (pre-upgrade) version.

Connect to one database server

Use the following procedure to connect to the database server.

To launch the Ringtail Database Utility, on the Windows Start menu, select Ringtail Database Utility.

After you launch the Ringtail Database Utility, under Connect To Database Server, provide the following information:

In the Server Name box, type the name of the server to which you want to connect.

In the Port Number box, type the port number for that server. This is optional. If you do not assign a port, the default port number is used.

If you are using SQL Server authentication, select the Use SQL Authentication check box, and provide the SQL Server user name and password. If you do not specify SQL Server authentication, the default Windows authentication is used.

Click Connect.

When you connect to a database server, it appears on the left in the Ringtail Database Utility window, under Connections. Also, the utility displays the available database versions on the server. These database versions are installed on the Ringtail SQL component. Use this information to determine whether to update your databases. The Portal version number must match the Latest Server Version number of a database after it has been upgraded.

After connecting to the database server, perform any of the following actions:

Upgrade any database or case on that server. For more information, see Upgrade databases.

Create new databases on that server. For more information, see Create new databases.

Connect to multiple database servers

Note: Ringtail SQL components must be installed on each SQL Server machine.

You can connect to multiple database servers at the same time.

Use the following procedure to connect to multiple database servers.

Under Connections, click Servers.

Under Connect To Database Server, provide the details for the additional servers, and then click Connect.

Use the following procedure to connect to the database server.

To launch the Ringtail Database Utility, on the Windows Start menu, select Ringtail Database Utility.

After you launch the Ringtail Database Utility, under Connect To Database Server.

Under Connections, click Servers, and then provide the details of the additional servers.

Click Connect.

After connecting to the database servers, perform any of the following actions:

Upgrade any database or case on that server. For more information, see Upgrade databases.

Create new databases on that server. For more information, see Create new databases.

Upgrade databases

Use the procedures in this section to upgrade databases.

Warning: Before you upgrade, we advise that you back up all databases. To apply an upgrade, you must have system administrator access to the database server.
‎
‎Always upgrade the temp (rs_tempdb) database before creating or upgrading the case or portal databases.

You must have an SA account to upgrade the rs_tempdb database.

Database names cannot contain the hyphen (-) character.

For the application to operate correctly, all databases must be the latest versions. After each upgrade, use the Ringtail Database Utility to update your Ringtail databases to the correct versions. Database upgrades are required on the portal database and on each case database connected to that portal.

Note that you must always upgrade the temp (rs_tempdb) database before upgrading the portal or case database. You can upgrade databases individually by connecting to each database separately and then applying the upgrade to it. To upgrade databases at the case level, attach all cases to the portal. You can upgrade multiple databases at once as a batch upgrade.

Note: Always ensure that all target database servers have the latest Ringtail SQL component installed. This is important because if cases reside on a remote server, they are upgraded to the latest SQL component version on their target server, and not to the version that is on the portal servers.

Use the following procedure to upgrade the database.

Connect to the database server. For more information, see Connect to the database server.

If you are connected to multiple database servers, under Connections, click the server on which you want to apply the upgrades.

Under Actions, click Connect.

Under Connect to Database, in the Database Name box, type the name of the database, and then click Connect.

When you have connected to the database, its details appear under Database Information. Use this information to determine whether to upgrade databases.

Type: Database type

Database Version: Database version number

Status:

Ready: The database is ready and actionable.

Upgrade: Database creation/upgrade process in progress. Do not modify databases with this status.

Upgrade Failed: The last upgrade attempt for the database failed. You can attempt another upgrade with this status.

Upgrade Stalled: This occurs when the database indicates that an upgrade is in progress, but the process is no longer running.

Error Connecting: Unable to connect to the case with the user or server details that were provided.

Note: To retry a database upgrade that has stalled, use the Connect to Database function to connect to that specific stalled case, and then retry the upgrade.

Queued: Database is waiting to be upgraded as soon as resources become available.

Latest Server Version: The version number of the latest Ringtail SQL component installed on the target server.

Note: To retry a database upgrade that has stalled, use the Connect to Database function to connect to that specific stalled case, and then retry the upgrade.

To ensure that the application functions correctly, you must upgrade a database so that its Version number matches that of the Latest Server Version number.

To upgrade the portal database, under Actions, under Portal Database, click the Upgrade to arrow, and then select the version you want.

If the upgrade is successful, the Version number of the updated database will match the Latest Server Version number.

To upgrade the case databases, do the following:

Under Actions, click Get Cases to view all cases of the selected portal.

Tip: If a case appears unavailable, use Get Cases to check.

If the case databases are on remote servers to the portal database, the SQL Authentication Details window appears. In this window, provide the SQL Server credentials to the remote servers, and then click OK to connect.

Note: Always type your credentials. Do not use the copy and paste function, because it may include leading or trailing spaces.

To connect all cases only on the connected database, click Skip.

In the Case List, select the check boxes of the databases you want to update.

Under Case Databases, on the Upgrade to menu, select the version to upgrade to.

To check on the progress of the upgrade, under Upgrade Queue Viewer, click Refresh. You can do this to view the upgrade progress at any time.

When the upgrade is complete, the Version number of upgraded databases should match the Latest Server Version number.

Create new databases

Use the Ringtail Database Utility to create the following types of databases:

Portal

RPF

Temp (rs_tempdb)

For more information about creating databases with the Ringtail Database Utility, see Create the Ringtail system databases (Portal and RPF).

Use the error viewer

When you upgrade databases, errors may occur with the databases or upgrade process. To view the error, in the Portal List, select the upgrade that failed, and then click View Errors.

Upgrade/Creation queue

To view the progress of your batch upgrade anytime, under Actions, click Upgrade/Creation Queue, and then check the Progress column of the database of interest.

To refresh the list with the latest statuses, click Refresh.

‎