v5:dictionary:xmlschema
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision | ||
dictionary:xmlschema [2015/12/23 16:10] – mnewnham | v5:dictionary:xmlschema [2016/01/13 02:06] – ↷ Links adapted because of a move operation mnewnham | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | ======= ADOdb-xmlschema ====== | ||
+ | ~~NOTOC~~ | ||
+ | <WRAP right box round 300px> | ||
+ | ==See also== | ||
+ | [[axmls: | ||
+ | [[v5: | ||
+ | </ | ||
+ | |||
+ | ===== Introduction ===== | ||
+ | |||
+ | Adodb-xmlschema, | ||
+ | |||
+ | * An XML file contains all of the definitions required to create a table, the associated columns, indexes and constraints. | ||
+ | * The table can be created by processing the XML file with the [[axmls: | ||
+ | * That XML file can be used **unmodified** against any database supported by ADOdb. | ||
+ | * Any modifications to the table can be enabled by simply modifying the XML file, and re-executing the XML load command. The ADOdb Meta Functions take care of any processing required to apply those changes to the table. | ||
+ | * In limited circumstances, | ||
+ | |||
+ | |||
+ | ------------------------------ | ||
+ | |||
+ | <WRAP right box 200px> | ||
+ | == Original Author Credit == | ||
+ | Richard Tango-Lowy | ||
+ | Dan Cech | ||
+ | </ | ||
+ | ===== Installation ===== | ||
+ | This feature is included in the standard release | ||
+ | ===== Using AXMLS in Your Application ===== | ||
+ | There are two steps involved in using AXMLS in your application: | ||
+ | |||
+ | ==== A Basic Schema Definition ==== | ||
+ | Let's begin with a schema that describes a typical, if simplistic user management table for an application. | ||
+ | |||
+ | <code xml> | ||
+ | <?xml version=" | ||
+ | <schema version=" | ||
+ | |||
+ | <table name=" | ||
+ | < | ||
+ | <field name=" | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | | ||
+ | <field name=" | ||
+ | | ||
+ | <index name=" | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | </ | ||
+ | | ||
+ | <sql> | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | Let's take a detailed look at this schema. The opening ''<? | ||
+ | |||
+ | <code xml> | ||
+ | <?xml version=" | ||
+ | <schema version=" | ||
+ | ... | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | Next we define one or more tables. A table consists of a fields (and other objects) enclosed by ''< | ||
+ | |||
+ | <code xml> | ||
+ | <table name=" | ||
+ | |||
+ | < | ||
+ | <field name=" | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | | ||
+ | <field name=" | ||
+ | | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | This table is called " | ||
+ | |||
+ | * The description is optional, and is currently | ||
+ | * The first < | ||
+ | * The second < | ||
+ | |||
+ | ==== Adding Indexes ==== | ||
+ | |||
+ | There are two ways to add indexes to a table. The simplest is to mark a field with the < | ||
+ | |||
+ | <code xml> | ||
+ | <table name=" | ||
+ | ... | ||
+ | | ||
+ | <index name=" | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | | ||
+ | </ | ||
+ | </ | ||
+ | The < | ||
+ | |||
+ | ==== Arbitrary SQL Execution ==== | ||
+ | |||
+ | Finally, AXMLS allows you to include arbitrary SQL that will be applied to the database when the schema is executed. | ||
+ | |||
+ | <code xml> | ||
+ | <sql> | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | The <sql> tag encloses any number of SQL queries that you define for your own use. | ||
+ | |||
+ | ===== Executing A Script ===== | ||
+ | |||
+ | 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. | ||
+ | |||
+ | <code php> | ||
+ | /* You must tell the script where to find the ADOdb and | ||
+ | * the AXMLS libraries. | ||
+ | */ | ||
+ | require " | ||
+ | require " | ||
+ | |||
+ | /* Configuration information. Define the schema filename, | ||
+ | * RDBMS platform (see the ADODB documentation for valid | ||
+ | * platform names), and database connection information here. | ||
+ | */ | ||
+ | $schemaFile = ' | ||
+ | $platform = ' | ||
+ | $dbHost = ' | ||
+ | $dbName = ' | ||
+ | $dbUser = ' | ||
+ | $dbPassword = ' | ||
+ | |||
+ | /* Start by creating a normal ADODB connection. | ||
+ | */ | ||
+ | $db = ADONewConnection( $platform ); | ||
+ | $db-> | ||
+ | |||
+ | /* Use the database connection to create a new adoSchema object. | ||
+ | */ | ||
+ | $schema = new adoSchema( $db ); | ||
+ | |||
+ | /* Call ParseSchema() to build SQL from the XML schema file. | ||
+ | * Then call ExecuteSchema() to apply the resulting SQL to | ||
+ | * the database. | ||
+ | */ | ||
+ | $sql = $schema-> | ||
+ | $result = $schema-> | ||
+ | </ | ||
+ | |||
+ | 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. First, create a normal ADOdb connection. The variables and values here should be those required to connect to your database. | ||
+ | |||
+ | <code php> | ||
+ | $db = ADONewConnection( ' | ||
+ | $db-> | ||
+ | </ | ||
+ | |||
+ | 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. | ||
+ | |||
+ | <code php> | ||
+ | $schema = new adoSchema( $db ); | ||
+ | </ | ||
+ | |||
+ | Third, call ParseSchema() to parse the schema and then '' | ||
+ | |||
+ | <code php> | ||
+ | $schema-> | ||
+ | $schema-> | ||
+ | </ | ||
+ | |||
+ | 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. | ||
+ | |||
+ | You can find the source files for this tutorial in the '' | ||
+ | |||
+ | ===== Using AXMLS ===== | ||
+ | AXMLS consists of two parts: the **schema description**, | ||
+ | ==== Executing the Schema ==== | ||
+ | AXMLS provides two different methods for applying the SQL resulting from a parsed schema to the database: **inline execution** and **post execution**. Use the [[axmls: | ||
+ | |||
+ | **Inline Execution** applies each schema entity to the database immediately after that entity is parsed. I.e., the first table is read from the schema and applied to the database, then the second table, etc. | ||
+ | |||
+ | <code php> | ||
+ | $schema = new adoSchema( $this-> | ||
+ | |||
+ | // Inline Execution | ||
+ | $schema-> | ||
+ | $schema-> | ||
+ | $schema-> | ||
+ | </ | ||
+ | |||
+ | **Post Execution** parses the entire database and then applies all of the resulting SQL statements to the database in order. | ||
+ | |||
+ | <code php> | ||
+ | $schema = new adoSchema( $this-> | ||
+ | |||
+ | // Post Execution (default) | ||
+ | $schema-> | ||
+ | $schema-> | ||
+ | $schema-> | ||
+ | </ | ||
+ | |||
+ | If successful, either method will build or upgrade the database. | ||
+ | ==== Upgrading an Existing Database ==== | ||
+ | Upgrading a database is as simple as creating one. To upgrade an existing database to a new version of a schema, simply parse and execute the schema as above. AXMLS will automatically upgrade all tables and indices to match those provided in the schema. | ||
+ | ==== Object Prefixing==== | ||
+ | In a world of pluggable and reusable code, multiple applications often coexist in a single database. Object prefixes allow you to create a namespace for your application. For example, an application called Tackle might want to prefix all its tables and objects with **tackle_** so they' | ||
+ | |||
+ | <code php> | ||
+ | $schema = new adoSchema( $this-> | ||
+ | |||
+ | // Set the prefix for database objects (before parsing) | ||
+ | $schema-> | ||
+ | </ | ||
+ | ==== Getting at the SQL ==== | ||
+ | |||
+ | AXMLS provides several tools for accessing the SQL created by the schema parser. Calling [[axmls: | ||
+ | |||
+ | <code php> | ||
+ | $schema-> | ||
+ | $schema-> | ||
+ | |||
+ | print( $schema-> | ||
+ | print( $schema-> | ||
+ | $sql = $schema-> | ||
+ | |||
+ | // Save SQL to file | ||
+ | $schema-> | ||
+ | </ | ||
+ | As always, see the Class Documentation for detailed information about the methods. | ||
+ | |||
+ | |||
+ | |||
v5/dictionary/xmlschema.txt · Last modified: 2018/06/11 10:05 by dregad