Mercurial > defr > drupal > core

annotate includes/database.inc @ 13:8b6c45761e01 6.6

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Drupal 6.6
author Franck Deroche <webmaster@defr.org>
date Tue, 23 Dec 2008 14:32:33 +0100
parents fff6d4c8c043
children
rev   line source
webmaster@1 1 <?php
webmaster@13 2 // $Id: database.inc,v 1.92.2.3 2008/10/20 09:13:04 goba Exp $
webmaster@1 3
webmaster@1 4 /**
webmaster@1 5 * @file
webmaster@1 6 * Wrapper for database interface code.
webmaster@1 7 */
webmaster@1 8
webmaster@1 9 /**
webmaster@1 10 * A hash value to check when outputting database errors, md5('DB_ERROR').
webmaster@1 11 *
webmaster@1 12 * @see drupal_error_handler()
webmaster@1 13 */
webmaster@1 14 define('DB_ERROR', 'a515ac9c2796ca0e23adbe92c68fc9fc');
webmaster@1 15
webmaster@1 16 /**
webmaster@1 17 * @defgroup database Database abstraction layer
webmaster@1 18 * @{
webmaster@1 19 * Allow the use of different database servers using the same code base.
webmaster@1 20 *
webmaster@1 21 * Drupal provides a slim database abstraction layer to provide developers with
webmaster@1 22 * the ability to support multiple database servers easily. The intent of this
webmaster@1 23 * layer is to preserve the syntax and power of SQL as much as possible, while
webmaster@1 24 * letting Drupal control the pieces of queries that need to be written
webmaster@1 25 * differently for different servers and provide basic security checks.
webmaster@1 26 *
webmaster@1 27 * Most Drupal database queries are performed by a call to db_query() or
webmaster@1 28 * db_query_range(). Module authors should also consider using pager_query() for
webmaster@1 29 * queries that return results that need to be presented on multiple pages, and
webmaster@1 30 * tablesort_sql() for generating appropriate queries for sortable tables.
webmaster@1 31 *
webmaster@1 32 * For example, one might wish to return a list of the most recent 10 nodes
webmaster@1 33 * authored by a given user. Instead of directly issuing the SQL query
webmaster@1 34 * @code
webmaster@1 35 * SELECT n.title, n.body, n.created FROM node n WHERE n.uid = $uid LIMIT 0, 10;
webmaster@1 36 * @endcode
webmaster@1 37 * one would instead call the Drupal functions:
webmaster@1 38 * @code
webmaster@1 39 * $result = db_query_range('SELECT n.title, n.body, n.created
webmaster@1 40 * FROM {node} n WHERE n.uid = %d', $uid, 0, 10);
webmaster@1 41 * while ($node = db_fetch_object($result)) {
webmaster@1 42 * // Perform operations on $node->body, etc. here.
webmaster@1 43 * }
webmaster@1 44 * @endcode
webmaster@1 45 * Curly braces are used around "node" to provide table prefixing via
webmaster@1 46 * db_prefix_tables(). The explicit use of a user ID is pulled out into an
webmaster@1 47 * argument passed to db_query() so that SQL injection attacks from user input
webmaster@1 48 * can be caught and nullified. The LIMIT syntax varies between database servers,
webmaster@1 49 * so that is abstracted into db_query_range() arguments. Finally, note the
webmaster@1 50 * common pattern of iterating over the result set using db_fetch_object().
webmaster@1 51 */
webmaster@1 52
webmaster@1 53 /**
webmaster@1 54 * Perform an SQL query and return success or failure.
webmaster@1 55 *
webmaster@1 56 * @param $sql
webmaster@1 57 * A string containing a complete SQL query. %-substitution
webmaster@1 58 * parameters are not supported.
webmaster@1 59 * @return
webmaster@1 60 * An array containing the keys:
webmaster@1 61 * success: a boolean indicating whether the query succeeded
webmaster@1 62 * query: the SQL query executed, passed through check_plain()
webmaster@1 63 */
webmaster@1 64 function update_sql($sql) {
webmaster@1 65 $result = db_query($sql, true);
webmaster@1 66 return array('success' => $result !== FALSE, 'query' => check_plain($sql));
webmaster@1 67 }
webmaster@1 68
webmaster@1 69 /**
webmaster@1 70 * Append a database prefix to all tables in a query.
webmaster@1 71 *
webmaster@1 72 * Queries sent to Drupal should wrap all table names in curly brackets. This
webmaster@1 73 * function searches for this syntax and adds Drupal's table prefix to all
webmaster@1 74 * tables, allowing Drupal to coexist with other systems in the same database if
webmaster@1 75 * necessary.
webmaster@1 76 *
webmaster@1 77 * @param $sql
webmaster@1 78 * A string containing a partial or entire SQL query.
webmaster@1 79 * @return
webmaster@1 80 * The properly-prefixed string.
webmaster@1 81 */
webmaster@1 82 function db_prefix_tables($sql) {
webmaster@1 83 global $db_prefix;
webmaster@1 84
webmaster@1 85 if (is_array($db_prefix)) {
webmaster@1 86 if (array_key_exists('default', $db_prefix)) {
webmaster@1 87 $tmp = $db_prefix;
webmaster@1 88 unset($tmp['default']);
webmaster@1 89 foreach ($tmp as $key => $val) {
webmaster@1 90 $sql = strtr($sql, array('{'. $key .'}' => $val . $key));
webmaster@1 91 }
webmaster@1 92 return strtr($sql, array('{' => $db_prefix['default'], '}' => ''));
webmaster@1 93 }
webmaster@1 94 else {
webmaster@1 95 foreach ($db_prefix as $key => $val) {
webmaster@1 96 $sql = strtr($sql, array('{'. $key .'}' => $val . $key));
webmaster@1 97 }
webmaster@1 98 return strtr($sql, array('{' => '', '}' => ''));
webmaster@1 99 }
webmaster@1 100 }
webmaster@1 101 else {
webmaster@1 102 return strtr($sql, array('{' => $db_prefix, '}' => ''));
webmaster@1 103 }
webmaster@1 104 }
webmaster@1 105
webmaster@1 106 /**
webmaster@1 107 * Activate a database for future queries.
webmaster@1 108 *
webmaster@1 109 * If it is necessary to use external databases in a project, this function can
webmaster@1 110 * be used to change where database queries are sent. If the database has not
webmaster@1 111 * yet been used, it is initialized using the URL specified for that name in
webmaster@1 112 * Drupal's configuration file. If this name is not defined, a duplicate of the
webmaster@1 113 * default connection is made instead.
webmaster@1 114 *
webmaster@1 115 * Be sure to change the connection back to the default when done with custom
webmaster@1 116 * code.
webmaster@1 117 *
webmaster@1 118 * @param $name
webmaster@1 119 * The name assigned to the newly active database connection. If omitted, the
webmaster@1 120 * default connection will be made active.
webmaster@1 121 *
webmaster@1 122 * @return the name of the previously active database or FALSE if non was found.
webmaster@1 123 */
webmaster@1 124 function db_set_active($name = 'default') {
webmaster@1 125 global $db_url, $db_type, $active_db;
webmaster@1 126 static $db_conns, $active_name = FALSE;
webmaster@1 127
webmaster@1 128 if (empty($db_url)) {
webmaster@1 129 include_once 'includes/install.inc';
webmaster@1 130 install_goto('install.php');
webmaster@1 131 }
webmaster@1 132
webmaster@1 133 if (!isset($db_conns[$name])) {
webmaster@1 134 // Initiate a new connection, using the named DB URL specified.
webmaster@1 135 if (is_array($db_url)) {
webmaster@1 136 $connect_url = array_key_exists($name, $db_url) ? $db_url[$name] : $db_url['default'];
webmaster@1 137 }
webmaster@1 138 else {
webmaster@1 139 $connect_url = $db_url;
webmaster@1 140 }
webmaster@1 141
webmaster@1 142 $db_type = substr($connect_url, 0, strpos($connect_url, '://'));
webmaster@1 143 $handler = "./includes/database.$db_type.inc";
webmaster@1 144
webmaster@1 145 if (is_file($handler)) {
webmaster@1 146 include_once $handler;
webmaster@1 147 }
webmaster@1 148 else {
webmaster@1 149 _db_error_page("The database type '". $db_type ."' is unsupported. Please use either 'mysql' or 'mysqli' for MySQL, or 'pgsql' for PostgreSQL databases.");
webmaster@1 150 }
webmaster@1 151
webmaster@1 152 $db_conns[$name] = db_connect($connect_url);
webmaster@1 153 }
webmaster@1 154
webmaster@1 155 $previous_name = $active_name;
webmaster@1 156 // Set the active connection.
webmaster@1 157 $active_name = $name;
webmaster@1 158 $active_db = $db_conns[$name];
webmaster@1 159
webmaster@1 160 return $previous_name;
webmaster@1 161 }
webmaster@1 162
webmaster@1 163 /**
webmaster@1 164 * Helper function to show fatal database errors.
webmaster@1 165 *
webmaster@1 166 * Prints a themed maintenance page with the 'Site off-line' text,
webmaster@1 167 * adding the provided error message in the case of 'display_errors'
webmaster@1 168 * set to on. Ends the page request; no return.
webmaster@1 169 *
webmaster@1 170 * @param $error
webmaster@1 171 * The error message to be appended if 'display_errors' is on.
webmaster@1 172 */
webmaster@1 173 function _db_error_page($error = '') {
webmaster@1 174 global $db_type;
webmaster@13 175 drupal_init_language();
webmaster@1 176 drupal_maintenance_theme();
webmaster@1 177 drupal_set_header('HTTP/1.1 503 Service Unavailable');
webmaster@1 178 drupal_set_title('Site off-line');
webmaster@1 179
webmaster@1 180 $message = '<p>The site is currently not available due to technical problems. Please try again later. Thank you for your understanding.</p>';
webmaster@1 181 $message .= '<hr /><p><small>If you are the maintainer of this site, please check your database settings in the <code>settings.php</code> file and ensure that your hosting provider\'s database server is running. For more help, see the <a href="http://drupal.org/node/258">handbook</a>, or contact your hosting provider.</small></p>';
webmaster@1 182
webmaster@1 183 if ($error && ini_get('display_errors')) {
webmaster@1 184 $message .= '<p><small>The '. theme('placeholder', $db_type) .' error was: '. theme('placeholder', $error) .'.</small></p>';
webmaster@1 185 }
webmaster@1 186
webmaster@1 187 print theme('maintenance_page', $message);
webmaster@1 188 exit;
webmaster@1 189 }
webmaster@1 190
webmaster@1 191 /**
webmaster@1 192 * Returns a boolean depending on the availability of the database.
webmaster@1 193 */
webmaster@1 194 function db_is_active() {
webmaster@1 195 global $active_db;
webmaster@1 196 return !empty($active_db);
webmaster@1 197 }
webmaster@1 198
webmaster@1 199 /**
webmaster@1 200 * Helper function for db_query().
webmaster@1 201 */
webmaster@1 202 function _db_query_callback($match, $init = FALSE) {
webmaster@1 203 static $args = NULL;
webmaster@1 204 if ($init) {
webmaster@1 205 $args = $match;
webmaster@1 206 return;
webmaster@1 207 }
webmaster@1 208
webmaster@1 209 switch ($match[1]) {
webmaster@1 210 case '%d': // We must use type casting to int to convert FALSE/NULL/(TRUE?)
webmaster@1 211 return (int) array_shift($args); // We don't need db_escape_string as numbers are db-safe
webmaster@1 212 case '%s':
webmaster@1 213 return db_escape_string(array_shift($args));
webmaster@7 214 case '%n':
webmaster@7 215 // Numeric values have arbitrary precision, so can't be treated as float.
webmaster@7 216 // is_numeric() allows hex values (0xFF), but they are not valid.
webmaster@7 217 $value = trim(array_shift($args));
webmaster@7 218 return is_numeric($value) && !preg_match('/x/i', $value) ? $value : '0';
webmaster@1 219 case '%%':
webmaster@1 220 return '%';
webmaster@1 221 case '%f':
webmaster@1 222 return (float) array_shift($args);
webmaster@1 223 case '%b': // binary data
webmaster@1 224 return db_encode_blob(array_shift($args));
webmaster@1 225 }
webmaster@1 226 }
webmaster@1 227
webmaster@1 228 /**
webmaster@1 229 * Generate placeholders for an array of query arguments of a single type.
webmaster@1 230 *
webmaster@1 231 * Given a Schema API field type, return correct %-placeholders to
webmaster@1 232 * embed in a query
webmaster@1 233 *
webmaster@1 234 * @param $arguments
webmaster@1 235 * An array with at least one element.
webmaster@1 236 * @param $type
webmaster@1 237 * The Schema API type of a field (e.g. 'int', 'text', or 'varchar').
webmaster@1 238 */
webmaster@1 239 function db_placeholders($arguments, $type = 'int') {
webmaster@1 240 $placeholder = db_type_placeholder($type);
webmaster@1 241 return implode(',', array_fill(0, count($arguments), $placeholder));
webmaster@1 242 }
webmaster@1 243
webmaster@1 244 /**
webmaster@1 245 * Indicates the place holders that should be replaced in _db_query_callback().
webmaster@1 246 */
webmaster@7 247 define('DB_QUERY_REGEXP', '/(%d|%s|%%|%f|%b|%n)/');
webmaster@1 248
webmaster@1 249 /**
webmaster@1 250 * Helper function for db_rewrite_sql.
webmaster@1 251 *
webmaster@1 252 * Collects JOIN and WHERE statements via hook_db_rewrite_sql()
webmaster@1 253 * Decides whether to select primary_key or DISTINCT(primary_key)
webmaster@1 254 *
webmaster@1 255 * @param $query
webmaster@1 256 * Query to be rewritten.
webmaster@1 257 * @param $primary_table
webmaster@1 258 * Name or alias of the table which has the primary key field for this query.
webmaster@1 259 * Typical table names would be: {blocks}, {comments}, {forum}, {node},
webmaster@1 260 * {menu}, {term_data} or {vocabulary}. However, in most cases the usual
webmaster@1 261 * table alias (b, c, f, n, m, t or v) is used instead of the table name.
webmaster@1 262 * @param $primary_field
webmaster@1 263 * Name of the primary field.
webmaster@1 264 * @param $args
webmaster@1 265 * Array of additional arguments.
webmaster@1 266 * @return
webmaster@1 267 * An array: join statements, where statements, field or DISTINCT(field).
webmaster@1 268 */
webmaster@1 269 function _db_rewrite_sql($query = '', $primary_table = 'n', $primary_field = 'nid', $args = array()) {
webmaster@1 270 $where = array();
webmaster@1 271 $join = array();
webmaster@1 272 $distinct = FALSE;
webmaster@1 273 foreach (module_implements('db_rewrite_sql') as $module) {
webmaster@1 274 $result = module_invoke($module, 'db_rewrite_sql', $query, $primary_table, $primary_field, $args);
webmaster@1 275 if (isset($result) && is_array($result)) {
webmaster@1 276 if (isset($result['where'])) {
webmaster@1 277 $where[] = $result['where'];
webmaster@1 278 }
webmaster@1 279 if (isset($result['join'])) {
webmaster@1 280 $join[] = $result['join'];
webmaster@1 281 }
webmaster@1 282 if (isset($result['distinct']) && $result['distinct']) {
webmaster@1 283 $distinct = TRUE;
webmaster@1 284 }
webmaster@1 285 }
webmaster@1 286 elseif (isset($result)) {
webmaster@1 287 $where[] = $result;
webmaster@1 288 }
webmaster@1 289 }
webmaster@1 290
webmaster@1 291 $where = empty($where) ? '' : '('. implode(') AND (', $where) .')';
webmaster@1 292 $join = empty($join) ? '' : implode(' ', $join);
webmaster@1 293
webmaster@1 294 return array($join, $where, $distinct);
webmaster@1 295 }
webmaster@1 296
webmaster@1 297 /**
webmaster@1 298 * Rewrites node, taxonomy and comment queries. Use it for listing queries. Do not
webmaster@1 299 * use FROM table1, table2 syntax, use JOIN instead.
webmaster@1 300 *
webmaster@1 301 * @param $query
webmaster@1 302 * Query to be rewritten.
webmaster@1 303 * @param $primary_table
webmaster@1 304 * Name or alias of the table which has the primary key field for this query.
webmaster@1 305 * Typical table names would be: {blocks}, {comments}, {forum}, {node},
webmaster@1 306 * {menu}, {term_data} or {vocabulary}. However, it is more common to use the
webmaster@1 307 * the usual table aliases: b, c, f, n, m, t or v.
webmaster@1 308 * @param $primary_field
webmaster@1 309 * Name of the primary field.
webmaster@1 310 * @param $args
webmaster@1 311 * An array of arguments, passed to the implementations of hook_db_rewrite_sql.
webmaster@1 312 * @return
webmaster@1 313 * The original query with JOIN and WHERE statements inserted from
webmaster@1 314 * hook_db_rewrite_sql implementations. nid is rewritten if needed.
webmaster@1 315 */
webmaster@1 316 function db_rewrite_sql($query, $primary_table = 'n', $primary_field = 'nid', $args = array()) {
webmaster@1 317 list($join, $where, $distinct) = _db_rewrite_sql($query, $primary_table, $primary_field, $args);
webmaster@1 318
webmaster@1 319 if ($distinct) {
webmaster@1 320 $query = db_distinct_field($primary_table, $primary_field, $query);
webmaster@1 321 }
webmaster@1 322
webmaster@1 323 if (!empty($where) || !empty($join)) {
webmaster@1 324 $pattern = '{
webmaster@1 325 # Beginning of the string
webmaster@1 326 ^
webmaster@1 327 ((?P<anonymous_view>
webmaster@1 328 # Everything within this set of parentheses is named "anonymous view"
webmaster@1 329 (?:
webmaster@1 330 [^()]++ # anything not parentheses
webmaster@1 331 |
webmaster@1 332 \( (?P>anonymous_view) \) # an open parenthesis, more "anonymous view" and finally a close parenthesis.
webmaster@1 333 )*
webmaster@1 334 )[^()]+WHERE)
webmaster@1 335 }x';
webmaster@1 336 preg_match($pattern, $query, $matches);
webmaster@1 337 if (!$where) {
webmaster@1 338 $where = '1 = 1';
webmaster@1 339 }
webmaster@1 340 if ($matches) {
webmaster@1 341 $n = strlen($matches[1]);
webmaster@1 342 $second_part = substr($query, $n);
webmaster@1 343 $first_part = substr($matches[1], 0, $n - 5) ." $join WHERE $where AND ( ";
webmaster@1 344 // PHP 4 does not support strrpos for strings. We emulate it.
webmaster@1 345 $haystack_reverse = strrev($second_part);
webmaster@1 346 }
webmaster@1 347 else {
webmaster@1 348 $haystack_reverse = strrev($query);
webmaster@1 349 }
webmaster@1 350 // No need to use strrev on the needle, we supply GROUP, ORDER, LIMIT
webmaster@1 351 // reversed.
webmaster@1 352 foreach (array('PUORG', 'REDRO', 'TIMIL') as $needle_reverse) {
webmaster@1 353 $pos = strpos($haystack_reverse, $needle_reverse);
webmaster@1 354 if ($pos !== FALSE) {
webmaster@1 355 // All needles are five characters long.
webmaster@1 356 $pos += 5;
webmaster@1 357 break;
webmaster@1 358 }
webmaster@1 359 }
webmaster@1 360 if ($matches) {
webmaster@1 361 if ($pos === FALSE) {
webmaster@1 362 $query = $first_part . $second_part .')';
webmaster@1 363 }
webmaster@1 364 else {
webmaster@1 365 $query = $first_part . substr($second_part, 0, -$pos) .')'. substr($second_part, -$pos);
webmaster@1 366 }
webmaster@1 367 }
webmaster@1 368 elseif ($pos === FALSE) {
webmaster@1 369 $query .= " $join WHERE $where";
webmaster@1 370 }
webmaster@1 371 else {
webmaster@1 372 $query = substr($query, 0, -$pos) . " $join WHERE $where " . substr($query, -$pos);
webmaster@1 373 }
webmaster@1 374 }
webmaster@1 375
webmaster@1 376 return $query;
webmaster@1 377 }
webmaster@1 378
webmaster@1 379 /**
webmaster@1 380 * Restrict a dynamic table, column or constraint name to safe characters.
webmaster@1 381 *
webmaster@1 382 * Only keeps alphanumeric and underscores.
webmaster@1 383 */
webmaster@1 384 function db_escape_table($string) {
webmaster@1 385 return preg_replace('/[^A-Za-z0-9_]+/', '', $string);
webmaster@1 386 }
webmaster@1 387
webmaster@1 388 /**
webmaster@1 389 * @} End of "defgroup database".
webmaster@1 390 */
webmaster@1 391
webmaster@1 392 /**
webmaster@1 393 * @defgroup schemaapi Schema API
webmaster@1 394 * @{
webmaster@1 395 *
webmaster@1 396 * A Drupal schema definition is an array structure representing one or
webmaster@1 397 * more tables and their related keys and indexes. A schema is defined by
webmaster@1 398 * hook_schema(), which usually lives in a modulename.install file.
webmaster@1 399 *
webmaster@1 400 * By implementing hook_schema() and specifying the tables your module
webmaster@1 401 * declares, you can easily create and drop these tables on all
webmaster@1 402 * supported database engines. You don't have to deal with the
webmaster@1 403 * different SQL dialects for table creation and alteration of the
webmaster@1 404 * supported database engines.
webmaster@1 405 *
webmaster@1 406 * hook_schema() should return an array with a key for each table that
webmaster@1 407 * the module defines.
webmaster@1 408 *
webmaster@1 409 * The following keys are defined:
webmaster@1 410 *
webmaster@1 411 * - 'description': A string describing this table and its purpose.
webmaster@1 412 * References to other tables should be enclosed in
webmaster@1 413 * curly-brackets. For example, the node_revisions table
webmaster@1 414 * description field might contain "Stores per-revision title and
webmaster@1 415 * body data for each {node}."
webmaster@1 416 * - 'fields': An associative array ('fieldname' => specification)
webmaster@1 417 * that describes the table's database columns. The specification
webmaster@1 418 * is also an array. The following specification parameters are defined:
webmaster@1 419 *
webmaster@1 420 * - 'description': A string describing this field and its purpose.
webmaster@1 421 * References to other tables should be enclosed in
webmaster@1 422 * curly-brackets. For example, the node table vid field
webmaster@1 423 * description might contain "Always holds the largest (most
webmaster@1 424 * recent) {node_revisions}.vid value for this nid."
webmaster@1 425 * - 'type': The generic datatype: 'varchar', 'int', 'serial'
webmaster@1 426 * 'float', 'numeric', 'text', 'blob' or 'datetime'. Most types
webmaster@1 427 * just map to the according database engine specific
webmaster@1 428 * datatypes. Use 'serial' for auto incrementing fields. This
webmaster@1 429 * will expand to 'int auto_increment' on mysql.
webmaster@1 430 * - 'size': The data size: 'tiny', 'small', 'medium', 'normal',
webmaster@1 431 * 'big'. This is a hint about the largest value the field will
webmaster@1 432 * store and determines which of the database engine specific
webmaster@1 433 * datatypes will be used (e.g. on MySQL, TINYINT vs. INT vs. BIGINT).
webmaster@1 434 * 'normal', the default, selects the base type (e.g. on MySQL,
webmaster@1 435 * INT, VARCHAR, BLOB, etc.).
webmaster@1 436 *
webmaster@1 437 * Not all sizes are available for all data types. See
webmaster@1 438 * db_type_map() for possible combinations.
webmaster@1 439 * - 'not null': If true, no NULL values will be allowed in this
webmaster@1 440 * database column. Defaults to false.
webmaster@1 441 * - 'default': The field's default value. The PHP type of the
webmaster@1 442 * value matters: '', '0', and 0 are all different. If you
webmaster@1 443 * specify '0' as the default value for a type 'int' field it
webmaster@1 444 * will not work because '0' is a string containing the
webmaster@1 445 * character "zero", not an integer.
webmaster@1 446 * - 'length': The maximal length of a type 'varchar' or 'text'
webmaster@1 447 * field. Ignored for other field types.
webmaster@1 448 * - 'unsigned': A boolean indicating whether a type 'int', 'float'
webmaster@1 449 * and 'numeric' only is signed or unsigned. Defaults to
webmaster@1 450 * FALSE. Ignored for other field types.
webmaster@1 451 * - 'precision', 'scale': For type 'numeric' fields, indicates
webmaster@1 452 * the precision (total number of significant digits) and scale
webmaster@1 453 * (decimal digits right of the decimal point). Both values are
webmaster@1 454 * mandatory. Ignored for other field types.
webmaster@1 455 *
webmaster@1 456 * All parameters apart from 'type' are optional except that type
webmaster@1 457 * 'numeric' columns must specify 'precision' and 'scale'.
webmaster@1 458 *
webmaster@1 459 * - 'primary key': An array of one or more key column specifiers (see below)
webmaster@1 460 * that form the primary key.
webmaster@1 461 * - 'unique key': An associative array of unique keys ('keyname' =>
webmaster@1 462 * specification). Each specification is an array of one or more
webmaster@1 463 * key column specifiers (see below) that form a unique key on the table.
webmaster@1 464 * - 'indexes': An associative array of indexes ('indexame' =>
webmaster@1 465 * specification). Each specification is an array of one or more
webmaster@1 466 * key column specifiers (see below) that form an index on the
webmaster@1 467 * table.
webmaster@1 468 *
webmaster@1 469 * A key column specifier is either a string naming a column or an
webmaster@1 470 * array of two elements, column name and length, specifying a prefix
webmaster@1 471 * of the named column.
webmaster@1 472 *
webmaster@1 473 * As an example, here is a SUBSET of the schema definition for
webmaster@1 474 * Drupal's 'node' table. It show four fields (nid, vid, type, and
webmaster@1 475 * title), the primary key on field 'nid', a unique key named 'vid' on
webmaster@1 476 * field 'vid', and two indexes, one named 'nid' on field 'nid' and
webmaster@1 477 * one named 'node_title_type' on the field 'title' and the first four
webmaster@1 478 * bytes of the field 'type':
webmaster@1 479 *
webmaster@1 480 * @code
webmaster@1 481 * $schema['node'] = array(
webmaster@1 482 * 'fields' => array(
webmaster@1 483 * 'nid' => array('type' => 'serial', 'unsigned' => TRUE, 'not null' => TRUE),
webmaster@1 484 * 'vid' => array('type' => 'int', 'unsigned' => TRUE, 'not null' => TRUE, 'default' => 0),
webmaster@1 485 * 'type' => array('type' => 'varchar', 'length' => 32, 'not null' => TRUE, 'default' => ''),
webmaster@1 486 * 'title' => array('type' => 'varchar', 'length' => 128, 'not null' => TRUE, 'default' => ''),
webmaster@1 487 * ),
webmaster@1 488 * 'primary key' => array('nid'),
webmaster@1 489 * 'unique keys' => array(
webmaster@1 490 * 'vid' => array('vid')
webmaster@1 491 * ),
webmaster@1 492 * 'indexes' => array(
webmaster@1 493 * 'nid' => array('nid'),
webmaster@1 494 * 'node_title_type' => array('title', array('type', 4)),
webmaster@1 495 * ),
webmaster@1 496 * );
webmaster@1 497 * @endcode
webmaster@1 498 *
webmaster@1 499 * @see drupal_install_schema()
webmaster@1 500 */
webmaster@1 501
webmaster@1 502 /**
webmaster@1 503 * Create a new table from a Drupal table definition.
webmaster@1 504 *
webmaster@1 505 * @param $ret
webmaster@1 506 * Array to which query results will be added.
webmaster@1 507 * @param $name
webmaster@1 508 * The name of the table to create.
webmaster@1 509 * @param $table
webmaster@1 510 * A Schema API table definition array.
webmaster@1 511 */
webmaster@1 512 function db_create_table(&$ret, $name, $table) {
webmaster@1 513 $statements = db_create_table_sql($name, $table);
webmaster@1 514 foreach ($statements as $statement) {
webmaster@1 515 $ret[] = update_sql($statement);
webmaster@1 516 }
webmaster@1 517 }
webmaster@1 518
webmaster@1 519 /**
webmaster@1 520 * Return an array of field names from an array of key/index column specifiers.
webmaster@1 521 *
webmaster@1 522 * This is usually an identity function but if a key/index uses a column prefix
webmaster@1 523 * specification, this function extracts just the name.
webmaster@1 524 *
webmaster@1 525 * @param $fields
webmaster@1 526 * An array of key/index column specifiers.
webmaster@1 527 * @return
webmaster@1 528 * An array of field names.
webmaster@1 529 */
webmaster@1 530 function db_field_names($fields) {
webmaster@1 531 $ret = array();
webmaster@1 532 foreach ($fields as $field) {
webmaster@1 533 if (is_array($field)) {
webmaster@1 534 $ret[] = $field[0];
webmaster@1 535 }
webmaster@1 536 else {
webmaster@1 537 $ret[] = $field;
webmaster@1 538 }
webmaster@1 539 }
webmaster@1 540 return $ret;
webmaster@1 541 }
webmaster@1 542
webmaster@1 543 /**
webmaster@1 544 * Given a Schema API field type, return the correct %-placeholder.
webmaster@1 545 *
webmaster@1 546 * Embed the placeholder in a query to be passed to db_query and and pass as an
webmaster@1 547 * argument to db_query a value of the specified type.
webmaster@1 548 *
webmaster@1 549 * @param $type
webmaster@1 550 * The Schema API type of a field.
webmaster@1 551 * @return
webmaster@1 552 * The placeholder string to embed in a query for that type.
webmaster@1 553 */
webmaster@1 554 function db_type_placeholder($type) {
webmaster@1 555 switch ($type) {
webmaster@1 556 case 'varchar':
webmaster@1 557 case 'char':
webmaster@1 558 case 'text':
webmaster@1 559 case 'datetime':
webmaster@7 560 return "'%s'";
webmaster@1 561
webmaster@1 562 case 'numeric':
webmaster@7 563 // Numeric values are arbitrary precision numbers. Syntacically, numerics
webmaster@7 564 // should be specified directly in SQL. However, without single quotes
webmaster@7 565 // the %s placeholder does not protect against non-numeric characters such
webmaster@7 566 // as spaces which would expose us to SQL injection.
webmaster@7 567 return '%n';
webmaster@1 568
webmaster@1 569 case 'serial':
webmaster@1 570 case 'int':
webmaster@1 571 return '%d';
webmaster@1 572
webmaster@1 573 case 'float':
webmaster@1 574 return '%f';
webmaster@1 575
webmaster@1 576 case 'blob':
webmaster@1 577 return '%b';
webmaster@1 578 }
webmaster@1 579
webmaster@1 580 // There is no safe value to return here, so return something that
webmaster@1 581 // will cause the query to fail.
webmaster@1 582 return 'unsupported type '. $type .'for db_type_placeholder';
webmaster@1 583 }
webmaster@1 584
webmaster@1 585 /**
webmaster@1 586 * @} End of "defgroup schemaapi".
webmaster@1 587 */