Merge pull request #3369 from jim-parry/userguide/database
Userguide/database - part 1
diff --git a/user_guide_src/source/database/helpers.rst b/user_guide_src/source/database/helpers.rst
index 77bf1b5..2d997a9 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 @@
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,33 +23,7 @@
affected rows. By default this hack is enabled but it can be turned off
in the database driver file.
-$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::
-
- echo $this->db->count_all('my_table');
-
- // Produces an integer, like 25
-
-$this->db->platform()
-=====================
-
-Outputs the database platform you are running (MySQL, MS SQL, Postgres,
-etc...)::
-
- echo $this->db->platform();
-
-$this->db->version()
-====================
-
-Outputs the database version you are running::
-
- echo $this->db->version();
-
-$this->db->last_query()
-=======================
+**$this->db->last_query()**
Returns the last query that was run (the query string, not the result).
Example::
@@ -61,9 +36,36 @@
.. note:: Disabling the **save_queries** setting in your database
configuration will render this function useless.
-$this->db->insert_string()
+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::
+
+ echo $this->db->count_all('my_table');
+
+ // Produces an integer, like 25
+
+**$this->db->platform()**
+
+Outputs the database platform you are running (MySQL, MS SQL, Postgres,
+etc...)::
+
+ echo $this->db->platform();
+
+**$this->db->version()**
+
+Outputs the database version you are running::
+
+ echo $this->db->version();
+
+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 @@
.. 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 7ccb8fb..cfd6242 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
diff --git a/user_guide_src/source/database/queries.rst b/user_guide_src/source/database/queries.rst
index 76ff108..43a0a30 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 @@
$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 @@
::
- $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 @@
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/results.rst b/user_guide_src/source/database/results.rst
index e0a87a8..e069851 100644
--- a/user_guide_src/source/database/results.rst
+++ b/user_guide_src/source/database/results.rst
@@ -4,10 +4,14 @@
There are several ways to generate query results:
+*************
+Result Arrays
+*************
+
result()
========
-This function returns the query result as an array of **objects**, or
+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 +24,7 @@
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::
@@ -53,7 +57,7 @@
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 +70,14 @@
echo $row['body'];
}
+***********
+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::
@@ -101,7 +109,7 @@
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,7 +144,8 @@
| **$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()
================
@@ -163,12 +172,11 @@
$query->unbuffered_row('object'); // object
$query->unbuffered_row('array'); // associative array
-***********************
-Result Helper Functions
-***********************
+*********************
+Result Helper Methods
+*********************
-$query->num_rows()
-==================
+**$query->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::
@@ -181,20 +189,18 @@
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.
+ resulting array in order to achieve the same methodality.
-$query->num_fields()
-====================
+**$query->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()
-=====================
+**$query->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
@@ -217,8 +223,7 @@
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()``.