forked from extern/egroupware
298 lines
12 KiB
HTML
298 lines
12 KiB
HTML
|
<html>
|
||
|
|
<head>
|
||
|
|
<title>ADODB Data Dictionary 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">
|
||
|
|
|
||
|
|
<h2>ADOdb Data Dictionary Library for PHP</h2>
|
||
|
|
<p> V3.94 13 Oct 2003 (c) 2000-2003 John Lim (<a href="mailto:jlim#natsoft.com.my">jlim#natsoft.com.my</a>)</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://php.weblogs.com/adodb?dd=1>Download</a> <a href=http://php.weblogs.com/adodb_manual?dd=1>Other Docs</a>
|
||
|
|
|
||
|
|
<p>This documentation describes a class library to automate the creation of tables,
|
||
|
|
indexes and foreign key constraints portably for multiple databases.
|
||
|
|
<p>Currently the following databases are supported:
|
||
|
|
<p> Well-tested: PostgreSQL, MySQL, Oracle, MSSQL. <br>
|
||
|
|
Beta-quality: DB2, Informix, Sybase, Interbase, Firebird.<br>
|
||
|
|
Alpha-quality: MS Access (does not support DEFAULT values) and generic ODBC.</p>
|
||
|
|
<h3>Example Usage</h3>
|
||
|
|
<pre>include_once('adodb.inc.php');
|
||
|
|
<font color="#006600">
|
||
|
|
# First create a normal connection
|
||
|
|
</font>$db->NewADOConnection('mysql');
|
||
|
|
$db->Connect(...);
|
||
|
|
<br>
|
||
|
|
<font color="#006600"># Then create a data dictionary object, using this connection
|
||
|
|
</font>$dict = <strong>NewDataDictionary</strong>($db);
|
||
|
|
|
||
|
|
<font color="#006600"># We have a portable declarative data dictionary format in ADOdb 3.50, similar to SQL.
|
||
|
|
# Field types use 1 character codes, and fields are separated by commas.
|
||
|
|
# The following example creates three fields: "col1", "col2" and "col3":</font>
|
||
|
|
$flds = "
|
||
|
|
<font color="#663300"><strong> col1 C(32) NOTNULL DEFAULT 'abc',
|
||
|
|
col2 I DEFAULT 0,
|
||
|
|
col3 N(12.2)</strong></font>
|
||
|
|
";<br>
|
||
|
|
<font color="#006600"># We demonstrate creating tables and indexes</font>
|
||
|
|
$sqlarray = $dict-><strong>CreateTableSQL</strong>($tabname, $flds, $taboptarray);
|
||
|
|
$dict-><strong>ExecuteSQLArray</strong>($sqlarray);<br>
|
||
|
|
$idxflds = 'co11, col2';
|
||
|
|
$sqlarray = $dict-><strong>CreateIndexSQL</strong>($idxname, $tabname, $idxflds);
|
||
|
|
$dict-><strong>ExecuteSQLArray</strong>($sqlarray);
|
||
|
|
</pre>
|
||
|
|
<h3>Functions</h3>
|
||
|
|
<p><b>function CreateDatabase($dbname, $optionsarray=false)</b>
|
||
|
|
<p>Create a database with the name $dbname;
|
||
|
|
<p><b>function CreateTableSQL($tabname, $fldarray, $taboptarray=false)</b>
|
||
|
|
<pre>
|
||
|
|
RETURNS: an array of strings, the sql to be executed, or false
|
||
|
|
$tabname: name of table
|
||
|
|
$fldarray: string (or array) containing field info
|
||
|
|
$taboptarray: array containing table options
|
||
|
|
</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:
|
||
|
|
<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:
|
||
|
|
<pre> array($fieldname, $type, [,$colsize] [,$otheroptions]*)</pre>
|
||
|
|
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>
|
||
|
|
Legal portable type codes include:
|
||
|
|
<pre>
|
||
|
|
C: varchar
|
||
|
|
X: Largest varchar size
|
||
|
|
XL: For Oracle, returns CLOB, otherwise same as 'X' above
|
||
|
|
|
||
|
|
C2: Multibyte varchar
|
||
|
|
X2: Multibyte varchar (largest size)
|
||
|
|
|
||
|
|
B: BLOB (binary large object)<br>
|
||
|
|
D: Date (some databases do not support this, and we return a datetime type)
|
||
|
|
T: Datetime or Timestamp
|
||
|
|
L: Integer field suitable for storing booleans (0 or 1)
|
||
|
|
I: Integer (mapped to I4)
|
||
|
|
I1: 1-byte integer
|
||
|
|
I2: 2-byte integer
|
||
|
|
I4: 4-byte integer
|
||
|
|
I8: 8-byte integer
|
||
|
|
F: Floating point number
|
||
|
|
N: Numeric or decimal number
|
||
|
|
</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>
|
||
|
|
The $otheroptions include the following keywords (case-insensitive):
|
||
|
|
<pre>
|
||
|
|
AUTO For autoincrement number. Emulated with triggers if not available.
|
||
|
|
Sets NOTNULL also.
|
||
|
|
AUTOINCREMENT Same as auto.
|
||
|
|
KEY Primary key field. Sets NOTNULL also. Compound keys are supported.
|
||
|
|
PRIMARY Same as KEY.
|
||
|
|
DEF Synonym for DEFAULT for lazy typists.
|
||
|
|
DEFAULT The default value. Character strings are auto-quoted unless
|
||
|
|
the string begins and ends with spaces, eg ' SYSDATE '.
|
||
|
|
NOTNULL If field is not null.
|
||
|
|
DEFDATE Set default value to call function to get today's date.
|
||
|
|
DEFTIMESTAMP Set default to call function to get today's datetime.
|
||
|
|
NOQUOTE Prevents autoquoting of default string values.
|
||
|
|
CONSTRAINTS Additional constraints defined at the end of the field
|
||
|
|
definition.
|
||
|
|
</pre>
|
||
|
|
<p> The Data Dictonary accepts two formats, the older array specification: </p>
|
||
|
|
<pre>
|
||
|
|
$flds = array(
|
||
|
|
array('COLNAME', 'DECIMAL', '8.4', 'DEFAULT' => 0, 'NotNull'),
|
||
|
|
array('ID', 'I' , 'AUTO'),
|
||
|
|
array('MYDATE', 'D' , 'DEFDATE'),
|
||
|
|
array('NAME', 'C' ,'32',
|
||
|
|
'CONSTRAINTS' => 'FOREIGN KEY REFERENCES reftable')
|
||
|
|
); </pre>
|
||
|
|
Or the simpler declarative format:
|
||
|
|
<pre> $flds = "
|
||
|
|
<font color="#660000"><strong> COLNAME DECIMAL(8.4) DEFAULT 0 NotNull,
|
||
|
|
ID I AUTO,
|
||
|
|
MYDATE D DEFDATE,
|
||
|
|
NAME C(32) CONSTRAINTS 'FOREIGN KEY REFERENCES reftable' </strong></font>
|
||
|
|
";
|
||
|
|
</pre>
|
||
|
|
<p>
|
||
|
|
The $taboptarray is the 3rd parameter of the CreateTableSQL function.
|
||
|
|
This contains table specific settings. Legal keywords include:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>REPLACE <br>
|
||
|
|
Indicates that the previous table definition should be removed (dropped)together
|
||
|
|
with ALL data. See first example below.<br>
|
||
|
|
</li>
|
||
|
|
<li>CONSTRAINTS <br>
|
||
|
|
Define this as the key, with the constraint as the value. See the postgresql
|
||
|
|
example 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 if the table already exists, drop the table first.
|
||
|
|
<pre> $taboptarray = array('mysql' => 'TYPE=ISAM', 'oci8' => 'tablespace users', 'REPLACE'); </pre>
|
||
|
|
<p>
|
||
|
|
You can also define foreignkey constraints. The following is syntax for
|
||
|
|
postgresql:<pre>
|
||
|
|
$taboptarray = array('constraints' =>
|
||
|
|
', FOREIGN KEY (col1) REFERENCES reftable (refcol)');
|
||
|
|
</pre>
|
||
|
|
<p><strong>function ChangeTableSQL($tabname, $flds)</strong>
|
||
|
|
<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>The class must be connected to the database for ChangeTableSQL to detect the
|
||
|
|
existance of the table. Idea and code contributed by Florian Buzin.
|
||
|
|
<p><b>function CreateIndexSQL($idxname, $tabname, $flds, $idxoptarray=false)</b>
|
||
|
|
<p>
|
||
|
|
RETURNS: an array of strings, the sql to be executed, or false
|
||
|
|
<pre>
|
||
|
|
$idxname: name of index
|
||
|
|
$tabname: name of table
|
||
|
|
$flds: list of fields as a comma delimited string or an array of strings
|
||
|
|
$idxoptarray: array of index creation options
|
||
|
|
</pre>
|
||
|
|
<p> $idxoptarray is similar to $taboptarray in that index specific information can
|
||
|
|
be embedded in the array. Other options include:
|
||
|
|
<pre>
|
||
|
|
CLUSTERED Create clustered index (only mssql)
|
||
|
|
BITMAP Create bitmap index (only oci8)
|
||
|
|
UNIQUE Make unique index
|
||
|
|
FULLTEXT Make fulltext index (only mysql)
|
||
|
|
HASH Create hash index (only postgres)
|
||
|
|
</pre>
|
||
|
|
<p> <strong>function AddColumnSQL($tabname, $flds)</strong>
|
||
|
|
<p>Add one or more columns. Not guaranteed to work under all situations.
|
||
|
|
<p><strong>function AlterColumnSQL($tabname, $flds)</strong>
|
||
|
|
<p>Warning, not all databases support this feature.
|
||
|
|
<p> <strong>function DropColumnSQL($tabname, $flds)</strong>
|
||
|
|
<p>Drop 1 or more columns.
|
||
|
|
<p> <strong>function ExecuteSQLArray($sqlarray, $contOnError = true)</strong>
|
||
|
|
<pre>
|
||
|
|
RETURNS: 0 if failed, 1 if executed all but with errors, 2 if executed successfully
|
||
|
|
$sqlarray: an array of strings with sql code (no semicolon at the end of string)
|
||
|
|
$contOnError: if true, then continue executing even if error occurs
|
||
|
|
</pre>
|
||
|
|
<p>Executes an array of SQL strings returned by CreateTableSQL or CreateIndexSQL.
|
||
|
|
<hr><a name=xmlschema></a>
|
||
|
|
<h2>XML Schema</h2>
|
||
|
|
This is a class contributed by Richard Tango-Lowy that allows the user to quickly
|
||
|
|
and easily build a database using the excellent
|
||
|
|
ADODB database library and a simple XML formatted file.
|
||
|
|
|
||
|
|
|
||
|
|
<H3>Quick Start</H3>
|
||
|
|
<P>First, create an XML database schema. Let's call it "schema.xml:"</P><PRE>
|
||
|
|
<?xml version="1.0"?>
|
||
|
|
<schema>
|
||
|
|
<table name="mytable">
|
||
|
|
<field name="row1" type="I">
|
||
|
|
<descr>An integer row that's a primary key and autoincrements</descr>
|
||
|
|
<KEY/>
|
||
|
|
<AUTOINCREMENT/>
|
||
|
|
</field>
|
||
|
|
<field name="row2" type="C" size="16">
|
||
|
|
<descr>A 16 character varchar row that can't be null</descr>
|
||
|
|
<NOTNULL/>
|
||
|
|
</field>
|
||
|
|
</table>
|
||
|
|
<index name="myindex" table="mytable">
|
||
|
|
<col>row1</col>
|
||
|
|
<col>row2</col>
|
||
|
|
</index>
|
||
|
|
<sql>
|
||
|
|
<descr>SQL to be executed only on specific platforms</descr>
|
||
|
|
<query platform="postgres|postgres7">
|
||
|
|
insert into mytable ( row1, row2 ) values ( 12, 'stuff' )
|
||
|
|
</query>
|
||
|
|
<query platform="mysql">
|
||
|
|
insert into mytable ( row1, row2 ) values ( 12, 'different stuff' )
|
||
|
|
</query>
|
||
|
|
</sql>
|
||
|
|
</schema>
|
||
|
|
</PRE><P>Create a new database using the appropriate tool for your platform.
|
||
|
|
Executing the following PHP code will create the a <i>mytable</i> and <i>myindex</i>
|
||
|
|
in the database and insert one row into <i>mytable</i> if the platform is postgres or mysql. </P><PRE>
|
||
|
|
include_once('/path/to/adodb.inc.php');
|
||
|
|
include_once('/path/to/adodb-xmlschema.inc.php');
|
||
|
|
|
||
|
|
// To build the schema, start by creating a normal ADOdb connection:
|
||
|
|
$db->NewADOConnection( 'mysql' );
|
||
|
|
$db->Connect( ... );
|
||
|
|
|
||
|
|
// Create the schema object and build the query array.
|
||
|
|
$schema = <B>new adoSchema</B>( $db );
|
||
|
|
|
||
|
|
// Optionally, set a prefix for newly-created tables. In this example
|
||
|
|
// the prefix "myprefix_" will result in a table named "myprefix_tablename".
|
||
|
|
//$schema-><B>setPrefix</B>( "myprefix_" );
|
||
|
|
|
||
|
|
// Build the SQL array
|
||
|
|
$sql = $schema-><B>ParseSchema</B>( "schema.xml" );
|
||
|
|
|
||
|
|
// Execute the SQL on the database
|
||
|
|
$result = $schema-><B>ExecuteSchema</B>( $sql );
|
||
|
|
|
||
|
|
// Finally, clean up after the XML parser
|
||
|
|
// (PHP won't do this for you!)
|
||
|
|
$schema-><B>Destroy</B>();
|
||
|
|
|
||
|
|
</PRE>
|
||
|
|
|
||
|
|
<H3>XML Schema Format:</H3>
|
||
|
|
<P>(See <a href="http://arscognita.com/xmlschema.dtd">ADOdb_schema.dtd</a> for the full specification)</P>
|
||
|
|
<PRE>
|
||
|
|
<?xml version="1.0"?>
|
||
|
|
<schema>
|
||
|
|
<table name="tablename" platform="platform1|platform2|...">
|
||
|
|
<descr>Optional description</descr>
|
||
|
|
<field name="fieldname" type="datadict_type" size="size">
|
||
|
|
<KEY/>
|
||
|
|
<NOTNULL/>
|
||
|
|
<AUTOINCREMENT/>
|
||
|
|
<DEFAULT value="value"/>
|
||
|
|
</field>
|
||
|
|
... <i>more fields</i>
|
||
|
|
</table>
|
||
|
|
... <i>more tables</i>
|
||
|
|
|
||
|
|
<index name="indexname" platform="platform1|platform2|...">
|
||
|
|
<descr>Optional description</descr>
|
||
|
|
<col>fieldname</col>
|
||
|
|
... <i>more columns</i>
|
||
|
|
</index>
|
||
|
|
... <i>more indices</i>
|
||
|
|
|
||
|
|
<sql platform="platform1|platform2|...">
|
||
|
|
<descr>Optional description</descr>
|
||
|
|
<query platform="platform1|platform2|...">SQL query</query>
|
||
|
|
... <i>more queries</i>
|
||
|
|
</sql>
|
||
|
|
... <i>more SQL</i>
|
||
|
|
</schema>
|
||
|
|
</PRE>
|
||
|
|
<HR>
|
||
|
|
|
||
|
|
<address>If you have any questions or comments, please email them to me at
|
||
|
|
<a href="mailto:richtl#arscognita.com">richtl#arscognita.com</a>.</address>
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|