7 Administrative Tasks for Oracle R Enterprise

This chapter describes administrative tasks for maintaining and optimizing Oracle R Enterprise. This chapter contains these topics:

• Upgrading Oracle R Enterprise

• Migrating Oracle R Enterprise Data

• Uninstalling Oracle R Enterprise

• Installing Additional R Packages on Linux or UNIX

• Creating a Database User for Oracle R Enterprise

• Creating and Modifying Environment Variables on Windows

• Creating an Oracle Wallet for an Oracle R Enterprise Connection

• Controlling Memory Used by Embedded R

7.1 Upgrading Oracle R Enterprise

You can upgrade Oracle R Enterprise to the current release from any previous release by reinstalling the product.

Note on IBM AIX:

Upgrade from Oracle R Enterprise 1.1 is not supported on IBM AIX. To upgrade Oracle R Enterprise 1.1 on IBM AIX, first uninstall Oracle R Enterprise 1.1 (including R) and then download and install the later version.

To upgrade Oracle R Enterprise and migrate your data: 

1. Ensure that you have the version of R that is required for the new version of Oracle R Enterprise.

   See Table 1-2, "Oracle R Enterprise Server Support Matrix" for the R requirement.

2. To upgrade Oracle R Enterprise Server, run the server script to perform an installation:

   ./server.sh --install
   

   When the script detects an earlier version of Oracle R Enterprise Server, it asks if you want to upgrade. Type Yes to start the upgrade. (Type No to aborts the process.)

   See Section 4.2, "About the SERVER Script" for details.

   .

3. To upgrade Oracle R Enterprise Client, re-install the Oracle R Enterprise packages and supporting packages. You do not need to uninstall the current packages before installing the new packages.

   See Chapter 6, "Installing Oracle R Enterprise Client" for instructions.

7.2 Migrating Oracle R Enterprise Data

Oracle R Enterprise Server includes migration scripts that you can run to migrate the rqsys schema and Oracle R Enterprise user data from a source database to a target database. The source and target must have the same version of the database and of Oracle R Enterprise Server.

To locate the scripts, navigate to the server directory and change to the migration subdirectory.

/oreserver_install_dir/server/migration

The migration subdirectory contains a README and the following subdirectories:

• exp — contains the script ore_srcexport.pl for exporting rqsys and all Oracle R Enterprise user data to a dump file.

• imp — contains the script ore_destimport.pl for importing rqsys and all Oracle R Enterprise user data from the dump file created by ore_screxport.pl.

• oreuser — contains scripts for exporting and importing data for a specific Oracle R Enterprise user.

Instructions for running the migration scripts are provided in the README.

7.3 Uninstalling Oracle R Enterprise

This topic contains these sections: 

• Section 7.3.1, "Uninstalling Oracle R Enterprise Server"

• Section 7.3.2, "Uninstalling Oracle R Enterprise Client"

See Also:

Section 3.7, "Uninstalling Oracle R Distribution"

7.3.1 Uninstalling Oracle R Enterprise Server

To uninstall Oracle R Enterprise Server, run the server script with the --uninstall option. you can perform either a full or a partial uninstall.A partial uninstall is performed by default.

7.3.1.1 Performing a Partial Uninstall

A partial uninstall removes the rqsys metadata and PL/SQL packages from the database but leaves the libraries and R packages that support Oracle R Enterprise Server in Oracle home. If Oracle R Enterprise Server support is installed in more than one database instance in the same Oracle home, or if it is installed in a pluggable database (PDB), then a partial uninstall removes Oracle R Enterprise Server support from the specified database without affecting the other databases. The server script performs a partial uninstall by default.

Note:

If you accidentally perform a full uninstall for one of the instances or PDBs that share support for Oracle R Enterprise Server, then the other shared instances or PDBs will no longer support Oracle R Enterprise Server. You can easily restore Oracle R Enterprise Server support in Oracle home by rerunning the server script to perform an installation in one of the shared instances or PDBs.

If you run the server script with the -u option, then a partial uninstall is performed. You can specify the --keep option to explicitly request a partial uninstall. The following commands all perform a partial uninstall of Oracle R Enterprise Server:

./server.sh  --uninstall  
./server.sh  -u
./server.sh  -u --keep
./server.sh  --uninstall  --keep

7.3.1.2 Performing a Full Uninstall

A full uninstall removes the rqsys metadata and PL/SQL code from the database and removes all Oracle R Enterprise Server libraries and R packages from Oracle home.

The following commands both perform a full uninstall of Oracle R Enterprise Server:

./server.sh --uninstall --full  
./server.sh -u  -full

Note:

If you accidentally perform a full uninstall in a shared Oracle home, then rerun the server script to reinstall Oracle R Enterprise Server support. See Section 7.3.1.1 for details.

7.3.2 Uninstalling Oracle R Enterprise Client

To uninstall the Oracle R Enterprise packages and supporting packages, start R and type the commands listed in Example 7-1.

Example 7-1 R Commands for Uninstalling Oracle R Enterprise Packages

remove.packages("ORE")
remove.packages("ORExml")
remove.packages("OREeda")
remove.packages("OREcommon")
remove.packages("OREembed")
remove.packages("OREgraphics")
remove.packages("OREstats")
remove.packages("OREbase")
remove.packages("ROracle")
remove.packages("DBI")
remove.packages("Cairo")
remove.packages("png")
remove.packages("OREdm")
remove.packages("OREpredict")
remove.packages("arules")
remove.packages("statmod")

7.4 Installing Additional R Packages on Linux or UNIX

On Linux and UNIX platforms, the Oracle R Enterprise Server installation provides the ORE script, which you can run from the operating system prompt to install additional R packages. The ORE script is a wrapper for the R installation command: R CMD INSTALL.

By default, R packages are installed in /usr/lib64/R/library. The ORE script, however, installs R packages in a subdirectory under $ORACLE_HOME/R/library.

To execute the script:

ORE CMD INSTALL R_package_name

7.5 Creating a Database User for Oracle R Enterprise

The server script installation process automatically creates or configures a user for Oracle R Enterprise if one does not already exist.

Example 7-2 Creating an Oracle R Enterprise User

./server.sh
.
.

Choosing ORE user
  ORE user to use [list]:

Press Enter to display a list of available users.

BI
HR
IX
OE
SCOTT
SH
  ORE user to use [list]: ruser2
.
.

If you choose a user that exists, the script configures the user to support Oracle R Enterprise. If you specify a user that does not already exist, the script creates the user.

Example 7-3 Creating an Oracle R Enterprise User in SQL*Plus

You can create an Oracle R Enterprise user in SQL*Plus by following these steps:

1. Log in with system privileges:

   SQLPLUS / AS SYSDBA
   

2. Execute a statement like the following to create the user:

   CREATE USER ore_username IDENTIFIED BY password
   DEFAULT TABLESPACE default_tablepace_name
   TEMPORARY TABLESPACE temp_tablespace_name 
   QUOTA UNLIMITED ON default_tablespace_name;
   

   See Also:

   Oracle Database SQL Language Reference for details about creating a user

3. Grant the required privileges:

   GRANT CREATE SESSION,
         CREATE TABLE,
         CREATE VIEW,
         CREATE PROCEDURE,
         CREATE MINING MODEL
   TO ore_username; 
   

   See Also:

   Oracle Database SQL Language Reference for details about granting privileges to a user

7.5.1 About the RQADMIN Role

The server script installation process creates a database role called rqadmin. When the rqadmin role is granted to an Oracle R Enterprise user, the user can create and drop R scripts for embedded R execution. By default, the server script does not grant the rqadmin role to the Oracle R Enterprise user.

Note:

Any Oracle R Enterprise user can execute embedded R, but only Oracle R Enterprise users with the rqadmin role can create and drop the R scripts.

As shown in Section 4.2.3.4, you can run the server script with the --admin option to grant the rqadmin role to an Oracle R Enterprise user. The --admin option is only available when you run the script in batch mode.

If you choose to grant the rqadmin role in SQL*Plus, then log in with system privileges and execute a statement like the following:

SQLPLUS / AS SYSDBA
GRANT RQADMIN TO ore_username;

Caution:

Use caution when granting the rqadmin role. Only users that require Oracle R Enterprise administrative privileges should have this role.

7.6 Creating and Modifying Environment Variables on Windows

If the PATH, ORACLE_SID, and ORACLE_HOME environment variables do not exist, you must create them and assign the values specified in Figure 7-2. On Windows systems, you must be an administrator to create or modify environment variables.

Follow these steps to create or modify environment variables on Windows: 

• 1. Right-click the Computer icon and choose Properties, or in Windows Control Panel, choose System.

  2. Choose Advanced system settings.

     Figure 7-1 Advanced System Settings in Windows

     
     Description of "Figure 7-1 Advanced System Settings in Windows"
     
     

  3. On the Advanced tab, click Environment Variables.

     Figure 7-2 Environment Variables Dialog in Windows

     
     Description of "Figure 7-2 Environment Variables Dialog in Windows"
     
     

  4. Click New to create a new environment variable. Click Edit to modify an existing environment variable.

Note:

The graphical user interface for creating environment variables may vary slightly, depending on your version of Windows.

7.7 Creating an Oracle Wallet for an Oracle R Enterprise Connection

An Oracle wallet is a password-protected container for storing security credentials in Oracle Database. Wallets provide a secure mechanism for specifying connection details in embedded R scripts.

To create a wallet for an Oracle R Enterprise connection: 

1. Start Oracle Wallet Manager:

   • (Linux and UNIX) At the command line, enter owm.

   • (Windows) Select Start, Programs, Oracle-HOME_NAME, Integrated Management Tools, Wallet Manager.

2. Follow the instructions in your Oracle Database documentation to create the wallet:

   • For Oracle Database 12.1, see ”Using Oracle Wallet Manager” in Oracle Database Enterprise User Security Administrator's Guide:

     http://www.oracle.com/pls/topic/lookup?ctx=db121&id=DBIMI160

   • For Oracle Database 11.2, see ”Using Oracle Wallet Manager” in Oracle Database Advanced Security Administrator's Guide:

     http://www.oracle.com/pls/topic/lookup?ctx=db112&id=ASOAG160

3. Locate the connection string for the Oracle R Enterprise database in tnsnames.ora. For example:

   mydb_test =
         (DESCRIPTION =
            (ADDRESS =
               (PROTOCOL = TCP)
               (HOST = server23)
               (PORT = 1521)
            )
            (CONNECT_DATA = (sid=ORCL))
         )
   

4. Specify the connection information in the wallet. Follow the instructions in the Oracle Database security documentation referenced in step 2.

5. After you configure the wallet, you can connect to the Oracle R Enterprise server database by simply specifying the connection identifier. For example:

   ore.connect(conn_string = "mydb_test", all = TRUE)
   

   To learn more about ore.connect, use the R help command:

   help(ore.connect)
   

7.8 Controlling Memory Used by Embedded R

You can control the memory used by embedded R execution by limiting the heap memory (vector and cons in R terminology) that is automatically managed by the R gc mechanism. To limit the size of heap memory in the database, use the sys.rqconfigset utility. The keyword arguments for sys.rqconfigset are described in Table 7-1.

Table 7-1 SYS.RQCONFIGSET Keyword Arguments

Keyword	Default	Description
MIN_VSIZE	32M	Minimum R vector heap memory
MAX_VSIZE	4G	Maximum R vector heap memory
MIN_NSIZE	1M	Minimum number of R cons cells
MAX_NSIZE	20M	Maximum number of R cons cells

Example 7-4 SQL Commands for Controlling Memory Used by Embedded R

-- Set the minimum R vector heap memory to 20M
EXEC sys.rqconfigset('MIN_VSIZE', '20M');

-- Set the maximum R vector heap memory to 100M
EXEC sys.rqconfigset('MAX_VSIZE', '100M')

-- Set the minimum number of R cons cells to 500x1024
EXEC sys.rqconfigset('MIN_NSIZE', '500K');

-- Set the maximum number of R cons cells to 10x10x1024
EXEC sys.rqconfigset('MAX_NSIZE', '10M');

-- Set maximum vector heap memory and maximum cons cells to unlimited
EXEC sys.rqconfigset('MAX_VSIZE', NULL); 
EXEC sys.rqconfigset('MAX_NSIZE', NULL);

Note:

The sys.rqconfigset procedure does not control the C type memory that may be allocated by Calloc, Realloc, calloc, or malloc. Such C type memory is mainly created to hold temporary values used by R functions that are implemented in C. Under normal circumstances, C type memory is limited in size and does not significantly affect the memory usage of R.

The sys.rqconfigset procedure edits settings in a configuration table called sys.rq_config. You can view the contents of this table to verify various environment settings for Oracle R Enterprise. Among the settings stored in sys.rq_config are the memory limits for embedded R. If necessary, you can modify these memory limits, however in most cases you should not modify the values in sys.rq_config.

The following query shows sample values stored in sys.rq_config.

SQL> SELECT * FROM sys.rq_config;
 
NAME                      VALUE
------------------------- -----------------------------------------------------
R_HOME                    /usr/lib64/R
R_LIBS_USER               /dbhome_1/R/library
VERSION                   1.4.1
MIN_VSIZE                 32M
MAX_VSIZE                 4G
MIN_NSIZE                 2M
MAX_NSIZE                 20M