This chapter explains how to install version 1.4 of the database extension. The installation typically consists of the following steps:

1. Make a backup of your current system (optional)
2. Check the requirements
3. Download the database extension
4. Copy the downloaded package
5. Unpack the downloaded package
6. Enable the extension
7. Test connection to an Oracle database server
8. Create and initialize an Oracle database for eZ Publish

   • Automated initialization
   • Manual initialization
9. Configure eZ Publish
10. Restart Apache

1. Make a backup of your current system (optional)

If you are planning to migrate an existing site that uses MySQL to Oracle, you should make a backup of both the eZ Publish directory itself and the MySQL database. Even though the chances for something going wrong are slim, it is still strongly advised to make a backup. Please refer to the "Backup" section of the "Upgrading" manual for more information.

2. Check the requirements

Please verify that the requirements for being able to use the database extension are met.

3. Download the database extension

The eZ Publish Extension for Oracle® Database, which was licensed under the eZ proprietary license before, is now available under GPL. You can download the latest version here.

4. Copy the downloaded package

Copy the downloaded "tar.gz" package into the "extension" directory of your eZ Publish installation.

5. Unpack the downloaded package

The package should be unpacked inside the "extension" directory. When done correctly, an "ezoracle" directory will be created inside the "extension" directory.

On UNIX/Linux, the package can be unpacked like this:

$ tar -zxvf ezoracle-extension-1.4.tar.gz

On Windows, you can just unzip the files using the built-in zip features.

At this point, the unpacked files should be available under "extension/ezoracle".

6. Enable the extension

To enable the database extension for all of your siteaccesses, edit the "site.ini.append.php" file located in the "settings/override" directory. Add the following line under the "[ExtensionSettings]" section:

ActiveExtensions[]=ezoracle

Please note that you'll have to manually create the file and/or the section if they do not exist.

To enable the database extension for only a single siteaccess called "example", edit the "site.ini.append.php" file located in the "settings/siteaccess/example" directory. Add the following line under the "[ExtensionSettings]" section:

ActiveAccessExtensions[]=ezoracle

Please note that you'll have to manually create the file and/or the section if they do not exist.

7. Test connection to an Oracle database server

Before doing anything else, make sure you can connect to an Oracle database using an Oracle client. This manual assumes that you are using the SQL*Plus command-line utility. Assuming that an Oracle instance called "ORCL" is running on your Oracle server and can be accessed using an Oracle account with username "scott" and password "tiger", the shell command for creating a test connection will look like this:

sqlplus scott/tiger@ORCL

Please note that SQL*Plus will retrieve configuration information from your operating system's environment variables (these are listed in the SQL*Plus documentation). UNIX/Linux users can set their environment manually or by using the "oraenv" utility. On Windows, the Oracle environment variables are stored in the registry.

Example

UNIX/Linux users might not be able to connect using SQL*Plus if the path to the Oracle client libraries directory where the "libsqlplus.so" file is located is not listed in $LD_LIBRARY_PATH. The following shell commands can be used to display and set this environment variable:

echo $LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ORACLE_HOME/lib

8. Create and initialize an Oracle database for eZ Publish

An eZ Publish database must be created on the Oracle server. This means that you will need to initialize the necessary structure and import pre-defined data to the database. You can either do this using the "ora-initialize.sh" script (which attempts to do everything automatically) or manually. Please note that the script does not work under Windows. Also, you might have problems running the script on UNIX/Linux if you're using the Oracle Instant Client. The following text reveals both methods.

Automated initialization

Automated initialization is carried out using the "ora-initialize.sh" script. This script is included in the database extension. It is intended to help UNIX/Linux users creating a new eZ Publish site that uses an Oracle database. It is also possible to re-initialize an existing Oracle database that contains eZ Publish related information left after a previous eZ Publish installation. Please refer to the "Automated initialization" section for more information about this method.

Manual initialization

Manual initialization is a generic method that can be used to either create a new eZ Publish site running on an Oracle database or migrate an existing site from MySQL to Oracle. Both UNIX/Linux and Windows users can perform manual initialization. Please refer to the "Manual initialization" section for more information about this method.

9. Configure eZ Publish

In order to create a new eZ Publish site that uses an Oracle database, you need to configure file permissions, siteaccesses, Unicode support and languages for your site as described on the "Configuring eZ Publish" documentation page.

If you are migrating an existing site from MySQL to Oracle, the only thing you need to do is changing the database settings for your site. Simply open the "settings/override/site.ini.append.php" configuration file and change the "[DatabaseSettings]" block to something that resembles the example below:

[DatabaseSettings]
DatabaseImplementation=ezoracle
User=scott
Password=tiger
Database=ORCL

The example above assumes that you are using an Oracle database called "ORCL" which can be accessed using "scott" as the username and "tiger" as the password.

10. Restart Apache

A restart of the Apache web server is required in order for the changes outlined in the previous steps to take effect. Once it has been restarted, your eZ Publish installation should be using the Oracle database server (if you log in to the admin interface, access the "Setup" tab and select "System information" from the left menu, you should see "oracle" in the "Database type" section). Please note that the Oracle environment variables must be set before Apache is restarted, otherwise the PHP Oracle functions will not work.

---