summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/database/db_driver_reference.rst
diff options
context:
space:
mode:
authorAndrey Andreev <narf@devilix.net>2019-01-16 16:49:35 +0100
committerAndrey Andreev <narf@devilix.net>2019-01-16 16:49:35 +0100
commitc576995304fc3609cca0b7b92d1b2cd611ec82f5 (patch)
treec8b9121cb295b56bbabe3aeaad0a3eb1f2d390bb /user_guide_src/source/database/db_driver_reference.rst
parent4eaf80a6ec0b58a0adc95638153363e00ebf5378 (diff)
[ci skip] 3.1.10 release
Diffstat (limited to 'user_guide_src/source/database/db_driver_reference.rst')
-rw-r--r--user_guide_src/source/database/db_driver_reference.rst439
1 files changed, 0 insertions, 439 deletions
diff --git a/user_guide_src/source/database/db_driver_reference.rst b/user_guide_src/source/database/db_driver_reference.rst
deleted file mode 100644
index 1f036cd77..000000000
--- a/user_guide_src/source/database/db_driver_reference.rst
+++ /dev/null
@@ -1,439 +0,0 @@
-###################
-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.
-
-.. important:: Not all methods are supported by all database drivers,
- some of them may fail (and return FALSE) if the underlying
- driver does not support them.
-
-.. php:class:: CI_DB_driver
-
- .. php:method:: initialize()
-
- :returns: TRUE on success, FALSE on failure
- :rtype: bool
-
- Initialize database settings, establish a connection to
- the database.
-
- .. php:method:: db_connect($persistent = TRUE)
-
- :param bool $persistent: Whether to establish a persistent connection or a regular one
- :returns: Database connection resource/object or FALSE on failure
- :rtype: mixed
-
- Establish a connection with the database.
-
- .. note:: The returned value depends on the underlying
- driver in use. For example, a ``mysqli`` instance
- will be returned with the 'mysqli' driver.
-
- .. php:method:: db_pconnect()
-
- :returns: Database connection resource/object or FALSE on failure
- :rtype: mixed
-
- Establish a persistent connection with the database.
-
- .. note:: This method is just an alias for ``db_connect(TRUE)``.
-
- .. php:method:: reconnect()
-
- :returns: TRUE on success, FALSE on failure
- :rtype: bool
-
- Keep / reestablish the database connection if no queries
- have been sent for a length of time exceeding the
- server's idle timeout.
-
- .. php:method:: db_select([$database = ''])
-
- :param string $database: Database name
- :returns: TRUE on success, FALSE on failure
- :rtype: bool
-
- Select / switch the current database.
-
- .. php:method:: db_set_charset($charset)
-
- :param string $charset: Character set name
- :returns: TRUE on success, FALSE on failure
- :rtype: bool
-
- Set client character set.
-
- .. php:method:: platform()
-
- :returns: Platform name
- :rtype: string
-
- The name of the platform in use (mysql, mssql, etc...).
-
- .. php:method:: version()
-
- :returns: The version of the database being used
- :rtype: string
-
- Database version number.
-
- .. php: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: Whether to return a result object or not
- :returns: TRUE for successful "write-type" queries, CI_DB_result instance (method chaining) on "query" success, FALSE on failure
- :rtype: mixed
-
- Execute an SQL 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" queries
- - Boolean FALSE upon failure
- - ``CI_DB_result`` object for "read type" queries
-
- .. note: If 'db_debug' setting is set to TRUE, an error
- page will be displayed instead of returning FALSE
- on failures and script execution will stop.
-
- .. php:method:: simple_query($sql)
-
- :param string $sql: The SQL statement to execute
- :returns: Whatever the underlying driver's "query" function returns
- :rtype: mixed
-
- A simplified version of the ``query()`` method, appropriate
- for use when you don't need to get a result object or to
- just send a query to the database and not care for the result.
-
- .. php:method:: affected_rows()
-
- :returns: Number of rows affected
- :rtype: int
-
- Returns the number of rows *changed* by the last executed query.
-
- Useful for checking how much rows were created, updated or deleted
- during the last executed query.
-
- .. php:method:: trans_strict([$mode = TRUE])
-
- :param bool $mode: Strict mode flag
- :rtype: void
-
- Enable/disable transaction "strict" mode.
-
- When strict mode is enabled, if you are running multiple
- groups of transactions and one group fails, all subsequent
- 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.
-
- .. php:method:: trans_off()
-
- :rtype: void
-
- Disables transactions at run-time.
-
- .. php:method:: trans_start([$test_mode = FALSE])
-
- :param bool $test_mode: Test mode flag
- :returns: TRUE on success, FALSE on failure
- :rtype: bool
-
- Start a transaction.
-
- .. php:method:: trans_complete()
-
- :returns: TRUE on success, FALSE on failure
- :rtype: bool
-
- Complete Transaction.
-
- .. php:method:: trans_status()
-
- :returns: TRUE if the transaction succeeded, FALSE if it failed
- :rtype: bool
-
- Lets you retrieve the transaction status flag to
- determine if it has failed.
-
- .. php: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
-
- Compiles an SQL query with the bind values passed for it.
-
- .. php:method:: is_write_type($sql)
-
- :param string $sql: The SQL statement
- :returns: TRUE if the SQL statement is of "write type", FALSE if not
- :rtype: bool
-
- Determines if a query is of a "write" type (such as
- INSERT, UPDATE, DELETE) or "read" type (i.e. SELECT).
-
- .. php: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.
-
- .. php:method:: total_queries()
-
- :returns: The total number of queries executed
- :rtype: int
-
- Returns the total number of queries that have been
- executed so far.
-
- .. php:method:: last_query()
-
- :returns: The last query executed
- :rtype: string
-
- Returns the last query that was executed.
-
- .. php:method:: escape($str)
-
- :param mixed $str: The value to escape, or an array of multiple ones
- :returns: The escaped value(s)
- :rtype: mixed
-
- Escapes input data based on type, including boolean and
- NULLs.
-
- .. php:method:: escape_str($str[, $like = FALSE])
-
- :param mixed $str: A string value or array of multiple ones
- :param bool $like: Whether or not the string will be used in a LIKE condition
- :returns: The escaped string(s)
- :rtype: mixed
-
- Escapes string values.
-
- .. warning:: The returned strings do NOT include quotes
- around them.
-
- .. php:method:: escape_like_str($str)
-
- :param mixed $str: A string value or array of multiple ones
- :returns: The escaped string(s)
- :rtype: mixed
-
- Escape LIKE strings.
-
- Similar to ``escape_str()``, but will also escape the ``%``
- and ``_`` wildcard characters, so that they don't cause
- false-positives in LIKE conditions.
-
- .. important:: The ``escape_like_str()`` method uses '!' (exclamation mark)
- to escape special characters for *LIKE* conditions. Because this
- method escapes partial strings that you would wrap in quotes
- yourself, it cannot automatically add the ``ESCAPE '!'``
- condition for you, and so you'll have to manually do that.
-
-
- .. php:method:: primary($table)
-
- :param string $table: Table name
- :returns: The primary key name, FALSE if none
- :rtype: string
-
- Retrieves the primary key of a table.
-
- .. note:: If the database platform does not support primary
- key detection, the first column name may be assumed
- as the primary key.
-
- .. php:method:: count_all([$table = ''])
-
- :param string $table: Table name
- :returns: Row count for the specified table
- :rtype: int
-
- Returns the total number of rows in a table, or 0 if no
- table was provided.
-
- .. php:method:: list_tables([$constrain_by_prefix = FALSE])
-
- :param bool $constrain_by_prefix: TRUE to match table names by the configured dbprefix
- :returns: Array of table names or FALSE on failure
- :rtype: array
-
- Gets a list of the tables in the current database.
-
- .. php:method:: table_exists($table_name)
-
- :param string $table_name: The table name
- :returns: TRUE if that table exists, FALSE if not
- :rtype: bool
-
- Determine if a particular table exists.
-
- .. php:method:: list_fields($table)
-
- :param string $table: The table name
- :returns: Array of field names or FALSE on failure
- :rtype: array
-
- Gets a list of the field names in a table.
-
- .. php: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, FALSE if not
- :rtype: bool
-
- Determine if a particular field exists.
-
- .. php:method:: field_data($table)
-
- :param string $table: The table name
- :returns: Array of field data items or FALSE on failure
- :rtype: array
-
- Gets a list containing field data about a table.
-
- .. php:method:: escape_identifiers($item)
-
- :param mixed $item: The item or array of items to escape
- :returns: The input item(s), escaped
- :rtype: mixed
-
- Escape SQL identifiers, such as column, table and names.
-
- .. php:method:: insert_string($table, $data)
-
- :param string $table: The target table
- :param array $data: An associative array of key/value pairs
- :returns: The SQL INSERT statement, as a string
- :rtype: string
-
- Generate an INSERT statement string.
-
- .. php:method:: update_string($table, $data, $where)
-
- :param string $table: The target table
- :param array $data: An associative array of key/value pairs
- :param mixed $where: The WHERE statement conditions
- :returns: The SQL UPDATE statement, as a string
- :rtype: string
-
- Generate an UPDATE statement string.
-
- .. php:method:: call_function($function)
-
- :param string $function: Function name
- :returns: The function result
- :rtype: string
-
- Runs a native PHP function , using a platform agnostic
- wrapper.
-
- .. php:method:: cache_set_path([$path = ''])
-
- :param string $path: Path to the cache directory
- :rtype: void
-
- Sets the directory path to use for caching storage.
-
- .. php:method:: cache_on()
-
- :returns: TRUE if caching is on, FALSE if not
- :rtype: bool
-
- Enable database results caching.
-
- .. php:method:: cache_off()
-
- :returns: TRUE if caching is on, FALSE if not
- :rtype: bool
-
- Disable database results caching.
-
- .. php: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: bool
-
- Delete the cache files associated with a particular URI.
-
- .. php:method:: cache_delete_all()
-
- :returns: TRUE on success, FALSE on failure
- :rtype: bool
-
- Delete all cache files.
-
- .. php:method:: close()
-
- :rtype: void
-
- Close the DB Connection.
-
- .. php:method:: display_error([$error = ''[, $swap = ''[, $native = FALSE]]])
-
- :param string $error: The error message
- :param string $swap: Any "swap" values
- :param bool $native: Whether to localize the message
- :rtype: void
-
- :returns: Displays the DB error screensends the application/views/errors/error_db.php template
- :rtype: string
-
- Display an error message and stop script execution.
-
- The message is displayed using the
- *application/views/errors/error_db.php* template.
-
- .. php:method:: protect_identifiers($item[, $prefix_single = FALSE[, $protect_identifiers = NULL[, $field_exists = TRUE]]])
-
- :param string $item: The item to work with
- :param bool $prefix_single: Whether to apply the dbprefix even if the input item is a single identifier
- :param bool $protect_identifiers: Whether to quote identifiers
- :param bool $field_exists: Whether the supplied item contains a field name or not
- :returns: The modified item
- :rtype: string
-
- Takes a column or table name (optionally with an alias)
- and applies the configured *dbprefix* to 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.
-
- This method is used extensively by the Query Builder class. \ No newline at end of file