mirror of
https://github.com/php/php-src.git
synced 2024-10-21 08:22:42 +00:00
b9f72771a6
Cleaned up whitespace Fixed bug #44372 (compilation with Oracle 10gR1 libraries) http://bugs.php.net/bug.php?id=44372 Updated updated error number list to improve re-connection behavior after a database restart. Guard against potential internal list corruption after ping removes old oci_pconnect() information. Fix ini_set("oci8.connection_class", "abc") to get an appropriate persistent connection. Ping at oci8.ping_interval for oci_connect() and oci_new_connect() when DRCP connections are used. This improves non-persistent connection reliability if a database gets restarted.
361 lines
12 KiB
Plaintext
361 lines
12 KiB
Plaintext
Installing OCI8
|
|
---------------
|
|
|
|
1. Common requirements.
|
|
2. Installing as shared extension.
|
|
3. Installing as statically compiled extension.
|
|
4. Installing from PECL.
|
|
5. Testing OCI8
|
|
6. DRCP and FAN Support
|
|
|
|
1. Common requirements
|
|
----------------------
|
|
|
|
If you use a common Oracle Client installation that comes with the
|
|
Oracle server installation, you MUST set at least the ORACLE_HOME
|
|
environment variable and make it visible for your web-server BEFORE it
|
|
starts.
|
|
|
|
If you use Oracle Instant Client, you don't have to set ORACLE_HOME
|
|
and many of the other environment variables to build PHP with OCI8
|
|
support. The only variables you may have to set are:
|
|
|
|
LD_LIBRARY_PATH - it must include the Instant Client library directory
|
|
|
|
NLS_LANG - if you want to change the default encoding used during
|
|
interaction with Oracle servers
|
|
|
|
The most appropriate places to add the environment variables are:
|
|
|
|
/etc/profile
|
|
/etc/profile.local
|
|
/etc/profile.d
|
|
|
|
2. Installing as shared extension
|
|
---------------------------------
|
|
|
|
To install OCI8 as a shared extension (i.e. the one you should put
|
|
into your php.ini) use the following configure lines to configure PHP:
|
|
|
|
a) if you use a common Oracle or Oracle Client installation:
|
|
|
|
./configure --with-oci8=shared,$ORACLE_HOME
|
|
|
|
b) with Oracle Instant Client:
|
|
|
|
./configure --with-oci8=shared,instantclient,/path/to/instant/client/lib
|
|
|
|
If you use an RPM-based installation of Oracle Instant Client, your configure
|
|
line will look like this:
|
|
|
|
./configure --with-oci8=shared,instantclient,/usr/lib/oracle/<OIC version>/client/lib
|
|
|
|
Follow the usual building procedure after that and you'll get an OCI8
|
|
shared extension (i.e. oci8.so). Add it into the php.ini file like
|
|
this:
|
|
|
|
extension=oci8.so
|
|
|
|
and don't forget to specify the right extension_dir for PHP to be able
|
|
to find shared extensions correctly.
|
|
|
|
3. Installing as statically compiled extension
|
|
----------------------------------------------
|
|
|
|
To install OCI8 as statically compiled module use the following
|
|
configure lines:
|
|
|
|
a) with a common Oracle or Oracle Client installation
|
|
|
|
./configure --with-oci8=$ORACLE_HOME
|
|
|
|
b) with Oracle Instant Client
|
|
|
|
./configure --with-oci8=instantclient,/path/to/instant/client/lib
|
|
|
|
After successful compile, you don't have to add oci8.so to the
|
|
php.ini. The module will be usable without any additional actions.
|
|
|
|
4. Installing from PECL
|
|
-----------------------
|
|
|
|
TBD
|
|
|
|
5. Testing OCI8
|
|
---------------
|
|
|
|
OCI8 tests are in ext/oci8/tests. When OCI8 tests are run this
|
|
directory will contain logs of any failures.
|
|
|
|
5.1. Running OCI8 tests on Linux
|
|
|
|
5.1.1. Edit ext/oci8/tests/details.inc
|
|
|
|
Set the username, password and connection string for the database.
|
|
Most tests have been developed using the SYSTEM account: some tests
|
|
might fail unless the user has permissions to create necessary
|
|
tables, views, procedures etc.
|
|
|
|
If the database is on the same machine as PHP, set
|
|
$oracle_on_localhost to TRUE.
|
|
|
|
If Oracle 11g Database Resident Connection Pooling is being tested,
|
|
set $test_drcp to TRUE and ensure the connection string uses an
|
|
appropriate pooled server (see section 6.2.2).
|
|
|
|
An alternative to editing details.inc is the set the environment
|
|
variables
|
|
|
|
PHP_OCI8_TEST_USER
|
|
PHP_OCI8_TEST_PASS
|
|
PHP_OCI8_TEST_DB
|
|
PHP_OCI8_TEST_DB_ON_LOCALHOST
|
|
PHP_OCI8_TEST_DRCP
|
|
|
|
for example:
|
|
|
|
$ export PHP_OCI8_TEST_USER=system
|
|
$ export PHP_OCI8_TEST_PASS=oracle
|
|
$ export PHP_OCI8_TEST_DB=localhost/XE
|
|
$ export PHP_OCI8_TEST_DB_ON_LOCALHOST=TRUE
|
|
$ export PHP_OCI8_TEST_DRCP=FALSE
|
|
|
|
5.1.2. Set any necessary environment variables for the Oracle
|
|
database. With Oracle 10g XE do:
|
|
|
|
$ . /usr/lib/oracle/xe/app/oracle/product/10.2.0/server/bin/oracle_env.sh
|
|
|
|
For other versions of the Oracle database do:
|
|
|
|
$ . /usr/local/bin/oraenv
|
|
|
|
5.1.3. Check your php.ini has E in the variables_order parameter, for
|
|
example:
|
|
|
|
variables_order = "EGPCS"
|
|
|
|
5.1.4. Run the tests:
|
|
|
|
$ cd <your php src directory>
|
|
$ make test TESTS=ext/oci8
|
|
|
|
5.2. The tests execute rapidly. On fast machines with a local
|
|
database configured for light load (e.g. Oracle 10g XE) you might
|
|
see random tests fail with ORA-12516 or ORA-12520 errors. To
|
|
prevent this, increase the database PROCESSES parameter using the
|
|
following steps.
|
|
|
|
5.2.1. Connect as the oracle software owner:
|
|
|
|
$ su - oracle
|
|
|
|
5.2.2. Set the necessary environment variables as in 5.1.2.
|
|
|
|
5.2.3. Start the SQL*Plus command line tool and increase PROCESSES
|
|
|
|
$ sqlplus / as sysdba
|
|
SQL> alter system set processes=100 scope=spfile
|
|
|
|
5.2.4. Restart the database:
|
|
|
|
SQL> startup force
|
|
|
|
5.2.5. Rerun the tests
|
|
|
|
|
|
6. DRCP and FAN Support
|
|
-----------------------
|
|
|
|
The PHP 5.3 OCI8 Beta extension has support for the Oracle Database
|
|
Resident Connection Pool (DRCP) and Fast Application Notification
|
|
(FAN).
|
|
|
|
This release is for Beta testing only. Questions and issues can be
|
|
raised on the Oracle OTN forum (free registration required)
|
|
http://www.oracle.com/technology/forums/php.html
|
|
|
|
|
|
6.1. Oracle Version Compatibility
|
|
|
|
The OCI8 extension will compile with Oracle libraries from version
|
|
9iR2 onwards. However, full functionality (e.g. DRCP support) is only
|
|
available when Oracle 11g is used.
|
|
|
|
For other, general database functionality, the version of the Oracle
|
|
libraries used by PHP does not necessarily have to match the version
|
|
of the database.
|
|
|
|
|
|
6.2. Database Resident Connection Pooling (DRCP)
|
|
|
|
DRCP allows more efficient use of database machine memory and provides
|
|
high scalability.
|
|
|
|
For DRCP to be available in OCI8, Oracle client libraries used by PHP
|
|
and the version of the Oracle Database must both be 11g.
|
|
|
|
Documentation on DRCP is found in several Oracle manuals. For example,
|
|
see "Configuring Database Resident Connection Pooling" in the Oracle
|
|
Database Administrator's Guide 11g Release 1 (11.1)
|
|
http://download.oracle.com/docs/cd/B28359_01/server.111/b28310/manproc004.htm#CHDGIDBA
|
|
for usage information. A whitepaper
|
|
http://www.oracle.com/technology/tech/oci/pdf/oracledrcp11g.pdf
|
|
contains background information on DRCP.
|
|
|
|
After building PHP with the OCI8 extension and 11g libraries, follow
|
|
these steps:
|
|
|
|
6.2.0 Important: if Oracle Database 11.1.0.6 with DRCP connections is
|
|
used, then the Oracle database patch for bug 6474441 must be
|
|
applied (see section 6.5) or a workaround below used. Without
|
|
this patch, "ORA-01000: maximum open cursors exceeded", "ORA-01001
|
|
invalid cursor" or "ORA-01002 fetch out of sequence" errors may
|
|
occur.
|
|
|
|
If the Oracle 11.1.0.6 database patch cannot be applied, one of
|
|
the following three workarounds can be used to disable statement
|
|
caching instead:
|
|
|
|
(i) Connect using Oracle dedicated or shared servers instead of DRCP.
|
|
|
|
(ii) Set PHP's oci8.statement_cache_size to 0.
|
|
|
|
(iii) Set an event in the database initialization parameter file:
|
|
event="56699 trace name context forever, level 128".
|
|
|
|
|
|
6.2.1. As a privileged database administrator, use a program like
|
|
SQL*Plus to start the connection pool in the database:
|
|
|
|
SQL> execute dbms_connection_pool.start_pool;
|
|
|
|
Optional settings control the size and characteristics of the
|
|
pool.
|
|
|
|
6.2.2. For PHP applications that currently connect using a Network Alias
|
|
like:
|
|
|
|
$c = oci_pconnect("myuser", "mypassword", "MYDB");
|
|
|
|
Modify your tnsnames.ora file and add the "(SERVER=POOLED)"
|
|
clause, for example:
|
|
|
|
MYDB = (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) (HOST=myhost.dom.com)
|
|
(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=sales)
|
|
(SERVER=POOLED)))
|
|
|
|
Alternatively, modify the Easy Connect syntax in PHP and add
|
|
":POOLED" after the service name:
|
|
|
|
$c = oci_pconnect("myuser", "mypassword",
|
|
"myhost.dom.com:1521/sales:POOLED");
|
|
|
|
6.2.3. Edit php.ini and choose a connection class name. This name
|
|
indicates a logical division of the connection pool and can be
|
|
used to isolate pooling for separate applications. Any PHP
|
|
instance with the same connection class value will share
|
|
connections in the pool.
|
|
|
|
oci8.connection_class = "MY_APPLICATION_NAME"
|
|
|
|
6.2.4. Run your application, connecting to the 11g database.
|
|
|
|
|
|
6.3. Fast Application Notification (FAN) Support
|
|
|
|
FAN support gives fast connection failover, a high availability
|
|
feature. This allows PHP OCI8 scripts to be notified when a database
|
|
machine or database instance becomes unavailable. Without FAN, OCI8
|
|
can hang until a TCP timeout occurs and an error is returned, which
|
|
might be several minutes. Enabling FAN in OCI8 can allow your
|
|
applications to detect errors and re-connect to an available database
|
|
instance without the web user being aware of an outage.
|
|
|
|
FAN support is available when the Oracle client libraries that PHP
|
|
links with and the Oracle Database are either version 10gR2 or 11g.
|
|
|
|
FAN benefits users of Oracle's clustering technology (RAC) because
|
|
connections to surviving database instances can be immediately made.
|
|
Users of Oracle's Data Guard with a broker will see the FAN events
|
|
generated when the standby database goes online. Standalone databases
|
|
will send FAN events when the database restarts.
|
|
|
|
For active connections, when a machine or database instance becomes
|
|
unavailable, a connection failure error will be returned by the OCI8
|
|
extension function currently being called. On a subsequent PHP script
|
|
re-connect, a connection to a surviving database instance will be
|
|
established. The OCI8 extension also transparently cleans up any idle
|
|
connections affected by a database machine or instance failure so PHP
|
|
connect calls will establish a fresh connection without the script
|
|
being aware of any service disruption.
|
|
|
|
When oci8.events is On, it is suggested to set oci8.ping_interval to
|
|
-1 to disable pinging, since enabling FAN events provide pro-active
|
|
connection management of idle connections made invalid by a service
|
|
disruption.
|
|
|
|
To enable FAN support in PHP, after building PHP with Oracle 10gR2 or
|
|
11g libraries follow these steps:
|
|
|
|
6.3.1. As a privileged database administrator, use a program like
|
|
SQL*Plus to enable the database service to post FAN events, for
|
|
example:
|
|
|
|
SQL> execute dbms_service.modify_service(
|
|
SERVICE_NAME => 'sales',
|
|
AQ_HA_NOTIFICATIONS => TRUE);
|
|
|
|
6.3.2. Edit php.ini and add
|
|
|
|
oci8.events = On
|
|
|
|
6.3.3. If your application does not already handle OCI8 error
|
|
conditions, modify it to detect failures and take appropriate
|
|
action. This may include re-connecting and re-executing
|
|
statements.
|
|
|
|
6.3.4. Run your application, connecting to a 10gR2 or 11g database.
|
|
|
|
|
|
6.4. Recommendations and Known Limitations
|
|
|
|
6.4.1 Changing Password for DRCP connections
|
|
|
|
Changing a password over DRCP connections will fail with the error
|
|
"ORA-56609: Usage not supported with DRCP". This is an documented
|
|
restriction of Oracle Database 11g.
|
|
|
|
6.4.2 LOGON Triggers can be used to set session properties
|
|
|
|
The patch for Oracle Database 11.1.0.6 bug 6474441 (see section 6.5)
|
|
allows PHP applications with DRCP connection to use a database LOGON
|
|
trigger to set session properties at the time of session creation.
|
|
Examples of such settings are the NLS language and the date format.
|
|
|
|
If the Oracle 11.1.0.6 database patch cannot be applied, one of the
|
|
following workarounds can be used:
|
|
|
|
(i) After logon, explicitly set the session properties using PHP
|
|
application code.
|
|
|
|
(ii) Connect using Oracle dedicated or shared servers instead of DRCP.
|
|
|
|
With DRCP there is an connection management relationship between (i)
|
|
DRCP's automatic pool expansion and reduction, (ii) PHP's persistent
|
|
connection caching, (iii) with the way LOGON triggers fire with DRCP
|
|
authentication. Because of this interplay, LOGON triggers in PHP
|
|
(when DRCP is used) are only recommended for setting session
|
|
attributes and not for per-PHP connection events.
|
|
|
|
|
|
6.5. Patching Oracle Database 11g
|
|
|
|
The patch for bug 6474441 is available from Oracle Support's Metalink
|
|
system.
|
|
|
|
The bug is specific to Oracle 11.1.0.6 with DRCP connections. The
|
|
issues it fixes do not affect connections using Oracle's dedicated
|
|
(the default connection mode) or shared servers. They do not affect
|
|
earlier versions of Oracle. The bug is intended to be fixed in Oracle
|
|
Database 11.1.0.7 (as yet unreleased).
|