Skip to end of metadata
Go to start of metadata

In earlier versions of SuperSTAR, the user catalogue (details of users, permissions and passwords) was stored in an XML file. If you installed to the default location, this was saved in C:\ProgramData\STR\SuperADMIN\server\data\.repository\userCatalog.xml.

The use of XML can cause performance issues if you have a large number of user accounts. As a result, from version 9.9 onwards, SuperADMIN uses a relational database to store all user data.

When you upgrade to version 9.9 or later, SuperADMIN will automatically convert the user data from userCatalog.xml to a relational database (RDBMS). By default, it will store user data in an H2 database (located in C:\ProgramData\STR\SuperADMIN\server\data\superadmin.db), but you can switch to any of the following relational databases if you prefer:

  • MySQL / MariaDB
  • PostgreSQL
  • SQL Server
  • Oracle
  • DB2

 Making this change will also move data for the configuration server component and the user registration database to your chosen RDBMS.

This change should only be made before going into production. Please contact STR for advice if you wish to change the RDBMS for a production system.

In particular, if you have already updated to version 9.9 or later, then your SuperADMIN data will already have been moved to H2. STR does not currently provide an automated process for migrating from H2 to another RDBMS.

Step 1 - Create a Database and User

The first step is to create a database for the user data in your chosen RDBMS. To complete this step you may need to install a suitable database server or obtain access to an existing database server.

  1. Create a new database. For example, you might call the database SuperSTAR_Users.

    Set the default character set of your database to UTF8. This will allow the User Data Repository to save usernames containing the full range of unicode characters.
  2. Create a dedicated database user account and set the account password.

    If you are using Oracle or DB2 then the username for connecting to the database must be the same as the database schema.
  3. Grant your new user account full privileges over your new database.

Step 2 - Install a JDBC Driver

JDBC (Java Database Connectivity) is a programming interface that lets Java applications access a relational database. You need to install a JDBC driver for your RDBMS, so that SuperWEB2 can communicate with the User Data Repository database.

  1. Download the appropriate JDBC driver for your database:

    RDBMSRecommended DriverExample of JAR FileDriver ClassDownload From
    MySQLConnector/Jmysql-connector-java-5.1.41-bin.jarcom.mysql.jdbc.Driverhttp://www.mysql.com/downloads/connector/j/
    Oracleojdbc7.jarojdbc7.jaroracle.jdbc.driver.OracleDriverhttp://www.oracle.com/technetwork/database/features/jdbc/jdbc-drivers-12c-download-1958347.html
    SQL ServerMicrosoft JDBC Driversqljdbc42.jarcom.microsoft.sqlserver.jdbc.SQLServerDriverhttp://www.microsoft.com/en-au/download/details.aspx?id=11774
    DB2DB2 JDBC Driverdb2jcc4.jarcom.ibm.db2.jcc.DB2Driverhttp://www-01.ibm.com/software/data/db2/linux-unix-windows/downloads.html
    PostgreSQLPostgreSQL JDBC 4.2 Driver, 42.0.0postgresql-42.0.0.jarorg.postgresql.Driverhttps://jdbc.postgresql.org/download.html

     The JDBC driver must support JDBC 4.2 (Java 8).

    You do not need to download a driver to use the default H2 RDBMS as this driver is included with SuperADMIN.

  2. Copy the driver .jar file to C:\Program Files\STR\SuperADMIN\server\lib\endorsed (or equivalent directory if you installed to a non-default location).

Step 3 - Configure SuperADMIN

Configure SuperADMIN to use your preferred RDBMS by adding the following section to the local.conf configuration file.

If you installed to the default directory, this file is located in C:\ProgramData\STR\SuperADMIN\server\config\local.conf.

str.superadmin {
    jdbc {
        url: "URL"
        username: "USERNAME"
        password: "PASSWORD"
        platform: ${db."DBTYPE"}
    }
}

If your local.conf file already has a str.superadmin section, then add the new section within the existing str.superadmin section. For example:

 Click here to expand...
 str.superadmin {
  email {
        smtpHost: "localhost"
        smtpPort: 25
        startTls: false
        auth {
            enabled: false
            username: "changeme"
            password: "changeme"
        }
        debug: false
    }
    jdbc {
        url: "URL"
        username: "USERNAME"
        password: "PASSWORD"
        platform: ${db."DBTYPE"}
    }
}
Replace the following with the relevant values:

URL

 The JDBC connection string for your chosen RDBMS. The following are typical connection strings:

MySQL
jdbc:mysql://mydatabasehost:3306/superstar_users?useUnicode=true&characterEncoding=UTF-8
PostgreSQL
jdbc:postgresql://mydatabasehost:5432/SuperSTAR_Users
DB2
jdbc:db2://mydatabasehost:50000/SuperSTAR_Users:currentSchema=SuperSTAR
Oracle
jdbc:oracle:thin:@mydatabasehost:1521:SuperSTAR_Users
SQL Server
jdbc:sqlserver://mydatabasehost:1433;databaseName=SuperSTAR_Users
USERNAME The username for the account you created in Step 1.
PASSWORDThe password for the account you created in Step 1. 
DBTYPE

One of the following strings:

StringRDBMS
H2
Embedded H2
MySQL
MySQL / MariaDB
Postgres
PostgreSQL
DB2-LUW
The Linux/Unix/Windows edition of DB2
DB2-zOS
The z/OS edition of DB2
Oracle
Oracle
SQLServer
SQL Server

For example, the following section might be used to connect to SQL Server:

str.superadmin {
    jdbc {
        url: "jdbc:sqlserver://mydatabasehost:1433;databaseName=SuperSTAR_Users"
        username: "superadminuser"
        password: "asd3fws4gwsd"
        platform: ${db."SQLServer"}
    }
}

Step 4 - Check SuperADMIN Migration Settings

  1. Make sure that the following XML files are present in the server data repository directory: userCatalog.xml and accountCatalog.xml (if you installed to the default location, check that the files exist in the C:\ProgramData\STR\SuperADMIN\server\data\.repository\ directory).
  2. Run the following command in SuperADMIN:

    cfg global superadmin.migration.userCatalog set "false"

    This will ensure that the catalogue is migrated from XML on the next restart.

Step 5 - Restart SuperSERVER

You will need to restart the SuperADMIN/SuperSERVER service to apply this change. When the service has started, verify that the tables have been created in your RDBMS. For example:

SuperADMIN does not delete the legacy XML file (UserCatalog.xml) following a successful migration, although this file will no longer be required or used and will not need to be restored during a future upgrade.
  • No labels