Automated initialization

This section describes how you can create a clean eZ Publish database on your Oracle server using the "ora-initialize.sh" script. The script is intended to help those UNIX/Linux users who wish to create a new eZ Publish site running on an Oracle database (It is also possible to re-initialize an Oracle database that contains eZ Publish related information left after previous eZ Publish installations).

The "ora-initialize.sh" script is located in the "extension/ezoracle/scripts" directory and can be executed using the Bourne Again Shell (bash).

Please note that if you are using the Oracle Instant Client, the "ora-initialize.sh" script might not work correctly because the "ORACLE_HOME" environment variable is probably not in use and the script will not find the "$ORACLE_HOME/network/admin/tnsnames.ora" file. In this case, you can manually set this environment variable and copy the "tnsnames.ora" file to the "$ORACLE_HOME/network/admin/" directory before running the script. The following example demonstrates how this can be done.

1. Make sure that the "ORACLE_HOME" environment variable is not set:

   echo $ORACLE_HOME
   

2. Locate the "tnsnames.ora" file (in most cases it can be found in "/etc/tnsnames.ora" or "~/.tnsnames.ora").
3. Create the "~/network/admin/" directory and copy the "tnsnames.ora" file there. (If there is a dot in the beginning of a filename, remove it.)
4. Set the "ORACLE_HOME" environment variable:

   export ORACLE_HOME=path_to_your_home_directory
   

The following example shows how to run the "ora-initialize.sh" script.

1. Navigate into the eZ Publish installation directory.
2. Run the script using the following command:
   

   ./extension/ezoracle/scripts/ora-initialize.sh
   

The script will perform several steps (described below). Please note that when the script needs to perform any actions on an Oracle server, it will create a temporary (hidden) file called ".ezoracle_test.php", execute it and then remove it (the temporary file is a script that makes use of the PHP Oracle functions). This is done on every step except the 4-th one. In other words, the script must have write/create privileges in the directory.

Step 1. Checking requirements

The script will check if the following requirements are met:

• PHP CLI is available
• The environment variable $ORACLE_HOME, which points to the Oracle installation directory, is set and the "tnsnames.ora" file is present it the "network/admin" subdirectory
• PHP has support for Oracle compiled in
• The eZ Publish installation contains the "ezoracle" extension
• Both database schema and database data files ("share/db_schema.dba" and "share/db_data.dba") are present in the eZ Publish directory.

Step 2. Testing connection to an Oracle server (optional)

The script will ask you if this step should be performed or not (skipping is not recommended). If yes, you will have to provide the following information:

Step 3. Creating an Oracle user with sufficient privileges (optional)

The script will ask if you wish to create a new Oracle user account. If you already have a user with sufficient privileges, you can skip this step. To create a new user, you will have to provide the following:

• The username and password for the database administrator (or any other Oracle user that has the "CREATE USER" system privilege).
• The username and password for the user that is being created.
• The name of the Oracle instance.

The script will display the SQL query for creating a new user, ask for confirmation and finally add the user.

Step 4. Connecting to an Oracle server

If you did not create a new user account during step 3, the script will ask you to provide the username/password (not the DB administrator, but the one which the eZ Publish database belongs to) and the name of the Oracle instance. The user must have the required privileges, so that the script can connect to the specified Oracle database and perform the next steps.

Please note that this step will be skipped if you created a new user during step 3.

Step 5. Testing user info with Oracle

The script will now attempt to connect to the specified Oracle database using the Oracle account that was specified/created during step 3 or 4.

Step 6. Creating the "md5_digest" function

The database extension requires a custom function called "md5_digest" to be stored in the database. This function returns an MD5 hash (checksum) generated for the provided string input. The script will create this function if the Oracle account that is being used has "CREATE PROCEDURE" privilege.

Step 7. Cleaning up the database

The script will search for existing eZ Publish data in the database and get rid of it (if any).

Step 8. Initializing the database structure

The script will initialize the necessary database structure for eZ Publish (create all the necessary tables, sequences and triggers in the Oracle database) according to the instructions specified in the "share/db_schema.dba" file.

Step 9. Importing pre-defined data to the database

The script will import the pre-defined data from the "share/db_data.dba" file to the database, so that the clean eZ Publish database will be ready to use.

Once the automated initialization has successfully finished, you may continue the installation process by following the remaining steps.