Abstract database connection class.
Abstract database connection class.
This class is the base class for database connections, and is subclassed by specific database backends. AnewtDatabaseConnection instances cannot be created directly; see AnewtDatabase on how to setup and obtain AnewtDatabaseConnection instances.
The settings accepted by all backends are:
persistent: Whether a persistent connection should be made. This defaults to true.See the documentation for the backend-specific AnewtDatabaseConnection subclasses for more information:
AnewtDatabaseConnectionMySQLAnewtDatabaseConnectionMySQLOld (for older MySQL versions)AnewtDatabaseConnectionPostgreSQLAnewtDatabaseConnectionSQLite __construct($settings) ¶Create a new connection instance (internal use only).
Do not call this method directly; it is for internal use only. See the AnewtDatabase documentation on how to setup and obtain AnewtDatabaseConnection instances.
$settingsAssociative array with connection settings.
These methods can be used to connect and disconnect from the database. Note that, by default, database connections automatically connect when they are setup using AnewtDatabase::setup_connection(). If you do not want this, set the autoconnect property to false when setting up the connection.
connect() ¶Establish a database connection.
This function does nothing if the connection has been established already.
disconnect() ¶Disconnect a database connection.
This function does nothing if the connection has been disconnected already.
is_connected() ¶Check whether the connection is currently open.
True if the connection is open, false otherwise.
real_connect() [protected] ¶Establish a database connection.
real_disconnect() [protected] ¶Disconnect the database connection.
These methods provide a rich API to execute queries and retrieve resulting rows. The basic functionality to prepare a query that can later be executed is provided by prepare(), but several convenience methods are available that cover the most frequent use cases, e.g. fetching all rows from a result set.
To build complex SQL queries, while still using the extensive type checking this module offers, you can use create_sql_template() to obtain an AnewtDatabaseSQLTemplate instance that you can fill manually.
prepare($sql) ¶Prepare a query for execution.
This method can be used to execute the same query more than once, e.g. each with different values for the placeholders.
To obtain a result row (or all result rows) returned by a query, it is easier to use AnewtDatabaseConnection::prepare_execute_fetch or one of the other variants.
$sqlThe SQL query to be prepared (optionally with placeholders)
A new AnewtDatabasePreparedQuery instance.
prepare_execute($sql, $values=null) ¶Execute a query using the values passed as multiple parameters, without retrieving resulting rows.
See AnewtDatabaseConnection::prepare_executev for a detailed description.
$sqlThe SQL query to be prepared (optionally with placeholders)
$valuesZero or more values to be substituted for the placeholders
prepare_executev($sql, $values=null) ¶Execute a query using the values passed as a single parameter, without retrieving resulting rows.
For some query types the number of affected rows is returned. This only works for queries that operate on a number of rows, i.e. INSERT, UPDATE, REPLACE, and DELETE queries. For other query types null is returned.
Note that this method is mostly useless for SELECT queries since it will not return any results; use AnewtDatabaseConnection::prepare_execute_fetch or AnewtDatabaseConnection::prepare_execute_fetch_all if you want to retrieve result rows.
$sqlThe SQL query to be prepared (optionally with placeholders)
$valuesZero or more values to be substituted for the placeholders
The number of rows affected by the query.
prepare_execute_fetch_one($sql, $values=null) ¶Execute a query using the values passed as multiple parameters, and fetch the first row.
$sqlThe SQL query to be prepared (optionally with placeholders)
$valuesZero or more values to be substituted for the placeholders
A single row, or NULL
prepare_executev_fetch_one($sql, $values=null) ¶Execute a query using the values passed as a single parameter, and fetch the first row.
$sqlThe SQL query to be prepared (optionally with placeholders)
$valuesZero or more values to be substituted for the placeholders
A single row, or NULL
prepare_execute_fetch_all($sql, $values=null) ¶Execute a query using the values passed as multiple parameters, and fetch all rows.
$sqlThe SQL query to be prepared (optionally with placeholders)
$valuesZero or more values to be substituted for the placeholders
Array of all rows (may be empty)
prepare_executev_fetch_all($sql, $values=null) ¶Execute a query using the values passed as a single parameter, and fetch all rows.
$sqlThe SQL query to be prepared (optionally with placeholders)
$valuesZero or more values to be substituted for the placeholders
Array of all rows (may be empty)
create_sql_template($sql) ¶Return an AnewtDatabaseSQLTemplate for this connection.
$sqlThe SQL query to be prepared (optionally with placeholders)
A new AnewtDatabaseSQLTemplate instance.
last_insert_id($options=null) ¶Get the last insert id for this connection.
The $options parameter is database backend specific. For most backends this value is not needed. At least PostgreSQL needs a sequence name. See the backend documentation for more information.
$optionsBackend-specific value.
real_execute_sql($sql) [protected] ¶Execute SQL and create an AnewtDatabaseResultSet for a query.
This method is for internal use only and is backend-specific.
$sqlThe SQL query to execute.
execute_sql($sql) [private] ¶Execute SQL and create an AnewtDatabaseResultSet.
This method is for internal use only. Use one of the prepare() methods to prepare and execute queries.
$sqlThe SQL query to execute.
A new AnewtDatabaseResultSet instance.
transaction_begin() ¶Start a transaction.
transaction_commit() ¶Commit a transaction.
transaction_rollback() ¶Roll back a transaction.
The implementations of these methods in AnewtDatabaseConnection are generic. Some of those methods are overridden in the database backend specific subclasses.
Note that it is often not the right approach to invoke these methods yourself when building complex SQL queries. Creating an AnewtDatabaseSQLTemplate with create_sql_template() and filling that instead results in code that is much cleaner and more easy to read.
escape_boolean($value) ¶Escape a boolean for use in SQL queries.
$valueThe value to escape
The escaped value
escape_string($value) ¶Escape a string for use in SQL queries.
$valueThe value to escape
The escaped value
escape_table_name($value) ¶Escape a table name for use in SQL queries.
$valueThe value to escape
The escaped value
escape_column_name($value) ¶Escape a column name for use in SQL queries.
$valueThe value to escape
The escaped value
escape_date($value) ¶Escape a date for use in SQL queries.
This method merely adds quotes.
$valueThe value to escape
The escaped value
escape_time($value) ¶Escape a time for use in SQL queries.
This method merely adds quotes.
$valueThe value to escape
The escaped value
escape_datetime($value) ¶Escape a datetime for use in SQL queries.
This method merely adds quotes.
$valueThe value to escape
The escaped value
$queries_executedList of executed queries.
This is mostly useful for debugging. Note that only a certain number of queries are kept here before the first query is no longer kept around (ring buffer), hence the list may not be complete.
$connection_handleThe underlying database connection resource.