Contributions API

Database abstraction layer

Allow the use of different database servers using the same code base.

Drupal provides a slim database abstraction layer to provide developers with the ability to support multiple database servers easily. The intent of this layer is to preserve the syntax and power of SQL as much as possible, while letting Drupal control the pieces of queries that need to be written differently for different servers and provide basic security checks.

Most Drupal database queries are performed by a call to db_query() or db_query_range(). Module authors should also consider using pager_query() for queries that return results that need to be presented on multiple pages, and tablesort_sql() for generating appropriate queries for sortable tables.

For example, one might wish to return a list of the most recent 10 nodes authored by a given user. Instead of directly issuing the SQL query

<?php

SELECT n.title, n.body, n.created FROM node n WHERE n.uid = $uid LIMIT 0, 10;

?>

one would instead call the Drupal functions:

<?php

$result = db_query_range('SELECT n.title, n.body, n.created
FROM {node} n WHERE n.uid = %d', $uid, 0, 10);
while ($node = db_fetch_object($result)) {
// Perform operations on $node->body, etc. here.
  }

?>

Curly braces are used around "node" to provide table prefixing via db_prefix_tables(). The explicit use of a user ID is pulled out into an argument passed to db_query() so that SQL injection attacks from user input can be caught and nullified. The LIMIT syntax varies between database servers, so that is abstracted into db_query_range() arguments. Finally, note the common pattern of iterating over the result set using db_fetch_object().

Constants

Name	Location	Description
DB_QUERY_REGEXP	5/includes/database.inc	Indicates the place holders that should be replaced in _db_query_callback().

Functions

Name	Location	Description
db_affected_rows	5/includes/database.pgsql.inc	Determine the number of rows changed by the preceding query.
db_check_setup	5/includes/database.pgsql.inc	Verify if the database is set up correctly.
db_connect	5/includes/database.pgsql.inc	Initialize a database connection.
db_decode_blob	5/includes/database.pgsql.inc	Returns text from a Binary Large OBject value. In case of PostgreSQL decodes data after select from bytea field.
db_distinct_field	5/includes/database.pgsql.inc	Wraps the given table.field entry with a DISTINCT(). The wrapper is added to the SELECT list entry of the given query and the resulting query is returned. This function only applies the wrapper if a DISTINCT doesn't already exist in the query.
db_encode_blob	5/includes/database.pgsql.inc	Returns a properly formatted Binary Large OBject value. In case of PostgreSQL encodes data for insert into bytea field.
db_error	5/includes/database.pgsql.inc	Determine whether the previous query caused an error.
db_escape_string	5/includes/database.pgsql.inc	Prepare user input for use in a database query, preventing SQL injection attacks. Note: This function requires PostgreSQL 7.2 or later.
db_escape_table	5/includes/database.inc	Restrict a dynamic tablename to safe characters.
db_fetch_array	5/includes/database.pgsql.inc	Fetch one result row from the previous query as an array.
db_fetch_object	5/includes/database.pgsql.inc	Fetch one result row from the previous query as an object.
db_lock_table	5/includes/database.pgsql.inc	Lock a table. This function automatically starts a transaction.
db_next_id	5/includes/database.pgsql.inc	Return a new unique ID in the given sequence.
db_num_rows	5/includes/database.pgsql.inc	Determine how many result rows were found by the preceding query.
db_prefix_tables	5/includes/database.inc	Append a database prefix to all tables in a query.
db_query	5/includes/database.inc	Runs a basic query in the active database.
db_query_range	5/includes/database.pgsql.inc	Runs a limited-range query in the active database.
db_query_temporary	5/includes/database.pgsql.inc	Runs a SELECT query and stores its results in a temporary table.
db_result	5/includes/database.pgsql.inc	Return an individual result field from the previous query.
db_rewrite_sql	5/includes/database.inc	Rewrites node, taxonomy and comment queries. Use it for listing queries. Do not use FROM table1, table2 syntax, use JOIN instead.
db_set_active	5/includes/database.inc	Activate a database for future queries.
db_status_report	5/includes/database.pgsql.inc	Report database status.
db_table_exists	5/includes/database.pgsql.inc	Check if a table exists.
db_unlock_tables	5/includes/database.pgsql.inc	Unlock all locked tables. This function automatically commits a transaction.
db_version	5/includes/database.pgsql.inc	Returns the version of the database server currently in use.
hook_versioncontrol_branch_operation	contributions/versioncontrol/hook_versioncontrol.php	Act on database changes when branch operations are inserted or deleted. Note that this hook is not necessarily called at the time when the branch operation actually happens - they can also be inserted by a cron script when the actual operation has...
hook_versioncontrol_commit	contributions/versioncontrol/hook_versioncontrol.php	Act on database changes when commits are inserted or deleted. Note that this hook is not necessarily called at the time when the commit actually happens - commits can also be inserted by a cron script when the actual commit has been accomplished for...
hook_versioncontrol_repository	contributions/versioncontrol/hook_versioncontrol.php	Act on database changes when VCS repositories are inserted, updated or deleted.
hook_versioncontrol_tag_operation	contributions/versioncontrol/hook_versioncontrol.php	Act on database changes when tag operations are inserted or deleted. Note that this hook is not necessarily called at the time when the tag operation actually happens - they can also be inserted by a cron script when the actual operation has been...
pager_query	5/includes/pager.inc	Perform a paged database query.
tablesort_sql	5/includes/tablesort.inc	Create an SQL sort clause.
_db_query	5/includes/database.pgsql.inc	Helper function for db_query().
_db_query_callback	5/includes/database.inc	Helper function for db_query().
_db_rewrite_sql	5/includes/database.inc	Helper function for db_rewrite_sql.