Database repository

iKnowBase uses an Oracle Database for storing both data, metadata and applications. Inside the database, iKnowBase also stores a lot of system code, as well as public APIs for manipulating the data.

Fresh install

A fresh install of the Oracle repository is pretty simple, and consists of only a few steps:

• The database schema where iKnowBase is installed must be created, and it must be given the proper permissions. Also, an instance specific database package must be created.
• The database schema must be populated with startup data. These data can be loaded from an existing instance (for example, when doing a fresh install of a test environment, where the startup data comes from an existing production environment), or they can be loaded from the iKnowBase distribution.

A full set of typical commands is shown below, and further described in the following chapters.

$ cd /opt/iknowbase/production
$ ./quickstart.sh production.properties createUser
$ ./quickstart.sh production.properties uploadFile IKB_MASTER_67.dmp
$ ./quickstart.sh production.properties importFile IKB_MASTER_67.dmp IKB_MASTER_67
$ # Optionally download and display import log
$ ./quickstart.sh production.properties downloadFile IKB_MASTER_67.log .
$ cat IKB_MASTER_67.log

Prepare the database schema

Installing the database schema is most easily done using the Quickstart program. Assuming that you have created a file “production.properties” with the proper information, use the following command:

$ quickstart.sh production.properties createUser

This command will perform three actions:

• First, as user SYS, it will create the user specified in the property file, with the password also specified there.
• Next, as user SYS, it will grant required permissions to that user. A full list of permissions can be seen in the log file after executing the command.
• Finally, as the newly created user, it will create the database package IKB_GLOBAL_PREFS with default variables.

Custom step for Oracle 12c database with Pluggable databases (PDB)

If installing on a Oracle 12c database with Pluggable databases (PDB), DATA_PUMP_DIR does not work with PDBs. You must define an explicit Directory object within the PDB after you have created the new schema. Create a new directory and configure quickstart to use it:

• create directory as ‘<OS path to where datapump files should be stored>’;
• grant read,write on directory to <schema name>;
• Add a property to the quickstart configuration file e.g db.dataPumpDirectory=

Import startup data based on a export file

You can import startup data with any mechanims you choose, but once again the Quickstart program is the preferred and supported mechanism. Using the Quickstart program has two steps: First you upload the startup data to the oracle database server, and then you import them into the oracle database schema:

$ ./quickstart.sh production.properties uploadFile IKB_MASTER_67.dmp
$ ./quickstart.sh production.properties importFile IKB_MASTER_67.dmp IKB_MASTER_67

The first command will upload the file IKB_MASTER_67.dmp from the local directory, and store in an Oracle Directory on the server. The default (and recommended) directory is called DATA_PUMP_DIR, and is often available under /app/oracle/admin/INSTANCE/dpdump. Note that if you import data from another existing database, the file may have any other name. This command will run as the iKnowBase-user.

The second command will import the file IKB_MASTER_67.dmp from the Oracle Directory into the iKnowBase schema. The Quickstart program will in fact use Oracle Datapump to perform this import. For the datapump import to succeed, the name of the database user that exported the schema must be specified. In the distribution, and by convention, the name of the datafile reflects the name of the exporting user; here, it is IKB_MASTER_67.

If something fails during import, Oracle Datapump will store log messages in a log file in the Oracle Directory on the database server. When using the quickstart importFile command, the name of the logfile is always the same as the name of the datafile, with a .log-suffix.

Since the file already exist on the database server, you may view it there (i.e. typically /app/oracle/admin/INSTANCE/dpdump/IKB_MASTER_67.log). You can also use the following command to download the logfile to your local directory:

$ ./quickstart.sh production.properties downloadFile IKB_MASTER_67.log .

Note that it is often useful to store a copy of the logfile even when there are no appearent failures, in case you need it later.

Upgrade

Upgrading an iKnowBase-installation is technically more complex than a fresh install, mostly because there are already existing data that must not be deleted. An upgrade therefore have the following steps:

• If you want, take a copy of existing database object definitions for post-upgrade troubleshooting
• Next, update and verify the user/schema settings
• Run through schema upgrade scripts for all required versions, and install the latest code (types, packages, functions and procedures)
• Recompile any invalid packages

$ cd /opt/iknowbase/production
$ quickstart.sh production.properties exportSource scripts.zip
$ quickstart.sh production.properties configureUser
$ quickstart.sh production.properties upgradeAll
$ quickstart.sh production.properties compileInvalid

Export existing scripts

Export existing scripts is entirely optional, but we recommend this for easier post-upgrade troubleshooting. You may use any available tool for this process, but once again the Quickstart has an easy-to-use mechanism:

$ quickstart.sh production.properties exportSource scripts.zip

The above command will use DBMS_METADATA to recreate scripts for all TYPEs, PACKAGEs, PROCEDUREs and FUNCTIONs in the iKnowBase schema, and store it in a zip file. The zip-file will also contain compile-scripts for each of the object types, as well as a compile script that compiles everything.

Prepare the database schema

Various versions of iKnowBase require different permissions, and have different information in the IKB_GLOBAL_PREFS-package. It is therefore necessary to configure the database schema to the new requirements:

$ quickstart.sh production.properties configureUser

This command will perform two actions:

• First, as user SYS, it will grant required permissions to that user. A full list of permissions can be seen in the log file after executing the command.
• Then, as the iKnowBase user, it will recreate the database package IKB_GLOBAL_PREFS with default values.

Upgrade schema and install latest code

The most complex step in the upgrade process is to upgrade the schema and install the latest code. For convenience, use the Quickstart program’s upgradeAll feature:

$ quickstart.sh production.properties upgradeAll

This command does in fact comprise a number of schema upgrade steps (one for each schema version), and then a single code installation step.

Note that after installing the latest code, open database connections and open cursors may cache database type information that is no longer correct. It is therefore recommended to restart all application servers, email readers, search crawlers etc that may have open database connections.

Recompile invalid packages

After the upgrade step, it may be required to recompile invalid packages in the Oracle schema:

$ quickstart.sh production.properties compileInvalid

This command utilizes DBMS_UTILITY.RECOMPILE_SCHEMA for recompiling only invalid packages.

De-installation

De-installation of the iKnowBase installation is pretty simple: Remove the user and all it’s data:

$ quickstart.sh production.properties dropUserCascade

Note that you may have to set the value “allowDropUserCascade=true” in the property file before this command will work.

Note also that while a simple “drop user cascade” from sql*plus may work, it also may not: When a schema has Oracle AQ-tables (Advanced Queing), it is sometimes required to manually drop these queues first. The Quickstart command handles this, and is therefore the recommended way of deleting a user.

And finally, a word of warning: The dropUserCascade command is utterly unrecoverable, and if you drop a user by accident, you will have to reload data from a backup. Take care!

Advanced topics

Global runtime preferences

iKnowBase uses a database package header, IKB_GLOBAL_PREFS, to determine methods and options on certain functionality. To modify the package header you need access to the database with a proper tool e.g SqlDeveloper or Toad.

Duplicate an existing installation

Often, you will want to duplicate an existing installation. For example, you may have a development, test and production instance, and you may need to copy from production to test. Doing so is very simple:

$ quickstart.sh IKB_PROD.properties exportFile IKB_PROD.dmp
$ quickstart.sh IKB_TEST.properties importFile IKB_PROD.dmp IKB_PROD

In the example above, there are two property files. IKB_PROD.properties contain information about the production schema, while IKB_TEST contain information about the test schema. Data is first exported from the production schema, then imported into the test schema.

Note that the first time you do this, you will also need to run the createUser-command. Of course, if the IKB_PROD and IKB_TEST schemas reside on different Oracle-instances, you will also need to move the dump file between the instances, either using a combination of downloadFile and uploadFile, or by using some other file transfer mechanism.

Running iKnowBase in a Oracle Enterprise Edition database

By default, an iKnowBase installation is prepared for running in a Oracle Standard Edition database. It you are licened for running Oracle Database Enterprise Edition then run the following command to speed up queries displaying (or sorting) document popularity.

$ quickstart.sh production.properties dbscript source/common/mv_log_document.sql logfile

To switch back to the standard edition version do:

$ quickstart.sh production.properties dbscript source/common/view_log_document.sql logfile