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

1.  Choose the appropriate installation method
2.  Check the requirements
3.  Unclusterize images and other files (optional)
4.  Make a backup of your current system (optional)
5.  Download and unpack the database extension
6.  Test connection to an Oracle database server
7.  Test Oracle support in PHP
8.  Enable the extension
9.  Create and initialize an Oracle database for eZ Publish
    

   •  Automated initialization
   •  Manual initialization
10.  Configure eZ Publish
11.  Clear the caches
12.  Import the unclusterized data to the database (optional)

Note that for the sake of simplicity, this installation manual uses the term "instance name" when referring to connect identifiers. For example, "an instance called X" usually means "an instance that can be connected to using X as a connect identifier", where X is most likely defined in your "tnsnames.ora" file. When using the easy connect naming method, which enables you to connect to an Oracle database without using a "tnsnames.ora" file, a connect identifier could be something like "//dbserver.example.com:1521/ORCL".

1. Choose the appropriate installation method

Before installing the database extension, read the "Concepts and basics" section carefully in order to find out about the purpose of the extension and the possible limitations.

There are two possible ways of installing the database extension:

•  Migrating an existing eZ Publish site from MySQL to Oracle.
•  Creating a new eZ Publish site that uses an Oracle database from the beginning.

The first option assumes that you have eZ Publish already installed and configured. A typical example is when you have an eZ Publish site which is created by the setup wizard using either the "Plain site", "Website Interface" or "eZ Flow" site packages. If the site runs on a MySQL database, you can migrate it to Oracle without breaking the existing functionality.

The other option assumes that an eZ Publish distribution is downloaded and unpacked to a web-served directory. All further configuration will be done manually. The setup wizard cannot be used in this case. Therefore, if you want to install any of the standard site packages (such as Plain site, eZ Flow, or the Website Interface), you should choose the first option.

If your existing site uses the clustering functionality, you will have to unclusterize the data when migrating from MySQL to Oracle (see step 3 in the instructions below). If you want to continue using clustering after migrating to Oracle, the files should be imported to the new database at a later stage (see step 12). This is because eZ Publish does not use the same database tables for clustering on an Oracle database, and thus the clustering tables cannot be converted automatically when importing the database structure (and data) from MySQL. This will be improved in the future (refer to this page for more information).

2. Check the requirements

Verify that the requirements for the database extension are met.

3. Unclusterize images and other files (optional)

If your existing site stores images, binary files and content-related caches in a MySQL database, you must unclusterize the data before migrating to Oracle. Read the instructions on the "Reverting a cluster setup" documentation page to learn how this can be done.

If your existing site does not use the clustering functionality (or if you want to create a completely new site running on Oracle), skip this step.

4. 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. Refer to the "Backup" section of the "Upgrading" manual for more information.

The system must be closed to outside access during the backup and installation process.

5. Download and unpack the database extension

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

Make sure that you copy the downloaded ".zip" package into the "extension" directory of your eZ Publish installation.

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

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

unzip ezoracle-2.0.zip

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. 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

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

Example

Linux/UNIX 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 the LD_LIBRARY_PATH environment variable. The following instructions describe how to solve this problem.

1.  Check whether the LD_LIBRARY_PATH and ORACLE_HOME environment variables are set:

   echo $LD_LIBRARY_PATH
   echo $ORACLE_HOME
   

2.  If the ORACLE_HOME variable is set and points to the Oracle installation directory, set the LD_LIBRARY_PATH variable accordingly:

   export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ORACLE_HOME/lib
   

   Otherwise, locate the "libsqlplus.so" file first and then set the LD_LIBRARY_PATH variable:

   export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:path_to_library
   

   Replace "path_to_library" with the full path to the directory where the "libsqlplus.so" file resides (for example "/usr/lib/oracle/10.1.0.4/client/lib/").

7. Test Oracle support in PHP

The database extension requires Oracle support to be enabled in PHP. This means that the OCI8 extension module for PHP must be installed and configured properly. To check if this is taken care of, create a script "test.php" containing the following code:

<?php
  phpinfo();
?>

 and place it in an accessible directory on your web server. Access the script using a browser and look for a section called "oci8" on the browser page.

You can also check this from the command line by running the following command:

php -i

Note that a restart of the Apache web server might be needed when configuring the OCI8 extension for PHP. In addition, the Oracle environment variables must be set before Apache is restarted, otherwise the PHP Oracle functions will not work.

8. 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

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

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

To complete the activation of the extension, the autoload configuration must be regenerated, by running the php script ezpgenerateautoloads.php, which can be found in the bin/php directory (this is normally done automatically by eZ Publish itself when activating an extension via the administration interface).

Regenerate autoloads:

php bin/php/ezpgenerateautoloads.php --extension

9. 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. Note that the script does not work under Windows. The following text explains 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 Linux/UNIX 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. 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 Linux/UNIX and Windows users can perform manual initialization. Refer to the "Manual initialization" section for more information about this method.

10. Configure eZ Publish

In order to create a new eZ Publish site that uses an Oracle database, you need to configure file permissions, siteaccesses 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 to change the database settings for your site. To do this, you need to edit the "settings/override/site.ini.append.php" configuration file and make sure that the "[DatabaseSettings]" block contains 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.

11. Clear the caches

It is recommended to clear all eZ Publish caches after installing the database extension. This can be done from within a system shell:

1.  Navigate into your eZ Publish directory.

2.  Run the script using the following shell command:

   php bin/php/ezcache.php --clear-all --purge
   

After running the script, make sure that all cache files have been cleared by inspecting the contents of the various cache subdirectories within the "var" directory (typically the "var/cache/" and "var/<name_of_siteaccess>/cache/" directories). If there are any cache files left, remove them manually.

Once the changes outlined above take effect, your eZ Publish installation should be using the Oracle database server. If you log in to the administration interface, access the "Setup" tab and select "System information" from the left menu, you should see "oracle" in the "Database type" section.

12. Import the unclusterized data to the database (optional)

If you didn't unclusterize the files in step 3, skip this step.

If your site was using the clustering functionality on a MySQL database and you want it to continue doing so after migrating to Oracle, you need to set up clustering as described in the "clustering" section. Before doing so, make sure that your site works correctly and you do not experience any problems when running it on an Oracle database.