Database connection wrapper with Memcache result set caching.
Database connection wrapper with Memcache result set caching.
AnewtDatabaseConnectionMemcache is a wrapper around another database connection, providing a simple caching solution for SELECT queries. It is not supposed to be a fully featured database caching solution, but designed to work transparently in simple cases. Using AnewtDatabaseConnectionMemcache does not require any code changes, except for the database connection step. Just invoke AnewtDatabase::setup_connection() twice: one for the real connection, one for the cached connection.
Note that connect(), disconnect() and is_connected() only apply to the Memcache server connection, and do not propagate to the underlying database connection. Since connections to the Memcache server are only established if required, it usually does not make sense to connect() and disconnect() the connection manually.
How does it work? The rows returned from a SELECT query executed against a real database connection are temporarily stored in a Memcache cache. If the same query is executed again within a certain timespan (see expiry below), the exact same result is returned without hitting the database again. Note that this means that changes to the database while the data is in the cache are not immediately visible.
Result row caching only works if you execute your SELECT queries through one of these convenience functions:
prepare_execute_fetch_one()prepare_executev_fetch_one()prepare_execute_fetch_all()prepare_executev_fetch_all()Note that preparing and executing a query manually, i.e. by calling AnewtDatabaseConnection::prepare(), executing the returned AnewtDatabasePreparedQuery and then fetching rows with AnewtDatabaseResultSet::fetch_one() (or other fetch functions) will not result in caching!
Important note: if you change the contents of the database and want to see the results of e.g. INSERT queries reflected immediately if you perform a SELECT query right after the INSERT, you should not rely on AnewtDatabaseConnectionMemcache, but interact directly with the real AnewtDatabaseConnection, e.g. AnewtDatabaseConnectionMySQL. You can use both the AnewtDatabaseConnectionMemcache connection and the underlying AnewtDatabaseConnection at the same time. This way, you can opt to use the cache for some of your SELECT queries (when delays are not an issue), while you deliberately avoid it for other SELECT queries (if you want changes to be immediately visible).
Additionally, you can also delete all cached result sets by invoking AnewtDatabaseConnectionMemcache::flush_cache() directly.
The settings accepted by this backend are:
connection: The existing AnewtDatabaseConnection to wraphostname: The hostname of the memcache server (optional, defaults to localhost)port: The port number of the memcache server (optional, defaults to 11211)socket: Path to a Unix domain socket (optional). Instead of a network connection, you can also provide a path to a Unix socket where memcached listens. If this is specified, hostname and port are ignored.expiry: The number of seconds to cache result sets (optional, defaults to 600)identifier: An application-specific identifier (optional). Use this to avoid collisions if two instances of the same application use the same Memcache server but you do not want them to share their cached values. In this case, you should specify an identifier value that is unique to this application instance.compression: Whether to enable compression (optional, defaults to false) __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.
is_connected() ¶Check whether the connection is currently open.
True if the connection is open, false otherwise.
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) ¶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.
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_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)
flush_cache() ¶Flush the contents of the query cache.
This method can be used to flush the contents of the query cache. Note that this will delete all cached data from the Memcache server, i.e. including any data that has not been set from this connection!
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
real_connect() [protected] ¶Establish a database connection.
real_disconnect() [protected] ¶Disconnect the database connection.
build_key($sql, $values, $all_rows) [private] ¶Construct a key to be used as a memcache key.
$sqlThe SQL query
$valuesThe values for the SQL query
$all_rowsWhether this key is intended for single row or multiple row caching (boolean)
A key that can be used as a memcache key.
$n_cache_hitsThe number of Memcache hits.
$n_cache_missesThe number of Memcache misses.
$memcache_connectedWhether we are Memcache server is connected.
AnewtDatabaseConnection::transaction_begin()AnewtDatabaseConnection::transaction_commit()AnewtDatabaseConnection::prepare_execute_fetch_one()AnewtDatabaseConnection::disconnect()AnewtDatabaseConnection::prepare()AnewtDatabaseConnection::transaction_rollback()AnewtDatabaseConnection::$queries_executedAnewtDatabaseConnection::$connection_handleAnewtDatabaseConnection::$settingsAnewtDatabaseConnection::prepare_executev()AnewtDatabaseConnection::prepare_execute_fetch_all()AnewtDatabaseConnection::prepare_execute()AnewtDatabaseConnection::create_sql_template()AnewtDatabaseConnection::connect()AnewtDatabaseConnection::$n_queries_executed