User Guide - DB Driver Reference
First stab at DB driver reference. Methods are listed in order encountered in the source file.
Parameter or return types in DB_driver updated as needed, and reflected here.
TOC entry added to bottom of database index page.
Signed-off-by:James L Parry <jim_parry@bcit.ca>
diff --git a/system/database/DB_driver.php b/system/database/DB_driver.php
index 7c3df42..fdd9916 100644
--- a/system/database/DB_driver.php
+++ b/system/database/DB_driver.php
@@ -964,7 +964,7 @@
* Calculate the aggregate query elapsed time
*
* @param int The number of decimal places
- * @return int
+ * @return string
*/
public function elapsed_time($decimals = 6)
{
@@ -1034,7 +1034,7 @@
/**
* Escape String
*
- * @param string $str
+ * @param string|string[] $str
* @param bool $like Whether or not the string will be used in a LIKE condition
* @return string
*/
@@ -1103,7 +1103,7 @@
* position is the primary key
*
* @param string the table name
- * @return string
+ * @return mixed
*/
public function primary($table = '')
{
@@ -1146,7 +1146,7 @@
* Returns an array of table names
*
* @param string $constrain_by_prefix = FALSE
- * @return array
+ * @return mixed
*/
public function list_tables($constrain_by_prefix = FALSE)
{
@@ -1214,7 +1214,7 @@
* Fetch Field Names
*
* @param string the table name
- * @return array
+ * @return mixed
*/
public function list_fields($table = '')
{
diff --git a/user_guide_src/source/database/db_driver_reference.rst b/user_guide_src/source/database/db_driver_reference.rst
new file mode 100644
index 0000000..872077a
--- /dev/null
+++ b/user_guide_src/source/database/db_driver_reference.rst
@@ -0,0 +1,407 @@
+###################
+DB Driver Reference
+###################
+
+This is the platform-independent base DB implementation class.
+This class will not be called directly. Rather, the adapter
+class for the specific database will extend and instantiate it.
+
+The how-to material for this has been split over several articles.
+This article is intended to be a reference for them.
+
+.. class:: CI_DB_driver
+
+ .. method:: initialize()
+
+ :returns: TRUE on success, FALSE on failure
+ :rtype: boolean
+
+ Initialize Database Settings;
+ establish a connection to the database.
+
+ .. method:: db_pconnect()
+
+ :returns: TRUE on success, FALSE on failure
+ :rtype: boolean
+
+ Establish a persistent database connection
+
+ .. method:: reconnect()
+
+ :returns: TRUE on success, FALSE on failure
+ :rtype: boolean
+
+ Keep / reestablish the db connection if no queries have been
+ sent for a length of time exceeding the server's idle timeout.
+
+ This is only available in drivers that support it.
+
+ .. method:: db_select()
+
+ :returns: TRUE on success, FALSE on failure
+ :rtype: boolean
+
+ Select database
+
+ .. method:: db_set_charset($charset)
+
+ :param string $charset: Character set name
+ :returns: TRUE on success, FALSE on failure
+ :rtype: boolean
+
+ Set client character set
+
+ .. method:: platform()
+
+ :returns: Platform name
+ :rtype: string
+
+ The name of the platform in use (mysql, mssql, etc...)
+
+ .. method:: version()
+
+ :returns: The version of the database being used.
+ :rtype: string
+
+ Database version number
+
+ .. method:: query($sql[, $binds = FALSE[, $return_object = NULL]]])
+
+ :param string $sql: The SQL statement to execute
+ :param array $binds: An array of binding data
+ :param bool $return_object: Character set name
+ :returns: True on "update" success, DB_result object on "query" success, FALSE on failure
+ :rtype: mixed
+
+ Execute the query
+
+ Accepts an SQL string as input and returns a result object
+ upon
+ successful execution of a "read" type query. Returns boolean
+ TRUE
+ upon successful execution of a "write" type query.
+ Returns boolean
+ FALSE upon failure, and if the $db_debug variable is set
+ to TRUE
+ will raise an error.
+
+ .. method:: load_rdriver()
+
+ :returns: The DB_result object appropriate for the driver in use
+ :rtype: DB_result
+
+ Load the result drivers
+
+ .. method:: simple_query($sql)
+
+ :param string $sql: The SQL statement to execute
+ :returns: True on "update" success, DB_result object on "query" success, FALSE on failure
+ :rtype: mixed
+
+ Simple Query
+
+ This is a simplified version of the query() function. Internally
+ we only use it when running transaction commands since they do
+ not require all the features of the main query() function.
+
+ .. method:: trans_off()
+
+ :rtype: void
+
+ Disable Transactions.
+
+ This permits transactions to be disabled at run-time.
+
+ .. method:: trans_strict([$mode = TRUE])
+
+ :param boolean $mode: TRUE for strict mode
+ :rtype: void
+
+ Enable/disable Transaction Strict Mode.
+
+ When strict mode is enabled, if you are running multiple
+ groups of
+ transactions, if one group fails all groups will be rolled back.
+ If strict mode is disabled, each group is treated autonomously,
+ meaning
+ a failure of one group will not affect any others.
+
+ .. method:: trans_start([$test_mode = FALSE[)
+
+ :param boolean $test_mode: TRUE for testing mode
+ :rtype: void
+
+ Start Transaction.
+
+ .. method:: trans_complete()
+
+ :rtype: void
+
+ Complete Transaction.
+
+ .. method:: trans_status()
+
+ :returns: TRUE if the transaction succeeded, FALSE if it failed
+ :rtype: boolean
+
+ Lets you retrieve the transaction flag to determine if it
+ has failed.
+
+ .. method:: compile_binds($sql, $binds)
+
+ :param string $sql: The SQL statement
+ :param array $binds: An array of binding data
+ :returns: The updated SQL statement
+ :rtype: string
+
+ Compile Bindings
+
+ .. method:: is_write_type($sql)
+
+ :param string $sql: The SQL statement
+ :returns: TRUE if the SQL statement is a "write" type of statement
+ :rtype: boolean
+
+ Determines if a query is a "write" type.
+
+ .. method:: elapsed_time([$decimals = 6])
+
+ :param int $decimals: The number of decimal places
+ :returns: The aggregate query elapsed time, in microseconds
+ :rtype: string
+
+ Calculate the aggregate query elapsed time.
+
+ .. method:: total_queries()
+
+ :returns: The total number of queries
+ :rtype: int
+
+ Returns the total number of queries.
+
+ .. method:: last_query()
+
+ :returns: The last query executed
+ :rtype: string
+
+ Returns the last query that was executed.
+
+ .. method:: escape($str)
+
+ :param string $str: The string to work with
+ :returns: The escaped string
+ :rtype: mixed
+
+ "Smart" Escape String.
+
+ Escapes data based on type.
+ Sets boolean and null types
+
+ .. method:: escape_str($str[, $like = FALSE])
+
+ :param mixed $str: The string or array of strings to work with
+ :param boolean $like: Whether or not the string will be used in a LIKE condition
+ :returns: The escaped string(s)
+ :rtype: mixed
+
+ Escape String.
+
+ .. method:: escape_like_str($str)
+
+ :param mixed $str: The string or array of strings to work with
+ :returns: The escaped string(s)
+ :rtype: mixed
+
+ Escape LIKE String.
+
+ Calls the individual driver for platform
+ specific escaping for LIKE conditions.
+
+ .. method:: primary([$table = ''])
+
+ :param string $table: The table name
+ :returns: The primary key name, FALSE if none
+ :rtype: mixed
+
+ Primary.
+
+ Retrieves the primary key. It assumes that the row in the first
+ position is the primary key.
+
+ .. method:: count_all([$table = ''])
+
+ :param string $table: The table name
+ :returns: Record count for specified table
+ :rtype: int
+
+ "Count All" query.
+
+ Generates a platform-specific query string that counts
+ all records in
+ the specified database.
+
+ .. method:: list_tables([$constrain_by_prefix = FALSE])
+
+ :param boolean $constrain_by_prefix: TRUE to constrain the tables considered
+ :returns: Array of table names, FALSE if the operation is unsupported
+ :rtype: mixed
+
+ Returns an array of table names.
+
+ .. method:: table_exists($table_name)
+
+ :param string $table_name: The table name
+ :returns: TRUE if that table exists
+ :rtype: boolean
+
+ Determine if a particular table exists.
+
+ .. method:: list_fields([$table = ''])
+
+ :param string $table: The table name
+ :returns: Array of field names, FALSE if the table doesn't exist or the operation is un-supported
+ :rtype: mixed
+
+ Fetch Field Names.
+
+ .. method:: field_exists($field_name, $table_name)
+
+ :param string $table_name: The table name
+ :param string $field_name: The field name
+ :returns: TRUE if that field exists in that table
+ :rtype: boolean
+
+ Determine if a particular field exists.
+
+ .. method:: field_data([$table = ''])
+
+ :param string $table: The table name
+ :returns: Object with field data, FALSE if no table given
+ :rtype: mixed
+
+ Returns an object with field data.
+
+ .. method:: escape_identifiers($item)
+
+ :param mixed $item: The item or array of items to escape
+ :returns: The item(s), escaped
+ :rtype: mixed
+
+ Escape the SQL Identifiers.
+
+ This function escapes column and table names
+
+ .. method:: insert_string($table, $data)
+
+ :param string $table: The table upon which the query will be performed
+ :param array $data: an associative array of data key/values
+ :returns: The SQL insert string
+ :rtype: string
+
+ Generate an insert string.
+
+ .. method:: update_string($table, $data, $where)
+
+ :param string $table: The table upon which the query will be performed
+ :param array $data: an associative array of data key/values
+ :param mixed $where: the "where" statement
+ :returns: The SQL update string
+ :rtype: string
+
+ Generate an update string.
+
+ .. method:: call_function($function)
+
+ :param string $function: Function name
+ :returns: The function result
+ :rtype: string
+
+ Enables a native PHP function to be run, using a platform
+ agnostic wrapper.
+
+ .. method:: cache_set_path([$path = ''])
+
+ :param string $path: the path to the cache directory
+ :rtype: void
+
+ Set Cache Directory Path.
+
+ .. method:: cache_on()
+
+ :returns: cache_on value
+ :rtype: boolean
+
+ Enable Query Caching.
+
+ .. method:: cache_off()
+
+ :returns: cache_on value
+ :rtype: boolean
+
+ Disable Query Caching.
+
+ .. method:: cache_delete([$segment_one = ''[, $segment_two = '']])
+
+ :param string $segment_one: first URI segment
+ :param string $segment_two: second URI segment
+ :returns: TRUE on success, FALSE on failure
+ :rtype: boolean
+
+ Delete the cache files associated with a particular URI
+
+ .. method:: cache_delete_all()
+
+ :returns: TRUE on success, FALSE on failure
+ :rtype: boolean
+
+ Delete All cache files
+
+ .. method:: close()
+
+ :rtype: void
+
+ Close DB Connection
+
+ .. method:: display_error([$error = ''[, $swap = ''[, $native = FALSE]]])
+
+ :param string $error: the error message
+ :param string $swap: any "swap" values
+ :param boolean $native: whether to localize the message
+ :returns: sends the application/views/errors/error_db.php template
+ :rtype: string
+
+ Display an error message
+
+ .. method:: protect_identifiers($item[, $prefix_single = FALSE[, $protect_identifiers = NULL[, $field_exists = TRUE]]])
+
+ :param string $item: the item
+ :param boolean $prefix_single: whether to use a single prefix
+ :param boolean $protect_identifiers: whether to protect identifiers
+ :param boolean $field_exists: whether the supplied item does not contain a field name.
+ :returns: the modified item
+ :rtype: string
+
+ Protect Identifiers.
+
+ This function is used extensively by the Query Builder class,
+ and by
+ a couple functions in this class.
+ It takes a column or table name (optionally with an alias)
+ and inserts
+ the table prefix onto it. Some logic is necessary in order
+ to deal with
+ column names that include the path. Consider a query like this::
+
+ SELECT * FROM hostname.database.table.column AS c FROM hostname.database.table
+
+ Or a query with aliasing::
+
+ SELECT m.member_id, m.member_name FROM members AS m
+
+ Since the column name can include up to four segments
+ (host, DB, table, column)
+ or also have an alias prefix, we need to do a bit of work
+ to figure this out and
+ insert the table prefix (if it exists) in the proper position,
+ and escape only
+ the correct identifiers.
\ No newline at end of file
diff --git a/user_guide_src/source/database/index.rst b/user_guide_src/source/database/index.rst
index 4612daf..2fb50f9 100644
--- a/user_guide_src/source/database/index.rst
+++ b/user_guide_src/source/database/index.rst
@@ -21,4 +21,5 @@
Custom Function Calls <call_function>
Query Caching <caching>
Database Manipulation with Database Forge <forge>
- Database Utilities Class <utilities>
\ No newline at end of file
+ Database Utilities Class <utilities>
+ Database Driver Reference <db_driver_reference>
\ No newline at end of file