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
SELECT n.nid, n.title, n.created FROM node n WHERE n.uid = $uid LIMIT 0, 10;
one would instead call the Drupal functions:
$result = db_query_range('SELECT n.nid, n.title, 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().
File
- drupal-6.x/
includes/ database.inc, line 15 - Wrapper for database interface code.
Functions
Name | Location | Description |
---|---|---|
update_sql |
drupal-6.x/ |
Perform an SQL query and return success or failure. |
db_prefix_tables |
drupal-6.x/ |
Append a database prefix to all tables in a query. |
db_set_active |
drupal-6.x/ |
Activate a database for future queries. |
_db_error_page |
drupal-6.x/ |
Helper function to show fatal database errors. |
db_is_active |
drupal-6.x/ |
Returns a boolean depending on the availability of the database. |
_db_query_callback |
drupal-6.x/ |
Helper function for db_query(). |
db_placeholders |
drupal-6.x/ |
Generate placeholders for an array of query arguments of a single type. |
_db_rewrite_sql |
drupal-6.x/ |
Helper function for db_rewrite_sql. |
db_rewrite_sql |
drupal-6.x/ |
Rewrites node, taxonomy and comment queries. Use it for listing queries. Do not use FROM table1, table2 syntax, use JOIN instead. |
db_distinct_field |
drupal-6.x/ |
Adds the DISTINCT flag to the supplied query and returns the altered query. |
db_escape_table |
drupal-6.x/ |
Restrict a dynamic table, column or constraint name to safe characters. |
db_status_report |
drupal-6.x/ |
Report database status. |
db_version |
drupal-6.x/ |
Returns the version of the database server currently in use. |
db_connect |
drupal-6.x/ |
Initialize a database connection. |
_db_query |
drupal-6.x/ |
Helper function for db_query(). |
db_fetch_object |
drupal-6.x/ |
Fetch one result row from the previous query as an object. |
db_fetch_array |
drupal-6.x/ |
Fetch one result row from the previous query as an array. |
db_result |
drupal-6.x/ |
Return an individual result field from the previous query. |
db_error |
drupal-6.x/ |
Determine whether the previous query caused an error. |
db_affected_rows |
drupal-6.x/ |
Determine the number of rows changed by the preceding query. |
db_query_range |
drupal-6.x/ |
Runs a limited-range query in the active database. |
db_query_temporary |
drupal-6.x/ |
Runs a SELECT query and stores its results in a temporary table. |
db_encode_blob |
drupal-6.x/ |
Returns a properly formatted Binary Large OBject value. |
db_decode_blob |
drupal-6.x/ |
Returns text from a Binary Large Object value. |
db_escape_string |
drupal-6.x/ |
Prepare user input for use in a database query, preventing SQL injection attacks. |
db_lock_table |
drupal-6.x/ |
Lock a table. |
db_unlock_tables |
drupal-6.x/ |
Unlock all locked tables. |
db_table_exists |
drupal-6.x/ |
Check if a table exists. |
db_column_exists |
drupal-6.x/ |
Check if a column exists in the given table. |
db_status_report |
drupal-6.x/ |
Report database status. |
db_version |
drupal-6.x/ |
Returns the version of the database server currently in use. |
db_connect |
drupal-6.x/ |
Initialise a database connection. |
_db_query |
drupal-6.x/ |
Helper function for db_query(). |
db_fetch_object |
drupal-6.x/ |
Fetch one result row from the previous query as an object. |
db_fetch_array |
drupal-6.x/ |
Fetch one result row from the previous query as an array. |
db_result |
drupal-6.x/ |
Return an individual result field from the previous query. |
db_error |
drupal-6.x/ |
Determine whether the previous query caused an error. |
db_affected_rows |
drupal-6.x/ |
Determine the number of rows changed by the preceding query. |
db_query_range |
drupal-6.x/ |
Runs a limited-range query in the active database. |
db_query_temporary |
drupal-6.x/ |
Runs a SELECT query and stores its results in a temporary table. |
db_encode_blob |
drupal-6.x/ |
Returns a properly formatted Binary Large Object value. |
db_decode_blob |
drupal-6.x/ |
Returns text from a Binary Large OBject value. |
db_escape_string |
drupal-6.x/ |
Prepare user input for use in a database query, preventing SQL injection attacks. |
db_lock_table |
drupal-6.x/ |
Lock a table. |
db_unlock_tables |
drupal-6.x/ |
Unlock all locked tables. |
db_table_exists |
drupal-6.x/ |
Check if a table exists. |
db_column_exists |
drupal-6.x/ |
Check if a column exists in the given table. |
db_status_report |
drupal-6.x/ |
Report database status. |
db_version |
drupal-6.x/ |
Returns the version of the database server currently in use. |
db_connect |
drupal-6.x/ |
Initialize a database connection. |
db_query |
drupal-6.x/ |
Runs a basic query in the active database. |
_db_query |
drupal-6.x/ |
Helper function for db_query(). |
db_fetch_object |
drupal-6.x/ |
Fetch one result row from the previous query as an object. |
db_fetch_array |
drupal-6.x/ |
Fetch one result row from the previous query as an array. |
db_result |
drupal-6.x/ |
Return an individual result field from the previous query. |
db_error |
drupal-6.x/ |
Determine whether the previous query caused an error. |
db_last_insert_id |
drupal-6.x/ |
Returns the last insert id. This function is thread safe. |
db_affected_rows |
drupal-6.x/ |
Determine the number of rows changed by the preceding query. |
db_query_range |
drupal-6.x/ |
Runs a limited-range query in the active database. |
db_query_temporary |
drupal-6.x/ |
Runs a SELECT query and stores its results in a temporary table. |
db_encode_blob |
drupal-6.x/ |
Returns a properly formatted Binary Large OBject value. In case of PostgreSQL encodes data for insert into bytea field. |
db_decode_blob |
drupal-6.x/ |
Returns text from a Binary Large OBject value. In case of PostgreSQL decodes data after select from bytea field. |
db_escape_string |
drupal-6.x/ |
Prepare user input for use in a database query, preventing SQL injection attacks. Note: This function requires PostgreSQL 7.2 or later. |
db_lock_table |
drupal-6.x/ |
Lock a table. This function automatically starts a transaction. |
db_unlock_tables |
drupal-6.x/ |
Unlock all locked tables. This function automatically commits a transaction. |
db_table_exists |
drupal-6.x/ |
Check if a table exists. |
db_column_exists |
drupal-6.x/ |
Check if a column exists in the given table. |
db_check_setup |
drupal-6.x/ |
Verify if the database is set up correctly. |
pager_query |
drupal-6.x/ |
Perform a paged database query. |
tablesort_sql |
drupal-6.x/ |
Create an SQL sort clause. |
Constants
Name | Location | Description |
---|---|---|
DB_QUERY_REGEXP |
drupal-6.x/ |
Indicates the place holders that should be replaced in _db_query_callback(). |