/
connection.xml
266 lines (264 loc) · 9.49 KB
/
connection.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<chapter xml:id="oci8.connection" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>OCI8 Connection Handling and Connection Pooling</title>
<section>
<title>Connection Functions</title>
<para>
The OCI8 extension provides three different functions for
connecting to Oracle. The standard connection function
is <function>oci_connect</function>. This creates a connection to
an Oracle database and returns a resource used by subsequent
database calls.
</para>
<para>
Connecting to an Oracle server is a reasonably expensive operation
in terms of the time that it takes to complete.
The <function>oci_pconnect</function> function uses a persistent
cache of connections that can be re-used across different script
requests. This means that the connection overhead will typically
only occur once per PHP process (or Apache child).
</para>
<para>
If the application connects to Oracle using a different set of database
credentials for each web user, the persistent cache employed by
<function>oci_pconnect</function> will become less useful as the
number of concurrent users increases, to the point where it may
start to adversely affect the overall performance of the Oracle
server due to maintaining too many idle connections. If the
application is structured in this way, it is recommended to either
tune the application using
the <link linkend="ini.oci8.max-persistent">oci8.max_persistent</link>
and <link linkend="ini.oci8.persistent-timeout">oci8.persistent_timeout</link>
configuration settings (these will give control over the persistent
connection cache size and lifetime), use Oracle Database
Resident Connection Pooling (in Oracle Database 11g or later), or use
<function>oci_connect</function> instead.
</para>
<para>
Both <function>oci_connect</function>
and <function>oci_pconnect</function> employ a connection cache; if
multiple calls to
<function>oci_connect</function> use the same parameters in a given
script, the second and subsequent calls return the existing
connection handle. The cache used
by <function>oci_connect</function> is cleaned up at the end of the
script run, or when the connection handle is explicitly closed. The
function <function>oci_pconnect</function> has similar behavior,
although its cache is maintained separately and survives between
HTTP requests.
</para>
<para>
This caching feature means the two handles are not transactionally
isolated (they are in fact the same connection handle, so there is
no isolation of any kind). If the application needs two separate,
transactionally isolated connections, then
use <function>oci_new_connect</function>.
</para>
<para>
The <function>oci_pconnect</function> cache is cleared and any
database connections closed when the PHP process terminates, so
effective use of persistent connections requires that PHP be an
Apache module or used with FPM, or similar. Persistent connections
will not have any benefits over <function>oci_connect</function>
when PHP is used with CGI or via the command-line.
</para>
<para>
The function <function>oci_new_connect</function> always creates a
new connection to the Oracle server, regardless of what other
connections might already exist. High traffic web applications
should avoid using
<function>oci_new_connect</function>, especially in the busiest sections of
the application.
</para>
<para>
Persistent connections can be
closed by the user, allowing greater control over connection
resource usage. Persistent connections will now also be closed
automatically when there is no PHP variable referencing them, such
as at the end of scope of a PHP user function. This will rollback
any uncommitted transaction. These changes to persistent
connections make them behave similarly to non-persistent
connections, simplifying the interface, allowing for greater
application consistency and predictability.
Use <link linkend="ini.oci8.old-oci-close-semantics">oci8.old_oci_close_semantics</link>
set to
<emphasis>On</emphasis> to retain the historical behavior.
</para>
<para>
The automatic re-establishment of PHP persistent connections after an Apache
or FPM process respawns means Oracle Database <literal>LOGON</literal>
triggers are only recommended for setting session attributes and not for
per-application user connection requests.
</para>
</section>
<section>
<title>DRCP Connection Pooling</title>
<para>
PHP supports Oracle Database Resident
Connection Pooling (DRCP). DRCP allows more efficient use of
database machine memory and provides high scalability. No, or
minimal, application changes are needed to use DRCP.
</para>
<para>
DRCP is suited for applications that connect using few database
schemas and hold database connections open for a short period of
time. Other applications should use Oracle's
default <literal>Dedicated</literal> database server processes, or
use <literal>Shared</literal> servers.
</para>
<para>
DRCP benefits all three connection functions, but gives the highest
scalability when connections are created
with <function>oci_pconnect</function>.
</para>
<para>
For DRCP to be available in OCI8, Oracle client libraries used by
PHP and the version of the Oracle Database must both be 11g or greater.
</para>
<para>
Documentation on DRCP is found in several Oracle manuals. For
example,
see <link xlink:href="&url.oracle.drcp.configure;">Configuring
Database Resident Connection Pooling</link> in the Oracle
documentation for usage information.
A <link xlink:href="&url.oracle.drcp.whitepaper;">DRCP
white paper</link> contains background information on DRCP.
</para>
<para>
To use DRCP, install the OCI8 extension and Oracle 11g (or later)
libraries and then follow these steps:
</para>
<para>
<itemizedlist>
<listitem>
<para>
As a privileged database administrator, use a program like
SQL*Plus to start the connection pool in the database:
</para>
<para>
<informalexample>
<screen>
<![CDATA[
SQL> execute dbms_connection_pool.start_pool;
]]>
</screen>
</informalexample>
</para>
</listitem>
<listitem>
<para>
Optionally
use <literal>dbms_connection_pool.alter_param()</literal> to
configure DRCP settings. The current pool settings can be
queried from the <literal>DBA_CPOOL_INFO</literal> view.
</para>
</listitem>
<listitem>
<para>
Update the connection strings used. For PHP applications that
currently connect using a Network Connect Name
like <literal>MYDB</literal>:
</para>
<para>
<informalexample>
<screen>
<![CDATA[
$c = oci_pconnect("myuser", "mypassword", "MYDB");
]]>
</screen>
</informalexample>
</para>
<para>
modify the tnsnames.ora file and add
a <literal>(SERVER=POOLED)</literal> clause, for example:
</para>
<para>
<informalexample>
<screen>
<![CDATA[
MYDB = (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) (HOST=myhost.dom.com)
(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=sales)
(SERVER=POOLED)))
]]>
</screen>
</informalexample>
</para>
<para>
Alternatively, modify the Easy Connect syntax in PHP and add
<literal>:POOLED</literal> after the service name:
</para>
<para>
<informalexample>
<screen>
<![CDATA[
$c = oci_pconnect("myuser", "mypassword", "myhost.dom.com:1521/sales:POOLED");
]]>
</screen>
</informalexample>
</para>
</listitem>
<listitem>
<para>
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
applications with the same user name and connection class value
will be able to share connections in the pool, giving greater
scalability.
</para>
<para>
<informalexample>
<screen>
<![CDATA[
oci8.connection_class = "MY_APPLICATION_NAME"
]]>
</screen>
</informalexample>
</para>
</listitem>
<listitem>
<para>
Run the application, connecting to the 11g (or later) database.
</para>
</listitem>
</itemizedlist>
</para>
<note>
<para>
Applications using Oracle Client libraries 10g that require the performance of
persistent connections can reduce the amount of database server
memory needed by using Oracle <literal>Shared</literal> servers
(previously known as Multi Threaded Servers). Refer to Oracle
documentation for information.
</para>
</note>
<note>
<para>
Changing a password over DRCP connections will fail with the error
<emphasis>ORA-56609: Usage not supported with DRCP</emphasis>.
This is a documented restriction of Oracle Database 11g.
</para>
</note>
</section>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->