summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/database
diff options
context:
space:
mode:
authorAndrey Andreev <narf@devilix.net>2015-01-12 16:23:26 +0100
committerAndrey Andreev <narf@devilix.net>2015-01-12 16:23:26 +0100
commit45a8afaabc6d09ad59bbb3c89a6cdfe8cbc3312c (patch)
tree7ca4207099f9225b5ef74b31f48627a282e7fdf2 /user_guide_src/source/database
parentcd94dd7e1d8969658810ccc4158a75d2936d0a44 (diff)
parent934d6d9797f4dadd4e4d05b12bc4d7309fedb6c3 (diff)
Merge branch 'develop' into feature/session
Diffstat (limited to 'user_guide_src/source/database')
-rw-r--r--user_guide_src/source/database/configuration.rst3
-rw-r--r--user_guide_src/source/database/db_driver_reference.rst420
-rw-r--r--user_guide_src/source/database/forge.rst136
-rw-r--r--user_guide_src/source/database/helpers.rst61
-rw-r--r--user_guide_src/source/database/index.rst8
-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.rst24
-rw-r--r--user_guide_src/source/database/query_builder.rst745
-rw-r--r--user_guide_src/source/database/results.rst272
-rw-r--r--user_guide_src/source/database/table_data.rst31
-rw-r--r--user_guide_src/source/database/utilities.rst131
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