diff options
| author | Andrey Andreev <narf@devilix.net> | 2015-01-12 16:23:26 +0100 |
|---|---|---|
| committer | Andrey Andreev <narf@devilix.net> | 2015-01-12 16:23:26 +0100 |
| commit | 45a8afaabc6d09ad59bbb3c89a6cdfe8cbc3312c (patch) | |
| tree | 7ca4207099f9225b5ef74b31f48627a282e7fdf2 /user_guide_src/source/database | |
| parent | cd94dd7e1d8969658810ccc4158a75d2936d0a44 (diff) | |
| parent | 934d6d9797f4dadd4e4d05b12bc4d7309fedb6c3 (diff) | |
Merge branch 'develop' into feature/session
Diffstat (limited to 'user_guide_src/source/database')
| -rw-r--r-- | user_guide_src/source/database/configuration.rst | 3 | ||||
| -rw-r--r-- | user_guide_src/source/database/db_driver_reference.rst | 420 | ||||
| -rw-r--r-- | user_guide_src/source/database/forge.rst | 136 | ||||
| -rw-r--r-- | user_guide_src/source/database/helpers.rst | 61 | ||||
| -rw-r--r-- | user_guide_src/source/database/index.rst | 8 | ||||
| -rw-r--r-- | user_guide_src/source/database/metadata.rst (renamed from user_guide_src/source/database/fields.rst) | 70 | ||||
| -rw-r--r-- | user_guide_src/source/database/queries.rst | 24 | ||||
| -rw-r--r-- | user_guide_src/source/database/query_builder.rst | 745 | ||||
| -rw-r--r-- | user_guide_src/source/database/results.rst | 272 | ||||
| -rw-r--r-- | user_guide_src/source/database/table_data.rst | 31 | ||||
| -rw-r--r-- | user_guide_src/source/database/utilities.rst | 131 |
11 files changed, 1606 insertions, 295 deletions
diff --git a/user_guide_src/source/database/configuration.rst b/user_guide_src/source/database/configuration.rst index 34cefffbd..9f52ad2a2 100644 --- a/user_guide_src/source/database/configuration.rst +++ b/user_guide_src/source/database/configuration.rst @@ -141,7 +141,8 @@ Query Builder The :doc:`Query Builder Class <query_builder>` is globally enabled or disabled by setting the $query_builder variable in the database -configuration file to TRUE/FALSE (boolean). If you are not using the +configuration file to TRUE/FALSE (boolean). The default setting is TRUE. +If you are not using the query builder class, setting it to FALSE will utilize fewer resources when the database classes are initialized. 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 000000000..7bee555c8 --- /dev/null +++ b/user_guide_src/source/database/db_driver_reference.rst @@ -0,0 +1,420 @@ +################### +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. + +.. class:: CI_DB_driver + + .. method:: initialize() + + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Initialize database settings, establish a connection to + the database. + + .. 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. + + .. 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)``. + + .. 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. + + .. method:: db_select([$database = '']) + + :param string $database: Database name + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Select / switch the current database. + + .. method:: db_set_charset($charset) + + :param string $charset: Character set name + :returns: TRUE on success, FALSE on failure + :rtype: bool + + 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: 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. + + .. 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. + + .. 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 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_off() + + :rtype: void + + Disables transactions at run-time. + + .. method:: trans_start([$test_mode = FALSE]) + + :param bool $test_mode: Test mode flag + :rtype: void + + Start a transaction. + + .. method:: trans_complete() + + :rtype: void + + Complete Transaction. + + .. 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. + + .. 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. + + .. 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). + + .. 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 executed + :rtype: int + + Returns the total number of queries that have been + executed so far. + + .. method:: last_query() + + :returns: The last query executed + :rtype: string + + Returns the last query that was executed. + + .. 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. + + .. 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. + + .. 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. + + .. 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. + + .. 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. + + .. 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. + + .. 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. + + .. 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. + + .. 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. + + .. 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. + + .. 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. + + .. 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. + + .. 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. + + .. 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. + + .. method:: cache_set_path([$path = '']) + + :param string $path: Path to the cache directory + :rtype: void + + Sets the directory path to use for caching storage. + + .. method:: cache_on() + + :returns: TRUE if caching is on, FALSE if not + :rtype: bool + + Enable database results caching. + + .. method:: cache_off() + + :returns: TRUE if caching is on, FALSE if not + :rtype: bool + + Disable database results 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: bool + + Delete the cache files associated with a particular URI. + + .. method:: cache_delete_all() + + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Delete all cache files. + + .. method:: close() + + :rtype: void + + Close the DB Connection. + + .. 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. + + .. 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 diff --git a/user_guide_src/source/database/forge.rst b/user_guide_src/source/database/forge.rst index 48642ad7e..59a6591b7 100644 --- a/user_guide_src/source/database/forge.rst +++ b/user_guide_src/source/database/forge.rst @@ -6,6 +6,7 @@ The Database Forge Class contains methods that help you manage your database. .. contents:: Table of Contents + :depth: 3 **************************** Initializing the Forge Class @@ -35,8 +36,11 @@ object:: $this->dbforge->some_method(); -$this->dbforge->create_database('db_name') -========================================== +******************************* +Creating and Dropping Databases +******************************* + +**$this->dbforge->create_database('db_name')** Permits you to create the database specified in the first parameter. Returns TRUE/FALSE based on success or failure:: @@ -46,8 +50,7 @@ Returns TRUE/FALSE based on success or failure:: echo 'Database created!'; } -$this->dbforge->drop_database('db_name') -========================================== +**$this->dbforge->drop_database('db_name')** Permits you to drop the database specified in the first parameter. Returns TRUE/FALSE based on success or failure:: @@ -57,6 +60,7 @@ Returns TRUE/FALSE based on success or failure:: echo 'Database deleted!'; } + **************************** Creating and Dropping Tables **************************** @@ -123,11 +127,11 @@ After the fields have been defined, they can be added using ``$this->dbforge->add_field($fields);`` followed by a call to the ``create_table()`` method. -$this->dbforge->add_field() ---------------------------- +**$this->dbforge->add_field()** The add fields method will accept the above array. + Passing strings as fields ------------------------- @@ -211,6 +215,7 @@ You could also pass optional table attributes, such as MySQL's ``ENGINE``:: ``create_table()`` will always add them with your configured *char_set* and *dbcollat* values, as long as they are not empty (MySQL only). + Dropping a table ================ @@ -224,6 +229,7 @@ Execute a DROP TABLE statement and optionally add an IF EXISTS clause. // Produces: DROP TABLE IF EXISTS table_name $this->dbforge->drop_table('table_name'); + Renaming a table ================ @@ -239,8 +245,10 @@ Executes a TABLE rename Modifying Tables **************** -$this->dbforge->add_column() -============================ +Adding a Column to a Table +========================== + +**$this->dbforge->add_column()** The ``add_column()`` method is used to modify an existing table. It accepts the same field array as above, and can be used for an unlimited @@ -269,8 +277,11 @@ Examples:: 'preferences' => array('type' => 'TEXT', 'first' => TRUE) ); -$this->dbforge->drop_column() -============================= + +Dropping a Column From a Table +============================== + +**$this->dbforge->drop_column()** Used to remove a column from a table. @@ -279,8 +290,11 @@ Used to remove a column from a table. $this->dbforge->drop_column('table_name', 'column_to_drop'); -$this->dbforge->modify_column() -=============================== + +Modifying a Column in a Table +============================= + +**$this->dbforge->modify_column()** The usage of this method is identical to ``add_column()``, except it alters an existing column rather than adding a new one. In order to @@ -295,4 +309,100 @@ change the name you can add a "name" key into the field defining array. ), ); $this->dbforge->modify_column('table_name', $fields); - // gives ALTER TABLE table_name CHANGE old_name new_name TEXT
\ No newline at end of file + // gives ALTER TABLE table_name CHANGE old_name new_name TEXT + + +*************** +Class Reference +*************** + +.. class:: CI_DB_forge + + .. method:: add_column($table[, $field = array()[, $_after = NULL]]) + + :param string $table: Table name to add the column to + :param array $field: Column definition(s) + :param string $_after: Column for AFTER clause (deprecated) + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Adds a column to a table. Usage: See `Adding a Column to a Table`_. + + .. method:: add_field($field) + + :param array $field: Field definition to add + :returns: CI_DB_forge instance (method chaining) + :rtype: CI_DB_forge + + Adds a field to the set that will be used to create a table. Usage: See `Adding fields`_. + + .. method:: add_key($key[, $primary = FALSE]) + + :param array $key: Name of a key field + :param bool $primary: Set to TRUE if it should be a primary key or a regular one + :returns: CI_DB_forge instance (method chaining) + :rtype: CI_DB_forge + + Adds a key to the set that will be used to create a table. Usage: See `Adding Keys`_. + + .. method:: create_database($db_name) + + :param string $db_name: Name of the database to create + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Creates a new database. Usage: See `Creating and Dropping Databases`_. + + .. method:: create_table($table[, $if_not_exists = FALSE[, array $attributes = array()]]) + + :param string $table: Name of the table to create + :param string $if_not_exists: Set to TRUE to add an 'IF NOT EXISTS' clause + :param string $attributes: An associative array of table attributes + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Creates a new table. Usage: See `Creating a table`_. + + .. method:: drop_column($table, $column_name) + + :param string $table: Table name + :param array $column_name: The column name to drop + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Drops a column from a table. Usage: See `Dropping a Column From a Table`_. + + .. method:: drop_database($db_name) + + :param string $db_name: Name of the database to drop + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Drops a database. Usage: See `Creating and Dropping Databases`_. + + .. method:: drop_table($table_name[, $if_exists = FALSE]) + + :param string $table: Name of the table to drop + :param string $if_exists: Set to TRUE to add an 'IF EXISTS' clause + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Drops a table. Usage: See `Dropping a table`_. + + .. method:: modify_column($table, $field) + + :param string $table: Table name + :param array $field: Column definition(s) + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Modifies a table column. Usage: See `Modifying a Column in a Table`_. + + .. method:: rename_table($table_name, $new_table_name) + + :param string $table: Current of the table + :param string $new_table_name: New name of the table + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Renames a table. Usage: See `Renaming a table`_.
\ No newline at end of file diff --git a/user_guide_src/source/database/helpers.rst b/user_guide_src/source/database/helpers.rst index 77bf1b5d2..2d997a9e0 100644 --- a/user_guide_src/source/database/helpers.rst +++ b/user_guide_src/source/database/helpers.rst @@ -1,9 +1,11 @@ -###################### -Query Helper Functions -###################### +#################### +Query Helper Methods +#################### -$this->db->insert_id() -====================== +Information From Executing a Query +================================== + +**$this->db->insert_id()** The insert ID number when performing database inserts. @@ -11,8 +13,7 @@ The insert ID number when performing database inserts. driver, this function requires a $name parameter, which specifies the appropriate sequence to check for the insert id. -$this->db->affected_rows() -========================== +**$this->db->affected_rows()** Displays the number of affected rows, when doing "write" type queries (insert, update, etc.). @@ -22,8 +23,23 @@ Displays the number of affected rows, when doing "write" type queries affected rows. By default this hack is enabled but it can be turned off in the database driver file. -$this->db->count_all() -====================== +**$this->db->last_query()** + +Returns the last query that was run (the query string, not the result). +Example:: + + $str = $this->db->last_query(); + + // Produces: SELECT * FROM sometable.... + + +.. note:: Disabling the **save_queries** setting in your database + configuration will render this function useless. + +Information About Your Database +=============================== + +**$this->db->count_all()** Permits you to determine the number of rows in a particular table. Submit the table name in the first parameter. Example:: @@ -32,38 +48,24 @@ Submit the table name in the first parameter. Example:: // Produces an integer, like 25 -$this->db->platform() -===================== +**$this->db->platform()** Outputs the database platform you are running (MySQL, MS SQL, Postgres, etc...):: echo $this->db->platform(); -$this->db->version() -==================== +**$this->db->version()** Outputs the database version you are running:: echo $this->db->version(); -$this->db->last_query() -======================= - -Returns the last query that was run (the query string, not the result). -Example:: - - $str = $this->db->last_query(); - - // Produces: SELECT * FROM sometable.... - - -.. note:: Disabling the **save_queries** setting in your database - configuration will render this function useless. - -$this->db->insert_string() +Making Your Queries Easier ========================== +**$this->db->insert_string()** + This function simplifies the process of writing database inserts. It returns a correctly formatted SQL insert string. Example:: @@ -78,8 +80,7 @@ array with the data to be inserted. The above example produces:: .. note:: Values are automatically escaped, producing safer queries. -$this->db->update_string() -========================== +**$this->db->update_string()** This function simplifies the process of writing database updates. It returns a correctly formatted SQL update string. Example:: diff --git a/user_guide_src/source/database/index.rst b/user_guide_src/source/database/index.rst index 7ccb8fb00..2fb50f9be 100644 --- a/user_guide_src/source/database/index.rst +++ b/user_guide_src/source/database/index.rst @@ -1,5 +1,5 @@ ################## -The Database Class +Database Reference ################## CodeIgniter comes with a full-featured and very fast abstracted database @@ -17,9 +17,9 @@ patterns. The database functions offer clear, simple syntax. Query Helper Functions <helpers> Query Builder Class <query_builder> Transactions <transactions> - Table MetaData <table_data> - Field MetaData <fields> + Getting MetaData <metadata> 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 diff --git a/user_guide_src/source/database/fields.rst b/user_guide_src/source/database/metadata.rst index b706ace7d..b8be809b6 100644 --- a/user_guide_src/source/database/fields.rst +++ b/user_guide_src/source/database/metadata.rst @@ -1,9 +1,53 @@ -########## -Field Data -########## +################# +Database Metadata +################# -$this->db->list_fields() -========================= +************** +Table MetaData +************** + +These functions let you fetch table information. + +List the Tables in Your Database +================================ + +**$this->db->list_tables();** + +Returns an array containing the names of all the tables in the database +you are currently connected to. Example:: + + $tables = $this->db->list_tables(); + + foreach ($tables as $table) + { + echo $table; + } + + +Determine If a Table Exists +=========================== + +**$this->db->table_exists();** + +Sometimes it's helpful to know whether a particular table exists before +running an operation on it. Returns a boolean TRUE/FALSE. Usage example:: + + if ($this->db->table_exists('table_name')) + { + // some code... + } + +.. note:: Replace *table_name* with the name of the table you are looking for. + + +************** +Field MetaData +************** + +List the Fields in a Table +========================== + +**$this->db->list_fields()** Returns an array containing the field names. This query can be called two ways: @@ -28,8 +72,11 @@ calling the function from your query result object:: echo $field; } -$this->db->field_exists() -========================== + +Determine If a Field is Present in a Table +========================================== + +**$this->db->field_exists()** Sometimes it's helpful to know whether a particular field exists before performing an action. Returns a boolean TRUE/FALSE. Usage example:: @@ -43,8 +90,11 @@ performing an action. Returns a boolean TRUE/FALSE. Usage example:: for, and replace *table_name* with the name of the table you are looking for. -$this->db->field_data() -======================== + +Retrieve Field Metadata +======================= + +**$this->db->field_data()** Returns an array of objects containing field information. @@ -77,4 +127,4 @@ database: - name - column name - max_length - maximum length of the column - primary_key - 1 if the column is a primary key -- type - the type of the column
\ No newline at end of file +- type - the type of the column diff --git a/user_guide_src/source/database/queries.rst b/user_guide_src/source/database/queries.rst index 76ff1083f..43a0a30bf 100644 --- a/user_guide_src/source/database/queries.rst +++ b/user_guide_src/source/database/queries.rst @@ -2,10 +2,14 @@ Queries ####### -$this->db->query(); -=================== +************ +Query Basics +************ -To submit a query, use the following function:: +Regular Queries +=============== + +To submit a query, use the **query** function:: $this->db->query('YOUR QUERY HERE'); @@ -18,10 +22,11 @@ this:: $query = $this->db->query('YOUR QUERY HERE'); -$this->db->simple_query(); -========================== +Simplified Queries +================== -This is a simplified version of the $this->db->query() method. It DOES +The **simple_query** method is a simplified version of the +$this->db->query() method. It DOES NOT return a database result set, nor does it set the query timer, or compile bind data, or store your query for debugging. It simply lets you submit a query. Most users will rarely use this function. @@ -116,7 +121,9 @@ this: :: - $search = '20% raise'; $sql = "SELECT id FROM table WHERE column LIKE '%".$this->db->escape_like_str($search)."%'"; + $search = '20% raise'; + $sql = "SELECT id FROM table WHERE column LIKE '%" . + $this->db->escape_like_str($search)."%'"; ************** @@ -150,8 +157,7 @@ you. Handling Errors *************** -$this->db->error(); -=================== +**$this->db->error();** If you need to get the last error that has occured, the error() method will return an array containing its code and message. Here's a quick diff --git a/user_guide_src/source/database/query_builder.rst b/user_guide_src/source/database/query_builder.rst index 5bfdfdb52..b06396e96 100644 --- a/user_guide_src/source/database/query_builder.rst +++ b/user_guide_src/source/database/query_builder.rst @@ -2,8 +2,8 @@ Query Builder Class ################### -CodeIgniter gives you access to a Query Builder class. This pattern -allows information to be retrieved, inserted, and updated in your +CodeIgniter gives you access to a Query Builder class. This pattern +allows information to be retrieved, inserted, and updated in your database with minimal scripting. In some cases only one or two lines of code are necessary to perform a database action. CodeIgniter does not require that each database table be its own class @@ -19,7 +19,9 @@ system. class in your database config file, allowing the core database library and adapter to utilize fewer resources. -.. contents:: Page Contents +.. contents:: + :local: + :depth: 1 ************** Selecting Data @@ -27,8 +29,7 @@ Selecting Data The following functions allow you to build SQL **SELECT** statements. -$this->db->get() -================ +**$this->db->get()** Runs the selection query and returns the result. Can be used by itself to retrieve all records from a table:: @@ -39,7 +40,9 @@ The second and third parameters enable you to set a limit and offset clause:: $query = $this->db->get('mytable', 10, 20); - // Produces: SELECT * FROM mytable LIMIT 20, 10 (in MySQL. Other databases have slightly different syntax) + + // Executes: SELECT * FROM mytable LIMIT 20, 10 + // (in MySQL. Other databases have slightly different syntax) You'll notice that the above function is assigned to a variable named $query, which can be used to show the results:: @@ -54,10 +57,9 @@ $query, which can be used to show the results:: Please visit the :doc:`result functions <results>` page for a full discussion regarding result generation. -$this->db->get_compiled_select() -================================ +**$this->db->get_compiled_select()** -Compiles the selection query just like `$this->db->get()`_ but does not *run* +Compiles the selection query just like **$this->db->get()** but does not *run* the query. This method simply returns the SQL query as a string. Example:: @@ -65,28 +67,27 @@ Example:: $sql = $this->db->get_compiled_select('mytable'); echo $sql; - // Produces string: SELECT * FROM mytable + // Prints string: SELECT * FROM mytable The second parameter enables you to set whether or not the query builder query will be reset (by default it will be reset, just like when using `$this->db->get()`):: echo $this->db->limit(10,20)->get_compiled_select('mytable', FALSE); - // Produces string: SELECT * FROM mytable LIMIT 20, 10 + + // Prints string: SELECT * FROM mytable LIMIT 20, 10 // (in MySQL. Other databases have slightly different syntax) echo $this->db->select('title, content, date')->get_compiled_select(); - // Produces string: SELECT title, content, date FROM mytable LIMIT 20, 10 + // Prints string: SELECT title, content, date FROM mytable LIMIT 20, 10 The key thing to notice in the above example is that the second query did not -utilize `$this->db->from()`_ and did not pass a table name into the first +utilize **$this->db->from()** and did not pass a table name into the first parameter. The reason for this outcome is because the query has not been -executed using `$this->db->get()`_ which resets values or reset directly -using `$this->db->reset_query()`_. +executed using **$this->db->get()** which resets values or reset directly +using **$this->db->reset_query()**. - -$this->db->get_where() -====================== +**$this->db->get_where()** Identical to the above function except that it permits you to add a "where" clause in the second parameter, instead of using the db->where() @@ -98,32 +99,32 @@ Please read the about the where function below for more information. .. note:: get_where() was formerly known as getwhere(), which has been removed -$this->db->select() -=================== +**$this->db->select()** Permits you to write the SELECT portion of your query:: $this->db->select('title, content, date'); - $query = $this->db->get('mytable'); // Produces: SELECT title, content, date FROM mytable + $query = $this->db->get('mytable'); + // Executes: SELECT title, content, date FROM mytable .. note:: If you are selecting all (\*) from a table you do not need to - use this function. When omitted, CodeIgniter assumes you wish to SELECT * + use this function. When omitted, CodeIgniter assumes that you wish + to select all fields and automatically adds 'SELECT \*'. -$this->db->select() accepts an optional second parameter. If you set it -to FALSE, CodeIgniter will not try to protect your field or table names -with backticks. This is useful if you need a compound select statement. +``$this->db->select()`` accepts an optional second parameter. If you set it +to FALSE, CodeIgniter will not try to protect your field or table names. +This is useful if you need a compound select statement where automatic +escaping of fields may break them. :: $this->db->select('(SELECT SUM(payments.amount) FROM payments WHERE payments.invoice_id=4') AS amount_paid', FALSE); $query = $this->db->get('mytable'); +**$this->db->select_max()** -$this->db->select_max() -======================= - -Writes a "SELECT MAX(field)" portion for your query. You can optionally +Writes a ``SELECT MAX(field)`` portion for your query. You can optionally include a second parameter to rename the resulting field. :: @@ -135,8 +136,7 @@ include a second parameter to rename the resulting field. $query = $this->db->get('members'); // Produces: SELECT MAX(age) as member_age FROM members -$this->db->select_min() -======================= +**$this->db->select_min()** Writes a "SELECT MIN(field)" portion for your query. As with select_max(), You can optionally include a second parameter to rename @@ -148,8 +148,7 @@ the resulting field. $query = $this->db->get('members'); // Produces: SELECT MIN(age) as age FROM members -$this->db->select_avg() -======================= +**$this->db->select_avg()** Writes a "SELECT AVG(field)" portion for your query. As with select_max(), You can optionally include a second parameter to rename @@ -161,8 +160,7 @@ the resulting field. $query = $this->db->get('members'); // Produces: SELECT AVG(age) as age FROM members -$this->db->select_sum() -======================= +**$this->db->select_sum()** Writes a "SELECT SUM(field)" portion for your query. As with select_max(), You can optionally include a second parameter to rename @@ -173,9 +171,7 @@ the resulting field. $this->db->select_sum('age'); $query = $this->db->get('members'); // Produces: SELECT SUM(age) as age FROM members - -$this->db->from() -================= +**$this->db->from()** Permits you to write the FROM portion of your query:: @@ -186,8 +182,7 @@ Permits you to write the FROM portion of your query:: .. note:: As shown earlier, the FROM portion of your query can be specified in the $this->db->get() function, so use whichever method you prefer. -$this->db->join() -================= +**$this->db->join()** Permits you to write the JOIN portion of your query:: @@ -211,8 +206,11 @@ outer, and right outer. $this->db->join('comments', 'comments.id = blogs.id', 'left'); // Produces: LEFT JOIN comments ON comments.id = blogs.id -$this->db->where() -================== +************************* +Looking for Specific Data +************************* + +**$this->db->where()** This function enables you to set **WHERE** clauses using one of four methods: @@ -239,6 +237,7 @@ methods: // WHERE name = 'Joe' AND title = 'boss' AND status = 'active' #. **Custom key/value method:** + You can include an operator in the first parameter in order to control the comparison: @@ -269,17 +268,14 @@ methods: $this->db->where($where); -$this->db->where() accepts an optional third parameter. If you set it to -FALSE, CodeIgniter will not try to protect your field or table names -with backticks. +``$this->db->where()`` accepts an optional third parameter. If you set it to +FALSE, CodeIgniter will not try to protect your field or table names. :: $this->db->where('MATCH (field) AGAINST ("value")', NULL, FALSE); - -$this->db->or_where() -===================== +**$this->db->or_where()** This function is identical to the one above, except that multiple instances are joined by OR:: @@ -290,8 +286,7 @@ instances are joined by OR:: .. note:: or_where() was formerly known as orwhere(), which has been removed. -$this->db->where_in() -===================== +**$this->db->where_in()** Generates a WHERE field IN ('item', 'item') SQL query joined with AND if appropriate @@ -303,8 +298,7 @@ appropriate // Produces: WHERE username IN ('Frank', 'Todd', 'James') -$this->db->or_where_in() -======================== +**$this->db->or_where_in()** Generates a WHERE field IN ('item', 'item') SQL query joined with OR if appropriate @@ -315,9 +309,7 @@ appropriate $this->db->or_where_in('username', $names); // Produces: OR username IN ('Frank', 'Todd', 'James') - -$this->db->where_not_in() -========================= +**$this->db->where_not_in()** Generates a WHERE field NOT IN ('item', 'item') SQL query joined with AND if appropriate @@ -329,8 +321,7 @@ AND if appropriate // Produces: WHERE username NOT IN ('Frank', 'Todd', 'James') -$this->db->or_where_not_in() -============================ +**$this->db->or_where_not_in()** Generates a WHERE field NOT IN ('item', 'item') SQL query joined with OR if appropriate @@ -341,9 +332,11 @@ if appropriate $this->db->or_where_not_in('username', $names); // Produces: OR username NOT IN ('Frank', 'Todd', 'James') +************************ +Looking for Similar Data +************************ -$this->db->like() -================= +**$this->db->like()** This method enables you to generate **LIKE** clauses, useful for doing searches. @@ -383,8 +376,7 @@ searches. // WHERE `title` LIKE '%match%' ESCAPE '!' AND `page1` LIKE '%match%' ESCAPE '!' AND `page2` LIKE '%match%' ESCAPE '!' -$this->db->or_like() -==================== +**$this->db->or_like()** This method is identical to the one above, except that multiple instances are joined by OR:: @@ -394,16 +386,14 @@ instances are joined by OR:: .. note:: ``or_like()`` was formerly known as ``orlike()``, which has been removed. -$this->db->not_like() -===================== +**$this->db->not_like()** This method is identical to ``like()``, except that it generates NOT LIKE statements:: $this->db->not_like('title', 'match'); // WHERE `title` NOT LIKE '%match% ESCAPE '!' -$this->db->or_not_like() -======================== +**$this->db->or_not_like()** This method is identical to ``not_like()``, except that multiple instances are joined by OR:: @@ -412,8 +402,7 @@ instances are joined by OR:: $this->db->or_not_like('body', 'match'); // WHERE `title` LIKE '%match% OR `body` NOT LIKE '%match%' ESCAPE '!' -$this->db->group_by() -===================== +**$this->db->group_by()** Permits you to write the GROUP BY portion of your query:: @@ -426,8 +415,7 @@ You can also pass an array of multiple values as well:: .. note:: group_by() was formerly known as groupby(), which has been removed. -$this->db->distinct() -===================== +**$this->db->distinct()** Adds the "DISTINCT" keyword to a query @@ -436,9 +424,7 @@ Adds the "DISTINCT" keyword to a query $this->db->distinct(); $this->db->get('table'); // Produces: SELECT DISTINCT * FROM table - -$this->db->having() -=================== +**$this->db->having()** Permits you to write the HAVING portion of your query. There are 2 possible syntaxes, 1 argument or 2:: @@ -462,13 +448,15 @@ setting it to FALSE. $this->db->having('user_id', 45, FALSE); // Produces: HAVING user_id = 45 -$this->db->or_having() -====================== +**$this->db->or_having()** Identical to having(), only separates multiple clauses with "OR". -$this->db->order_by() -===================== +**************** +Ordering results +**************** + +**$this->db->order_by()** Lets you set an ORDER BY clause. @@ -512,8 +500,11 @@ be ignored, unless you specify a numeric seed value. .. note:: Random ordering is not currently supported in Oracle and will default to ASC instead. -$this->db->limit() -================== +**************************** +Limiting or Counting Results +**************************** + +**$this->db->limit()** Lets you limit the number of rows you would like returned by the query:: @@ -525,8 +516,7 @@ The second parameter lets you set a result offset. $this->db->limit(10, 20); // Produces: LIMIT 20, 10 (in MySQL. Other databases have slightly different syntax) -$this->db->count_all_results() -============================== +**$this->db->count_all_results()** Permits you to determine the number of rows in a particular Active Record query. Queries will accept Query Builder restrictors such as @@ -537,8 +527,7 @@ where(), or_where(), like(), or_like(), etc. Example:: $this->db->from('my_table'); echo $this->db->count_all_results(); // Produces an integer, like 17 -$this->db->count_all() -====================== +**$this->db->count_all()** Permits you to determine the number of rows in a particular table. Submit the table name in the first parameter. Example:: @@ -568,28 +557,23 @@ you to create queries with complex WHERE clauses. Nested groups are supported. E .. note:: groups need to be balanced, make sure every group_start() is matched by a group_end(). -$this->db->group_start() -======================== +**$this->db->group_start()** Starts a new group by adding an opening parenthesis to the WHERE clause of the query. -$this->db->or_group_start() -=========================== +**$this->db->or_group_start()** Starts a new group by adding an opening parenthesis to the WHERE clause of the query, prefixing it with 'OR'. -$this->db->not_group_start() -============================ +**$this->db->not_group_start()** Starts a new group by adding an opening parenthesis to the WHERE clause of the query, prefixing it with 'NOT'. -$this->db->or_not_group_start() -=============================== +**$this->db->or_not_group_start()** Starts a new group by adding an opening parenthesis to the WHERE clause of the query, prefixing it with 'OR NOT'. -$this->db->group_end() -====================== +**$this->db->group_end()** Ends the current group by adding an closing parenthesis to the WHERE clause of the query. @@ -597,8 +581,7 @@ Ends the current group by adding an closing parenthesis to the WHERE clause of t Inserting Data ************** -$this->db->insert() -=================== +**$this->db->insert()** Generates an insert string based on the data you supply, and runs the query. You can either pass an **array** or an **object** to the @@ -635,9 +618,9 @@ object. .. note:: All values are escaped automatically producing safer queries. -$this->db->get_compiled_insert() -================================ -Compiles the insertion query just like `$this->db->insert()`_ but does not +**$this->db->get_compiled_insert()** + +Compiles the insertion query just like $this->db->insert() but does not *run* the query. This method simply returns the SQL query as a string. Example:: @@ -654,7 +637,7 @@ Example:: // Produces string: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date') The second parameter enables you to set whether or not the query builder query -will be reset (by default it will be--just like `$this->db->insert()`_):: +will be reset (by default it will be--just like $this->db->insert()):: echo $this->db->set('title', 'My Title')->get_compiled_insert('mytable', FALSE); @@ -672,8 +655,7 @@ using `$this->db->insert()` which resets values or reset directly using .. note:: This method doesn't work for batched inserts. -$this->db->insert_batch() -========================= +**$this->db->insert_batch()** Generates an insert string based on the data you supply, and runs the query. You can either pass an **array** or an **object** to the @@ -700,8 +682,11 @@ associative array of values. .. note:: All values are escaped automatically producing safer queries. -$this->db->replace() -==================== +************* +Updating Data +************* + +**$this->db->replace()** This method executes a REPLACE statement, which is basically the SQL standard for (optional) DELETE + INSERT, using *PRIMARY* and *UNIQUE* @@ -729,8 +714,7 @@ will be deleted with our new row data replacing it. Usage of the ``set()`` method is also allowed and all fields are automatically escaped, just like with ``insert()``. -$this->db->set() -================ +**$this->db->set()** This function enables you to set values for inserts or updates. @@ -788,12 +772,7 @@ Or an object:: $this->db->set($object); $this->db->insert('mytable'); -************* -Updating Data -************* - -$this->db->update() -=================== +**$this->db->update()** Generates an update string and runs the query based on the data you supply. You can pass an **array** or an **object** to the function. Here @@ -839,9 +818,7 @@ Or as an array:: You may also use the $this->db->set() function described above when performing updates. - -$this->db->update_batch() -========================= +**$this->db->update_batch()** Generates an update string based on the data you supply, and runs the query. You can either pass an **array** or an **object** to the function. @@ -882,8 +859,7 @@ array of values, the third parameter is the where key. due to the very nature of how it works. Instead, ``update_batch()`` returns the number of rows affected. -$this->db->get_compiled_update() -================================ +**$this->db->get_compiled_update()** This works exactly the same way as ``$this->db->get_compiled_insert()`` except that it produces an UPDATE SQL string instead of an INSERT SQL string. @@ -896,8 +872,7 @@ For more information view documentation for `$this->db->get_compiled_insert()`. Deleting Data ************* -$this->db->delete() -=================== +**$this->db->delete()** Generates a delete SQL string and runs the query. @@ -930,17 +905,14 @@ delete data from more than 1 table. If you want to delete all data from a table, you can use the truncate() function, or empty_table(). -$this->db->empty_table() -======================== +**$this->db->empty_table()** Generates a delete SQL string and runs the query.:: $this->db->empty_table('mytable'); // Produces: DELETE FROM mytable - -$this->db->truncate() -===================== +**$this->db->truncate()** Generates a truncate SQL string and runs the query. @@ -959,12 +931,12 @@ Generates a truncate SQL string and runs the query. .. note:: If the TRUNCATE command isn't available, truncate() will execute as "DELETE FROM table". -$this->db->get_compiled_delete() -================================ +**$this->db->get_compiled_delete()** + This works exactly the same way as ``$this->db->get_compiled_insert()`` except that it produces a DELETE SQL string instead of an INSERT SQL string. -For more information view documentation for `$this->db->get_compiled_insert()`_. +For more information view documentation for $this->db->get_compiled_insert(). *************** Method Chaining @@ -994,23 +966,23 @@ Cached calls are cumulative. If you make 2 cached select() calls, and then 2 uncached select() calls, this will result in 4 select() calls. There are three Caching functions available: -$this->db->start_cache() -======================== +**$this->db->start_cache()** This function must be called to begin caching. All Query Builder queries of the correct type (see below for supported queries) are stored for later use. -$this->db->stop_cache() -======================= +**$this->db->stop_cache()** This function can be called to stop caching. -$this->db->flush_cache() -======================== +**$this->db->flush_cache()** This function deletes all items from the Query Builder cache. +An example of caching +--------------------- + Here's a usage example:: $this->db->start_cache(); @@ -1033,8 +1005,11 @@ Here's a usage example:: where, like, group_by, having, order_by, set -$this->db->reset_query() -======================== +*********************** +Resetting Query Builder +*********************** + +**$this->db->reset_query()** Resetting Query Builder allows you to start fresh with your query without executing it first using a method like $this->db->get() or $this->db->insert(). @@ -1063,4 +1038,506 @@ run the query:: .. note:: Double calls to ``get_compiled_select()`` while you're using the Query Builder Caching functionality and NOT resetting your queries will results in the cache being merged twice. That in turn will - i.e. if you're caching a ``select()`` - select the same field twice.
\ No newline at end of file + i.e. if you're caching a ``select()`` - select the same field twice. + +*************** +Class Reference +*************** + +.. class:: CI_DB_query_builder + + .. method:: reset_query() + + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Resets the current Query Builder state. Useful when you want + to build a query that can be cancelled under certain conditions. + + .. method:: start_cache() + + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Starts the Query Builder cache. + + .. method:: stop_cache() + + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Stops the Query Builder cache. + + .. method:: flush_cache() + + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Empties the Query Builder cache. + + .. method:: set_dbprefix([$prefix = '']) + + :param string $prefix: The new prefix to use + :returns: The DB prefix in use + :rtype: string + + Sets the database prefix, without having to reconnect. + + .. method:: dbprefix([$table = '']) + + :param string $table: The table name to prefix + :returns: The prefixed table name + :rtype: string + + Prepends a database prefix, if one exists in configuration. + + .. method:: count_all_results([$table = '']) + + :param string $table: Table name + :returns: Number of rows in the query result + :rtype: int + + Generates a platform-specific query string that counts + all records returned by an Query Builder query. + + .. method:: get([$table = ''[, $limit = NULL[, $offset = NULL]]]) + + :param string $table: The table to query + :param int $limit: The LIMIT clause + :param int $offset: The OFFSET clause + :returns: CI_DB_result instance (method chaining) + :rtype: CI_DB_result + + Compiles and runs SELECT statement based on the already + called Query Builder methods. + + .. method:: get_where([$table = ''[, $where = NULL[, $limit = NULL[, $offset = NULL]]]]) + + :param mixed $table: The table(s) to fetch data from; string or array + :param string $where: The WHERE clause + :param int $limit: The LIMIT clause + :param int $offset: The OFFSET clause + :returns: CI_DB_result instance (method chaining) + :rtype: CI_DB_result + + Same as ``get()``, but also allows the WHERE to be added directly. + + .. method:: select([$select = '*'[, $escape = NULL]]) + + :param string $select: The SELECT portion of a query + :param bool $escape: Whether to escape values and identifiers + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Adds a SELECT clause to a query. + + .. method:: select_avg([$select = ''[, $alias = '']]) + + :param string $select: Field to compute the average of + :param string $alias: Alias for the resulting value name + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Adds a SELECT AVG(field) clause to a query. + + .. method:: select_max([$select = ''[, $alias = '']]) + + :param string $select: Field to compute the maximum of + :param string $alias: Alias for the resulting value name + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Adds a SELECT MAX(field) clause to a query. + + .. method:: select_min([$select = ''[, $alias = '']]) + + :param string $select: Field to compute the minimum of + :param string $alias: Alias for the resulting value name + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Adds a SELECT MIN(field) clause to a query. + + .. method:: select_sum([$select = ''[, $alias = '']]) + + :param string $select: Field to compute the sum of + :param string $alias: Alias for the resulting value name + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Adds a SELECT SUM(field) clause to a query. + + .. method:: distinct([$val = TRUE]) + + :param bool $val: Desired value of the "distinct" flag + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Sets a flag which tells the query builder to add + a DISTINCT clause to the SELECT portion of the query. + + .. method:: from($from) + + :param mixed $from: Table name(s); string or array + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Specifies the FROM clause of a query. + + .. method:: join($table, $cond[, $type = ''[, $escape = NULL]]) + + :param string $table: Table name to join + :param string $cond: The JOIN ON condition + :param string $type: The JOIN type + :param bool $escape: Whether to escape values and identifiers + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Adds a JOIN clause to a query. + + .. method:: where($key[, $value = NULL[, $escape = NULL]]) + + :param mixed $key: Name of field to compare, or associative array + :param mixed $value: If a single key, compared to this value + :param boolean $escape: Whether to escape values and identifiers + :returns: DB_query_builder instance + :rtype: object + + Generates the WHERE portion of the query. + Separates multiple calls with 'AND'. + + .. method:: or_where($key[, $value = NULL[, $escape = NULL]]) + + :param mixed $key: Name of field to compare, or associative array + :param mixed $value: If a single key, compared to this value + :param boolean $escape: Whether to escape values and identifiers + :returns: DB_query_builder instance + :rtype: object + + Generates the WHERE portion of the query. + Separates multiple calls with 'OR'. + + .. method:: or_where_in([$key = NULL[, $values = NULL[, $escape = NULL]]]) + + :param string $key: The field to search + :param array $values: The values searched on + :param boolean $escape: Whether to escape values and identifiers + :returns: DB_query_builder instance + :rtype: object + + Generates a WHERE field IN('item', 'item') SQL query, + joined with 'OR' if appropriate. + + .. method:: or_where_not_in([$key = NULL[, $values = NULL[, $escape = NULL]]]) + + :param string $key: The field to search + :param array $values: The values searched on + :param boolean $escape: Whether to escape values and identifiers + :returns: DB_query_builder instance + :rtype: object + + Generates a WHERE field NOT IN('item', 'item') SQL query, + joined with 'OR' if appropriate. + + .. method:: where_in([$key = NULL[, $values = NULL[, $escape = NULL]]]) + + :param string $key: Name of field to examine + :param array $values: Array of target values + :param boolean $escape: Whether to escape values and identifiers + :returns: DB_query_builder instance + :rtype: object + + Generates a WHERE field IN('item', 'item') SQL query, + joined with 'AND' if appropriate. + + .. method:: where_not_in([$key = NULL[, $values = NULL[, $escape = NULL]]]) + + :param string $key: Name of field to examine + :param array $values: Array of target values + :param boolean $escape: Whether to escape values and identifiers + :returns: DB_query_builder instance + :rtype: object + + Generates a WHERE field NOT IN('item', 'item') SQL query, + joined with 'AND' if appropriate. + + .. method:: group_start() + + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Starts a group expression, using ANDs for the conditions inside it. + + .. method:: or_group_start() + + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Starts a group expression, using ORs for the conditions inside it. + + .. method:: not_group_start() + + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Starts a group expression, using AND NOTs for the conditions inside it. + + .. method:: or_not_group_start() + + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Starts a group expression, using OR NOTs for the conditions inside it. + + .. method:: group_end() + + :returns: DB_query_builder instance + :rtype: object + + Ends a group expression. + + .. method:: like($field[, $match = ''[, $side = 'both'[, $escape = NULL]]]) + + :param string $field: Field name + :param string $match: Text portion to match + :param string $side: Which side of the expression to put the '%' wildcard on + :param bool $escape: Whether to escape values and identifiers + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Adds a LIKE clause to a query, separating multiple calls with AND. + + .. method:: or_like($field[, $match = ''[, $side = 'both'[, $escape = NULL]]]) + + :param string $field: Field name + :param string $match: Text portion to match + :param string $side: Which side of the expression to put the '%' wildcard on + :param bool $escape: Whether to escape values and identifiers + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Adds a LIKE clause to a query, separating multiple class with OR. + + .. method:: not_like($field[, $match = ''[, $side = 'both'[, $escape = NULL]]]) + + :param string $field: Field name + :param string $match: Text portion to match + :param string $side: Which side of the expression to put the '%' wildcard on + :param bool $escape: Whether to escape values and identifiers + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Adds a NOT LIKE clause to a query, separating multiple calls with AND. + + .. method:: or_not_like($field[, $match = ''[, $side = 'both'[, $escape = NULL]]]) + + :param string $field: Field name + :param string $match: Text portion to match + :param string $side: Which side of the expression to put the '%' wildcard on + :param bool $escape: Whether to escape values and identifiers + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Adds a NOT LIKE clause to a query, separating multiple calls with OR. + + .. method:: having($key[, $value = NULL[, $escape = NULL]]) + + :param mixed $key: Identifier (string) or associative array of field/value pairs + :param string $value: Value sought if $key is an identifier + :param string $escape: Whether to escape values and identifiers + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Adds a HAVING clause to a query, separating multiple calls with AND. + + .. method:: or_having($key[, $value = NULL[, $escape = NULL]]) + + :param mixed $key: Identifier (string) or associative array of field/value pairs + :param string $value: Value sought if $key is an identifier + :param string $escape: Whether to escape values and identifiers + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Adds a HAVING clause to a query, separating multiple calls with OR. + + .. method:: group_by($by[, $escape = NULL]) + + :param mixed $by: Field(s) to group by; string or array + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Adds a GROUP BY clause to a query. + + .. method:: order_by($orderby[, $direction = ''[, $escape = NULL]]) + + :param string $orderby: Field to order by + :param string $direction: The order requested - ASC, DESC or random + :param bool $escape: Whether to escape values and identifiers + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Adds an ORDER BY clause to a query. + + .. method:: limit($value[, $offset = 0]) + + :param int $value: Number of rows to limit the results to + :param int $offset: Number of rows to skip + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Adds LIMIT and OFFSET clauses to a query. + + .. method:: offset($offset) + + :param int $offset: Number of rows to skip + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Adds an OFFSET clause to a query. + + .. method:: set($key[, $value = ''[, $escape = NULL]]) + + :param mixed $key: Field name, or an array of field/value pairs + :param string $value: Field value, if $key is a single field + :param bool $escape: Whether to escape values and identifiers + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Adds field/value pairs to be passed later to ``insert()``, + ``update()`` or ``replace()``. + + .. method:: insert([$table = ''[, $set = NULL[, $escape = NULL]]]) + + :param string $table: Table name + :param array $set: An associative array of field/value pairs + :param bool $escape: Whether to escape values and identifiers + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Compiles and executes an INSERT statement. + + .. method:: insert_batch([$table = ''[, $set = NULL[, $escape = NULL]]]) + + :param string $table: Table name + :param array $set: Data to insert + :param bool $escape: Whether to escape values and identifiers + :returns: Number of rows inserted or FALSE on failure + :rtype: mixed + + Compiles and executes batch INSERT statements. + + .. method:: set_insert_batch($key[, $value = ''[, $escape = NULL]]) + + :param mixed $key: Field name or an array of field/value pairs + :param string $value: Field value, if $key is a single field + :param bool $escape: Whether to escape values and identifiers + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Adds field/value pairs to be inserted in a table later via ``insert_batch()``. + + .. method:: update([$table = ''[, $set = NULL[, $where = NULL[, $limit = NULL]]]]) + + :param string $table: Table name + :param array $set: An associative array of field/value pairs + :param string $where: The WHERE clause + :param int $limit: The LIMIT clause + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Compiles and executes an UPDATE statement. + + .. method:: update_batch([$table = ''[, $set = NULL[, $value = NULL]]]) + + :param string $table: Table name + :param array $set: Field name, or an associative array of field/value pairs + :param string $value: Field value, if $set is a single field + :returns: Number of rows updated or FALSE on failure + :rtype: mixed + + Compiles and executes batch UPDATE statements. + + .. method:: set_update_batch($key[, $value = ''[, $escape = NULL]]) + + :param mixed $key: Field name or an array of field/value pairs + :param string $value: Field value, if $key is a single field + :param bool $escape: Whether to escape values and identifiers + :returns: CI_DB_query_builder instance (method chaining) + :rtype: CI_DB_query_builder + + Adds field/value pairs to be updated in a table later via ``update_batch()``. + + .. method:: replace([$table = ''[, $set = NULL]]) + + :param string $table: Table name + :param array $set: An associative array of field/value pairs + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Compiles and executes a REPLACE statement. + + .. method:: delete([$table = ''[, $where = ''[, $limit = NULL[, $reset_data = TRUE]]]]) + + :param mixed $table: The table(s) to delete from; string or array + :param string $where: The WHERE clause + :param int $limit: The LIMIT clause + :param bool $reset_data: TRUE to reset the query "write" clause + :returns: CI_DB_query_builder instance (method chaining) or FALSE on failure + :rtype: mixed + + Compiles and executes a DELETE query. + + .. method:: truncate([$table = '']) + + :param string $table: Table name + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Executes a TRUNCATE statement on a table. + + .. note:: If the database platform in use doesn't support TRUNCATE, + a DELETE statement will be used instead. + + .. method:: empty_table([$table = '']) + + :param string $table: Table name + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Deletes all records from a table via a DELETE statement. + + .. method:: get_compiled_select([$table = ''[, $reset = TRUE]]) + + :param string $table: Table name + :param bool $reset: Whether to reset the current QB values or not + :returns: The compiled SQL statement as a string + :rtype: string + + Compiles a SELECT statement and returns it as a string. + + .. method:: get_compiled_insert([$table = ''[, $reset = TRUE]]) + + :param string $table: Table name + :param bool $reset: Whether to reset the current QB values or not + :returns: The compiled SQL statement as a string + :rtype: string + + Compiles an INSERT statement and returns it as a string. + + .. method:: get_compiled_update([$table = ''[, $reset = TRUE]]) + + :param string $table: Table name + :param bool $reset: Whether to reset the current QB values or not + :returns: The compiled SQL statement as a string + :rtype: string + + Compiles an UPDATE statement and returns it as a string. + + .. method:: get_compiled_delete([$table = ''[, $reset = TRUE]]) + + :param string $table: Table name + :param bool $reset: Whether to reset the current QB values or not + :returns: The compiled SQL statement as a string + :rtype: string + + Compiles a DELETE statement and returns it as a string. diff --git a/user_guide_src/source/database/results.rst b/user_guide_src/source/database/results.rst index e0a87a851..ae81998c7 100644 --- a/user_guide_src/source/database/results.rst +++ b/user_guide_src/source/database/results.rst @@ -4,10 +4,17 @@ Generating Query Results There are several ways to generate query results: -result() -======== +.. contents:: + :local: + :depth: 2 -This function returns the query result as an array of **objects**, or +************* +Result Arrays +************* + +**result()** + +This method returns the query result as an array of **objects**, or **an empty array** on failure. Typically you'll use this in a foreach loop, like this:: @@ -20,7 +27,7 @@ loop, like this:: echo $row->body; } -The above function is an alias of result_object(). +The above method is an alias of ``result_object()``. If you run queries that might **not** produce a result, you are encouraged to test the result first:: @@ -46,14 +53,13 @@ instantiate for each result object (note: this class must be loaded) foreach ($query->result('User') as $user) { - echo $user->name; // call attributes - echo $user->reverse_name(); // or methods defined on the 'User' class + echo $user->name; // access attributes + echo $user->reverse_name(); // or methods defined on the 'User' class } -result_array() -=============== +**result_array()** -This function returns the query result as a pure array, or an empty +This method returns the query result as a pure array, or an empty array when no result is produced. Typically you'll use this in a foreach loop, like this:: @@ -66,10 +72,13 @@ loop, like this:: echo $row['body']; } -row() -===== +*********** +Result Rows +*********** + +**row()** -This function returns a single result row. If your query has more than +This method returns a single result row. If your query has more than one row, it returns only the first row. The result is returned as an **object**. Here's a usage example:: @@ -95,13 +104,12 @@ to instantiate the row with:: $query = $this->db->query("SELECT * FROM users LIMIT 1;"); $query->row(0, 'User'); - echo $row->name; // call attributes + echo $row->name; // access attributes echo $row->reverse_name(); // or methods defined on the 'User' class -row_array() -=========== +**row_array()** -Identical to the above row() function, except it returns an array. +Identical to the above ``row()`` method, except it returns an array. Example:: $query = $this->db->query("YOUR QUERY"); @@ -136,10 +144,11 @@ parameter: | **$row = $query->next_row('array')** | **$row = $query->previous_row('array')** -.. note:: all the functions above will load the whole result into memory (prefetching) use unbuffered_row() for processing large result sets. +.. note:: All the methods above will load the whole result into memory + (prefetching). Use ``unbuffered_row()`` for processing large + result sets. -unbuffered_row() -================ +**unbuffered_row()** This method returns a single result row without prefetching the whole result in memory as ``row()`` does. If your query has more than one row, @@ -163,12 +172,11 @@ the returned value's type:: $query->unbuffered_row('object'); // object $query->unbuffered_row('array'); // associative array -*********************** -Result Helper Functions -*********************** +********************* +Result Helper Methods +********************* -$query->num_rows() -================== +**num_rows()** The number of rows returned by the query. Note: In this example, $query is the variable that the query result object is assigned to:: @@ -177,30 +185,28 @@ is the variable that the query result object is assigned to:: echo $query->num_rows(); -.. note:: - Not all database drivers have a native way of getting the total +.. note:: Not all database drivers have a native way of getting the total number of rows for a result set. When this is the case, all of - the data is prefetched and count() is manually called on the - resulting array in order to achieve the same functionality. + the data is prefetched and ``count()`` is manually called on the + resulting array in order to achieve the same result. -$query->num_fields() -==================== +**num_fields()** The number of FIELDS (columns) returned by the query. Make sure to call -the function using your query result object:: +the method using your query result object:: $query = $this->db->query('SELECT * FROM my_table'); echo $query->num_fields(); -$query->free_result() -===================== +**free_result()** It frees the memory associated with the result and deletes the result resource ID. Normally PHP frees its memory automatically at the end of script execution. However, if you are running a lot of queries in a particular script you might want to free the result after each query -result has been generated in order to cut down on memory consumptions. +result has been generated in order to cut down on memory consumption. + Example:: $query = $this->db->query('SELECT title FROM my_table'); @@ -209,6 +215,7 @@ Example:: { echo $row->title; } + $query->free_result(); // The $query result object will no longer be available $query2 = $this->db->query('SELECT name FROM some_table'); @@ -217,8 +224,7 @@ Example:: echo $row->name; $query2->free_result(); // The $query2 result object will no longer be available -data_seek() -=========== +**data_seek()** This method sets the internal pointer for the next result row to be fetched. It is only useful in combination with ``unbuffered_row()``. @@ -233,4 +239,196 @@ TRUE on success or FALSE on failure. $row = $query->unbuffered_row(); .. note:: Not all database drivers support this feature and will return FALSE. - Most notably - you won't be able to use it with PDO.
\ No newline at end of file + Most notably - you won't be able to use it with PDO. + +*************** +Class Reference +*************** + +.. class:: CI_DB_result + + .. method:: result([$type = 'object']) + + :param string $type: Type of requested results - array, object, or class name + :returns: Array containing the fetched rows + :rtype: array + + A wrapper for the ``result_array()``, ``result_object()`` + and ``custom_result_object()`` methods. + + Usage: see `Result Arrays`_. + + .. method:: result_array() + + :returns: Array containing the fetched rows + :rtype: array + + Returns the query results as an array of rows, where each + row is itself an associative array. + + Usage: see `Result Arrays`_. + + .. method:: result_object() + + :returns: Array containing the fetched rows + :rtype: array + + Returns the query results as an array of rows, where each + row is an object of type ``stdClass``. + + Usage: see `Result Arrays`_. + + .. method:: custom_result_object($class_name) + + :param string $class_name: Class name for the resulting rows + :returns: Array containing the fetched rows + :rtype: array + + Returns the query results as an array of rows, where each + row is an instance of the specified class. + + .. method:: row([$n = 0[, $type = 'object']]) + + :param int $n: Index of the query results row to be returned + :param string $type: Type of the requested result - array, object, or class name + :returns: The requested row or NULL if it doesn't exist + :rtype: mixed + + A wrapper for the ``row_array()``, ``row_object() and + ``custom_row_object()`` methods. + + Usage: see `Result Rows`_. + + .. method:: unbuffered_row([$type = 'object']) + + :param string $type: Type of the requested result - array, object, or class name + :returns: Next row from the result set or NULL if it doesn't exist + :rtype: mixed + + Fetches the next result row and returns it in the + requested form. + + Usage: see `Result Rows`_. + + .. method:: row_array([$n = 0]) + + :param int $n: Index of the query results row to be returned + :returns: The requested row or NULL if it doesn't exist + :rtype: array + + Returns the requested result row as an associative array. + + Usage: see `Result Rows`_. + + .. method:: row_object([$n = 0]) + + :param int $n: Index of the query results row to be returned + :returns: The requested row or NULL if it doesn't exist + :rtype: stdClass + + Returns the requested result row as an object of type + ``stdClass``. + + Usage: see `Result Rows`_. + + .. method:: custom_row_object($n, $type) + + :param int $n: Index of the results row to return + :param string $class_name: Class name for the resulting row + :returns: The requested row or NULL if it doesn't exist + :rtype: $type + + Returns the requested result row as an instance of the + requested class. + + .. method:: data_seek([$n = 0]) + + :param int $n: Index of the results row to be returned next + :returns: TRUE on success, FALSE on failure + :rtype: bool + + Moves the internal results row pointer to the desired offset. + + Usage: see `Result Helper Methods`_. + + .. method:: set_row($key[, $value = NULL]) + + :param mixed $key: Column name or array of key/value pairs + :param mixed $value: Value to assign to the column, $key is a single field name + :rtype: void + + Assigns a value to a particular column. + + .. method:: next_row([$type = 'object']) + + :param string $type: Type of the requested result - array, object, or class name + :returns: Next row of result set, or NULL if it doesn't exist + :rtype: mixed + + Returns the next row from the result set. + + .. method:: previous_row([$type = 'object']) + + :param string $type: Type of the requested result - array, object, or class name + :returns: Previous row of result set, or NULL if it doesn't exist + :rtype: mixed + + Returns the previous row from the result set. + + .. method:: first_row([$type = 'object']) + + :param string $type: Type of the requested result - array, object, or class name + :returns: First row of result set, or NULL if it doesn't exist + :rtype: mixed + + Returns the first row from the result set. + + .. method:: last_row([$type = 'object']) + + :param string $type: Type of the requested result - array, object, or class name + :returns: Last row of result set, or NULL if it doesn't exist + :rtype: mixed + + Returns the last row from the result set. + + .. method:: num_rows() + + :returns: Number of rows in the result set + :rtype: int + + Returns the number of rows in the result set. + + Usage: see `Result Helper Methods`_. + + .. method:: num_fields() + + :returns: Number of fields in the result set + :rtype: int + + Returns the number of fields in the result set. + + Usage: see `Result Helper Methods`_. + + .. method:: field_data() + + :returns: Array containing field meta-data + :rtype: array + + Generates an array of ``stdClass`` objects containing + field meta-data. + + .. method:: free_result() + + :rtype: void + + Frees a result set. + + Usage: see `Result Helper Methods`_. + + .. method:: list_fields() + + :returns: Array of column names + :rtype: array + + Returns an array containing the field names in the + result set.
\ No newline at end of file diff --git a/user_guide_src/source/database/table_data.rst b/user_guide_src/source/database/table_data.rst deleted file mode 100644 index 744a05154..000000000 --- a/user_guide_src/source/database/table_data.rst +++ /dev/null @@ -1,31 +0,0 @@ -########## -Table Data -########## - -These functions let you fetch table information. - -$this->db->list_tables(); -========================== - -Returns an array containing the names of all the tables in the database -you are currently connected to. Example:: - - $tables = $this->db->list_tables(); - - foreach ($tables as $table) - { - echo $table; - } - -$this->db->table_exists(); -=========================== - -Sometimes it's helpful to know whether a particular table exists before -running an operation on it. Returns a boolean TRUE/FALSE. Usage example:: - - if ($this->db->table_exists('table_name')) - { - // some code... - } - -.. note:: Replace *table_name* with the name of the table you are looking for. diff --git a/user_guide_src/source/database/utilities.rst b/user_guide_src/source/database/utilities.rst index bd40cdadd..0d8137dd7 100644 --- a/user_guide_src/source/database/utilities.rst +++ b/user_guide_src/source/database/utilities.rst @@ -5,15 +5,13 @@ Database Utility Class The Database Utility Class contains methods that help you manage your database. -.. contents:: Table of Contents - - -****************** -Function Reference -****************** +.. contents:: + :local: + :depth: 2 +****************************** Initializing the Utility Class -============================== +****************************** .. important:: In order to initialize the Utility class, your database driver must already be running, since the utilities class relies on it. @@ -39,7 +37,11 @@ object:: $this->dbutil->some_method() -$this->dbutil->list_databases(); +**************************** +Using the Database Utilities +**************************** + +Retrieve list of database names ================================ Returns an array of database names:: @@ -51,8 +53,9 @@ Returns an array of database names:: echo $db; } -$this->dbutil->database_exists(); -================================= + +Determine If a Database Exists +============================== Sometimes it's helpful to know whether a particular database exists. Returns a boolean TRUE/FALSE. Usage example:: @@ -65,8 +68,8 @@ Returns a boolean TRUE/FALSE. Usage example:: .. note:: Replace *database_name* with the name of the table you are looking for. This method is case sensitive. -$this->dbutil->optimize_table('table_name'); -============================================ +Optimize a Table +================ Permits you to optimize a table using the table name specified in the first parameter. Returns TRUE/FALSE based on success or failure:: @@ -79,8 +82,8 @@ first parameter. Returns TRUE/FALSE based on success or failure:: .. note:: Not all database platforms support table optimization. It is mostly for use with MySQL. -$this->dbutil->repair_table('table_name'); -========================================== +Repair a Table +============== Permits you to repair a table using the table name specified in the first parameter. Returns TRUE/FALSE based on success or failure:: @@ -92,8 +95,8 @@ first parameter. Returns TRUE/FALSE based on success or failure:: .. note:: Not all database platforms support table repairs. -$this->dbutil->optimize_database(); -==================================== +Optimize a Database +=================== Permits you to optimize the database your DB class is currently connected to. Returns an array containing the DB status messages or @@ -111,8 +114,8 @@ FALSE on failure. .. note:: Not all database platforms support table optimization. It it is mostly for use with MySQL. -$this->dbutil->csv_from_result($db_result); -=========================================== +Export a Query Result as a CSV File +=================================== Permits you to generate a CSV file from a query result. The first parameter of the method must contain the result object from your @@ -139,8 +142,8 @@ is used as the enclosure. Example:: simply creates the CSV layout. If you need to write the file use the :doc:`File Helper <../helpers/file_helper>`. -$this->dbutil->xml_from_result($db_result); -=========================================== +Export a Query Result as an XML Document +======================================== Permits you to generate an XML file from a query result. The first parameter expects a query result object, the second may contain an @@ -163,8 +166,12 @@ optional array of config parameters. Example:: simply creates the XML layout. If you need to write the file use the :doc:`File Helper <../helpers/file_helper>`. -$this->dbutil->backup(); -======================== +******************** +Backup Your Database +******************** + +Database Backup Notes +===================== Permits you to backup your full database or individual tables. The backup data can be compressed in either Zip or Gzip format. @@ -182,7 +189,7 @@ backup data can be compressed in either Zip or Gzip format. have root privileges. Usage Example -------------- +============= :: @@ -201,7 +208,7 @@ Usage Example force_download('mybackup.gz', $backup); Setting Backup Preferences --------------------------- +========================== Backup preferences are set by submitting an array of values to the first parameter of the ``backup()`` method. Example:: @@ -219,7 +226,7 @@ parameter of the ``backup()`` method. Example:: $this->dbutil->backup($prefs); Description of Backup Preferences ---------------------------------- +================================= ======================= ======================= ======================= ======================================================================== Preference Default Value Options Description @@ -234,4 +241,76 @@ Preference Default Value Options Descript **add_insert** TRUE TRUE/FALSE Whether to include INSERT statements in your SQL export file. **newline** "\\n" "\\n", "\\r", "\\r\\n" Type of newline to use in your SQL export file. **foreign_key_checks** TRUE TRUE/FALSE Whether output should keep foreign key checks enabled. -======================= ======================= ======================= ========================================================================
\ No newline at end of file +======================= ======================= ======================= ======================================================================== + +*************** +Class Reference +*************** + +.. class:: CI_DB_utility + + .. method:: backup([$params = array()]) + + :param array $params: An associative array of options + :returns: void + :rtype: void + + Perform a database backup, per user preferences. + + .. method:: database_exists($database_name) + + :param string $database_name: Database name + :returns: TRUE if the database exists, FALSE otherwise + :rtype: bool + + Check for the existence of a database. + + .. method:: list_databases() + + :returns: Array of database names found + :rtype: array + + Retrieve a list of all the database names. + + .. method:: optimize_database() + + :returns: Array of optimization messages or FALSE on failure + :rtype: array + + Optimizes the database. + + .. method:: optimize_table($table_name) + + :param string $table_name: Name of the table to optimize + :returns: Array of optimization messages or FALSE on failure + :rtype: array + + Optimizes a database table. + + .. method:: repair_table($table_name) + + :param string $table_name: Name of the table to repair + :returns: Array of repair messages or FALSE on failure + :rtype: array + + Repairs a database table. + + .. method:: csv_from_results($query[, $delim = ','[, $newline = "\n"[, $enclosure = '"']]]) + + :param object $query: A database result object + :param string $delim: The CSV field delimiter to use + :param string $newline: The newline character to use + :param string $enclosure: The enclosure delimiter to use + :returns: The generated CSV file as a string + :rtype: string + + Translates a database result object into a CSV document. + + .. method:: xml_from_results($query[, $params = array()]) + + :param object $query: A database result object + :param array $params: An associative array of preferences + :returns: The generated XML document as a string + :rtype: string + + Translates a database result object into an XML document.
\ No newline at end of file |