diff --git a/reference/sdodasrel/functions/SDO-DAS-Relational-executePreparedQuery.xml b/reference/sdodasrel/functions/SDO-DAS-Relational-executePreparedQuery.xml new file mode 100644 index 0000000000..38175a93a6 --- /dev/null +++ b/reference/sdodasrel/functions/SDO-DAS-Relational-executePreparedQuery.xml @@ -0,0 +1,226 @@ + + + + + SDO_DAS_Relational::executePreparedQuery + + Executes an SQL query passed as a prepared statement, with a + list of values to substitute for placeholders, and return the + results as a normalised data graph. + + + + + &reftitle.description; + + SDODataObject + SDO_DAS_Relational::executePreparedQuery + + PDO + database_handle + + + PDOStatement + prepared_statement + + + array + value_list + + + array + column_specifier + + + + &warn.experimental.func; + + + Executes a given query against the relational database, + using the supplied PDO database handle. + Differs from the simpler + executeQuery + in that it takes a prepared statement and a list of values. + This is the appropriate call to use either when the statement is + to executed a number of times with different arguments, and there + is therefore a performance benefit to be had from preparing the + statement only once, or when the the SQL statement is to contain + varying values taken from a source that cannot be completely trusted. + In this latter case it may be unsafe to construct the SQL statement + by simply concatenating the parts of the statement together, + since the values may contain pieces of SQL. + To guard against this, a so-called SQL injection attack, + it is safer to prepare the SQL statement with placeholders + (also known as parameter markers, denoted by '?') and supply a + list of the values to be substituted as a separate argument. + Otherwise this function is the same as + executeQuery in that + it uses the model that it built from the the metadata + to interpret the result set and returns a data graph. + + + + + &reftitle.parameters; + + + + PDO_database_handle + + + Constructed using the PDO extension. + A typical line to construct a PDO database handle might look + like this: + + + + + + + + prepared_statement + + + A prepared SQL statement to be executed against the database. + This will have been prepared by PDO's + prepare + method. + + + + + value_list + + + An array of the values to be substituted into the + SQL stement in place of the placeholders. In the event + that there are no placeholders or parameter markers in the + SQL statement then this argument can be specified as &null; + or as an empty array; + + + + + column_specifier + + + The Relational DAS needs to examine the result set and + for every column, know which table and which column of + that table it came from. + In some circumstances it can find this information for itself, + but sometimes it cannot. + In these cases a column specifier is needed, + which is an array that identifies the columns. + Each entry in the array is simply a string in the form + table-name.column_name. + + + + + The column specifier is needed when there are duplicate + column names in the database metadata, + For example, in the database used within the examples, + all the tables have both a + id + and a + name + column. + When the Relational DAS fetches the result set from PDO + it can do so with the PDO_FETCH_ASSOC attribute, + which will cause the columns in the results set + to be labelled with the column name, but will not distinguish + duplicates. + So this will only work when there are no duplicates + possible in the results set. + + + + To summarise, specify a column specifier array whenever there + is any uncertainty about which column could be from which table and + only omit it when every column name in the database metadata is unique. + + + + All of the examples in the + Examples + use a column specifier. + There is one example in the + Scenarios + directory of the installation that does not: + that which works with just the employee table, + and because it works with just one table, + there can not exist duplicate column names. + + + + + + + + + &reftitle.returnvalues; + + Returns a data graph. + Specifically, it returns a root object of a special type. + Under this root object will be the data from the result set. + The root object will have a multi-valued containment property + with the same name as the application root type + specified on the constructor, + and that property will contain one or more data objects + of the application root type. + + + In the event that the query returns no data, + the special root object will still be returned but + the containment property for the application root type will be empty. + + + + + &reftitle.exceptions; + + SDO_DAS_Relational::executeQuery + can throw an SDO_DAS_Relational_Exception if it is unable + to construct the data graph correctly. + This can occur for a number of reasons: + for example if it finds that it does not have primary keys + in the result set for all the objects. + It also catches any PDO exceptions and obtains PDO + diagnostic information which it includes in an + SDO_DAS_Relational_Exception which it then throws. + + + + + &reftitle.examples; + + Please see the + Examples + section in the general information about the + Relational DAS for many examples of calling this method. + + + + + diff --git a/reference/sdodasrel/reference.xml b/reference/sdodasrel/reference.xml index acf2d36a43..d5dbc2274e 100644 --- a/reference/sdodasrel/reference.xml +++ b/reference/sdodasrel/reference.xml @@ -1,5 +1,5 @@ - + SDO Relational Data Access Service Functions @@ -54,7 +54,11 @@ The next step might be to call the executeQuery - method on the Relational DAS, passing an SQL statement. + or + executePreparedQuery + methods on the Relational DAS, passing either a literal SQL statement + for the DAS to prepare and execute, or a prepared statement with + placeholders and a list of values to be inserted. You may also need to specify a small amount of metadata about the query itself, so that the Relational DAS knows exactly what columns will be returned from the database and @@ -64,6 +68,8 @@ The return value from executeQuery + or + executePreparedQuery is a normalised data graph containing all the data from the result set. For a query that returns data obtained from a number of tables, this graph will contain a number of data objects, @@ -160,9 +166,11 @@ require_once 'SDO/DAS/Relational.php'; The Relational DAS uses PDO to access the relational database, and so should run with a variety of different relational databases, - but at the time of writing has only been tested with MySQL 4.1. - On Windows it operates correctly with the php_pdo_mysql driver - that comes with the pre-built binaries in PHP 5.1.0b3. + but at the time of writing has only been tested with MySQL 4.1.7 + on Windows and Linux, and DB2 8.2 Personal Edition on Windows. + On Windows it operates correctly with the php_pdo_mysql and + php_pdo_odbc drivers, for MySQL and DB2 respectively, + that come with the pre-built binaries in PHP 5.1.0b3. On Linux it is necessary to have the most up-to-date PDO driver for MySQL. It may be necessary to uninstall the usual driver that would have come from PECL (using @@ -239,16 +247,6 @@ require_once 'SDO/DAS/Relational.php'; for example. - - - No support for prepared statements or bound variables. - Although PDO allows both of these - the ability to prepare and SQL - statement once and execute it many times, perhaps picking different - arguments for the query from variables within the application - - there is no support in the current Relational DAS interface - to allow this. - - @@ -290,14 +288,31 @@ require_once 'SDO/DAS/Relational.php'; - These examples all differ from the expected use of SDO in one important - respect: they show all interactions with the database completed within + These examples all differ from the expected use of SDO in two + important respects. + + + First, they show all interactions with the database completed within one script. In this respect these scenarios are not realistic but are chosen to illustrate just the use of the Relational DAS. It is expected that interactions with the database will be separated in time and the data graph serialised and deserialised into the PHP session one or more times as the application interacts with an end user. + + Second, all queries executed against the database use hard-coded + queries with no variables substituted. In this case it is safe to + use the simple + executeQuery + call, and this is what the examples illustrate. + In practice, though,it is unlikely that the SQL statement is known + entirely ahead of time. In order to allow variables to be safely + substituted into the SQL queries, without running the risk of + injecting SQL with unknown effects, it is safer to use the + executePreparedQuery + which takes a prepared SQL statement containing placeholders + and a list of values to be substituted. +
Specifying the metadata @@ -408,7 +423,7 @@ $database_metadata = array($company_table, $department_table, $employee_table); This metadata corresponds to a relational database that might have - been defined to MySQL as follows. + been defined to MySQL as: + + or to DB2 as: + + + + + Note that although in this example there are no foreign keys specified to the database and so the database is not expected to enforce @@ -717,7 +759,7 @@ $acme->name = "Acme"; /************************************************************** * Get a database connection and write the object to the database ***************************************************************/ -$dbh = new PDO("mysql:dbname=COMPANYDB;host=localhost",DATABASE_USER,DATABASE_PASSWORD); +$dbh = new PDO(PDO_DSN,DATABASE_USER,DATABASE_PASSWORD); $das -> applyChanges($dbh, $root); ?> ]]> @@ -761,7 +803,7 @@ $das = new SDO_DAS_Relational ($database_metadata,'company',$SDO_reference_metad /************************************************************** * Get a database connection ***************************************************************/ -$dbh = new PDO("mysql:dbname=COMPANYDB;host=localhost",DATABASE_USER,DATABASE_PASSWORD); +$dbh = new PDO(PDO_DSN,DATABASE_USER,DATABASE_PASSWORD); /************************************************************** * Issue a query to obtain a company object - possibly more if they exist @@ -820,7 +862,7 @@ $das = new SDO_DAS_Relational ($database_metadata,'company',$SDO_reference_metad /************************************************************** * Get a database connection ***************************************************************/ -$dbh = new PDO("mysql:dbname=COMPANYDB;host=localhost",DATABASE_USER,DATABASE_PASSWORD); +$dbh = new PDO(PDO_DSN,DATABASE_USER,DATABASE_PASSWORD); /************************************************************** * Issue a query to obtain a company object - possibly more if they exist @@ -872,7 +914,7 @@ $das = new SDO_DAS_Relational ($database_metadata,'company',$SDO_reference_metad /************************************************************** * Get a database connection ***************************************************************/ -$dbh = new PDO("mysql:dbname=COMPANYDB;host=localhost",DATABASE_USER,DATABASE_PASSWORD); +$dbh = new PDO(PDO_DSN,DATABASE_USER,DATABASE_PASSWORD); /************************************************************** * Issue a query to obtain a company object - possibly more if they exist @@ -958,7 +1000,7 @@ require_once 'company_metadata.inc.php'; /************************************************************************************* * Empty out the two tables *************************************************************************************/ -$dbh = new PDO("mysql:dbname=COMPANYDB;host=localhost",DATABASE_USER,DATABASE_PASSWORD); +$dbh = new PDO(PDO_DSN,DATABASE_USER,DATABASE_PASSWORD); $pdo_stmt = $dbh->prepare('DELETE FROM COMPANY;'); $rows_affected = $pdo_stmt->execute(); $pdo_stmt = $dbh->prepare('DELETE FROM DEPARTMENT;'); @@ -967,7 +1009,7 @@ $rows_affected = $pdo_stmt->execute(); /************************************************************** * Create a company with name Acme and one department, the Shoe department ***************************************************************/ -$dbh = new PDO("mysql:dbname=COMPANYDB;host=localhost",DATABASE_USER,DATABASE_PASSWORD); +$dbh = new PDO(PDO_DSN,DATABASE_USER,DATABASE_PASSWORD); $das = new SDO_DAS_Relational ($database_metadata,'company',$SDO_reference_metadata); $root = $das -> createRootDataObject(); @@ -1042,7 +1084,7 @@ require_once 'company_metadata.inc.php'; /************************************************************** * Retrieve the company and Shoe department, then delete Shoe and add IT ***************************************************************/ -$dbh = new PDO("mysql:dbname=COMPANYDB;host=localhost",DATABASE_USER,DATABASE_PASSWORD); +$dbh = new PDO(PDO_DSN,DATABASE_USER,DATABASE_PASSWORD); $das = new SDO_DAS_Relational ($database_metadata,'company',$SDO_reference_metadata); $root = $das->executeQuery($dbh, @@ -1109,7 +1151,7 @@ require_once 'company_metadata.inc.php'; /************************************************************** * Retrieve the company and IT department, then delete the whole company ***************************************************************/ -$dbh = new PDO("mysql:dbname=COMPANYDB;host=localhost",DATABASE_USER,DATABASE_PASSWORD); +$dbh = new PDO(PDO_DSN,DATABASE_USER,DATABASE_PASSWORD); $das = new SDO_DAS_Relational ($database_metadata,'company',$SDO_reference_metadata); $root = $das->executeQuery($dbh, @@ -1195,7 +1237,7 @@ require_once 'company_metadata.inc.php'; /************************************************************************************* * Empty out the three tables *************************************************************************************/ -$dbh = new PDO("mysql:dbname=COMPANYDB;host=localhost",DATABASE_USER,DATABASE_PASSWORD); +$dbh = new PDO(PDO_DSN,DATABASE_USER,DATABASE_PASSWORD); $pdo_stmt = $dbh->prepare('DELETE FROM COMPANY;'); $rows_affected = $pdo_stmt->execute(); $pdo_stmt = $dbh->prepare('DELETE FROM DEPARTMENT;'); @@ -1211,7 +1253,7 @@ $rows_affected = $pdo_stmt->execute(); * The employee of the month is Sue. *************************************************************************************/ $das = new SDO_DAS_Relational ($database_metadata,'company',$SDO_reference_metadata); -$dbh = new PDO("mysql:dbname=COMPANYDB;host=localhost",DATABASE_USER,DATABASE_PASSWORD); +$dbh = new PDO(PDO_DSN,DATABASE_USER,DATABASE_PASSWORD); $root = $das -> createRootDataObject(); $acme = $root -> createDataObject('company'); @@ -1260,13 +1302,12 @@ require_once 'company_metadata.inc.php'; * Change the employee of the month. *************************************************************************************/ $das = new SDO_DAS_Relational ($database_metadata,'company',$SDO_reference_metadata); -$dbh = new PDO("mysql:dbname=COMPANYDB;host=localhost",DATABASE_USER,DATABASE_PASSWORD); +$dbh = new PDO(PDO_DSN,DATABASE_USER,DATABASE_PASSWORD); -$name = 'Acme'; $root = $das->executeQuery($dbh, - 'select c.id, c.name, c.employee_of_the_month, d.id, d.name, e.id, e.name ' . - 'from company c, department d, employee e ' . - 'where e.dept_id = d.id and d.co_id = c.id and c.name="' . $name . '";', + "select c.id, c.name, c.employee_of_the_month, d.id, d.name, e.id, e.name " . + "from company c, department d, employee e " . + "where e.dept_id = d.id and d.co_id = c.id and c.name='Acme'", array('company.id','company.name','company.employee_of_the_month', 'department.id','department.name','employee.id','employee.name')); $acme = $root['company'][0]; @@ -1320,13 +1361,12 @@ require_once 'company_metadata.inc.php'; * reassigning. For safety here we delete the company all in one go. *************************************************************************************/ $das = new SDO_DAS_Relational ($database_metadata,'company',$SDO_reference_metadata); -$dbh = new PDO("mysql:dbname=COMPANYDB;host=localhost",DATABASE_USER,DATABASE_PASSWORD); +$dbh = new PDO(PDO_DSN,DATABASE_USER,DATABASE_PASSWORD); -$name='MegaCorp'; $root = $das->executeQuery($dbh, - 'select c.id, c.name, c.employee_of_the_month, d.id, d.name, e.id, e.name ' . - 'from company c, department d, employee e ' . - 'where e.dept_id = d.id and d.co_id = c.id and c.name="' . $name . '";', + "select c.id, c.name, c.employee_of_the_month, d.id, d.name, e.id, e.name " . + "from company c, department d, employee e " . + "where e.dept_id = d.id and d.co_id = c.id and c.name='MegaCorp';", array('company.id','company.name','company.employee_of_the_month', 'department.id','department.name','employee.id','employee.name')); $megacorp = $root['company'][0]; @@ -1414,8 +1454,18 @@ echo "Deleted the company, departments and employees all in one go.\n"; executeQuery - - execute a passed SQL query against the database and return the - results as a normalised data graph + - execute an SQL query passed as a literal string and return + the results as a normalised data graph + + + + + + executePreparedQuery + + - execute an SQL query passed as a prepared statement, with a + list of values to substitute for placeholders, and return the + results as a normalised data graph