adodb-xmlschema

Written by Richard Tango-Lowy.

For more information, contact richtl@arscognita.com or visit our site at www.arscognita.com.

To report bugs or enhancements, or to download the latest version, visit the adodb-xmlschema Sourceforge Project Page.

Introduction

adodb-xmlschema is a class that allows the user to quickly and easily build a database using the excellent ADODB database library and a simple XML formatted file.

This library is dual-licensed under a BSD-style license and under the GNU Lesser Public License. See the LICENSE file for more information.

New for this release:

20031001 Snapshot

• upgradeSchema() now drops and recreates any indexes that exist in the schema file.
• It is now possible to drop a table or index by inserting a tag:

  		<table name="oldtable"><DROP/></table> or
  		<index name="oldindex"><DROP/></index>
  

20030924 Snapshot

• The upgrade code actually works. To upgrade an existing database to the provided schema, call the upgradeSchema method after creating the adoSchema object:

  		$schema = new adoSchema( 'dbname' );
  		$schema->upgradeSchema();
  		

  The upgrade and forceReplace arguments in the adoSchema call have been deprecated in favor of the new upgradeSchema method.

  The upgrade code has not yet been thoroughly tested, so use it at your own risk and kindly report the bugs!

Features

• Darned easy to install
• Quickly to create schemas that build on any platform supported by ADODB.

Installation

To install adodb-xmlschema, simply copy the adodb-xmlschema.inc.php file into your ADODB directory.

Documentation

See the online documentation in the docs directory.

Quick Start

First, create an XML database schema. Let's call it "schema.xml:"

<?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>

Create a new database using the appropriate tool for your platform. Executing the following PHP code will create the a mytable and myindex in the database and insert one row into mytable if the platform is postgres or mysql.

				
// 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 = new adoSchema( $db );

// Optionally, set a prefix for newly-created tables. In this example
// the prefix "myprefix_" will result in a table named "myprefix_tablename".
//$schema->setPrefix( "myprefix_" );
	
// Build the SQL array
$sql = $schema->ParseSchema( "schema.xml" );

// Execute the SQL on the database
$result = $schema->ExecuteSchema( $sql );

// Finally, clean up after the XML parser
// (PHP won't do this for you!)
$schema->Destroy();

XML Schema Format:

(See ADOdb_schema.dtd for the full specification)

<?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>
	... more fields
  </table>
  ... more tables
  
  <index name="indexname" platform="platform1|platform2|...">
    <descr>Optional description</descr>
    <col>fieldname</col>
    ... more columns
  </index>
  ... more indices
  
  <sql platform="platform1|platform2|...">
    <descr>Optional description</descr>
    <query platform="platform1|platform2|...">SQL query</query>
    ... more queries
  </sql>
  ... more SQL
  </schema>

Thanks

Thanks to John Lim for giving us ADODB, and for the hard work that keeps it on top of things. And particulary for the datadict code that made xmlschema possible.

And to Mike Benoit (http://phpgacl.sourceforge.net) for a recent patch or two and some good ideas.

And to the kind folks at PHP Documentor. Cool tool.

And to Linus. I thought the end of Amiga was the end of computing. Guess I was wrong :-)

$Id: default.html,v 1.2 2003/10/01 18:32:36 richtl Exp $