mirror of
https://github.com/ACSPRI/queXS
synced 2024-04-02 12:12:16 +00:00
Merging the Limesurvey 1.91+ branch of queXS in to the trunk
This commit is contained in:
azammitdcarf
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -1,329 +0,0 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
<html>
|
||||
<head>
|
||||
<title>ADOdb Data Dictionary Manual</title>
|
||||
<meta http-equiv="Content-Type"
|
||||
content="text/html; charset=iso-8859-1">
|
||||
<style type="text/css">
|
||||
body, td {
|
||||
/*font-family: Arial, Helvetica, sans-serif;*/
|
||||
font-size: 11pt;
|
||||
}
|
||||
pre {
|
||||
font-size: 9pt;
|
||||
background-color: #EEEEEE; padding: .5em; margin: 0px;
|
||||
}
|
||||
.toplink {
|
||||
font-size: 8pt;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body style="background-color: rgb(255, 255, 255);">
|
||||
<h2>ADOdb Data Dictionary Library for PHP</h2>
|
||||
<p>V5.06 16 Oct 2008 (c) 2000-2009 John Lim (<a
|
||||
href="mailto:jlim#natsoft.com">jlim#natsoft.com</a>).<br>
|
||||
AXMLS (c) 2004 ars Cognita, Inc</p>
|
||||
<p><font size="1">This software is dual licensed using BSD-Style and
|
||||
LGPL. This means you can use it in compiled proprietary and commercial
|
||||
products.</font></p>
|
||||
|
||||
<p>Useful ADOdb links: <a href="http://adodb.sourceforge.net/#download">Download</a>
|
||||
<a href="http://adodb.sourceforge.net/#docs">Other Docs</a>
|
||||
</p>
|
||||
<p>This documentation describes a PHP class library to automate the
|
||||
creation of tables, indexes and foreign key constraints portably for
|
||||
multiple databases. Richard Tango-Lowy and Dan Cech have been kind
|
||||
enough to contribute <a href="#xmlschema">AXMLS</a>, an XML schema
|
||||
system for defining databases. You can contact them at
|
||||
dcech#phpwerx.net and richtl#arscognita.com.</p>
|
||||
<p>Currently the following databases are supported:</p>
|
||||
<p> <b>Well-tested:</b> PostgreSQL, MySQL, Oracle, MSSQL.<br>
|
||||
<b>Beta-quality:</b> DB2, Informix, Sybase, Interbase, Firebird.<br>
|
||||
<b>Alpha-quality:</b> MS Access (does not support DEFAULT values) and
|
||||
generic ODBC.
|
||||
</p>
|
||||
<h3>Example Usage</h3>
|
||||
<pre> include_once('adodb.inc.php');<br> <font color="#006600"># First create a normal connection</font><br> $db = NewADOConnection('mysql');<br> $db->Connect(...);<br><br> <font
|
||||
color="#006600"># Then create a data dictionary object, using this connection</font><br> $dict = <strong>NewDataDictionary</strong>($db);<br><br> <font
|
||||
color="#006600"># We have a portable declarative data dictionary format in ADOdb, similar to SQL.<br> # Field types use 1 character codes, and fields are separated by commas.<br> # The following example creates three fields: "col1", "col2" and "col3":</font><br> $flds = " <br> <font
|
||||
color="#663300"><strong> col1 C(32) NOTNULL DEFAULT 'abc',<br> col2 I DEFAULT 0,<br> col3 N(12.2)</strong></font><br> ";<br><br> <font
|
||||
color="#006600"># We demonstrate creating tables and indexes</font><br> $sqlarray = $dict-><strong>CreateTableSQL</strong>($tabname, $flds, $taboptarray);<br> $dict-><strong>ExecuteSQLArray</strong>($sqlarray);<br><br> $idxflds = 'co11, col2';<br> $sqlarray = $dict-><strong>CreateIndexSQL</strong>($idxname, $tabname, $idxflds);<br> $dict-><strong>ExecuteSQLArray</strong>($sqlarray);<br></pre>
|
||||
<h3>More Complex Table Sample</h3>
|
||||
<p>
|
||||
The following string will create a table with a primary key event_id and multiple indexes, including one compound index idx_ev1. The ability to define indexes using the INDEX keyword was added in ADOdb 4.94 by Gaetano Giunta.
|
||||
<pre>
|
||||
$flds = "
|
||||
event_id I(11) NOTNULL AUTOINCREMENT PRIMARY,
|
||||
event_type I(4) NOTNULL <b>INDEX idx_evt</b>,
|
||||
event_start_date T DEFAULT NULL <b>INDEX id_esd</b>,
|
||||
event_end_date T DEFAULT '0000-00-00 00:00:00' <b>INDEX id_eted</b>,
|
||||
event_parent I(11) UNSIGNED NOTNULL DEFAULT 0 <b>INDEX id_evp</b>,
|
||||
event_owner I(11) DEFAULT 0 <b>INDEX idx_ev1</b>,
|
||||
event_project I(11) DEFAULT 0 <b>INDEX idx_ev1</b>,
|
||||
event_times_recuring I(11) UNSIGNED NOTNULL DEFAULT 0,
|
||||
event_icon C(20) DEFAULT 'obj/event',
|
||||
event_description X
|
||||
";
|
||||
$sqlarray = $db-><b>CreateTableSQL</b>($tablename, $flds);
|
||||
$dict-><b>ExecuteSQLArray</b>($sqlarray);
|
||||
</pre>
|
||||
<h3>Class Factory</h3>
|
||||
<h4>NewDataDictionary($connection, $drivername=false)</h4>
|
||||
<p>Creates a new data dictionary object. You pass a database connection object in $connection. The $connection does not have to be actually connected to the database. Some database connection objects are generic (eg. odbtp and odbc). Since 4.53, you can tell ADOdb the actual database with $drivername. E.g.</p>
|
||||
<pre>
|
||||
$db = NewADOConnection('odbtp');
|
||||
$datadict = NewDataDictionary($db, 'mssql'); # force mssql
|
||||
</pre>
|
||||
<h3>Class Functions</h3>
|
||||
<h4>function CreateDatabase($dbname, $optionsarray=false)</h4>
|
||||
<p>Create a database with the name $dbname;</p>
|
||||
<h4>function CreateTableSQL($tabname, $fldarray, $taboptarray=false)</h4>
|
||||
<pre> RETURNS: an array of strings, the sql to be executed, or false<br> $tabname: name of table<br> $fldarray: string (or array) containing field info<br> $taboptarray: array containing table options<br></pre>
|
||||
<p>The new format of $fldarray uses a free text format, where each
|
||||
field is comma-delimited.
|
||||
The first token for each field is the field name, followed by the type
|
||||
and optional
|
||||
field size. Then optional keywords in $otheroptions:</p>
|
||||
<pre> "$fieldname $type $colsize $otheroptions"</pre>
|
||||
<p>The older (and still supported) format of $fldarray is a
|
||||
2-dimensional array, where each row in the 1st dimension represents one
|
||||
field. Each row has this format:</p>
|
||||
<pre> array($fieldname, $type, [,$colsize] [,$otheroptions]*)</pre>
|
||||
<p>The first 2 fields must be the field name and the field type. The
|
||||
field type can be a portable type codes or the actual type for that
|
||||
database.</p>
|
||||
<p>Legal portable type codes include:</p>
|
||||
<pre> C: Varchar, capped to 255 characters.<br> X: Larger varchar, capped to 4000 characters (to be compatible with Oracle). <br> XL: For Oracle, returns CLOB, otherwise the largest varchar size.<br><br> C2: Multibyte varchar<br> X2: Multibyte varchar (largest size)<br><br> B: BLOB (binary large object)<br><br> D: Date (some databases do not support this, and we return a datetime type)<br> T: Datetime or Timestamp<br> L: Integer field suitable for storing booleans (0 or 1)<br> I: Integer (mapped to I4)<br> I1: 1-byte integer<br> I2: 2-byte integer<br> I4: 4-byte integer<br> I8: 8-byte integer<br> F: Floating point number<br> N: Numeric or decimal number<br></pre>
|
||||
<p>The $colsize field represents the size of the field. If a decimal
|
||||
number is used, then it is assumed that the number following the dot is
|
||||
the precision, so 6.2 means a number of size 6 digits and 2 decimal
|
||||
places. It is recommended that the default for number types be
|
||||
represented as a string to avoid any rounding errors.</p>
|
||||
<p>The $otheroptions include the following keywords (case-insensitive):</p>
|
||||
<pre> AUTO For autoincrement number. Emulated with triggers if not available.<br> Sets NOTNULL also.<br> AUTOINCREMENT Same as auto.<br> KEY Primary key field. Sets NOTNULL also. Compound keys are supported.<br> PRIMARY Same as KEY.<br> DEF Synonym for DEFAULT for lazy typists.<br> DEFAULT The default value. Character strings are auto-quoted unless<br> the string begins and ends with spaces, eg ' SYSDATE '.<br> NOTNULL If field is not null.<br> DEFDATE Set default value to call function to get today's date.<br> DEFTIMESTAMP Set default to call function to get today's datetime.<br> NOQUOTE Prevents autoquoting of default string values.<br> CONSTRAINTS Additional constraints defined at the end of the field<br> definition.<br></pre>
|
||||
<p>The Data Dictonary accepts two formats, the older array
|
||||
specification:</p>
|
||||
<pre> $flds = array(<br> array('COLNAME', 'DECIMAL', '8.4', 'DEFAULT' =gt; 0, 'NOTNULL'),<br> array('id', 'I' , 'AUTO'),<br> array('`MY DATE`', 'D' , 'DEFDATE'),<br> array('NAME', 'C' , '32', 'CONSTRAINTS' =gt; 'FOREIGN KEY REFERENCES reftable')<br> );<br></pre>
|
||||
<p>Or the simpler declarative format:</p>
|
||||
<pre> $flds = "<font color="#660000"><strong><br> COLNAME DECIMAL(8.4) DEFAULT 0 NOTNULL,<br> id I AUTO,<br> `MY DATE` D DEFDATE,<br> NAME C(32) CONSTRAINTS 'FOREIGN KEY REFERENCES reftable'</strong></font><br> ";<br></pre>
|
||||
<p>Note that if you have special characters in the field name (e.g. My
|
||||
Date), you should enclose it in back-quotes. Normally field names are
|
||||
not case-sensitive, but if you enclose it in back-quotes, some
|
||||
databases will treat the names as case-sensitive (eg. Oracle) , and
|
||||
others won't. So be careful.</p>
|
||||
<p>The $taboptarray is the 3rd parameter of the CreateTableSQL
|
||||
function. This contains table specific settings. Legal keywords include:</p>
|
||||
<ul>
|
||||
<li><b>REPLACE</b><br>
|
||||
Indicates that the previous table definition should be removed
|
||||
(dropped)together with ALL data. See first example below. </li>
|
||||
<li><b>DROP</b><br>
|
||||
Drop table. Useful for removing unused tables. </li>
|
||||
<li><b>CONSTRAINTS</b><br>
|
||||
Define this as the key, with the constraint as the value. See the
|
||||
postgresql <a href="#foreignkey">example</a> below. Additional constraints defined for the whole
|
||||
table. You will probably need to prefix this with a comma. </li>
|
||||
</ul>
|
||||
<p>Database specific table options can be defined also using the name
|
||||
of the database type as the array key. In the following example, <em>create
|
||||
the table as ISAM with MySQL, and store the table in the "users"
|
||||
tablespace if using Oracle</em>. And because we specified REPLACE, drop
|
||||
the table first.</p>
|
||||
<pre> $taboptarray = array('mysql' =gt; 'TYPE=ISAM', 'oci8' =gt; 'tablespace users', 'REPLACE');</pre>
|
||||
<p><a name=foreignkey></a>You can also define foreign key constraints. The following is syntax
|
||||
for postgresql:
|
||||
</p>
|
||||
<pre> $taboptarray = array('constraints' =gt; ', FOREIGN KEY (col1) REFERENCES reftable (refcol)');</pre>
|
||||
<h4>function DropTableSQL($tabname)</h4>
|
||||
<p>Returns the SQL to drop the specified table.</p>
|
||||
<h4>function ChangeTableSQL($tabname, $flds, $tableOptions=false, $dropOldFlds=false)</h4>
|
||||
<p>Checks to see if table exists, if table does not exist, behaves like
|
||||
CreateTableSQL. If table exists, generates appropriate ALTER TABLE
|
||||
MODIFY COLUMN commands if field already exists, or ALTER TABLE ADD
|
||||
$column if field does not exist.</p>
|
||||
<p>The class must be connected to the database for ChangeTableSQL to
|
||||
detect the existence of the table. Idea and code contributed by Florian
|
||||
Buzin.</p>
|
||||
<p>Old fields not defined in $flds are not dropped by default. To drop old fields, set $dropOldFlds to true.
|
||||
<h4>function RenameTableSQL($tabname,$newname)</h4>
|
||||
<p>Rename a table. Returns the an array of strings, which is the SQL required to rename a table. Since ADOdb 4.53. Contributed by Ralf Becker.</p>
|
||||
<h4> function RenameColumnSQL($tabname,$oldcolumn,$newcolumn,$flds='')</h4>
|
||||
<p>Rename a table field. Returns the an array of strings, which is the SQL required to rename a column. The optional $flds is a complete column-defintion-string like for AddColumnSQL, only used by mysql at the moment. Since ADOdb 4.53. Contributed by Ralf Becker.</p>
|
||||
<h4>function CreateIndexSQL($idxname, $tabname, $flds,
|
||||
$idxoptarray=false)</h4>
|
||||
<pre> RETURNS: an array of strings, the sql to be executed, or false<br> $idxname: name of index<br> $tabname: name of table<br> $flds: list of fields as a comma delimited string or an array of strings<br> $idxoptarray: array of index creation options<br></pre>
|
||||
<p>$idxoptarray is similar to $taboptarray in that index specific
|
||||
information can be embedded in the array. Other options include:</p>
|
||||
<pre> CLUSTERED Create clustered index (only mssql)<br> BITMAP Create bitmap index (only oci8)<br> UNIQUE Make unique index<br> FULLTEXT Make fulltext index (only mysql)<br> HASH Create hash index (only postgres)<br> DROP Drop legacy index<br></pre>
|
||||
<h4>function DropIndexSQL ($idxname, $tabname = NULL)</h4>
|
||||
<p>Returns the SQL to drop the specified index.</p>
|
||||
<h4>function AddColumnSQL($tabname, $flds)</h4>
|
||||
<p>Add one or more columns. Not guaranteed to work under all situations.</p>
|
||||
<h4>function AlterColumnSQL($tabname, $flds)</h4>
|
||||
<p>Warning, not all databases support this feature.</p>
|
||||
<h4>function DropColumnSQL($tabname, $flds)</h4>
|
||||
<p>Drop 1 or more columns.</p>
|
||||
<h4>function SetSchema($schema)</h4>
|
||||
<p>Set the schema.</p>
|
||||
<h4>function MetaTables()</h4>
|
||||
<h4>function MetaColumns($tab, $upper=true, $schema=false)</h4>
|
||||
<h4>function MetaPrimaryKeys($tab,$owner=false,$intkey=false)</h4>
|
||||
<h4>function MetaIndexes($table, $primary = false, $owner = false)</h4>
|
||||
<p>These functions are wrappers for the corresponding functions in the
|
||||
connection object. However, the table names will be autoquoted by the
|
||||
TableName function (see below) before being passed to the connection
|
||||
object.</p>
|
||||
<h4>function NameQuote($name = NULL)</h4>
|
||||
<p>If the provided name is quoted with backquotes (`) or contains
|
||||
special characters, returns the name quoted with the appropriate quote
|
||||
character, otherwise the name is returned unchanged.</p>
|
||||
<h4>function TableName($name)</h4>
|
||||
<p>The same as NameQuote, but will prepend the current schema if
|
||||
specified</p>
|
||||
<h4>function MetaType($t,$len=-1,$fieldobj=false)</h4>
|
||||
<h4>function ActualType($meta)</h4>
|
||||
<p>Convert between database-independent 'Meta' and database-specific
|
||||
'Actual' type codes.</p>
|
||||
<h4>function ExecuteSQLArray($sqlarray, $contOnError = true)</h4>
|
||||
<pre> RETURNS: 0 if failed, 1 if executed all but with errors, 2 if executed successfully<br> $sqlarray: an array of strings with sql code (no semicolon at the end of string)<br> $contOnError: if true, then continue executing even if error occurs<br></pre>
|
||||
<p>Executes an array of SQL strings returned by CreateTableSQL or
|
||||
CreateIndexSQL.</p>
|
||||
<hr />
|
||||
<a name="xmlschema"></a>
|
||||
<h2>ADOdb XML Schema (AXMLS)</h2>
|
||||
<p>This is a class contributed by Richard Tango-Lowy and Dan Cech that
|
||||
allows the user to quickly
|
||||
and easily build a database using the excellent ADODB database library
|
||||
and a simple XML formatted file.
|
||||
You can <a href="http://sourceforge.net/projects/adodb-xmlschema/">download
|
||||
the latest version of AXMLS here</a>.</p>
|
||||
<h3>Quick Start</h3>
|
||||
<p>Adodb-xmlschema, or AXMLS, is a set of classes that allow the user
|
||||
to quickly and easily build or upgrade a database on almost any RDBMS
|
||||
using the excellent ADOdb database library and a simple XML formatted
|
||||
schema file. Our goal is to give developers a tool that's simple to
|
||||
use, but that will allow them to create a single file that can build,
|
||||
upgrade, and manipulate databases on most RDBMS platforms.</p>
|
||||
<span style="font-weight: bold;"> Installing axmls</span>
|
||||
<p>The easiest way to install AXMLS to download and install any recent
|
||||
version of the ADOdb database abstraction library. To install AXMLS
|
||||
manually, simply copy the adodb-xmlschema.inc.php file and the xsl
|
||||
directory into your adodb directory.</p>
|
||||
<span style="font-weight: bold;"> Using AXMLS in Your Application</span>
|
||||
<p>There are two steps involved in using AXMLS in your application:
|
||||
first, you must create a schema, or XML representation of your
|
||||
database, and second, you must create the PHP code that will parse and
|
||||
execute the schema.</p>
|
||||
<p>Let's begin with a schema that describes a typical, if simplistic
|
||||
user management table for an application.</p>
|
||||
<pre class="listing"><pre><?xml version="1.0"?><br><schema version="0.2"><br><br> <table name="users"><br> <desc>A typical users table for our application.</desc><br> <field name="userId" type="I"><br> <descr>A unique ID assigned to each user.</descr><br><br> <KEY/><br> <AUTOINCREMENT/><br> </field><br> <br> <field name="userName" type="C" size="16"><NOTNULL/></field><br><br> <br> <index name="userName"><br> <descr>Put a unique index on the user name</descr><br> <col>userName</col><br> <UNIQUE/><br><br> </index><br> </table><br> <br> <sql><br> <descr>Insert some data into the users table.</descr><br> <query>insert into users (userName) values ( 'admin' )</query><br><br> <query>insert into users (userName) values ( 'Joe' )</query><br> </sql><br></schema> <br></pre></pre>
|
||||
<p>Let's take a detailed look at this schema.</p>
|
||||
<p>The opening <?xml version="1.0"?> tag is required by XML. The
|
||||
<schema> tag tells the parser that the enclosed markup defines an
|
||||
XML schema. The version="0.2" attribute sets <em>the version of the
|
||||
AXMLS DTD used by the XML schema.</em> </p>
|
||||
<p>All versions of AXMLS prior to version 1.0 have a schema version of
|
||||
"0.1". The current schema version is "0.2".</p>
|
||||
<pre class="listing"><pre><?xml version="1.0"?><br><schema version="0.2"><br> ...<br></schema><br></pre></pre>
|
||||
<p>Next we define one or more tables. A table consists of a fields (and
|
||||
other objects) enclosed by <table> tags. The name="" attribute
|
||||
specifies the name of the table that will be created in the database.</p>
|
||||
<pre class="listing"><pre><table name="users"><br><br> <desc>A typical users table for our application.</desc><br> <field name="userId" type="I"><br><br> <descr>A unique ID assigned to each user.</descr><br> <KEY/><br> <AUTOINCREMENT/><br> </field><br> <br> <field name="userName" type="C" size="16"><NOTNULL/></field><br><br> <br></table><br></pre></pre>
|
||||
<p>This table is called "users" and has a description and two fields.
|
||||
The description is optional, and is currently only for your own
|
||||
information; it is not applied to the database.</p>
|
||||
<p>The first <field> tag will create a field named "userId" of
|
||||
type "I", or integer. (See the ADOdb Data Dictionary documentation for
|
||||
a list of valid types.) This <field> tag encloses two special
|
||||
field options: <KEY/>, which specifies this field as a primary
|
||||
key, and <AUTOINCREMENT/>, which specifies that the database
|
||||
engine should automatically fill this field with the next available
|
||||
value when a new row is inserted.</p>
|
||||
<p>The second <field> tag will create a field named "userName" of
|
||||
type "C", or character, and of length 16 characters. The
|
||||
<NOTNULL/> option specifies that this field does not allow NULLs.</p>
|
||||
<p>There are two ways to add indexes to a table. The simplest is to
|
||||
mark a field with the <KEY/> option as described above; a primary
|
||||
key is a unique index. The second and more powerful method uses the
|
||||
<index> tags.</p>
|
||||
<pre class="listing"><pre><table name="users"><br> ...<br> <br> <index name="userName"><br> <descr>Put a unique index on the user name</descr><br> <col>userName</col><br><br> <UNIQUE/><br> </index><br> <br></table><br></pre></pre>
|
||||
<p>The <index> tag specifies that an index should be created on
|
||||
the enclosing table. The name="" attribute provides the name of the
|
||||
index that will be created in the database. The description, as above,
|
||||
is for your information only. The <col> tags list each column
|
||||
that will be included in the index. Finally, the <UNIQUE/> tag
|
||||
specifies that this will be created as a unique index.</p>
|
||||
<p>Finally, AXMLS allows you to include arbitrary SQL that will be
|
||||
applied to the database when the schema is executed.</p>
|
||||
<pre class="listing"><pre><sql><br> <descr>Insert some data into the users table.</descr><br> <query>insert into users (userName) values ( 'admin' )</query><br><br> <query>insert into users (userName) values ( 'Joe' )</query><br></sql><br></pre></pre>
|
||||
<p>The <sql> tag encloses any number of SQL queries that you
|
||||
define for your own use.</p>
|
||||
<p>Now that we've defined an XML schema, you need to know how to apply
|
||||
it to your database. Here's a simple PHP script that shows how to load
|
||||
the schema.</p>
|
||||
<pre class="listing"><pre><?PHP<br>/* You must tell the script where to find the ADOdb and<br> * the AXMLS libraries.<br> */
|
||||
require( "path_to_adodb/adodb.inc.php");
|
||||
require( "path_to_adodb/adodb-xmlschema.inc.php" ); # or adodb-xmlschema03.inc.php
|
||||
|
||||
/* Configuration information. Define the schema filename,<br> * RDBMS platform (see the ADODB documentation for valid<br> * platform names), and database connection information here.<br> */<br>$schemaFile = 'example.xml';<br>$platform = 'mysql';<br>$dbHost = 'localhost';<br>$dbName = 'database';<br>$dbUser = 'username';<br>$dbPassword = 'password';<br><br>/* Start by creating a normal ADODB connection.<br> */<br>$db = ADONewConnection( $platform );<br>$db->Connect( $dbHost, $dbUser, $dbPassword, $dbName );<br><br>/* Use the database connection to create a new adoSchema object.<br> */<br>$schema = new adoSchema( $db );<br><br>/* Call ParseSchema() to build SQL from the XML schema file.<br> * Then call ExecuteSchema() to apply the resulting SQL to <br> * the database.<br> */<br>$sql = $schema->ParseSchema( $schemaFile );<br>$result = $schema->ExecuteSchema();<br>?><br></pre></pre>
|
||||
<p>Let's look at each part of the example in turn. After you manually
|
||||
create the database, there are three steps required to load (or
|
||||
upgrade) your schema.</p>
|
||||
<p>First, create a normal ADOdb connection. The variables and values
|
||||
here should be those required to connect to your database.</p>
|
||||
<pre class="listing"><pre>$db = ADONewConnection( 'mysql' );<br>$db->Connect( 'host', 'user', 'password', 'database' );<br></pre></pre>
|
||||
<p>Second, create the adoSchema object that load and manipulate your
|
||||
schema. You must pass an ADOdb database connection object in order to
|
||||
create the adoSchema object.</p>
|
||||
<pre class="listing">$schema = new adoSchema( $db );<br></pre>
|
||||
<p>Third, call ParseSchema() to parse the schema and then
|
||||
ExecuteSchema() to apply it to the database. You must pass
|
||||
ParseSchema() the path and filename of your schema file.</p>
|
||||
<pre class="listing">$schema->ParseSchema( $schemaFile ); <br>$schema->ExecuteSchema();</pre>
|
||||
<p>Execute the above code and then log into your database. If you've
|
||||
done all this right, you should see your tables, indexes, and SQL.</p>
|
||||
<p>You can find the source files for this tutorial in the examples
|
||||
directory as tutorial_shema.xml and tutorial.php. See the class
|
||||
documentation for a more detailed description of the adoSchema methods,
|
||||
including methods and schema elements that are not described in this
|
||||
tutorial.</p>
|
||||
<h3>XML Schema Version 3</h3>
|
||||
<p>In March 2006, we added adodb-xmlschema03.inc.php to the release, which supports version 3 of XML Schema.
|
||||
The adodb-xmlschema.inc.php remains the same as previous releases, and supports version 2 of XML Schema.
|
||||
Version 3 provides some enhancements:
|
||||
|
||||
<ul>
|
||||
<li> Support for updating table data during an upgrade.
|
||||
<li> Support for platform-specific table options and platform negation.
|
||||
<li> Support for unsigned fields.
|
||||
<li> Fixed opt and constraint support
|
||||
<li> Many other fixes such as OPT tag, which allows you to set optional platform settings:
|
||||
</ul>
|
||||
|
||||
<p>Example usage:
|
||||
<pre><?xml version="1.0"?>
|
||||
<b><schema version="0.3"></b>
|
||||
<table name="ats_kb">
|
||||
<descr>ATS KnowledgeBase</descr>
|
||||
<opt platform="mysql">TYPE=INNODB</opt>
|
||||
<field name="recid" type="I"/>
|
||||
<field name="organization_code" type="I4"/>
|
||||
<field name="sub_code" type="C" size="20"/>
|
||||
etc...
|
||||
</pre>
|
||||
<p>To use it, change your code to include adodb-xmlschema03.inc.php.
|
||||
|
||||
<h3>Upgrading</h3>
|
||||
<p>
|
||||
If your schema version is older, than XSLT is used to transform the
|
||||
schema to the newest version. This means that if you are using an older
|
||||
XML schema format, you need to have the XSLT extension installed.
|
||||
If you do not want to require your users to have the XSLT extension
|
||||
installed, make sure you modify your XML schema to conform to the
|
||||
latest version.
|
||||
<hr />
|
||||
<address>If you have any questions or comments, please email them to
|
||||
Richard at richtl#arscognita.com.
|
||||
</address>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,542 +0,0 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
<html>
|
||||
<head>
|
||||
<style>
|
||||
pre {
|
||||
background-color: #eee;
|
||||
padding: 0.75em 1.5em;
|
||||
font-size: 12px;
|
||||
border: 1px solid #ddd;
|
||||
}
|
||||
.greybg {
|
||||
background-color: #eee;
|
||||
padding: 0.75em 1.5em;
|
||||
font-size: 12px;
|
||||
border: 1px solid #ddd;
|
||||
}
|
||||
.style1 {color: #660000}
|
||||
</style>
|
||||
<title>ADOdb with PHP and Oracle</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
</style>
|
||||
</head>
|
||||
|
||||
<body>
|
||||
<table width=100%><tr><td>
|
||||
<h2>Using ADOdb with PHP and Oracle: an advanced tutorial</h2>
|
||||
</td><td><div align="right"><img src=cute_icons_for_site/adodb.gif width="88" height="31"></div></tr></table>
|
||||
<p><font size="1">(c)2004-2005 John Lim. All rights reserved.</font></p>
|
||||
<h3>1. Introduction</h3>
|
||||
<p>Oracle is the most popular commercial database used with PHP. There are many ways of accessing Oracle databases in PHP. These include:</p>
|
||||
<ul>
|
||||
<li>The oracle extension</li>
|
||||
<li>The oci8 extension</li>
|
||||
<li>PEAR DB library</li>
|
||||
<li>ADOdb library</li>
|
||||
</ul>
|
||||
<p>The wide range of choices is confusing to someone just starting with Oracle and PHP. I will briefly summarize the differences, and show you the advantages of using <a href="http://adodb.sourceforge.net/">ADOdb</a>. </p>
|
||||
<p>First we have the C extensions which provide low-level access to Oracle functionality. These C extensions are precompiled into PHP, or linked in dynamically when the web server starts up. Just in case you need it, here's a <a href=http://www.oracle.com/technology/tech/opensource/php/apache/inst_php_apache_linux.html>guide to installing Oracle and PHP on Linux</a>.</p>
|
||||
<table width="75%" border="1" align="center">
|
||||
<tr valign="top">
|
||||
<td nowrap><b>Oracle extension</b></td>
|
||||
<td>Designed for Oracle 7 or earlier. This is obsolete.</td>
|
||||
</tr>
|
||||
<tr valign="top">
|
||||
<td nowrap><b>Oci8 extension</b></td>
|
||||
<td> Despite it's name, which implies it is only for Oracle 8i, this is the standard method for accessing databases running Oracle 8i, 9i or 10g (and later).</td>
|
||||
</tr>
|
||||
</table>
|
||||
<p>Here is an example of using the oci8 extension to query the <i>emp</i> table of the <i>scott</i> schema with bind parameters:
|
||||
<pre>
|
||||
$conn = OCILogon("scott","tiger", $tnsName);
|
||||
|
||||
$stmt = OCIParse($conn,"select * from emp where empno > :emp order by empno");
|
||||
$emp = 7900;
|
||||
OCIBindByName($stmt, ':emp', $emp);
|
||||
$ok = OCIExecute($stmt);
|
||||
while (OCIFetchInto($stmt,$arr)) {
|
||||
print_r($arr);
|
||||
echo "<hr>";
|
||||
}
|
||||
</pre>
|
||||
<p>This generates the following output:
|
||||
<div class=greybg>
|
||||
Array ( [0] => 7902 [1] => FORD [2] => ANALYST [3] => 7566 [4] => 03/DEC/81 [5] => 3000 [7] => 20 )
|
||||
<hr />
|
||||
Array ( [0] => 7934 [1] => MILLER [2] => CLERK [3] => 7782 [4] => 23/JAN/82 [5] => 1300 [7] => 10 )
|
||||
</div>
|
||||
<p>We also have many higher level PHP libraries that allow you to simplify the above code. The most popular are <a href="http://pear.php.net/">PEAR DB</a> and <a href="http://adodb.sourceforge.net/">ADOdb</a>. Here are some of the differences between these libraries:</p>
|
||||
<table width="75%" border="1" align="center">
|
||||
<tr>
|
||||
<td><b>Feature</b></td>
|
||||
<td><b>PEAR DB 1.6</b></td>
|
||||
<td><b>ADOdb 4.52</b></td>
|
||||
</tr>
|
||||
<tr valign="top">
|
||||
<td>General Style</td>
|
||||
<td>Simple, easy to use. Lacks Oracle specific functionality.</td>
|
||||
<td>Has multi-tier design. Simple high-level design for beginners, and also lower-level advanced Oracle functionality.</td>
|
||||
</tr>
|
||||
<tr valign="top">
|
||||
<td>Support for Prepare</td>
|
||||
<td>Yes, but only on one statement, as the last prepare overwrites previous prepares.</td>
|
||||
<td>Yes (multiple simultaneous prepare's allowed)</td>
|
||||
</tr>
|
||||
<tr valign="top">
|
||||
<td>Support for LOBs</td>
|
||||
<td>No</td>
|
||||
<td>Yes, using update semantics</td>
|
||||
</tr>
|
||||
<tr valign="top">
|
||||
<td>Support for REF Cursors</td>
|
||||
<td>No</td>
|
||||
<td>Yes</td>
|
||||
</tr>
|
||||
<tr valign="top">
|
||||
<td>Support for IN Parameters</td>
|
||||
<td>Yes</td>
|
||||
<td>Yes</td>
|
||||
</tr>
|
||||
<tr valign="top">
|
||||
<td>Support for OUT Parameters</td>
|
||||
<td>No</td>
|
||||
<td>Yes</td>
|
||||
</tr>
|
||||
<tr valign="top">
|
||||
<td>Schema creation using XML</td>
|
||||
<td>No</td>
|
||||
<td>Yes, including ability to define tablespaces and constraints</td>
|
||||
</tr>
|
||||
<tr valign="top">
|
||||
<td>Provides database portability features</td>
|
||||
<td>No</td>
|
||||
<td>Yes, has some ability to abstract features that differ between databases such as dates, bind parameters, and data types.</td>
|
||||
</tr>
|
||||
<tr valign="top">
|
||||
<td>Performance monitoring and tracing</td>
|
||||
<td>No</td>
|
||||
<td>Yes. SQL can be traced and linked to web page it was executed on. Explain plan support included.</td>
|
||||
</tr>
|
||||
<tr valign="top">
|
||||
<td>Recordset caching for frequently used queries</td>
|
||||
<td>No</td>
|
||||
<td>Yes. Provides great speedups for SQL involving complex <i>where, group-by </i>and <i>order-by</i> clauses.</td>
|
||||
</tr>
|
||||
<tr valign="top">
|
||||
<td>Popularity</td>
|
||||
<td>Yes, part of PEAR release</td>
|
||||
<td>Yes, many open source projects are using this software, including PostNuke, Xaraya, Mambo, Tiki Wiki.</td>
|
||||
</tr>
|
||||
<tr valign="top">
|
||||
<td>Speed</td>
|
||||
<td>Medium speed.</td>
|
||||
<td>Very high speed. Fastest database abstraction library available for PHP. <a href="http://phplens.com/lens/adodb/">Benchmarks are available</a>.</td>
|
||||
</tr>
|
||||
<tr valign="top">
|
||||
<td>High Speed Extension available</td>
|
||||
<td>No</td>
|
||||
<td>Yes. You can install the optional ADOdb extension, which reimplements the most frequently used parts of ADOdb as fast C code. Note that the source code version of ADOdb runs just fine without this extension, and only makes use of the extension if detected.</td>
|
||||
</tr>
|
||||
</table>
|
||||
<p> PEAR DB is good enough for simple web apps. But if you need more power, you can see ADOdb offers more sophisticated functionality. The rest of this article will concentrate on using ADOdb with Oracle. You can find out more about <a href="#connecting">connecting to Oracle</a> later in this guide.</p>
|
||||
<h4>ADOdb Example</h4>
|
||||
<p>In ADOdb, the above oci8 example querying the <i>emp</i> table could be written as:</p>
|
||||
<pre>
|
||||
include "/path/to/adodb.inc.php";
|
||||
$db = NewADOConnection("oci8");
|
||||
$db->Connect($tnsName, "scott", "tiger");
|
||||
|
||||
$rs = $db->Execute("select * from emp where empno>:emp order by empno",
|
||||
array('emp' => 7900));
|
||||
while ($arr = $rs->FetchRow()) {
|
||||
print_r($arr);
|
||||
echo "<hr>";
|
||||
}
|
||||
</pre>
|
||||
<p>The Execute( ) function returns a recordset object, and you can retrieve the rows returned using $recordset->FetchRow( ). </p>
|
||||
<p>If we ignore the initial connection preamble, we can see the ADOdb version is much easier and simpler:</p>
|
||||
<table width="100%" border="1">
|
||||
<tr valign="top" bgcolor="#FFFFFF">
|
||||
<td width="50%" bgcolor="#e0e0e0"><b>Oci8</b></td>
|
||||
<td bgcolor="#e0e0e0"><b>ADOdb</b></td>
|
||||
</tr>
|
||||
<tr valign="top" bgcolor="#CCCCCC">
|
||||
<td><pre><font size="1">$stmt = <b>OCIParse</b>($conn,
|
||||
"select * from emp where empno > :emp");
|
||||
$emp = 7900;
|
||||
<b>OCIBindByName</b>($stmt, ':emp', $emp);
|
||||
$ok = <b>OCIExecute</b>($stmt);
|
||||
|
||||
while (<b>OCIFetchInto</b>($stmt,$arr)) {
|
||||
print_r($arr);
|
||||
echo "<hr>";
|
||||
} </font></pre></td>
|
||||
<td><pre><font size="1">$recordset = $db-><b>Execute</b>("select * from emp where empno>:emp",
|
||||
array('emp' => 7900));
|
||||
|
||||
while ($arr = $recordset-><b>FetchRow</b>()) {
|
||||
print_r($arr);
|
||||
echo "<hr>";
|
||||
}</font></pre></td>
|
||||
</tr>
|
||||
</table>
|
||||
<p> </p>
|
||||
<h3>2. ADOdb Query Semantics</h3>
|
||||
<p>You can also query the database using the standard Microsoft ADO MoveNext( ) metaphor. The data array for the current row is stored in the <i>fields</i> property of the recordset object, $rs.
|
||||
MoveNext( ) offers the highest performance among all the techniques for iterating through a recordset:
|
||||
<pre>
|
||||
$rs = $db->Execute("select * from emp where empno>:emp", array('emp' => 7900));
|
||||
while (!$rs->EOF) {
|
||||
print_r($rs->fields);
|
||||
$rs->MoveNext();
|
||||
}
|
||||
</pre>
|
||||
<p>And if you are interested in having the data returned in a 2-dimensional array, you can use:
|
||||
<pre>
|
||||
$arr = $db->GetArray("select * from emp where empno>:emp", array('emp' => 7900));
|
||||
</pre>
|
||||
<p>Now to obtain only the first row as an array:
|
||||
<pre>
|
||||
$arr = $db->GetRow("select * from emp where empno=:emp", array('emp' => 7900));
|
||||
</pre>
|
||||
<p>Or to retrieve only the first field of the first row:
|
||||
<pre>
|
||||
$arr = $db->GetOne("select ename from emp where empno=:emp", array('emp' => 7900));
|
||||
</pre>
|
||||
<p>For easy pagination support, we provide the SelectLimit function. The following will perform a select query, limiting it to 100 rows, starting from row 201 (row 1 being the 1st row):
|
||||
<pre>
|
||||
$offset = 200; $limitrows = 100;
|
||||
$rs = $db->SelectLimit('select * from table', $limitrows, $offset);
|
||||
</pre>
|
||||
<p>The $offset parameter is optional.
|
||||
<h4>Array Fetch Mode</h4>
|
||||
<p>When data is being returned in an array, you can choose the type of array the data is returned in.
|
||||
<ol>
|
||||
<li> Numeric indexes - use <font size="2" face="Courier New, Courier, mono">$connection->SetFetchMode(ADODB_FETCH_NUM).</font></li>
|
||||
<li>Associative indexes - the keys of the array are the names of the fields (in upper-case). Use <font size="2" face="Courier New, Courier, mono">$connection->SetFetchMode(ADODB_FETCH_ASSOC)</font><font face="Courier New, Courier, mono">.</font></li>
|
||||
<li>Both numeric and associative indexes - use <font size="2" face="Courier New, Courier, mono">$connection->SetFetchMode(ADODB_FETCH_BOTH).</font></li>
|
||||
</ol>
|
||||
<p>The default is ADODB_FETCH_BOTH for Oracle.</p>
|
||||
<h4><b>Caching</b></h4>
|
||||
<p>You can define a database cache directory using $ADODB_CACHE_DIR, and cache the results of frequently used queries that rarely change. This is particularly useful for SQL with complex where clauses and group-by's and order-by's. It is also good for relieving heavily-loaded database servers.</p>
|
||||
<p>This example will cache the following select statement for 3600 seconds (1 hour):</p>
|
||||
<pre>
|
||||
$ADODB_CACHE_DIR = '/var/adodb/tmp';
|
||||
$rs = $db->CacheExecute(3600, "select names from allcountries order by 1");
|
||||
</pre>
|
||||
There are analogous CacheGetArray(
|
||||
), CacheGetRow( ), CacheGetOne( ) and CacheSelectLimit( ) functions. The first parameter is the number of seconds to cache. You can also pass a bind array as a 3rd parameter (not shown above).
|
||||
<p>There is an alternative syntax for the caching functions. The first parameter is omitted, and you set the cacheSecs
|
||||
property of the connection object:
|
||||
<pre>
|
||||
$ADODB_CACHE_DIR = '/var/adodb/tmp';
|
||||
$connection->cacheSecs = 3600;
|
||||
$rs = $connection->CacheExecute($sql, array('id' => 1));
|
||||
</pre>
|
||||
<h3> </h3>
|
||||
<h3>3. Using Prepare( ) For Frequently Used Statements</h3>
|
||||
<p>Prepare( ) is for compiling frequently used SQL statement for reuse. For example, suppose we have a large array which needs to be inserted into an Oracle database. The following will result in a massive speedup in query execution (at least 20-40%), as the SQL statement only needs to be compiled once:</p>
|
||||
<pre>
|
||||
$stmt = $db->Prepare('insert into table (field1, field2) values (:f1, :f2)');
|
||||
foreach ($arrayToInsert as $key => $value) {
|
||||
$db->Execute($stmt, array('f1' => $key, 'f2' => $val);
|
||||
}
|
||||
</pre>
|
||||
<p> </p>
|
||||
<h3>4. Working With LOBs</h3>
|
||||
<p>Oracle treats data which is more than 4000 bytes in length specially. These are called Large Objects, or LOBs for short. Binary LOBs are BLOBs, and character LOBs are CLOBs. In most Oracle libraries, you need to do a lot of work to process LOBs, probably because Oracle designed it to work in systems with little memory. ADOdb tries to make things easy by assuming the LOB can fit into main memory. </p>
|
||||
<p>ADOdb will transparently handle LOBs in <i>select</i> statements. The LOBs are automatically converted to PHP variables without any special coding.</p>
|
||||
<p>For updating records with LOBs, the functions UpdateBlob( ) and UpdateClob( ) are provided. Here's a BLOB example. The parameters should be self-explanatory:
|
||||
<pre>
|
||||
$ok = $db->Execute("insert into aTable (id, name, ablob)
|
||||
values (aSequence.nextVal, 'Name', null)");
|
||||
if (!$ok) return LogError($db->ErrorMsg());
|
||||
<font color="#006600"># params: $tableName, $blobFieldName, $blobValue, $whereClause</font>
|
||||
$db->UpdateBlob('aTable', 'ablob', $blobValue, 'id=aSequence.currVal');
|
||||
</pre>
|
||||
<p>and the analogous CLOB example:
|
||||
<pre>
|
||||
$ok = $db->Execute("insert into aTable (id, name, aclob)
|
||||
values (aSequence.nextVal, 'Name', null)");
|
||||
if (!$ok) return LogError($db->ErrorMsg());
|
||||
$db->UpdateClob('aTable', 'aclob', $clobValue, 'id=aSequence.currVal');
|
||||
</pre>
|
||||
<p>Note that LogError( ) is a user-defined function, and not part of ADOdb.
|
||||
<p>Inserting LOBs is more complicated. Since ADOdb 4.55, we allow you to do this
|
||||
(assuming that the <em>photo</em> field is a BLOB, and we want to store $blob_data into
|
||||
this field, and the primary key is the <em>id</em> field):
|
||||
<pre>
|
||||
$sql = <span class="style1">"INSERT INTO photos ( ID, photo) ".
|
||||
"VALUES ( :id, empty_blob() )".
|
||||
" RETURNING photo INTO :xx"</span>;
|
||||
|
||||
$stmt = $db->PrepareSP($sql);
|
||||
$db->InParameter($stmt, $<strong>id</strong>, <span class="style1">'id'</span>);
|
||||
$blob = $db->InParameter($stmt, $<strong>blob_data</strong>, <span class="style1">'xx'</span>,-1, OCI_B_BLOB);
|
||||
$db->StartTrans();
|
||||
$ok = $db->Execute($stmt);
|
||||
$db->CompleteTrans();
|
||||
</pre>
|
||||
<p>
|
||||
<h3>5. REF CURSORs</h3>
|
||||
<p>Oracle recordsets can be passed around as variables called REF Cursors. For example, in PL/SQL, we could define a function <i>open_tab</i> that returns a REF CURSOR in the first parameter:</p>
|
||||
<pre>
|
||||
TYPE TabType IS REF CURSOR RETURN TAB%ROWTYPE;
|
||||
|
||||
PROCEDURE open_tab (tabcursor IN OUT TabType,tablenames IN VARCHAR) IS
|
||||
BEGIN
|
||||
OPEN tabcursor FOR SELECT * FROM TAB WHERE tname LIKE tablenames;
|
||||
END open_tab;
|
||||
</pre>
|
||||
<p>In ADOdb, we could access this REF Cursor using the ExecuteCursor() function. The following will find
|
||||
all table names that begin with 'A' in the current schema:
|
||||
<pre>
|
||||
$rs = $db->ExecuteCursor("BEGIN open_tab(:refc,'A%'); END;",'refc');
|
||||
while ($arr = $rs->FetchRow()) print_r($arr);
|
||||
</pre>
|
||||
<p>The first parameter is the PL/SQL statement, and the second parameter is the name of the REF Cursor.
|
||||
</p>
|
||||
<p> </p>
|
||||
<h3>6. In and Out Parameters</h3>
|
||||
<p>The following PL/SQL
|
||||
stored procedure requires an input variable, and returns a result into an output variable:
|
||||
<pre>
|
||||
PROCEDURE data_out(input IN VARCHAR, output OUT VARCHAR) IS
|
||||
BEGIN
|
||||
output := 'I love '||input;
|
||||
END;
|
||||
</pre>
|
||||
<p>The following ADOdb code allows you to call the stored procedure:</p>
|
||||
<pre>
|
||||
$stmt = $db->PrepareSP("BEGIN adodb.data_out(:a1, :a2); END;");
|
||||
$input = 'Sophia Loren';
|
||||
$db->InParameter($stmt,$input,'a1');
|
||||
$db->OutParameter($stmt,$output,'a2');
|
||||
$ok = $db->Execute($stmt);
|
||||
if ($ok) echo ($output == 'I love Sophia Loren') ? 'OK' : 'Failed';
|
||||
</pre>
|
||||
<p>PrepareSP( ) is a special function that knows about bind parameters.
|
||||
The main limitation currently is that IN OUT parameters do not work.
|
||||
<h4>Bind Parameters and REF CURSORs</h4>
|
||||
<p>We could also rewrite the REF CURSOR example to use InParameter (requires ADOdb 4.53 or later):
|
||||
<pre>
|
||||
$stmt = $db->PrepareSP("BEGIN adodb.open_tab(:refc,:tabname); END;");
|
||||
$input = 'A%';
|
||||
$db->InParameter($stmt,$input,'tabname');
|
||||
$rs = $db->ExecuteCursor($stmt,'refc');
|
||||
while ($arr = $rs->FetchRow()) print_r($arr);
|
||||
</pre>
|
||||
<h4>Bind Parameters and LOBs</h4>
|
||||
<p>You can also operate on LOBs. In this example, we have IN and OUT parameters using CLOBs.
|
||||
<pre>
|
||||
$text = 'test test test';
|
||||
$sql = "declare rs clob; begin :rs := lobinout(:sa0); end;";
|
||||
$stmt = $conn -> PrepareSP($sql);
|
||||
$conn -> InParameter($stmt,$text,'sa0', -1, OCI_B_CLOB); # -1 means variable length
|
||||
$rs = '';
|
||||
$conn -> OutParameter($stmt,$rs,'rs', -1, OCI_B_CLOB);
|
||||
$conn -> Execute($stmt);
|
||||
echo "return = ".$rs."<br>";
|
||||
</pre>
|
||||
<p>Similarly, you can use the constant OCI_B_BLOB to indicate that you are using BLOBs.
|
||||
<h4>Reusing Bind Parameters with CURSOR_SHARING=FORCE</h4>
|
||||
<p>Many web programmers do not care to use bind parameters, and prefer to enter the SQL directly. So instead of:</p>
|
||||
<pre>
|
||||
$arr = $db->GetArray("select * from emp where empno>:emp", array('emp' => 7900));
|
||||
</pre>
|
||||
<p>They prefer entering the values inside the SQL:
|
||||
<pre>
|
||||
$arr = $db->GetArray("select * from emp where empno>7900");
|
||||
</pre>
|
||||
<p>This reduces Oracle performance because Oracle will reuse compiled SQL which is identical to previously compiled SQL. The above example with the values inside the SQL
|
||||
is unlikely to be reused. As an optimization, from Oracle 8.1 onwards, you can set the following session parameter after you login:
|
||||
<pre>
|
||||
ALTER SESSION SET CURSOR_SHARING=FORCE
|
||||
</pre>
|
||||
<p>This will force Oracle to convert all such variables (eg. the 7900 value) into constant bind parameters, improving SQL reuse.</p>
|
||||
<p>More <a href="http://phplens.com/adodb/code.initialization.html#speed">speedup tips</a>.</p>
|
||||
<p> </p>
|
||||
<h3>7. Dates and Datetime in ADOdb</h3>
|
||||
<p>There are two things you need to know about dates in ADOdb. </p>
|
||||
<p>First, to ensure cross-database compability, ADOdb assumes that dates are returned in ISO format (YYYY-MM-DD H24:MI:SS).</p>
|
||||
<p>Secondly, since Oracle treats dates and datetime as the same data type, we decided not to display the time in the default date format. So on login, ADOdb will set the NLS_DATE_FORMAT to 'YYYY-MM-DD'. If you prefer to show the date and time by default, do this:</p>
|
||||
<pre>
|
||||
$db = NewADOConnection('oci8');
|
||||
$db->NLS_DATE_FORMAT = 'RRRR-MM-DD HH24:MI:SS';
|
||||
$db->Connect($tns, $user, $pwd);
|
||||
</pre>
|
||||
<p>Or execute:</p>
|
||||
<pre>$sql = quot;ALTER SESSION SET NLS_DATE_FORMAT = 'RRRR-MM-DD HH24:MI:SS'";
|
||||
$db->Execute($sql);
|
||||
</pre>
|
||||
<p>If you are not concerned about date portability and do not use ADOdb's portability layer, you can use your preferred date format instead.
|
||||
<p>
|
||||
<h3>8. Database Portability Layer</h3>
|
||||
<p>ADOdb provides the following functions for portably generating SQL functions
|
||||
as strings to be merged into your SQL statements:</p>
|
||||
<table width="75%" border="1" align=center>
|
||||
<tr>
|
||||
<td width=30%><b>Function</b></td>
|
||||
<td><b>Description</b></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>DBDate($date)</td>
|
||||
<td>Pass in a UNIX timestamp or ISO date and it will convert it to a date
|
||||
string formatted for INSERT/UPDATE</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>DBTimeStamp($date)</td>
|
||||
<td>Pass in a UNIX timestamp or ISO date and it will convert it to a timestamp
|
||||
string formatted for INSERT/UPDATE</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SQLDate($date, $fmt)</td>
|
||||
<td>Portably generate a date formatted using $fmt mask, for use in SELECT
|
||||
statements.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>OffsetDate($date, $ndays)</td>
|
||||
<td>Portably generate a $date offset by $ndays.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Concat($s1, $s2, ...)</td>
|
||||
<td>Portably concatenate strings. Alternatively, for mssql use mssqlpo driver,
|
||||
which allows || operator.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>IfNull($fld, $replaceNull)</td>
|
||||
<td>Returns a string that is the equivalent of MySQL IFNULL or Oracle NVL.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Param($name)</td>
|
||||
<td>Generates bind placeholders, using ? or named conventions as appropriate.</td>
|
||||
</tr>
|
||||
<tr><td>$db->sysDate</td><td>Property that holds the SQL function that returns today's date</td>
|
||||
</tr>
|
||||
<tr><td>$db->sysTimeStamp</td><td>Property that holds the SQL function that returns the current
|
||||
timestamp (date+time).
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>$db->concat_operator</td><td>Property that holds the concatenation operator
|
||||
</td>
|
||||
</tr>
|
||||
<tr><td>$db->length</td><td>Property that holds the name of the SQL strlen function.
|
||||
</td></tr>
|
||||
|
||||
<tr><td>$db->upperCase</td><td>Property that holds the name of the SQL strtoupper function.
|
||||
</td></tr>
|
||||
<tr><td>$db->random</td><td>Property that holds the SQL to generate a random number between 0.00 and 1.00.
|
||||
</td>
|
||||
</tr>
|
||||
<tr><td>$db->substr</td><td>Property that holds the name of the SQL substring function.
|
||||
</td></tr>
|
||||
</table>
|
||||
<p>ADOdb also provides multiple oracle oci8 drivers for different scenarios:</p>
|
||||
<table width="75%" border="1" align="center">
|
||||
<tr>
|
||||
<td nowrap><b>Driver Name</b></td>
|
||||
<td><b>Description</b></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>oci805 </td>
|
||||
<td>Specifically for Oracle 8.0.5. This driver has a slower SelectLimit( ).</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>oci8</td>
|
||||
<td>The default high performance driver. The keys of associative arrays returned in a recordset are upper-case.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>oci8po</td>
|
||||
<td> The portable Oracle driver. Slightly slower than oci8. This driver uses ? instead of :<i>bindvar</i> for binding variables, which is the standard for other databases. Also the keys of associative arrays are in lower-case like other databases.</td>
|
||||
</tr>
|
||||
</table>
|
||||
<p>Here's an example of calling the <i>oci8po</i> driver. Note that the bind variables use question-mark:</p>
|
||||
<pre>$db = NewADOConnection('oci8po');
|
||||
$db->Connect($tns, $user, $pwd);
|
||||
$db->Execute("insert into atable (f1, f2) values (?,?)", array(12, 'abc'));</pre>
|
||||
<p> <a name=connecting></a>
|
||||
<h3>9. Connecting to Oracle</h3>
|
||||
<p>Before you can use ADOdb, you need to have the Oracle client installed and setup the oci8 extension. This extension comes pre-compiled for Windows (but you still need to enable it in the php.ini file). For information on compiling the oci8 extension for PHP and Apache on Unix, there is an excellent guide at <a href="http://www.oracle.com/technology/tech/opensource/php/apache/inst_php_apache_linux.html">oracle.com</a>. </p>
|
||||
<h4>Should You Use Persistent Connections</h4>
|
||||
<p>One question that is frequently asked is should you use persistent connections to Oracle. Persistent connections allow PHP to recycle existing connections, reusing them after the previous web pages have completed. Non-persistent connections close automatically after the web page has completed. Persistent connections are faster because the cost of reconnecting is expensive, but there is additional resource overhead. As an alternative, Oracle allows you to pool and reuse server processes; this is called <a href="http://www.cise.ufl.edu/help/database/oracle-docs/server.920/a96521/manproc.htm#13132">Shared Server</a> (also known as MTS).</p>
|
||||
<p>The author's benchmarks suggest that using non-persistent connections and the Shared Server configuration offer the best performance. If Shared Server is not an option, only then consider using persistent connections.</p>
|
||||
<h4>Connection Examples</h4>
|
||||
<p>Just in case you are having problems connecting to Oracle, here are some examples:</p>
|
||||
<p>a. PHP and Oracle reside on the same machine, use default SID, with non-persistent connections:</p>
|
||||
<pre> $conn = NewADOConnection('oci8');
|
||||
$conn->Connect(false, 'scott', 'tiger');</pre>
|
||||
<p>b. TNS Name defined in tnsnames.ora (or ONAMES or HOSTNAMES), eg. 'myTNS', using persistent connections:</p>
|
||||
<pre> $conn = NewADOConnection('oci8');
|
||||
$conn->PConnect(false, 'scott', 'tiger', 'myTNS');</pre>
|
||||
<p>or</p>
|
||||
<pre> $conn->PConnect('myTNS', 'scott', 'tiger');</pre>
|
||||
<p>c. Host Address and SID</p>
|
||||
<pre>
|
||||
$conn->connectSID = true;
|
||||
$conn->Connect('192.168.0.1', 'scott', 'tiger', 'SID');</pre>
|
||||
<p>d. Host Address and Service Name</p>
|
||||
<pre> $conn->Connect('192.168.0.1', 'scott', 'tiger', 'servicename');</pre>
|
||||
<p>e. Oracle connection string:
|
||||
<pre> $cstr = "(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=$host)(PORT=$port))
|
||||
(CONNECT_DATA=(SID=$sid)))";
|
||||
$conn->Connect($cstr, 'scott', 'tiger');
|
||||
</pre>
|
||||
<p>f. ADOdb data source names (dsn):
|
||||
<pre>
|
||||
$dsn = 'oci8://user:pwd@tnsname/?persist'; # persist is optional
|
||||
$conn = ADONewConnection($dsn); # no need for Connect/PConnect
|
||||
|
||||
$dsn = 'oci8://user:pwd@host/sid';
|
||||
$conn = ADONewConnection($dsn);
|
||||
|
||||
$dsn = 'oci8://user:pwd@/'; # oracle on local machine
|
||||
$conn = ADONewConnection($dsn);</pre>
|
||||
<p>With ADOdb data source names,
|
||||
you don't have to call Connect( ) or PConnect( ).
|
||||
</p>
|
||||
<p> </p>
|
||||
<h3>10. Error Checking</h3>
|
||||
<p>The examples in this article are easy to read but a bit simplistic because we ignore error-handling. Execute( ) and Connect( ) will return false on error. So a more realistic way to call Connect( ) and Execute( ) is:
|
||||
<pre>function InvokeErrorHandler()
|
||||
{<br>global $db; ## assume global
|
||||
MyLogFunction($db->ErrorNo(), $db->ErrorMsg());
|
||||
}
|
||||
if (!$db->Connect($tns, $usr, $pwd)) InvokeErrorHandler();
|
||||
|
||||
$rs = $db->Execute("select * from emp where empno>:emp order by empno",
|
||||
array('emp' => 7900));
|
||||
if (!$rs) return InvokeErrorHandler();
|
||||
while ($arr = $rs->FetchRow()) {
|
||||
print_r($arr);
|
||||
echo "<hr>";
|
||||
}
|
||||
</pre>
|
||||
<p>You can retrieve the error message and error number of the last SQL statement executed from ErrorMsg( ) and ErrorNo( ). You can also <a href=http://phplens.com/adodb/using.custom.error.handlers.and.pear_error.html>define a custom error handler function</a>.
|
||||
ADOdb also supports throwing exceptions in PHP5.
|
||||
<p> </p>
|
||||
<h3>Handling Large Recordsets (added 27 May 2005)</h3>
|
||||
The oci8 driver does not support counting the number of records returned in a SELECT statement, so the function RecordCount()
|
||||
is emulated when the global variable $ADODB_COUNTRECS is set to true, which is the default.
|
||||
We emulate this by buffering all the records. This can take up large amounts of memory for big recordsets.
|
||||
Set $ADODB_COUNTRECS to false for the best performance.
|
||||
<p>
|
||||
This variable is checked every time a query is executed, so you can selectively choose which recordsets to count.
|
||||
<p> </p>
|
||||
<h3>11. Other ADOdb Features</h3>
|
||||
<p><a href="http://phplens.com/lens/adodb/docs-datadict.htm">Schema generation</a>. This allows you to define a schema using XML and import it into different RDBMS systems portably.</p>
|
||||
<p><a href="http://phplens.com/lens/adodb/docs-perf.htm">Performance monitoring and tracing</a>. Highlights of performance monitoring include identification of poor and suspicious SQL, with explain plan support, and identifying which web pages the SQL ran on.</p>
|
||||
<p> </p>
|
||||
<h3>12. Download</h3>
|
||||
<p>You can <a href="http://adodb.sourceforge.net/#download">download ADOdb from sourceforge</a>. ADOdb uses a BSD style license. That means that it is free for commercial use, and redistribution without source code is allowed.</p>
|
||||
<p> </p>
|
||||
<h3>13. Resources</h3>
|
||||
<ul>
|
||||
<li>Oracle's <a href="http://www.oracle.com/technology/pub/articles/php_experts/index.html">Hitchhiker Guide to PHP</a></li>
|
||||
<li>OTN article on <a href=http://www.oracle.com/technology/pub/articles/deployphp/lim_deployphp.html>Optimizing PHP and Oracle</a> by this author.
|
||||
<li>Oracle has an excellent <a href="http://www.oracle.com/technology/tech/opensource/php/php_troubleshooting_faq.html">FAQ on PHP</a></li>
|
||||
<li>PHP <a href="http://php.net/oci8">oci8</a> manual pages</li>
|
||||
<li><a href=http://phplens.com/lens/lensforum/topics.php?id=4>ADOdb forums</a>.
|
||||
</ul>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,965 +0,0 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
<html>
|
||||
<head>
|
||||
<title>ADOdb Performance Monitoring Library</title>
|
||||
<style type="text/css">
|
||||
body, td {
|
||||
/*font-family: Arial, Helvetica, sans-serif;*/
|
||||
font-size: 11pt;
|
||||
}
|
||||
pre {
|
||||
font-size: 9pt;
|
||||
background-color: #EEEEEE; padding: .5em; margin: 0px;
|
||||
}
|
||||
.toplink {
|
||||
font-size: 8pt;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h3>The ADOdb Performance Monitoring Library</h3>
|
||||
<p>V5.06 16 Oct 2008 (c) 2000-2009 John Lim (jlim#natsoft.com)</p>
|
||||
<p><font size="1">This software is dual licensed using BSD-Style and
|
||||
LGPL. This means you can use it in compiled proprietary and commercial
|
||||
products.</font></p>
|
||||
<p>Useful ADOdb links: <a href="http://adodb.sourceforge.net/#download">Download</a>
|
||||
<a href="http://adodb.sourceforge.net/#docs">Other Docs</a>
|
||||
</p>
|
||||
<h3>Introduction</h3>
|
||||
<p>This module, part of the ADOdb package, provides both CLI and HTML
|
||||
interfaces for viewing key performance indicators of your database.
|
||||
This is very useful because web apps such as the popular phpMyAdmin
|
||||
currently do not provide effective database health monitoring tools.
|
||||
The module provides the following: </p>
|
||||
<ul>
|
||||
<li>A quick health check of your database server using <code>$perf->HealthCheck()</code>
|
||||
or <code>$perf->HealthCheckCLI()</code>. </li>
|
||||
<li>User interface for performance monitoring, <code>$perf->UI()</code>.
|
||||
This UI displays:
|
||||
<ul>
|
||||
<li>the health check, </li>
|
||||
<li>all SQL logged and their query plans, </li>
|
||||
<li>a list of all tables in the current database</li>
|
||||
<li>an interface to continiously poll the server for key
|
||||
performance indicators such as CPU, Hit Ratio, Disk I/O</li>
|
||||
<li>a form where you can enter and run SQL interactively.</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>Gives you an API to build database monitoring tools for a server
|
||||
farm, for example calling <code>$perf->DBParameter('data cache hit
|
||||
ratio')</code> returns this very important statistic in a database
|
||||
independant manner. </li>
|
||||
</ul>
|
||||
<p>ADOdb also has the ability to log all SQL executed, using <a
|
||||
href="docs-adodb.htm#logsql">LogSQL</a>. All SQL logged can be
|
||||
analyzed through the performance monitor <a href="#ui">UI</a>. In the <i>View
|
||||
SQL</i> mode, we categorize the SQL into 3 types:
|
||||
</p>
|
||||
<ul>
|
||||
<li><b>Suspicious SQL</b>: queries with high average execution times,
|
||||
and are potential candidates for rewriting</li>
|
||||
<li><b>Expensive SQL</b>: queries with high total execution times
|
||||
(#executions * avg execution time). Optimizing these queries will
|
||||
reduce your database server load.</li>
|
||||
<li><b>Invalid SQL</b>: queries that generate errors.</li>
|
||||
</ul>
|
||||
<p>Each query is hyperlinked to a description of the query plan, and
|
||||
every PHP script that executed that query is also shown.</p>
|
||||
<p>Please note that the information presented is a very basic database
|
||||
health check, and does not provide a complete overview of database
|
||||
performance. Although some attempt has been made to make it work across
|
||||
multiple databases in the same way, it is impossible to do so. For the
|
||||
health check, we do try to display the following key database
|
||||
parameters for all drivers:</p>
|
||||
<ul>
|
||||
<li><b>data cache size</b> - The amount of memory allocated to the
|
||||
cache.</li>
|
||||
<li><b>data cache hit ratio</b> - A measure of how effective the
|
||||
cache is, as a percentage. The higher, the better.</li>
|
||||
<li><b>current connections</b> - The number of sessions currently
|
||||
connected to the database. </li>
|
||||
</ul>
|
||||
<p>You will need to connect to the database as an administrator to view
|
||||
most of the parameters. </p>
|
||||
<p>Code improvements as very welcome, particularly adding new database
|
||||
parameters and automated tuning hints.</p>
|
||||
<a name="usage"></a>
|
||||
<h3>Usage</h3>
|
||||
<p>Currently, the following drivers: <em>mysql</em>, <em>postgres</em>,
|
||||
<em>oci8</em>, <em>mssql</em>, <i>informix</i> and <em>db2</em> are
|
||||
supported. To create a new performance monitor, call NewPerfMonitor( )
|
||||
as demonstrated below: </p>
|
||||
<pre><?php<br>include_once('adodb.inc.php');<br>session_start(); <font
|
||||
color="#006600"># session variables required for monitoring</font><br>$conn = ADONewConnection($driver);<br>$conn->Connect($server,$user,$pwd,$db);<br>$perf =& NewPerfMonitor($conn);<br>$perf->UI($pollsecs=5);<br>?><br></pre>
|
||||
<p>It is also possible to retrieve a single database parameter:</p>
|
||||
<pre>$size = $perf->DBParameter('data cache size');<br></pre>
|
||||
<p>
|
||||
Thx to Fernando Ortiz for the informix module. </p>
|
||||
<h3>Methods</h3>
|
||||
<a name="ui"></a>
|
||||
<p><font face="Courier New, Courier, mono">function <b>UI($pollsecs=5)</b></font></p>
|
||||
<p>Creates a web-based user interface for performance monitoring. When
|
||||
you click on Poll, server statistics will be displayed every $pollsecs
|
||||
seconds. See <a href="#usage">Usage</a> above. </p>
|
||||
<p>Since 4.11, we allow users to enter and run SQL interactively via
|
||||
the "Run SQL" link. To disable this for security reasons, set this
|
||||
constant before calling $perf->UI(). </p>
|
||||
<p> </p>
|
||||
<pre>define('ADODB_PERF_NO_RUN_SQL',1);</pre>
|
||||
<p>Sample output follows below:</p>
|
||||
<table bgcolor="lightyellow" border="1" width="100%">
|
||||
<tbody>
|
||||
<tr>
|
||||
<td> <b><a href="http://php.weblogs.com/adodb?perf=1">ADOdb</a>
|
||||
Performance Monitor</b> for localhost, db=test<br>
|
||||
<font size="-1">PostgreSQL 7.3.2 on i686-pc-cygwin, compiled by
|
||||
GCC gcc (GCC) 3.2 20020927 (prerelease)</font></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td> <a href="#">Performance Stats</a> <a href="#">View
|
||||
SQL</a> <a href="#">View Tables</a> <a href="#">Poll
|
||||
Stats</a></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<table bgcolor="white" border="1">
|
||||
<tbody>
|
||||
<tr>
|
||||
<td colspan="3">
|
||||
<h3>postgres7</h3>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>Parameter</b></td>
|
||||
<td><b>Value</b></td>
|
||||
<td><b>Description</b></td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Ratios</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>statistics collector</td>
|
||||
<td>TRUE</td>
|
||||
<td>Value must be TRUE to enable hit ratio statistics (<i>stats_start_collector</i>,<i>stats_row_level</i>
|
||||
and <i>stats_block_level</i> must be set to true in postgresql.conf)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data cache hit ratio</td>
|
||||
<td>99.7967555299239</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>IO</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data reads</td>
|
||||
<td>125</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data writes</td>
|
||||
<td>21.78125000000000000</td>
|
||||
<td>Count of inserts/updates/deletes * coef</td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Data Cache</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data cache buffers</td>
|
||||
<td>640</td>
|
||||
<td>Number of cache buffers. <a
|
||||
href="http://www.varlena.com/GeneralBits/Tidbits/perf.html#basic">Tuning</a></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>cache blocksize</td>
|
||||
<td>8192</td>
|
||||
<td>(estimate)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data cache size</td>
|
||||
<td>5M</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>operating system cache size</td>
|
||||
<td>80M</td>
|
||||
<td>(effective cache size)</td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Memory Usage</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>sort buffer size</td>
|
||||
<td>1M</td>
|
||||
<td>Size of sort buffer (per query)</td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Connections</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>current connections</td>
|
||||
<td>0</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>max connections</td>
|
||||
<td>32</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Parameters</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>rollback buffers</td>
|
||||
<td>8</td>
|
||||
<td>WAL buffers</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>random page cost</td>
|
||||
<td>4</td>
|
||||
<td>Cost of doing a seek (default=4). See <a
|
||||
href="http://www.varlena.com/GeneralBits/Tidbits/perf.html#less">random_page_cost</a></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p><font face="Courier New, Courier, mono">function <b>HealthCheck</b>()</font></p>
|
||||
<p>Returns database health check parameters as a HTML table. You will
|
||||
need to echo or print the output of this function,</p>
|
||||
<p><font face="Courier New, Courier, mono">function <b>HealthCheckCLI</b>()</font></p>
|
||||
<p>Returns database health check parameters formatted for a command
|
||||
line interface. You will need to echo or print the output of this
|
||||
function. Sample output for mysql:</p>
|
||||
<pre>-- Ratios -- <br> MyISAM cache hit ratio =gt; 56.5635738832 <br> InnoDB cache hit ratio =gt; 0 <br> sql cache hit ratio =gt; 0 <br> -- IO -- <br> data reads =gt; 2622 <br> data writes =gt; 2415.5 <br> -- Data Cache -- <br> MyISAM data cache size =gt; 512K <br> BDB data cache size =gt; 8388600<br> InnoDB data cache size =gt; 8M<br> -- Memory Pools -- <br> read buffer size =gt; 131072 <br> sort buffer size =gt; 65528 <br> table cache =gt; 4 <br> -- Connections -- <br> current connections =gt; 3<br> max connections =gt; 100</pre>
|
||||
<p><font face="Courier New, Courier, mono">function <b>Poll</b>($pollSecs=5)
|
||||
</font> </p>
|
||||
<p> Run in infinite loop, displaying the following information every
|
||||
$pollSecs. This will not work properly if output buffering is enabled.
|
||||
In the example below, $pollSecs=3:
|
||||
</p>
|
||||
<pre>Accumulating statistics...<br> Time WS-CPU% Hit% Sess Reads/s Writes/s<br>11:08:30 0.7 56.56 1 0.0000 0.0000<br>11:08:33 1.8 56.56 2 0.0000 0.0000<br>11:08:36 11.1 56.55 3 2.5000 0.0000<br>11:08:39 9.8 56.55 2 3.1121 0.0000<br>11:08:42 2.8 56.55 1 0.0000 0.0000<br>11:08:45 7.4 56.55 2 0.0000 1.5000<br></pre>
|
||||
<p><b>WS-CPU%</b> is the Web Server CPU load of the server that PHP is
|
||||
running from (eg. the database client), and not the database. The <b>Hit%</b>
|
||||
is the data cache hit ratio. <b>Sess</b> is the current number of
|
||||
sessions connected to the database. If you are using persistent
|
||||
connections, this should not change much. The <b>Reads/s</b> and <b>Writes/s</b>
|
||||
are synthetic values to give the viewer a rough guide to I/O, and are
|
||||
not to be taken literally. </p>
|
||||
<p><font face="Courier New, Courier, mono">function <b>SuspiciousSQL</b>($numsql=10)</font></p>
|
||||
<p>Returns SQL which have high average execution times as a HTML table.
|
||||
Each sql statement
|
||||
is hyperlinked to a new window which details the execution plan and the
|
||||
scripts that execute this SQL.
|
||||
</p>
|
||||
<p> The number of statements returned is determined by $numsql. Data is
|
||||
taken from the adodb_logsql table, where the sql statements are logged
|
||||
when
|
||||
$connection->LogSQL(true) is enabled. The adodb_logsql table is
|
||||
populated using <a href="docs-adodb.htm#logsql">$conn->LogSQL</a>.
|
||||
</p>
|
||||
<p>For Oracle, Ixora Suspicious SQL returns a list of SQL statements
|
||||
that are most cache intensive as a HTML table. These are data intensive
|
||||
SQL statements that could benefit most from tuning. </p>
|
||||
<p><font face="Courier New, Courier, mono">function <b>ExpensiveSQL</b>($numsql=10)</font></p>
|
||||
<p>Returns SQL whose total execution time (avg time * #executions) is
|
||||
high as a HTML table. Each sql statement
|
||||
is hyperlinked to a new window which details the execution plan and the
|
||||
scripts that execute this SQL.
|
||||
</p>
|
||||
<p> The number of statements returned is determined by $numsql. Data is
|
||||
taken from the adodb_logsql table, where the sql statements are logged
|
||||
when
|
||||
$connection->LogSQL(true) is enabled. The adodb_logsql table is
|
||||
populated using <a href="docs-adodb.htm#logsql">$conn->LogSQL</a>.
|
||||
</p>
|
||||
<p>For Oracle, Ixora Expensive SQL returns a list of SQL statements
|
||||
that are taking the most CPU load when run.
|
||||
</p>
|
||||
<p><font face="Courier New, Courier, mono">function <b>InvalidSQL</b>($numsql=10)</font></p>
|
||||
<p>Returns a list of invalid SQL as an HTML table.
|
||||
</p>
|
||||
<p>Data is taken from the adodb_logsql table, where the sql statements
|
||||
are logged when
|
||||
$connection->LogSQL(true) is enabled.
|
||||
</p>
|
||||
<p><font face="Courier New, Courier, mono">function <b>Tables</b>($orderby=1)</font></p>
|
||||
<p>Returns information on all tables in a database, with the first two
|
||||
fields containing the table name and table size, the remaining fields
|
||||
depend on the database driver. If $orderby is set to 1, it will sort by
|
||||
name. If $orderby is set to 2, then it will sort by table size. Some
|
||||
database drivers (mssql and mysql) will ignore the $orderby clause. For
|
||||
postgresql, the information is up-to-date since the last <i>vacuum</i>.
|
||||
Not supported currently for db2.</p>
|
||||
<h3>Raw Functions</h3>
|
||||
<p>Raw functions return values without any formatting.</p>
|
||||
<p><font face="Courier New, Courier, mono">function <b>DBParameter</b>($paramname)</font></p>
|
||||
<p>Returns the value of a database parameter, such as
|
||||
$this->DBParameter("data cache size").</p>
|
||||
<p><font face="Courier New, Courier, mono">function <b>CPULoad</b>()</font></p>
|
||||
<p>Returns the CPU load of the database client (NOT THE SERVER) as a
|
||||
percentage. Only works for Linux and Windows. For Windows, WMI must be
|
||||
available.</p>
|
||||
<h3>$ADODB_PERF_MIN</h3>
|
||||
<p>New in adodb 4.97/5.03 is this global variable, which controls whether sql timings which are too small are not saved. Currently it defaults
|
||||
to 0.05 (seconds). This means that all sql's which are faster than 0.05 seconds to execute are not saved.
|
||||
<h3>Format of $settings Property</h3>
|
||||
<p> To create new database parameters, you need to understand
|
||||
$settings. The $settings data structure is an associative array. Each
|
||||
element of the array defines a database parameter. The key is the name
|
||||
of the database parameter. If no key is defined, then it is assumed to
|
||||
be a section break, and the value is the name of the section break. If
|
||||
this is too confusing, looking at the source code will help a lot!</p>
|
||||
<p> Each database parameter is itself an array consisting of the
|
||||
following elements:</p>
|
||||
<ol start="0">
|
||||
<li> Category code, used to group related db parameters. If the
|
||||
category code is 'HIDE', then
|
||||
the database parameter is not shown when HTML() is called. <br>
|
||||
</li>
|
||||
<li> either
|
||||
<ol type="a">
|
||||
<li>sql string to retrieve value, eg. "select value from
|
||||
v\$parameter where name='db_block_size'", </li>
|
||||
<li>array holding sql string and field to look for, e.g.
|
||||
array('show variables','table_cache'); optional 3rd parameter is the
|
||||
$rs->fields[$index] to use (otherwise $index=1), and optional 4th
|
||||
parameter is a constant to multiply the result with (typically 100 for
|
||||
percentage calculations),</li>
|
||||
<li>a string prefixed by =, then a PHP method of the class is
|
||||
invoked, e.g. to invoke $this->GetIndexValue(), set this array
|
||||
element to '=GetIndexValue', <br>
|
||||
</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li> Description of database parameter. If description begins with an
|
||||
=, then it is interpreted as a method call, just as in (1c) above,
|
||||
taking one parameter, the current value. E.g. '=GetIndexDescription'
|
||||
will invoke $this->GetIndexDescription($val). This is useful for
|
||||
generating tuning suggestions. For an example, see WarnCacheRatio().</li>
|
||||
</ol>
|
||||
<p>Example from MySQL, table_cache database parameter:</p>
|
||||
<pre>'table cache' =gt; array('CACHE', # category code<br> array("show variables", 'table_cache'), # array (type 1b)<br> 'Number of tables to keep open'), # description</pre>
|
||||
<h3>Example Health Check Output</h3>
|
||||
<p><a href="#db2">db2</a> <a href="#informix">informix</a> <a
|
||||
href="#mysql">mysql</a> <a href="#mssql">mssql</a> <a href="#oci8">oci8</a>
|
||||
<a href="#postgres">postgres</a></p>
|
||||
<p><a name="db2"></a></p>
|
||||
<table bgcolor="white" border="1">
|
||||
<tbody>
|
||||
<tr>
|
||||
<td colspan="3">
|
||||
<h3>db2</h3>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>Parameter</b></td>
|
||||
<td><b>Value</b></td>
|
||||
<td><b>Description</b></td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Ratios</i> </td>
|
||||
</tr>
|
||||
<tr bgcolor="#ffffff">
|
||||
<td>data cache hit ratio</td>
|
||||
<td>0 </td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Data Cache</i></td>
|
||||
</tr>
|
||||
<tr bgcolor="#ffffff">
|
||||
<td>data cache buffers</td>
|
||||
<td>250 </td>
|
||||
<td>See <a
|
||||
href="http://www7b.boulder.ibm.com/dmdd/library/techarticle/anshum/0107anshum.html#bufferpoolsize">tuning
|
||||
reference</a>.</td>
|
||||
</tr>
|
||||
<tr bgcolor="#ffffff">
|
||||
<td>cache blocksize</td>
|
||||
<td>4096 </td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr bgcolor="#ffffff">
|
||||
<td>data cache size</td>
|
||||
<td>1000K </td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Connections</i></td>
|
||||
</tr>
|
||||
<tr bgcolor="#ffffff">
|
||||
<td>current connections</td>
|
||||
<td>2 </td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p> </p>
|
||||
<p><a name="informix"></a>
|
||||
<table bgcolor="white" border="1">
|
||||
<tbody>
|
||||
<tr>
|
||||
<td colspan="3">
|
||||
<h3>informix</h3>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>Parameter</b></td>
|
||||
<td><b>Val
|
||||
ue</b></td>
|
||||
<td><b>Description</b></td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Ratios</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data cache hit
|
||||
ratio</td>
|
||||
<td>95.89</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>IO</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data
|
||||
reads</td>
|
||||
<td>1883884</td>
|
||||
<td>Page reads</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data writes</td>
|
||||
<td>1716724</td>
|
||||
<td>Page writes</td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Connections</i>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>current connections</td>
|
||||
<td>263.0</td>
|
||||
<td>Number of
|
||||
sessions</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</p>
|
||||
<p> </p>
|
||||
<p><a name="mysql" id="mysql"></a></p>
|
||||
<table bgcolor="white" border="1">
|
||||
<tbody>
|
||||
<tr>
|
||||
<td colspan="3">
|
||||
<h3>mysql</h3>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>Parameter</b></td>
|
||||
<td><b>Value</b></td>
|
||||
<td><b>Description</b></td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Ratios</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>MyISAM cache hit ratio</td>
|
||||
<td>56.5658301822</td>
|
||||
<td><font color="red"><b>Cache ratio should be at least 90%</b></font></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>InnoDB cache hit ratio</td>
|
||||
<td>0</td>
|
||||
<td><font color="red"><b>Cache ratio should be at least 90%</b></font></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>sql cache hit ratio</td>
|
||||
<td>0</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>IO</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data reads</td>
|
||||
<td>2622</td>
|
||||
<td>Number of selects (Key_reads is not accurate)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data writes</td>
|
||||
<td>2415.5</td>
|
||||
<td>Number of inserts/updates/deletes * coef (Key_writes is not
|
||||
accurate)</td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Data Cache</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>MyISAM data cache size</td>
|
||||
<td>512K</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>BDB data cache size</td>
|
||||
<td>8388600</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>InnoDB data cache size</td>
|
||||
<td>8M</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Memory Pools</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>read buffer size</td>
|
||||
<td>131072</td>
|
||||
<td>(per session)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>sort buffer size</td>
|
||||
<td>65528</td>
|
||||
<td>Size of sort buffer (per session)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>table cache</td>
|
||||
<td>4</td>
|
||||
<td>Number of tables to keep open</td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Connections</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>current connections</td>
|
||||
<td>3</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>max connections</td>
|
||||
<td>100</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p> </p>
|
||||
<p><a name="mssql" id="mssql"></a></p>
|
||||
<table bgcolor="white" border="1">
|
||||
<tbody>
|
||||
<tr>
|
||||
<td colspan="3">
|
||||
<h3>mssql</h3>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>Parameter</b></td>
|
||||
<td><b>Value</b></td>
|
||||
<td><b>Description</b></td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Ratios</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data cache hit ratio</td>
|
||||
<td>99.9999694824</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>prepared sql hit ratio</td>
|
||||
<td>99.7738579828</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>adhoc sql hit ratio</td>
|
||||
<td>98.4540169133</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>IO</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data reads</td>
|
||||
<td>2858</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data writes</td>
|
||||
<td>1438</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Data Cache</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data cache size</td>
|
||||
<td>4362</td>
|
||||
<td>in K</td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Connections</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>current connections</td>
|
||||
<td>14</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>max connections</td>
|
||||
<td>32767</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p> </p>
|
||||
<p><a name="oci8" id="oci8"></a></p>
|
||||
<table bgcolor="white" border="1">
|
||||
<tbody>
|
||||
<tr>
|
||||
<td colspan="3">
|
||||
<h3>oci8</h3>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>Parameter</b></td>
|
||||
<td><b>Value</b></td>
|
||||
<td><b>Description</b></td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Ratios</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data cache hit ratio</td>
|
||||
<td>96.98</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>sql cache hit ratio</td>
|
||||
<td>99.96</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>IO</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data reads</td>
|
||||
<td>842938</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data writes</td>
|
||||
<td>16852</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Data Cache</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data cache buffers</td>
|
||||
<td>3072</td>
|
||||
<td>Number of cache buffers</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data cache blocksize</td>
|
||||
<td>8192</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data cache size</td>
|
||||
<td>48M</td>
|
||||
<td>shared_pool_size</td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Memory Pools</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>java pool size</td>
|
||||
<td>0</td>
|
||||
<td>java_pool_size</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>sort buffer size</td>
|
||||
<td>512K</td>
|
||||
<td>sort_area_size (per query)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>user session buffer size</td>
|
||||
<td>8M</td>
|
||||
<td>large_pool_size</td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Connections</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>current connections</td>
|
||||
<td>1</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>max connections</td>
|
||||
<td>170</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data cache utilization ratio</td>
|
||||
<td>88.46</td>
|
||||
<td>Percentage of data cache actually in use</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>user cache utilization ratio</td>
|
||||
<td>91.76</td>
|
||||
<td>Percentage of user cache (large_pool) actually in use</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>rollback segments</td>
|
||||
<td>11</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Transactions</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>peak transactions</td>
|
||||
<td>24</td>
|
||||
<td>Taken from high-water-mark</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>max transactions</td>
|
||||
<td>187</td>
|
||||
<td>max transactions / rollback segments < 3.5 (or
|
||||
transactions_per_rollback_segment)</td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Parameters</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>cursor sharing</td>
|
||||
<td>EXACT</td>
|
||||
<td>Cursor reuse strategy. Recommended is FORCE (8i+) or SIMILAR
|
||||
(9i+). See <a
|
||||
href="http://www.praetoriate.com/oracle_tips_cursor_sharing.htm">cursor_sharing</a>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>index cache cost</td>
|
||||
<td>0</td>
|
||||
<td>% of indexed data blocks expected in the cache. Recommended
|
||||
is 20-80. Default is 0. See <a
|
||||
href="http://www.dba-oracle.com/oracle_tips_cbo_part1.htm">optimizer_index_caching</a>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>random page cost</td>
|
||||
<td>100</td>
|
||||
<td>Recommended is 10-50 for TP, and 50 for data warehouses.
|
||||
Default is 100. See <a
|
||||
href="http://www.dba-oracle.com/oracle_tips_cost_adj.htm">optimizer_index_cost_adj</a>.
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h3>Suspicious SQL</h3>
|
||||
<table bgcolor="white" border="1">
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><b>LOAD</b></td>
|
||||
<td><b>EXECUTES</b></td>
|
||||
<td><b>SQL_TEXT</b></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="right"> .73%</td>
|
||||
<td align="right">89</td>
|
||||
<td>select u.name, o.name, t.spare1, t.pctfree$ from sys.obj$ o,
|
||||
sys.user$ u, sys.tab$ t where (bitand(t.trigflag, 1048576) = 1048576)
|
||||
and o.obj#=t.obj# and o.owner# = u.user# select i.obj#, i.flags,
|
||||
u.name, o.name from sys.obj$ o, sys.user$ u, sys.ind$ i where
|
||||
(bitand(i.flags, 256) = 256 or bitand(i.flags, 512) = 512) and
|
||||
(not((i.type# = 9) and bitand(i.flags,8) = 8)) and o.obj#=i.obj# and
|
||||
o.owner# = u.user# </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="right"> .84%</td>
|
||||
<td align="right">3</td>
|
||||
<td>select /*+ RULE */ distinct tabs.table_name, tabs.owner ,
|
||||
partitioned, iot_type , TEMPORARY, table_type, table_type_owner from
|
||||
DBA_ALL_TABLES tabs where tabs.owner = :own </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="right"> 3.95%</td>
|
||||
<td align="right">6</td>
|
||||
<td>SELECT round(count(1)*avg(buf.block_size)/1048576) FROM
|
||||
DBA_OBJECTS obj, V$BH bh, dba_segments seg, v$buffer_pool buf WHERE
|
||||
obj.object_id = bh.objd AND obj.owner != 'SYS' and obj.owner =
|
||||
seg.owner and obj.object_name = seg.segment_name and obj.object_type =
|
||||
seg.segment_type and seg.buffer_pool = buf.name and buf.name =
|
||||
'DEFAULT' </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="right"> 4.50%</td>
|
||||
<td align="right">6</td>
|
||||
<td>SELECT round(count(1)*avg(tsp.block_size)/1048576) FROM
|
||||
DBA_OBJECTS obj, V$BH bh, dba_segments seg, dba_tablespaces tsp WHERE
|
||||
obj.object_id = bh.objd AND obj.owner != 'SYS' and obj.owner =
|
||||
seg.owner and obj.object_name = seg.segment_name and obj.object_type =
|
||||
seg.segment_type and seg.tablespace_name = tsp.tablespace_name </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="right">57.34%</td>
|
||||
<td align="right">9267</td>
|
||||
<td>select t.schema, t.name, t.flags, q.name from
|
||||
system.aq$_queue_tables t, sys.aq$_queue_table_affinities aft,
|
||||
system.aq$_queues q where aft.table_objno = t.objno and
|
||||
aft.owner_instance = :1 and q.table_objno = t.objno and q.usage = 0 and
|
||||
bitand(t.flags, 4+16+32+64+128+256) = 0 for update of t.name,
|
||||
aft.table_objno skip locked </td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h3>Expensive SQL</h3>
|
||||
<table bgcolor="white" border="1">
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><b>LOAD</b></td>
|
||||
<td><b>EXECUTES</b></td>
|
||||
<td><b>SQL_TEXT</b></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="right"> 5.24%</td>
|
||||
<td align="right">1</td>
|
||||
<td>select round(sum(bytes)/1048576) from dba_segments </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="right"> 6.89%</td>
|
||||
<td align="right">6</td>
|
||||
<td>SELECT round(count(1)*avg(buf.block_size)/1048576) FROM
|
||||
DBA_OBJECTS obj, V$BH bh, dba_segments seg, v$buffer_pool buf WHERE
|
||||
obj.object_id = bh.objd AND obj.owner != 'SYS' and obj.owner =
|
||||
seg.owner and obj.object_name = seg.segment_name and obj.object_type =
|
||||
seg.segment_type and seg.buffer_pool = buf.name and buf.name =
|
||||
'DEFAULT' </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="right"> 7.85%</td>
|
||||
<td align="right">6</td>
|
||||
<td>SELECT round(count(1)*avg(tsp.block_size)/1048576) FROM
|
||||
DBA_OBJECTS obj, V$BH bh, dba_segments seg, dba_tablespaces tsp WHERE
|
||||
obj.object_id = bh.objd AND obj.owner != 'SYS' and obj.owner =
|
||||
seg.owner and obj.object_name = seg.segment_name and obj.object_type =
|
||||
seg.segment_type and seg.tablespace_name = tsp.tablespace_name </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="right">33.69%</td>
|
||||
<td align="right">89</td>
|
||||
<td>select u.name, o.name, t.spare1, t.pctfree$ from sys.obj$ o,
|
||||
sys.user$ u, sys.tab$ t where (bitand(t.trigflag, 1048576) = 1048576)
|
||||
and o.obj#=t.obj# and o.owner# = u.user# </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="right">36.44%</td>
|
||||
<td align="right">89</td>
|
||||
<td>select i.obj#, i.flags, u.name, o.name from sys.obj$ o,
|
||||
sys.user$ u, sys.ind$ i where (bitand(i.flags, 256) = 256 or
|
||||
bitand(i.flags, 512) = 512) and (not((i.type# = 9) and
|
||||
bitand(i.flags,8) = 8)) and o.obj#=i.obj# and o.owner# = u.user# </td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p><a name="postgres" id="postgres"></a></p>
|
||||
<table bgcolor="white" border="1">
|
||||
<tbody>
|
||||
<tr>
|
||||
<td colspan="3">
|
||||
<h3>postgres7</h3>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>Parameter</b></td>
|
||||
<td><b>Value</b></td>
|
||||
<td><b>Description</b></td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Ratios</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>statistics collector</td>
|
||||
<td>FALSE</td>
|
||||
<td>Must be set to TRUE to enable hit ratio statistics (<i>stats_start_collector</i>,<i>stats_row_level</i>
|
||||
and <i>stats_block_level</i> must be set to true in postgresql.conf)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data cache hit ratio</td>
|
||||
<td>99.9666031916603</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>IO</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data reads</td>
|
||||
<td>15</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data writes</td>
|
||||
<td>0.000000000000000000</td>
|
||||
<td>Count of inserts/updates/deletes * coef</td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Data Cache</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data cache buffers</td>
|
||||
<td>1280</td>
|
||||
<td>Number of cache buffers. <a
|
||||
href="http://www.varlena.com/GeneralBits/Tidbits/perf.html#basic">Tuning</a></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>cache blocksize</td>
|
||||
<td>8192</td>
|
||||
<td>(estimate)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data cache size</td>
|
||||
<td>10M</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>operating system cache size</td>
|
||||
<td>80000K</td>
|
||||
<td>(effective cache size)</td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Memory Pools</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>sort buffer size</td>
|
||||
<td>1M</td>
|
||||
<td>Size of sort buffer (per query)</td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Connections</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>current connections</td>
|
||||
<td>13</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>max connections</td>
|
||||
<td>32</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr bgcolor="#f0f0f0">
|
||||
<td colspan="3"><i>Parameters</i> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>rollback buffers</td>
|
||||
<td>8</td>
|
||||
<td>WAL buffers</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>random page cost</td>
|
||||
<td>4</td>
|
||||
<td>Cost of doing a seek (default=4). See <a
|
||||
href="http://www.varlena.com/GeneralBits/Tidbits/perf.html#less">random_page_cost</a></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,336 +0,0 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
<html>
|
||||
<head>
|
||||
<title>ADODB Session Management Manual</title>
|
||||
<meta http-equiv="Content-Type"
|
||||
content="text/html; charset=iso-8859-1">
|
||||
<style type="text/css">
|
||||
body, td {
|
||||
/*font-family: Arial, Helvetica, sans-serif;*/
|
||||
font-size: 11pt;
|
||||
}
|
||||
pre {
|
||||
font-size: 9pt;
|
||||
background-color: #EEEEEE; padding: .5em; margin: 0px;
|
||||
}
|
||||
.toplink {
|
||||
font-size: 8pt;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body style="background-color: rgb(255, 255, 255);">
|
||||
<h1>ADODB Session 2 Management Manual</h1>
|
||||
<p>
|
||||
V5.06 16 Oct 2008 (c) 2000-2009 John Lim (jlim#natsoft.com)
|
||||
</p>
|
||||
<p> <font size="1">This software is dual licensed using BSD-Style and
|
||||
LGPL. This means you can use it in compiled proprietary and commercial
|
||||
products. </font>
|
||||
<p>Useful ADOdb links: <a href="http://adodb.sourceforge.net/#download">Download</a>
|
||||
<a href="http://adodb.sourceforge.net/#docs">Other Docs</a>
|
||||
</p>
|
||||
<h2>Introduction</h2>
|
||||
<p> This document discusses the newer session handler adodb-session2.php. If
|
||||
you have used the older adodb-session.php, then be forewarned that you will
|
||||
need to alter your session table format. Otherwise everything is <a href="#compat">backward
|
||||
compatible</a>.
|
||||
Here are the <a href="docs-session.old.htm">older
|
||||
docs</a> for
|
||||
adodb-session.php.</p>
|
||||
<h2>Why Session Variables in a Database? </h2>
|
||||
<p>We store state information specific to a user or web
|
||||
client in session variables. These session variables persist throughout a
|
||||
session, as the user moves from page to page. </p>
|
||||
<p>To use session variables, call session_start() at the beginning of
|
||||
your web page, before your HTTP headers are sent. Then for every
|
||||
variable you want to keep alive for the duration of the session, call
|
||||
session_register($variable_name). By default, the session handler will
|
||||
keep track of the session by using a cookie. You can save objects or
|
||||
arrays in session variables also.
|
||||
</p>
|
||||
<p>The default method of storing sessions is to store it in a file.
|
||||
However if you have special needs such as you:
|
||||
</p>
|
||||
<ul>
|
||||
<li>Have multiple web servers that need to share session info</li>
|
||||
<li>Need to do special processing of each session</li>
|
||||
<li>Require notification when a session expires</li>
|
||||
</ul>
|
||||
<p>The ADOdb session handler provides you with the above
|
||||
additional capabilities by storing the session information as records
|
||||
in a database table that can be shared across multiple servers. </p>
|
||||
<p>These records will be garbage collected based on the php.ini [session] timeout settings.
|
||||
You can register a notification function to notify you when the record has expired and
|
||||
is about to be freed by the garbage collector.</p>
|
||||
<p>An alternative to using a database backed session handler is to use <a href="http://www.danga.com/memcached/">memcached</a>.
|
||||
This is a distributed memory based caching system suitable for storing session
|
||||
information.
|
||||
</p>
|
||||
<h2> The Improved Session Handler</h2>
|
||||
<p>In ADOdb 4.91, we added a new session handler, in adodb-session2.php.
|
||||
It features the following improvements:
|
||||
<ul>
|
||||
<li>Fully supports server farms using a new database table format. The
|
||||
previous version used the web server time for timestamps, which can cause problems
|
||||
on a system with multiple web servers with possibly inconsistent
|
||||
times. The new version uses the database server time instead for all timestamps.
|
||||
<li>The older database table format is obsolete. The database table must be modified
|
||||
to support storage of the database server time mentioned above. Also the field
|
||||
named DATA has been changed to SESSDATA. In some databases, DATA is a reserved
|
||||
word.
|
||||
<li>The functions dataFieldName() and syncSeconds() is obsolete.
|
||||
</ul>
|
||||
|
||||
<p>Usage is
|
||||
|
||||
<pre>
|
||||
include_once("adodb/session/adodb-session2.php");
|
||||
ADOdb_Session::config($driver, $host, $user, $password, $database,$options=false);
|
||||
session_start();
|
||||
|
||||
<font
|
||||
color="#004040">#<br># Test session vars, the following should increment on refresh<br>#<br>$_SESSION['AVAR'] += 1;<br>print "<p>\$_SESSION['AVAR']={$_SESSION['AVAR']}</p>";</font>
|
||||
</pre>
|
||||
|
||||
<p>When the session is created in session_start( ), the global variable $<b>ADODB_SESS_CONN</b> holds
|
||||
the connection object.
|
||||
<p>The default name of the table is sessions2. If you want to override it:
|
||||
|
||||
<pre>
|
||||
include_once("adodb/session/adodb-session2.php");
|
||||
$options['table'] = 'mytablename';
|
||||
ADOdb_Session::config($driver, $host, $user, $password, $database,$options);
|
||||
session_start();
|
||||
</pre>
|
||||
|
||||
|
||||
<h3>ADOdb Session Handler Features</h3>
|
||||
<ul>
|
||||
<li>Ability to define a notification function that is called when a
|
||||
session expires. Typically
|
||||
used to detect session logout and release global resources. </li>
|
||||
<li>Optimization of database writes. We crc32 the session data and
|
||||
only perform an update
|
||||
to the session data if there is a data change. </li>
|
||||
<li>Support for large amounts of session data with CLOBs (see
|
||||
adodb-session-clob2.php). Useful
|
||||
for Oracle. </li>
|
||||
<li>Support for encrypted session data, see
|
||||
adodb-cryptsession2.php. Enabling encryption is simply a matter of
|
||||
including adodb-cryptsession2.php instead of adodb-session2.php. </li>
|
||||
</ul>
|
||||
<h3>Session Handler Files </h3>
|
||||
<p>There are 3 session management files that you can use:
|
||||
</p>
|
||||
<pre>adodb-session2.php : The default<br>adodb-cryptsession2.php : Use this if you want to store encrypted session data in the database<br>adodb-session-clob2.php : Use this if you are storing DATA in clobs and you are NOT using oci8 driver</pre>
|
||||
<h2><strong>Usage Examples</strong></h2>
|
||||
<p>To force non-persistent connections, call <font color="#004040"><b>Persist</b></font>() first before session_start():
|
||||
|
||||
|
||||
<pre>
|
||||
<font color="#004040">
|
||||
include_once("adodb/session/adodb-session2.php");
|
||||
$driver = 'mysql'; $host = 'localhost'; $user = 'auser'; $pwd = 'secret'; $database = 'sessiondb';
|
||||
ADOdb_Session::config($driver, $host, $user, $password, $database,$options=false);<b><br>ADOdb_session::Persist($connectMode=false);</b>
|
||||
session_start();<br> </font>
|
||||
</pre>
|
||||
<p> The parameter to the Persist( ) method sets the connection mode. You can
|
||||
pass the following:</p>
|
||||
<table width="50%" border="1">
|
||||
<tr>
|
||||
<td><b>$connectMode</b></td>
|
||||
<td><b>Connection Method</b></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>true</td>
|
||||
<td><p>PConnect( )</p></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>false</td>
|
||||
<td>Connect( )</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>'N'</td>
|
||||
<td>NConnect( )</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>'P'</td>
|
||||
<td>PConnect( )</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>'C'</td>
|
||||
<td>Connect( )</td>
|
||||
</tr>
|
||||
</table>
|
||||
<p>To use a encrypted sessions, simply replace the file adodb-session2.php:</p>
|
||||
<pre> <font
|
||||
color="#004040"><b><br>include('adodb/session/adodb-cryptsession2.php');</b><br>$driver = 'mysql'; $host = 'localhost'; $user = 'auser'; $pwd = 'secret'; $database = 'sessiondb';
|
||||
ADOdb_Session::config($driver, $host, $user, $password, $database,$options=false);<b><br>adodb_sess_open(false,false,$connectMode=false);</b>
|
||||
session_start();<br></font></pre>
|
||||
<p>And the same technique for adodb-session-clob2.php:</p>
|
||||
<pre> <font
|
||||
color="#004040"><br><b>include('adodb/session/adodb-session2-clob2.php');</b><br>$driver = 'oci8'; $host = 'localhost'; $user = 'auser'; $pwd = 'secret'; $database = 'sessiondb';
|
||||
ADOdb_Session::config($driver, $host, $user, $password, $database,$options=false);<b><br>adodb_sess_open(false,false,$connectMode=false);</b>
|
||||
session_start();</font></pre>
|
||||
<h2>Installation</h2>
|
||||
<p>1. Create this table in your database. Here is the MySQL version:
|
||||
<pre> <a
|
||||
name="sessiontab"></a> <font color="#004040">
|
||||
CREATE TABLE sessions2(
|
||||
sesskey VARCHAR( 64 ) NOT NULL DEFAULT '',
|
||||
expiry DATETIME NOT NULL ,
|
||||
expireref VARCHAR( 250 ) DEFAULT '',
|
||||
created DATETIME NOT NULL ,
|
||||
modified DATETIME NOT NULL ,
|
||||
sessdata LONGTEXT DEFAULT '',
|
||||
PRIMARY KEY ( sesskey ) ,
|
||||
INDEX sess2_expiry( expiry ),
|
||||
INDEX sess2_expireref( expireref )
|
||||
)</font></pre>
|
||||
|
||||
<p> For PostgreSQL, use:
|
||||
<pre>CREATE TABLE sessions2(
|
||||
sesskey VARCHAR( 64 ) NOT NULL DEFAULT '',
|
||||
expiry TIMESTAMP NOT NULL ,
|
||||
expireref VARCHAR( 250 ) DEFAULT '',
|
||||
created TIMESTAMP NOT NULL ,
|
||||
modified TIMESTAMP NOT NULL ,
|
||||
sessdata TEXT DEFAULT '',
|
||||
PRIMARY KEY ( sesskey )
|
||||
);
|
||||
</pre>
|
||||
<pre>create INDEX sess2_expiry on sessions2( expiry );
|
||||
create INDEX sess2_expireref on sessions2 ( expireref );</pre>
|
||||
<p>Here is the Oracle definition, which uses a CLOB for the SESSDATA field:
|
||||
<pre>
|
||||
<font
|
||||
color="#004040">CREATE TABLE SESSIONS2<br>(<br> SESSKEY VARCHAR2(48 BYTE) NOT NULL,<br> EXPIRY DATE NOT NULL,<br> EXPIREREF VARCHAR2(200 BYTE),<br> CREATED DATE NOT NULL,<br> MODIFIED DATE NOT NULL,<br> SESSDATA CLOB,<br> PRIMARY KEY(SESSKEY)<br>);
|
||||
<br>CREATE INDEX SESS2_EXPIRY ON SESSIONS2(EXPIRY);
|
||||
CREATE INDEX SESS2_EXPIREREF ON SESSIONS2(EXPIREREF);</font></pre>
|
||||
<p> We need to use a CLOB here because for text greater than 4000 bytes long,
|
||||
Oracle requires you to use the CLOB data type. If you are using the oci8 driver,
|
||||
ADOdb will automatically enable CLOB handling. So you can use either adodb-session2.php
|
||||
or adodb-session-clob2.php - in this case it doesn't matter. <br>
|
||||
<h2>Notifications</h2>
|
||||
<p>You can receive notification when your session is cleaned up by the session garbage collector or
|
||||
when you call session_destroy().
|
||||
<p>PHP's session extension will automatically run a special garbage collection function based on
|
||||
your php.ini session.cookie_lifetime and session.gc_probability settings. This will in turn call
|
||||
adodb's garbage collection function, which can be setup to do notification.
|
||||
<p>
|
||||
<pre>
|
||||
PHP Session --> ADOdb Session --> Find all recs --> Send --> Delete queued
|
||||
GC Function GC Function to be deleted notification records
|
||||
executed at called by for all recs
|
||||
random time Session Extension queued for deletion
|
||||
</pre>
|
||||
<p>When a session is created, we need to store a value in the session record (in the EXPIREREF field), typically
|
||||
the userid of the session. Later when the session has expired, just before the record is deleted,
|
||||
we reload the EXPIREREF field and call the notification function with the value of EXPIREREF, which
|
||||
is the userid of the person being logged off.
|
||||
<p>ADOdb uses a global variable $ADODB_SESSION_EXPIRE_NOTIFY that you must predefine before session
|
||||
start to store the notification configuration.
|
||||
$ADODB_SESSION_EXPIRE_NOTIFY is an array with 2 elements, the
|
||||
first being the name of the session variable you would like to store in
|
||||
the EXPIREREF field, and the 2nd is the notification function's name. </p>
|
||||
<p>For example, suppose we want to be notified when a user's session has expired,
|
||||
based on the userid. When the user logs in, we store the id in the global session variable
|
||||
$USERID. The function name is 'NotifyFn'.
|
||||
<p>
|
||||
So we define (before session_start() is called): </p>
|
||||
<pre> <font color="#004040">
|
||||
$ADODB_SESSION_EXPIRE_NOTIFY = array('USERID','NotifyFn');
|
||||
</font></pre>
|
||||
And when the NotifyFn is called (when the session expires), the
|
||||
$USERID is passed in as the first parameter, eg. NotifyFn($userid, $sesskey). The
|
||||
session key (which is the primary key of the record in the sessions
|
||||
table) is the 2nd parameter.
|
||||
<p> Here is an example of a Notification function that deletes some
|
||||
records in the database and temporary files: </p>
|
||||
<pre><font color="#004040">
|
||||
function NotifyFn($expireref, $sesskey)
|
||||
{
|
||||
global $ADODB_SESS_CONN; # the session connection object
|
||||
$user = $ADODB_SESS_CONN->qstr($expireref);
|
||||
|
||||
$ADODB_SESS_CONN->Execute("delete from shopping_cart where user=$user");
|
||||
system("rm /work/tmpfiles/$expireref/*");
|
||||
}</font>
|
||||
</pre>
|
||||
<p> NOTE 1: If you have register_globals disabled in php.ini, then you
|
||||
will have to manually set the EXPIREREF. E.g. </p>
|
||||
<pre> <font color="#004040">
|
||||
$GLOBALS['USERID'] = GetUserID();
|
||||
$ADODB_SESSION_EXPIRE_NOTIFY = array('USERID','NotifyFn');</font>
|
||||
</pre>
|
||||
<p> NOTE 2: If you want to change the EXPIREREF after the session
|
||||
record has been created, you will need to modify any session variable
|
||||
to force a database record update.
|
||||
</p>
|
||||
<h3>Neat Notification Tricks</h3>
|
||||
<p><i>ExpireRef</i> normally holds the user id of the current session.
|
||||
</p>
|
||||
<p>1. You can then write a session monitor, scanning expireref to see
|
||||
who is currently logged on.
|
||||
</p>
|
||||
<p>2. If you delete the sessions record for a specific user, eg.
|
||||
</p>
|
||||
<pre>delete from sessions where expireref = '$USER'<br></pre>
|
||||
then the user is logged out. Useful for ejecting someone from a
|
||||
site.
|
||||
<p>3. You can scan the sessions table to ensure no user
|
||||
can be logged in twice. Useful for security reasons.
|
||||
</p>
|
||||
<h2>Compression/Encryption Schemes</h2>
|
||||
Since ADOdb 4.05, thanks to Ross Smith, multiple encryption and
|
||||
compression schemes are supported. Currently, supported are:
|
||||
<p>
|
||||
<pre> MD5Crypt (crypt.inc.php)<br> MCrypt<br> Secure (Horde's emulation of MCrypt, if MCrypt module is not available.)<br> GZip<br> BZip2<br></pre>
|
||||
<p>These are stackable. E.g.
|
||||
<pre>ADODB_Session::filter(new ADODB_Compress_Bzip2());<br>ADODB_Session::filter(new ADODB_Encrypt_MD5());<br></pre>
|
||||
will compress and then encrypt the record in the database.
|
||||
<h2>Session Cookie Regeneration: adodb_session_regenerate_id()</h2>
|
||||
<p>Dynamically change the current session id with a newly generated one and update
|
||||
database. Currently only works with cookies. Useful to improve security by
|
||||
reducing the risk of session-hijacking. See this article on <a href=http://shiflett.org/articles/security-corner-feb2004>Session
|
||||
Fixation</a> for more info
|
||||
on the theory behind this feature. Usage:<pre>
|
||||
include('path/to/adodb/session/adodb-session2.php');
|
||||
|
||||
session_start();
|
||||
# Approximately every 10 page loads, reset cookie for safety.
|
||||
# This is extremely simplistic example, better
|
||||
# to regenerate only when the user logs in or changes
|
||||
# user privilege levels.
|
||||
if ((rand()%10) == 0) adodb_session_regenerate_id();
|
||||
</pre>
|
||||
<p>This function calls session_regenerate_id() internally or simulates it if the function does not exist.
|
||||
<h2>Vacuum/Optimize Database</h2>
|
||||
<p>During session garbage collection, if postgresql is detected,
|
||||
ADOdb can be set to run VACUUM. If mysql is detected, then optimize database
|
||||
could be called.You can turn this on or off using:</p>
|
||||
<pre>$turnOn = true; # or false
|
||||
ADODB_Session::optimize($turnOn);
|
||||
</pre>
|
||||
<p>The default is optimization is disabled.</p>
|
||||
<h2><a name=compat></a>Backwards Compatability </h2>
|
||||
<p>The older method of connecting to ADOdb using global variables is still supported:</p>
|
||||
<pre> $ADODB_SESSION_DRIVER='mysql';
|
||||
$ADODB_SESSION_CONNECT='localhost';
|
||||
$ADODB_SESSION_USER ='root';
|
||||
$ADODB_SESSION_PWD ='abc';
|
||||
$ADODB_SESSION_DB ='phplens';
|
||||
|
||||
include('path/to/adodb/session/adodb-<strong>session2</strong>.php'); </pre>
|
||||
<p>In the above example, the only things you need to change in your code to upgrade
|
||||
is </p>
|
||||
<ul>
|
||||
<li>your session table format to the new one.</li>
|
||||
<li>the include file from adodb-session.php to adodb-session2.php. </li>
|
||||
</ul>
|
||||
<h2>More Info</h2>
|
||||
<p>Also see the <a href="docs-adodb.htm">core ADOdb documentation</a>. And if
|
||||
you are interested in the obsolete adodb-session.php, see <a href="docs-session.old.htm">old
|
||||
session documentation</a>. </p>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,68 +0,0 @@
|
||||
<html>
|
||||
<head>
|
||||
<title>ADODB Manual</title>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
<XSTYLE
|
||||
body,td {font-family:Arial,Helvetica,sans-serif;font-size:11pt}
|
||||
pre {font-size:9pt}
|
||||
.toplink {font-size:8pt}
|
||||
/>
|
||||
</head>
|
||||
<body bgcolor="#FFFFFF">
|
||||
|
||||
<h3>ADOdb Library for PHP</h3>
|
||||
<p>ADOdb is a suite of database libraries that allow you to connect to multiple
|
||||
databases in a portable manner. Download from <a href=http://adodb.sourceforge.net/>http://adodb.sourceforge.net/</a>.
|
||||
<ul><li>The ADOdb documentation has moved to <a href=docs-adodb.htm>docs-adodb.htm</a>
|
||||
This allows you to query, update and insert records using a portable API.
|
||||
<p><li>The ADOdb data dictionary docs are at <a href=docs-datadict.htm>docs-datadict.htm</a>.
|
||||
This allows you to create database tables and indexes in a portable manner.
|
||||
<p><li>The ADOdb database performance monitoring docs are at <a href=docs-perf.htm>docs-perf.htm</a>.
|
||||
This allows you to perform health checks, tune and monitor your database.
|
||||
<p><li>The ADOdb database-backed session docs are at <a href=docs-session.htm>docs-session.htm</a>.
|
||||
</ul>
|
||||
<p>
|
||||
<h3>Installation</h3>
|
||||
Make sure you are running PHP4.0.4 or later. Unpack all the files into a directory accessible by your webserver.
|
||||
<p>
|
||||
To test, try modifying some of the tutorial examples. Make sure you customize the connection settings correctly. You can debug using:
|
||||
<pre>
|
||||
<?php
|
||||
include('adodb/adodb.inc.php');
|
||||
|
||||
$db = <b>ADONewConnection</b>($driver); # eg. 'mysql' or 'oci8'
|
||||
$db->debug = true;
|
||||
$db-><b>Connect</b>($server, $user, $password, $database);
|
||||
$rs = $db-><b>Execute</b>('select * from some_small_table');
|
||||
print "<pre>";
|
||||
print_r($rs-><b>GetRows</b>());
|
||||
print "</pre>";
|
||||
?>
|
||||
</pre>
|
||||
<h3>How are people using ADOdb</h3>
|
||||
Here are some examples of how people are using ADOdb:
|
||||
<ul>
|
||||
<li> <strong>PhpLens</strong> is a commercial data grid component that allows
|
||||
both cool Web designers and serious unshaved programmers to develop and
|
||||
maintain databases on the Web easily. Developed by the author of ADOdb.
|
||||
</li>
|
||||
<li> <strong>PHAkt</strong>: PHP Extension for DreamWeaver Ultradev allows
|
||||
you to script PHP in the popular Web page editor. Database handling provided
|
||||
by ADOdb. </li>
|
||||
<li> <strong>Analysis Console for Intrusion Databases (ACID)</strong>: PHP-based
|
||||
analysis engine to search and process a database of security incidents
|
||||
generated by security-related software such as IDSes and firewalls (e.g.
|
||||
Snort, ipchains). By Roman Danyliw. </li>
|
||||
<li> <strong>PostNuke</strong> is a very popular free content management system
|
||||
and weblog system. It offers full CSS support, HTML 4.01 transitional
|
||||
compliance throughout, an advanced blocks system, and is fully multi-lingual
|
||||
enabled. </li>
|
||||
<li><strong> EasyPublish CMS</strong> is another free content management system
|
||||
for managing information and integrated modules on your internet, intranet-
|
||||
and extranet-sites. From Norway. </li>
|
||||
<li> <strong>NOLA</strong> is a full featured accounting, inventory, and job
|
||||
tracking application. It is licensed under the GPL, and developed by Noguska.
|
||||
</li>
|
||||
</ul>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,367 +0,0 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
||||
|
||||
<html>
|
||||
<head>
|
||||
<title>Tips on Writing Portable SQL for Multiple Databases for PHP</title>
|
||||
</head>
|
||||
|
||||
<body bgcolor=white>
|
||||
<table width=100% border=0><tr><td><h2>Tips on Writing Portable SQL </h2></td><td>
|
||||
<div align=right><img src="cute_icons_for_site/adodb.gif"></div></td></tr></table>
|
||||
<p>Updated 6 Oct 2006. Added OffsetDate example.
|
||||
<p>Updated 18 Sep 2003. Added Portable Native SQL section.
|
||||
<p>
|
||||
|
||||
If you are writing an application that is used in multiple environments and
|
||||
operating systems, you need to plan to support multiple databases. This article
|
||||
is based on my experiences with multiple database systems, stretching from 4th
|
||||
Dimension in my Mac days, to the databases I currently use, which are: Oracle,
|
||||
FoxPro, Access, MS SQL Server and MySQL. Although most of the advice here applies
|
||||
to using SQL with Perl, Python and other programming languages, I will focus on PHP and how
|
||||
the <a href="http://adodb.sourceforge.net/">ADOdb</a> database abstraction library
|
||||
offers some solutions.<p></p>
|
||||
<p>Most database vendors practice product lock-in. The best or fastest way to
|
||||
do things is often implemented using proprietary extensions to SQL. This makes
|
||||
it extremely hard to write portable SQL code that performs well under all conditions.
|
||||
When the first ANSI committee got together in 1984 to standardize SQL, the database
|
||||
vendors had such different implementations that they could only agree on the
|
||||
core functionality of SQL. Many important application specific requirements
|
||||
were not standardized, and after so many years since the ANSI effort began,
|
||||
it looks as if much useful database functionality will never be standardized.
|
||||
Even though ANSI-92 SQL has codified much more, we still have to implement portability
|
||||
at the application level.</p>
|
||||
<h3><b>Selects</b></h3>
|
||||
<p>The SELECT statement has been standardized to a great degree. Nearly every
|
||||
database supports the following:</p>
|
||||
<p>SELECT [cols] FROM [tables]<br>
|
||||
[WHERE conditions]<br>
|
||||
[GROUP BY cols]<br>
|
||||
[HAVING conditions] <br>
|
||||
[ORDER BY cols]</p>
|
||||
<p>But so many useful techniques can only be implemented by using proprietary
|
||||
extensions. For example, when writing SQL to retrieve the first 10 rows for
|
||||
paging, you could write...</p>
|
||||
<table width="80%" border="1" cellspacing="0" cellpadding="0" align="center">
|
||||
<tr>
|
||||
<td><b>Database</b></td>
|
||||
<td><b>SQL Syntax</b></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>DB2</td>
|
||||
<td>select * from table fetch first 10 rows only</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Informix</td>
|
||||
<td>select first 10 * from table</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Microsoft SQL Server and Access</td>
|
||||
<td>select top 10 * from table</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>MySQL and PostgreSQL</td>
|
||||
<td>select * from table limit 10</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Oracle 8i</td>
|
||||
<td>select * from (select * from table) where rownum <= 10</td>
|
||||
</tr>
|
||||
</table>
|
||||
<p>This feature of getting a subset of data is so useful that in the PHP class
|
||||
library ADOdb, we have a SelectLimit( ) function that allows you to hide the
|
||||
implementation details within a function that will rewrite your SQL for you:</p>
|
||||
<pre>$connection->SelectLimit('select * from table', 10);
|
||||
</pre>
|
||||
<p><b>Selects: Fetch Modes</b></p>
|
||||
<p>PHP allows you to retrieve database records as arrays. You can choose to have
|
||||
the arrays indexed by field name or number. However different low-level PHP
|
||||
database drivers are inconsistent in their indexing efforts. ADOdb allows you
|
||||
to determine your prefered mode. You set this by setting the variable $ADODB_FETCH_MODE
|
||||
to either of the constants ADODB_FETCH_NUM (for numeric indexes) or ADODB_FETCH_ASSOC
|
||||
(using field names as an associative index).</p>
|
||||
<p>The default behaviour of ADOdb varies depending on the database you are using.
|
||||
For consistency, set the fetch mode to either ADODB_FETCH_NUM (for speed) or
|
||||
ADODB_FETCH_ASSOC (for convenience) at the beginning of your code. </p>
|
||||
<p><b>Selects: Counting Records</b></p>
|
||||
<p>Another problem with SELECTs is that some databases do not return the number
|
||||
of rows retrieved from a select statement. This is because the highest performance
|
||||
databases will return records to you even before the last record has been found.
|
||||
</p>
|
||||
<p>In ADOdb, RecordCount( ) returns the number of rows returned, or will emulate
|
||||
it by buffering the rows and returning the count after all rows have been returned.
|
||||
This can be disabled for performance reasons when retrieving large recordsets
|
||||
by setting the global variable $ADODB_COUNTRECS = false. This variable is checked
|
||||
every time a query is executed, so you can selectively choose which recordsets
|
||||
to count.</p>
|
||||
<p>If you prefer to set $ADODB_COUNTRECS = false, ADOdb still has the PO_RecordCount(
|
||||
) function. This will return the number of rows, or if it is not found, it will
|
||||
return an estimate using SELECT COUNT(*):</p>
|
||||
<pre>$rs = $db->Execute("select * from table where state=$state");
|
||||
$numrows = $rs->PO_RecordCount('table', "state=$state");</pre>
|
||||
<p><b>Selects: Locking</b> </p>
|
||||
<p>SELECT statements are commonly used to implement row-level locking of tables.
|
||||
Other databases such as Oracle, Interbase, PostgreSQL and MySQL with InnoDB
|
||||
do not require row-level locking because they use versioning to display data
|
||||
consistent with a specific point in time.</p>
|
||||
<p>Currently, I recommend encapsulating the row-level locking in a separate function,
|
||||
such as RowLock($table, $where):</p>
|
||||
<pre>$connection->BeginTrans( );
|
||||
$connection->RowLock($table, $where); </pre>
|
||||
<pre><font color=green># some operation</font></pre>
|
||||
<pre>if ($ok) $connection->CommitTrans( );
|
||||
else $connection->RollbackTrans( );
|
||||
</pre>
|
||||
<p><b>Selects: Outer Joins</b></p>
|
||||
<p>Not all databases support outer joins. Furthermore the syntax for outer joins
|
||||
differs dramatically between database vendors. One portable (and possibly slower)
|
||||
method of implementing outer joins is using UNION.</p>
|
||||
<p>For example, an ANSI-92 left outer join between two tables t1 and t2 could
|
||||
look like:</p>
|
||||
<pre>SELECT t1.col1, t1.col2, t2.cola <br> FROM t1 <i>LEFT JOIN</i> t2 ON t1.col = t2.col</pre>
|
||||
<p>This can be emulated using:</p>
|
||||
<pre>SELECT t1.col1, t1.col2, t2.cola FROM t1, t2 <br> WHERE t1.col = t2.col
|
||||
UNION ALL
|
||||
SELECT col1, col2, null FROM t1 <br> WHERE t1.col not in (select distinct col from t2)
|
||||
</pre>
|
||||
<p>Since ADOdb 2.13, we provide some hints in the connection object as to legal
|
||||
join variations. This is still incomplete and sometimes depends on the database
|
||||
version you are using, but is useful as a general guideline:</p>
|
||||
<p><font face="Courier New, Courier, mono">$conn->leftOuter</font>: holds the
|
||||
operator used for left outer joins (eg. '*='), or false if not known or not
|
||||
available.<br>
|
||||
<font face="Courier New, Courier, mono">$conn->rightOuter</font>: holds the
|
||||
operator used for right outer joins (eg '=*'), or false if not known or not
|
||||
available.<br>
|
||||
<font face="Courier New, Courier, mono">$conn->ansiOuter</font>: boolean
|
||||
that if true means that ANSI-92 style outer joins are supported, or false if
|
||||
not known.</p>
|
||||
<h3><b>Inserts</b> </h3>
|
||||
<p>When you create records, you need to generate unique id's for each record.
|
||||
There are two common techniques: (1) auto-incrementing columns and (2) sequences.
|
||||
</p>
|
||||
<p>Auto-incrementing columns are supported by MySQL, Sybase and Microsoft Access
|
||||
and SQL Server. However most other databases do not support this feature. So
|
||||
for portability, you have little choice but to use sequences. Sequences are
|
||||
special functions that return a unique incrementing number every time you call
|
||||
it, suitable to be used as database keys. In ADOdb, we use the GenID( ) function.
|
||||
It has takes a parameter, the sequence name. Different tables can have different
|
||||
sequences. </p>
|
||||
<pre>$id = $connection->GenID('sequence_name');<br>$connection->Execute("insert into table (id, firstname, lastname) <br> values ($id, $firstname, $lastname)");</pre>
|
||||
<p>For databases that do not support sequences natively, ADOdb emulates sequences
|
||||
by creating a table for every sequence.</p>
|
||||
<h3><b>Binding</b></h3>
|
||||
<p>Binding variables in an SQL statement is another tricky feature. Binding is
|
||||
useful because it allows pre-compilation of SQL. When inserting multiple records
|
||||
into a database in a loop, binding can offer a 50% (or greater) speedup. However
|
||||
many databases such as Access and MySQL do not support binding natively and
|
||||
there is some overhead in emulating binding. Furthermore, different databases
|
||||
(specificly Oracle!) implement binding differently. My recommendation is to
|
||||
use binding if your database queries are too slow, but make sure you are using
|
||||
a database that supports it like Oracle. </p>
|
||||
<p>ADOdb supports portable Prepare/Execute with:</p>
|
||||
<pre>$stmt = $db->Prepare('select * from customers where custid=? and state=?');
|
||||
$rs = $db->Execute($stmt, array($id,'New York'));</pre>
|
||||
<p>Oracle uses named bind placeholders, not "?", so to support portable binding, we have Param() that generates
|
||||
the correct placeholder (available since ADOdb 3.92):
|
||||
<pre><font color="#000000">$sql = <font color="#993300">'insert into table (col1,col2) values ('</font>.$DB->Param('a').<font color="#993300">','</font>.$DB->Param('b').<font color="#993300">')'</font>;
|
||||
<font color="#006600"># generates 'insert into table (col1,col2) values (?,?)'
|
||||
# or 'insert into table (col1,col2) values (:a,:b)</font>'
|
||||
$stmt = $DB->Prepare($sql);
|
||||
$stmt = $DB->Execute($stmt,array('one','two'));
|
||||
</font></pre>
|
||||
<a name="native"></a>
|
||||
<h2>Portable Native SQL</h2>
|
||||
<p>ADOdb provides the following functions for portably generating SQL functions
|
||||
as strings to be merged into your SQL statements (some are only available since
|
||||
ADOdb 3.92): </p>
|
||||
<table width="75%" border="1" align=center>
|
||||
<tr>
|
||||
<td width=30%><b>Function</b></td>
|
||||
<td><b>Description</b></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>DBDate($date)</td>
|
||||
<td>Pass in a UNIX timestamp or ISO date and it will convert it to a date
|
||||
string formatted for INSERT/UPDATE</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>DBTimeStamp($date)</td>
|
||||
<td>Pass in a UNIX timestamp or ISO date and it will convert it to a timestamp
|
||||
string formatted for INSERT/UPDATE</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SQLDate($date, $fmt)</td>
|
||||
<td>Portably generate a date formatted using $fmt mask, for use in SELECT
|
||||
statements.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>OffsetDate($date, $ndays)</td>
|
||||
<td>Portably generate a $date offset by $ndays.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Concat($s1, $s2, ...)</td>
|
||||
<td>Portably concatenate strings. Alternatively, for mssql use mssqlpo driver,
|
||||
which allows || operator.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>IfNull($fld, $replaceNull)</td>
|
||||
<td>Returns a string that is the equivalent of MySQL IFNULL or Oracle NVL.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Param($name)</td>
|
||||
<td>Generates bind placeholders, using ? or named conventions as appropriate.</td>
|
||||
</tr>
|
||||
<tr><td>$db->sysDate</td><td>Property that holds the SQL function that returns today's date</td>
|
||||
</tr>
|
||||
<tr><td>$db->sysTimeStamp</td><td>Property that holds the SQL function that returns the current
|
||||
timestamp (date+time).
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>$db->concat_operator</td><td>Property that holds the concatenation operator
|
||||
</td>
|
||||
</tr>
|
||||
<tr><td>$db->length</td><td>Property that holds the name of the SQL strlen function.
|
||||
</td></tr>
|
||||
|
||||
<tr><td>$db->upperCase</td><td>Property that holds the name of the SQL strtoupper function.
|
||||
</td></tr>
|
||||
<tr><td>$db->random</td><td>Property that holds the SQL to generate a random number between 0.00 and 1.00.
|
||||
</td>
|
||||
</tr>
|
||||
<tr><td>$db->substr</td><td>Property that holds the name of the SQL substring function.
|
||||
</td></tr>
|
||||
</table>
|
||||
<p> </p>
|
||||
<h2>DDL and Tuning</h2>
|
||||
There are database design tools such as ERWin or Dezign that allow you to generate data definition language commands such as ALTER TABLE or CREATE INDEX from Entity-Relationship diagrams.
|
||||
<p>
|
||||
However if you prefer to use a PHP-based table creation scheme, adodb provides you with this feature. Here is the code to generate the SQL to create a table with:
|
||||
<ol>
|
||||
<li> Auto-increment primary key 'ID', </li>
|
||||
<li>The person's 'NAME' VARCHAR(32) NOT NULL and defaults to '', </li>
|
||||
<li>The date and time of record creation 'CREATED', </li>
|
||||
<li> The person's 'AGE', defaulting to 0, type NUMERIC(16). </li>
|
||||
</ol>
|
||||
<p>
|
||||
Also create a compound index consisting of 'NAME' and 'AGE':
|
||||
<pre>
|
||||
$datadict = <strong>NewDataDictionary</strong>($connection);
|
||||
$flds = "
|
||||
<font color="#660000"> ID I AUTOINCREMENT PRIMARY,
|
||||
NAME C(32) DEFAULT '' NOTNULL,
|
||||
CREATED T DEFTIMESTAMP,
|
||||
AGE N(16) DEFAULT 0</font>
|
||||
";
|
||||
$sql1 = $datadict-><strong>CreateTableSQL</strong>('tabname', $flds);
|
||||
$sql2 = $datadict-><strong>CreateIndexSQL</strong>('idx_name_age', 'tabname', 'NAME,AGE');
|
||||
</pre>
|
||||
|
||||
<h3>Data Types</h3>
|
||||
<p>Stick to a few data types that are available in most databases. Char, varchar
|
||||
and numeric/number are supported by most databases. Most other data types (including
|
||||
integer, boolean and float) cannot be relied on being available. I recommend
|
||||
using char(1) or number(1) to hold booleans. </p>
|
||||
<p>Different databases have different ways of representing dates and timestamps/datetime.
|
||||
ADOdb attempts to display all dates in ISO (YYYY-MM-DD) format. ADOdb also provides
|
||||
DBDate( ) and DBTimeStamp( ) to convert dates to formats that are acceptable
|
||||
to that database. Both functions accept Unix integer timestamps and date strings
|
||||
in ISO format.</p>
|
||||
<pre>$date1 = $connection->DBDate(time( ));<br>$date2 = $connection->DBTimeStamp('2002-02-23 13:03:33');</pre>
|
||||
<p>We also provide functions to convert database dates to Unix timestamps:</p>
|
||||
<pre>$unixts = $recordset->UnixDate('#2002-02-30#'); <font color="green"># MS Access date =gt; unix timestamp</font></pre>
|
||||
<p>For date calculations, we have OffsetDate which allows you to calculate dates such as <i>yesterday</i> and <i>next week</i> in a RDBMS independant fashion. For example, if we want to set a field to 6 hour from now, use:
|
||||
<pre>
|
||||
$sql = 'update table set dtimefld='.$db->OffsetDate($db->sysTimeStamp, 6/24).' where ...';
|
||||
</pre>
|
||||
<p>The maximum length of a char/varchar field is also database specific. You can
|
||||
only assume that field lengths of up to 250 characters are supported. This is
|
||||
normally impractical for web based forum or content management systems. You
|
||||
will need to be familiar with how databases handle large objects (LOBs). ADOdb
|
||||
implements two functions, UpdateBlob( ) and UpdateClob( ) that allow you to
|
||||
update fields holding Binary Large Objects (eg. pictures) and Character Large
|
||||
Objects (eg. HTML articles):</p>
|
||||
<pre><font color=green># for oracle </font>
|
||||
$conn->Execute('INSERT INTO blobtable (id, blobcol) VALUES (1,empty_blob())');
|
||||
$conn->UpdateBlob('blobtable','blobcol',$blobvalue,'id=1');
|
||||
|
||||
<font color=green># non-oracle databases</font>
|
||||
$conn->Execute('INSERT INTO blobtable (id, blobcol) VALUES (1, null)');
|
||||
$conn->UpdateBlob('blobtable','blobcol',$blobvalue,'id=1');
|
||||
</pre>
|
||||
<p>Null handling is another area where differences can occur. This is a mine-field,
|
||||
because 3-value logic is tricky.
|
||||
<p>In general, I avoid using nulls except for dates and default all my numeric
|
||||
and character fields to 0 or the empty string. This maintains consistency with
|
||||
PHP, where empty strings and zero are treated as equivalent, and avoids SQL
|
||||
ambiguities when you use the ANY and EXISTS operators. However if your database
|
||||
has significant amounts of missing or unknown data, using nulls might be a good
|
||||
idea.
|
||||
<p>
|
||||
ADOdb also supports a portable <a href=http://phplens.com/adodb/reference.functions.concat.html#ifnull>IfNull</a> function, so you can define what to display
|
||||
if the field contains a null.
|
||||
<h3><b>Stored Procedures</b></h3>
|
||||
<p>Stored procedures are another problem area. Some databases allow recordsets
|
||||
to be returned in a stored procedure (Microsoft SQL Server and Sybase), and
|
||||
others only allow output parameters to be returned. Stored procedures sometimes
|
||||
need to be wrapped in special syntax. For example, Oracle requires such code
|
||||
to be wrapped in an anonymous block with BEGIN and END. Also internal sql operators
|
||||
and functions such as +, ||, TRIM( ), SUBSTR( ) or INSTR( ) vary between vendors.
|
||||
</p>
|
||||
<p>An example of how to call a stored procedure with 2 parameters and 1 return
|
||||
value follows:</p>
|
||||
<pre> switch ($db->databaseType) {
|
||||
case '<font color="#993300">mssql</font>':
|
||||
$sql = <font color="#000000"><font color="#993333">'<font color="#993300">SP_RUNSOMETHING</font>'</font></font>; break;
|
||||
case '<font color="#993300">oci8</font>':
|
||||
$sql =
|
||||
<font color="#993300"> </font><font color="#000000"><font color="#993300">"declare RETVAL integer;begin :RETVAL := </font><font color="#000000"><font color="#993333"><font color="#993300">SP_RUNSOMETHING</font></font></font><font color="#993300">(:myid,:group);end;";
|
||||
</font> break;</font>
|
||||
default:
|
||||
die('<font color="#993300">Unsupported feature</font>');
|
||||
}
|
||||
<font color="#000000"><font color="green"> # @RETVAL = SP_RUNSOMETHING @myid,@group</font>
|
||||
$stmt = $db->PrepareSP($sql); <br> $db->Parameter($stmt,$id,'<font color="#993300">myid</font>');
|
||||
$db->Parameter($stmt,$group,'<font color="#993300">group</font>');
|
||||
<font color="green"># true indicates output parameter<br> </font>$db->Parameter($stmt,$ret,'<font color="#993300">RETVAL</font>',true);
|
||||
$db->Execute($stmt); </font></pre>
|
||||
<p>As you can see, the ADOdb API is the same for both databases. But the stored
|
||||
procedure SQL syntax is quite different between databases and is not portable,
|
||||
so be forewarned! However sometimes you have little choice as some systems only
|
||||
allow data to be accessed via stored procedures. This is when the ultimate portability
|
||||
solution might be the only solution: <i>treating portable SQL as a localization
|
||||
exercise...</i></p>
|
||||
<h3><b>SQL as a Localization Exercise</b></h3>
|
||||
<p> In general to provide real portability, you will have to treat SQL coding
|
||||
as a localization exercise. In PHP, it has become common to define separate
|
||||
language files for English, Russian, Korean, etc. Similarly, I would suggest
|
||||
you have separate Sybase, Intebase, MySQL, etc files, and conditionally include
|
||||
the SQL based on the database. For example, each MySQL SQL statement would be
|
||||
stored in a separate variable, in a file called 'mysql-lang.inc.php'.</p>
|
||||
<pre>$sqlGetPassword = '<font color="#993300">select password from users where userid=%s</font>';
|
||||
$sqlSearchKeyword = quot;<font color="#993300">SELECT * FROM articles WHERE match (title,body) against (%s</font>)";</pre>
|
||||
<p>In our main PHP file:</p>
|
||||
<pre><font color=green># define which database to load...</font>
|
||||
<b>$database = '<font color="#993300">mysql</font>';
|
||||
include_once("<font color="#993300">$database-lang.inc.php</font>");</b>
|
||||
|
||||
$db = NewADOConnection($database);
|
||||
$db->PConnect(...) or die('<font color="#993300">Failed to connect to database</font>');
|
||||
|
||||
<font color=green># search for a keyword $word</font>
|
||||
$rs = $db->Execute(sprintf($sqlSearchKeyWord,$db->qstr($word)));</pre>
|
||||
<p>Note that we quote the $word variable using the qstr( ) function. This is because
|
||||
each database quotes strings using different conventions.</p>
|
||||
<p>
|
||||
<h3>Final Thoughts</h3>
|
||||
<p>The best way to ensure that you have portable SQL is to have your data tables designed using
|
||||
sound principles. Learn the theory of normalization and entity-relationship diagrams and model
|
||||
your data carefully. Understand how joins and indexes work and how they are used to tune performance.
|
||||
<p> Visit the following page for more references on database theory and vendors:
|
||||
<a href="http://php.weblogs.com/sql_tutorial">http://php.weblogs.com/sql_tutorial</a>.
|
||||
Also read this article on <a href=http://phplens.com/lens/php-book/optimizing-debugging-php.php>Optimizing PHP</a>.
|
||||
<p>
|
||||
<font size=1>(c) 2002-2003 John Lim.</font>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,290 +0,0 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
||||
|
||||
<html>
|
||||
<head>
|
||||
<title>Tutorial: Moving from MySQL to ADODB</title>
|
||||
</head>
|
||||
|
||||
<body bgcolor=white>
|
||||
<h1>Tutorial: Moving from MySQL to ADODB</h1>
|
||||
|
||||
<pre> You say eether and I say eyether,
|
||||
You say neether and I say nyther;
|
||||
Eether, eyether, neether, nyther -
|
||||
Let's call the whole thing off !
|
||||
<br>
|
||||
You like potato and I like po-tah-to,
|
||||
You like tomato and I like to-mah-to;
|
||||
Potato, po-tah-to, tomato, to-mah-to -
|
||||
Let's call the whole thing off !
|
||||
</pre>
|
||||
<p>I love this song, especially the version with Louis Armstrong and Ella singing
|
||||
duet. It is all about how hard it is for two people in love to be compatible
|
||||
with each other. It's about compromise and finding a common ground, and that's
|
||||
what this article is all about.
|
||||
<p>PHP is all about creating dynamic web-sites with the least fuss and the most
|
||||
fun. To create these websites we need to use databases to retrieve login information,
|
||||
to splash dynamic news onto the web page and store forum postings. So let's
|
||||
say we were using the popular MySQL database for this. Your company has done
|
||||
such a fantastic job that the Web site is more popular than your wildest dreams.
|
||||
You find that MySQL cannot scale to handle the workload; time to switch databases.
|
||||
<p> Unfortunately in PHP every database is accessed slightly differently. To connect
|
||||
to MySQL, you would use <i>mysql_connect()</i>; when you decide to upgrade to
|
||||
Oracle or Microsoft SQL Server, you would use <i>ocilogon() </i>or <i>mssql_connect()</i>
|
||||
respectively. What is worse is that the parameters you use for the different
|
||||
connect functions are different also.. One database says po-tato, the other
|
||||
database says pota-to. Oh-oh.
|
||||
<h3>Let's NOT call the whole thing off</h3>
|
||||
<p>A database wrapper library such as ADODB comes in handy when you need to ensure portability. It provides
|
||||
you with a common API to communicate with any supported database so you don't have to call things off. <p>
|
||||
|
||||
<p>ADODB stands for Active Data Objects DataBase (sorry computer guys are sometimes
|
||||
not very original). ADODB currently supports MySQL, PostgreSQL, Oracle, Interbase,
|
||||
Microsoft SQL Server, Access, FoxPro, Sybase, ODBC and ADO. You can download
|
||||
ADODB from <a href=http://php.weblogs.com/adodb></a><a href="http://php.weblogs.com/adodb">http://php.weblogs.com/adodb</a>.
|
||||
<h3>MySQL Example</h3>
|
||||
<p>The most common database used with PHP is MySQL, so I guess you should be familiar
|
||||
with the following code. It connects to a MySQL server at <i>localhost</i>,
|
||||
database <i>mydb</i>, and executes an SQL select statement. The results are
|
||||
printed, one line per row.
|
||||
<pre><font color="#666600">$db = <b>mysql_connect</b>("localhost", "root", "password");
|
||||
<b>mysql_select_db</b>("mydb",$db);</font>
|
||||
<font color="#660000">$result = <b>mysql_query</b>("SELECT * FROM employees",$db)</font><code><font color="#663300">;
|
||||
if ($result === false) die("failed");</font></code>
|
||||
<font color="#006666"><b>while</b> ($fields =<b> mysql_fetch_row</b>($result)) {
|
||||
<b>for</b> ($i=0, $max=sizeof($fields); $i < $max; $i++) {
|
||||
<b>print</b> $fields[$i].' ';
|
||||
}
|
||||
<b>print</b> "<br>\n";
|
||||
}</font>
|
||||
</pre>
|
||||
<p>The above code has been color-coded by section. The first section is the connection
|
||||
phase. The second is the execution of the SQL, and the last section is displaying
|
||||
the fields. The <i>while</i> loop scans the rows of the result, while the <i>for</i>
|
||||
loop scans the fields in one row.</p>
|
||||
<p>Here is the equivalent code in ADODB</p>
|
||||
<pre><b><font color="#666600"> include("adodb.inc.php");</font></b><font color="#666600">
|
||||
$db = <b>NewADOConnection</b>('mysql');
|
||||
$db-><b>Connect</b>("localhost", "root", "password", "mydb");</font>
|
||||
<font color="#663300">$result = $db-><b>Execute</b>("SELECT * FROM employees");
|
||||
</font><font color="#663300"></font><code><font color="#663300">if ($result === false) die("failed")</font></code><code><font color="#663300">;</font></code>
|
||||
<font color="#006666"><b>while</b> (!$result->EOF) {
|
||||
<b>for</b> ($i=0, $max=$result-><b>FieldCount</b>(); $i < $max; $i++)
|
||||
<b>print</b> $result->fields[$i].' ';
|
||||
$result-><b>MoveNext</b>();
|
||||
<b>print</b> "<br>\n";
|
||||
}</font> </pre>
|
||||
<p></p>
|
||||
<p>Now porting to Oracle is as simple as changing the second line to <code>NewADOConnection('oracle')</code>.
|
||||
Let's walk through the code...</p>
|
||||
<h3>Connecting to the Database</h3>
|
||||
<p></p>
|
||||
<pre><b><font color="#666600">include("adodb.inc.php");</font></b><font color="#666600">
|
||||
$db = <b>NewADOConnection</b>('mysql');
|
||||
$db-><b>Connect</b>("localhost", "root", "password", "mydb");</font></pre>
|
||||
<p>The connection code is a bit more sophisticated than MySQL's because our needs
|
||||
are more sophisticated. In ADODB, we use an object-oriented approach to managing
|
||||
the complexity of handling multiple databases. We have different classes to
|
||||
handle different databases. If you aren't familiar with object-oriented programing,
|
||||
don't worry -- the complexity is all hidden away in the<code> NewADOConnection()</code>
|
||||
function.</p>
|
||||
<p>To conserve memory, we only load the PHP code specific to the database you
|
||||
are connecting to. We do this by calling <code>NewADOConnection(databasedriver)</code>.
|
||||
Legal database drivers include <i>mysql, mssql, oracle, oci8, postgres, sybase,
|
||||
vfp, access, ibase </i>and many others.</p>
|
||||
<p>Then we create a new instance of the connection class by calling <code>NewADOConnection()</code>.
|
||||
Finally we connect to the database using <code>$db->Connect(). </code></p>
|
||||
<h3>Executing the SQL</h3>
|
||||
<p><code><font color="#663300">$result = $db-><b>Execute</b>("SELECT *
|
||||
FROM employees");<br>
|
||||
if ($result === false) die("failed")</font></code><code><font color="#663300">;</font></code>
|
||||
<br>
|
||||
</p>
|
||||
<p>Sending the SQL statement to the server is straight forward. Execute() will
|
||||
return a recordset object on successful execution. You should check $result
|
||||
as we do above.
|
||||
<p>An issue that confuses beginners is the fact that we have two types of objects
|
||||
in ADODB, the connection object and the recordset object. When do we use each?
|
||||
<p>The connection object ($db) is responsible for connecting to the database,
|
||||
formatting your SQL and querying the database server. The recordset object ($result)
|
||||
is responsible for retrieving the results and formatting the reply as text or
|
||||
as an array.
|
||||
<p>The only thing I need to add is that ADODB provides several helper functions
|
||||
for making INSERT and UPDATE statements easier, which we will cover in the Advanced
|
||||
section.
|
||||
<h3>Retrieving the Data<br>
|
||||
</h3>
|
||||
<pre><font color="#006666"><b>while</b> (!$result->EOF) {
|
||||
<b>for</b> ($i=0, $max=$result-><b>FieldCount</b>(); $i < $max; $i++)
|
||||
<b>print</b> $result->fields[$i].' ';
|
||||
$result-><b>MoveNext</b>();
|
||||
<b>print</b> "<br>\n";
|
||||
}</font></pre>
|
||||
<p>The paradigm for getting the data is that it's like reading a file. For every
|
||||
line, we check first whether we have reached the end-of-file (EOF). While not
|
||||
end-of-file, loop through each field in the row. Then move to the next line
|
||||
(MoveNext) and repeat.
|
||||
<p>The <code>$result->fields[]</code> array is generated by the PHP database
|
||||
extension. Some database extensions do not index the array by field name.
|
||||
To force indexing by name - that is associative arrays -
|
||||
use the $ADODB_FETCH_MODE global variable.
|
||||
<pre>
|
||||
$<b>ADODB_FETCH_MODE</b> = ADODB_FETCH_NUM;
|
||||
$rs1 = $db->Execute('select * from table');
|
||||
$<b>ADODB_FETCH_MODE</b> = ADODB_FETCH_ASSOC;
|
||||
$rs2 = $db->Execute('select * from table');
|
||||
print_r($rs1->fields); // shows <i>array([0]=>'v0',[1] =>'v1')</i>
|
||||
print_r($rs2->fields); // shows <i>array(['col1']=>'v0',['col2'] =>'v1')</i>
|
||||
</pre>
|
||||
<p>
|
||||
As you can see in the above example, both recordsets store and use different fetch modes
|
||||
based on the $ADODB_FETCH_MODE setting when the recordset was created by Execute().</p>
|
||||
<h2>ADOConnection<a name="ADOConnection"></a></h2>
|
||||
<p>Object that performs the connection to the database, executes SQL statements
|
||||
and has a set of utility functions for standardising the format of SQL statements
|
||||
for issues such as concatenation and date formats.</p>
|
||||
|
||||
<h3>Other Useful Functions</h3>
|
||||
<p><code>$recordset->Move($pos)</code> scrolls to that particular row. ADODB supports forward
|
||||
scrolling for all databases. Some databases will not support backwards scrolling.
|
||||
This is normally not a problem as you can always cache records to simulate backwards
|
||||
scrolling.
|
||||
<p><code>$recordset->RecordCount()</code> returns the number of records accessed by the
|
||||
SQL statement. Some databases will return -1 because it is not supported.
|
||||
<p><code>$recordset->GetArray()</code> returns the result as an array.
|
||||
<p><code>rs2html($recordset)</code> is a function that is generates a HTML table based on the
|
||||
$recordset passed to it. An example with the relevant lines in bold:
|
||||
<pre> include('adodb.inc.php');
|
||||
<b>include('tohtml.inc.php');</b> /* includes the rs2html function */
|
||||
$conn = ADONewConnection('mysql');
|
||||
$conn->PConnect('localhost','userid','password','database');
|
||||
$rs = $conn->Execute('select * from table');
|
||||
<b> rs2html($rs)</b>; /* recordset to html table */ </pre>
|
||||
<p>There are many other helper functions that are listed in the documentation available at <a href="http://php.weblogs.com/adodb_manual"></a><a href="http://php.weblogs.com/adodb_manual">http://php.weblogs.com/adodb_manual</a>.
|
||||
<h2>Advanced Material</h2>
|
||||
<h3>Inserts and Updates </h3>
|
||||
<p>Let's say you want to insert the following data into a database.
|
||||
<p><b>ID</b> = 3<br>
|
||||
<b>TheDate</b>=mktime(0,0,0,8,31,2001) /* 31st August 2001 */<br>
|
||||
<b>Note</b>= sugar why don't we call it off
|
||||
<p>When you move to another database, your insert might no longer work.</p>
|
||||
<p>The first problem is that each database has a different default date format.
|
||||
MySQL expects YYYY-MM-DD format, while other databases have different defaults.
|
||||
ADODB has a function called DBDate() that addresses this issue by converting
|
||||
converting the date to the correct format.</p>
|
||||
<p>The next problem is that the <b>don't</b> in the Note needs to be quoted. In
|
||||
MySQL, we use <b>don\'t</b> but in some other databases (Sybase, Access, Microsoft
|
||||
SQL Server) we use <b>don''t. </b>The qstr() function addresses this issue.</p>
|
||||
<p>So how do we use the functions? Like this:</p>
|
||||
<pre>$sql = "INSERT INTO table (id, thedate,note) values ("
|
||||
. $<b>ID</b> . ','
|
||||
. $db->DBDate($<b>TheDate</b>) .','
|
||||
. $db->qstr($<b>Note</b>).")";
|
||||
$db->Execute($sql);</pre>
|
||||
<p>ADODB also supports <code>$connection->Affected_Rows()</code> (returns the
|
||||
number of rows affected by last update or delete) and <code>$recordset->Insert_ID()</code>
|
||||
(returns last autoincrement number generated by an insert statement). Be forewarned
|
||||
that not all databases support the two functions.<br>
|
||||
</p>
|
||||
<h3>MetaTypes</h3>
|
||||
<p>You can find out more information about each of the fields (I use the words
|
||||
fields and columns interchangebly) you are selecting by calling the recordset
|
||||
method <code>FetchField($fieldoffset)</code>. This will return an object with
|
||||
3 properties: name, type and max_length.
|
||||
<pre>For example:</pre>
|
||||
<pre>$recordset = $conn->Execute("select adate from table");<br>$f0 = $recordset->FetchField(0);
|
||||
</pre>
|
||||
<p>Then <code>$f0->name</code> will hold <i>'adata'</i>, <code>$f0->type</code>
|
||||
will be set to '<i>date'</i>. If the max_length is unknown, it will be set to
|
||||
-1.
|
||||
<p>One problem with handling different databases is that each database often calls
|
||||
the same type by a different name. For example a <i>timestamp</i> type is called
|
||||
<i>datetime</i> in one database and <i>time</i> in another. So ADODB has a special
|
||||
<code>MetaType($type, $max_length)</code> function that standardises the types
|
||||
to the following:
|
||||
<p>C: character and varchar types<br>
|
||||
X: text or long character (eg. more than 255 bytes wide).<br>
|
||||
B: blob or binary image<br>
|
||||
D: date<br>
|
||||
T: timestamp<br>
|
||||
L: logical (boolean)<br>
|
||||
I: integer<br>
|
||||
N: numeric (float, double, money)
|
||||
<p>In the above date example,
|
||||
<p><code>$recordset = $conn->Execute("select adate from table");<br>
|
||||
$f0 = $recordset->FetchField(0);<br>
|
||||
$type = $recordset->MetaType($f0->type, $f0->max_length);<br>
|
||||
print $type; /* should print 'D'</code> */
|
||||
<p>
|
||||
<p><b>Select Limit and Top Support</b>
|
||||
<p>ADODB has a function called $connection->SelectLimit($sql,$nrows,$offset) that allows
|
||||
you to retrieve a subset of the recordset. This will take advantage of native
|
||||
SELECT TOP on Microsoft products and SELECT ... LIMIT with PostgreSQL and MySQL, and
|
||||
emulated if the database does not support it.
|
||||
<p><b>Caching Support</b>
|
||||
<p>ADODB allows you to cache recordsets in your file system, and only requery the database
|
||||
server after a certain timeout period with $connection->CacheExecute($secs2cache,$sql) and
|
||||
$connection->CacheSelectLimit($secs2cache,$sql,$nrows,$offset).
|
||||
<p><b>PHP4 Session Handler Support</b>
|
||||
<p>ADODB also supports PHP4 session handlers. You can store your session variables
|
||||
in a database for true scalability using ADODB. For further information, visit
|
||||
<a href="http://php.weblogs.com/adodb-sessions"></a><a href="http://php.weblogs.com/adodb-sessions">http://php.weblogs.com/adodb-sessions</a>
|
||||
<h3>Commercial Use Encouraged</h3>
|
||||
<p>If you plan to write commercial PHP applications that you want to resell, you should consider ADODB. It has been released using the lesser GPL, which means you can legally include it in commercial applications, while keeping your code proprietary. Commercial use of ADODB is strongly encouraged! We are using it internally for this reason.<p>
|
||||
|
||||
<h2>Conclusion</h2>
|
||||
<p>As a thank you for finishing this article, here are the complete lyrics for
|
||||
<i>let's call the whole thing off</i>.<br>
|
||||
<br>
|
||||
<pre>
|
||||
Refrain
|
||||
<br>
|
||||
You say eether and I say eyether,
|
||||
You say neether and I say nyther;
|
||||
Eether, eyether, neether, nyther -
|
||||
Let's call the whole thing off !
|
||||
<br>
|
||||
You like potato and I like po-tah-to,
|
||||
You like tomato and I like to-mah-to;
|
||||
Potato, po-tah-to, tomato, to-mah-to -
|
||||
Let's call the whole thing off !
|
||||
<br>
|
||||
But oh, if we call the whole thing off, then we must part.
|
||||
And oh, if we ever part, then that might break my heart.
|
||||
<br>
|
||||
So, if you like pajamas and I like pa-jah-mas,
|
||||
I'll wear pajamas and give up pa-jah-mas.
|
||||
For we know we
|
||||
Need each other, so we
|
||||
Better call the calling off off.
|
||||
Let's call the whole thing off !
|
||||
<br>
|
||||
Second Refrain
|
||||
<br>
|
||||
You say laughter and I say lawfter,
|
||||
You say after and I say awfter;
|
||||
Laughter, lawfter, after, awfter -
|
||||
Let's call the whole thing off !
|
||||
<br>
|
||||
You like vanilla and I like vanella,
|
||||
You, sa's'parilla and I sa's'parella;
|
||||
Vanilla, vanella, choc'late, strawb'ry -
|
||||
Let's call the whole thing off !
|
||||
<br>
|
||||
But oh, if we call the whole thing off, then we must part.
|
||||
And oh, if we ever part, then that might break my heart.
|
||||
<br>
|
||||
So, if you go for oysters and I go for ersters,
|
||||
I'll order oysters and cancel the ersters.
|
||||
For we know we
|
||||
Need each other, so we
|
||||
Better call the calling off off.
|
||||
Let's call the whole thing off !
|
||||
</pre>
|
||||
<p><font size=2>Song and lyrics by George and Ira Gershwin, introduced by Fred Astaire and Ginger Rogers
|
||||
in the film "Shall We Dance?" </font><p>
|
||||
<p>
|
||||
(c)2001-2002 John Lim.
|
||||
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user