Added possibility to pass custom database objects to DB Forge and DB Utilities

Also, their  property is no longer public and the utility class no longer extends CI_DB_forge.

4 files changed, 99 insertions, 71 deletions

diff --git a/user_guide_src/source/changelog.rst b/user_guide_src/source/changelog.rst
index 717d7f6ba..2cd0d7978 100644
--- a/user_guide_src/source/changelog.rst
+++ b/user_guide_src/source/changelog.rst
@@ -89,6 +89,26 @@ Release Date: Not Released
 
 -  Database
 
+   -  Added **dsn** configuration setting for drivers that support DSN strings (PDO, PostgreSQL, Oracle, ODBC, CUBRID).
+   -  Added **schema** configuration setting (defaults to *public*) for drivers that might need it (currently used by PostgreSQL and ODBC).
+   -  Added subdrivers support (currently only used by PDO).
+   -  Added an optional database name parameter to ``db_select()``.
+   -  Added a constructor to the ``DB_result`` class and moved all driver-specific properties and logic out of the base ``DB_driver`` class to allow better abstraction.
+   -  Removed ``protect_identifiers()`` and renamed internal method ``_protect_identifiers()`` to it instead - it was just an alias.
+   -  Renamed internal method ``_escape_identifiers()`` to ``escape_identifiers()``.
+   -  Updated ``escape_identifiers()`` to accept an array of fields as well as strings.
+   -  MySQL and MySQLi drivers now require at least MySQL version 5.1.
+   -  ``db_set_charset()`` now only requires one parameter (collation was only needed due to legacy support for MySQL versions prior to 5.1).
+   -  Replaced the ``_error_message()`` and ``_error_number()`` methods with ``error()``, which returns an array containing the last database error code and message.
+   -  Improved ``version()`` implementation so that drivers that have a native function to get the version number don't have to be defined in the core ``DB_driver`` class.
+   -  Added ``unbuffered_row()`` method for getting a row without prefetching whole result (consume less memory).
+   -  Added capability for packages to hold *database.php* config files.
+   -  Added MySQL client compression support.
+   -  Added encrypted connections support (for *mysql*, *sqlsrv* and PDO with *sqlsrv*).
+   -  Removed :doc:`Loader Class <libraries/loader>` from Database error tracing to better find the likely culprit.
+   -  Added support for SQLite3 database driver.
+   -  Added Interbase/Firebird database support via the *ibase* driver.
+   -  Added ODBC support for ``create_database()``, ``drop_database()`` and ``drop_table()`` in :doc:`Database Forge <database/forge>`.
    -  :doc:`Query Builder <database/query_builder>` changes include:
 	 - Renamed the Active Record class to Query Builder to remove confusion with the Active Record design pattern.
 	 - Added the ability to insert objects with ``insert_batch()``.
@@ -104,13 +124,10 @@ Release Date: Not Released
 	 - Server version checking is now done via ``mysqli::$server_info`` instead of running an SQL query.
 	 - Added persistent connections support for PHP >= 5.3.
 	 - Added support for ``backup()`` in :doc:`Database Utilities <database/utilities>`.
-   -  Added **dsn** configuration setting for drivers that support DSN strings (PDO, PostgreSQL, Oracle, ODBC, CUBRID).
-   -  Added **schema** configuration setting (defaults to *public*) for drivers that might need it (currently used by PostgreSQL and ODBC).
-   -  Improved PDO database support.
-   -  Added Interbase/Firebird database support via the *ibase* driver.
-   -  Added an optional database name parameter to ``db_select()``.
-   -  Replaced the ``_error_message()`` and ``_error_number()`` methods with ``error()``, which returns an array containing the last database error code and message.
-   -  Improved ``version()`` implementation so that drivers that have a native function to get the version number don't have to be defined in the core ``DB_driver`` class.
+   -  Improved support of the PDO driver, including:
+	 - Added support for ``create_database()``, ``drop_database()`` and ``drop_table()`` in :doc:`Database Forge <database/forge>`.
+	 - Added support for ``list_fields()`` in :doc:`Database Results <database/results>`.
+	 - Subdrivers are now isolated from each other instead of being in one large class.
    -  Improved support of the PostgreSQL driver, including:
 	 - ``pg_version()`` is now used to get the database version number, when possible.
 	 - Added ``db_set_charset()`` support.
@@ -119,13 +136,6 @@ Release Date: Not Released
 	 - Added ``update_batch()`` support.
 	 - Removed ``limit()`` and ``order_by()`` support for *UPDATE* and *DELETE* queries as PostgreSQL does not support those features.
 	 - Added a work-around for dead persistent connections to be re-created after a database restart.
-   -  Added a constructor to the ``DB_result`` class and moved all driver-specific properties and logic out of the base ``DB_driver`` class to allow better abstraction.
-   -  Removed ``protect_identifiers()`` and renamed internal method ``_protect_identifiers()`` to it instead - it was just an alias.
-   -  Renamed internal method ``_escape_identifiers()`` to ``escape_identifiers()``.
-   -  Updated ``escape_identifiers()`` to accept an array of fields as well as strings.
-   -  MySQL and MySQLi drivers now require at least MySQL version 5.1.
-   -  ``db_set_charset()`` now only requires one parameter (collation was only needed due to legacy support for MySQL versions prior to 5.1).
-   -  Added support for SQLite3 database driver.
    -  Improved support of the CUBRID driver, including:
 	 - Added DSN string support.
 	 - Added persistent connections support.
@@ -145,17 +155,15 @@ Release Date: Not Released
    -  Improved support of the SQLite driver, including:
 	 - Added support for ``replace()`` in :doc:`Query Builder <database/query_builder>`.
 	 - Added support for ``drop_table()`` in :doc:`Database Forge <database/forge>`.
-   -  Added ODBC support for ``create_database()``, ``drop_database()`` and ``drop_table()`` in :doc:`Database Forge <database/forge>`.
-   -  Added PDO support for ``create_database()``, ``drop_database()`` and ``drop_table()`` in :doc:`Database Forge <database/forge>`.
-   -  Added ``unbuffered_row()`` method for getting a row without prefetching whole result (consume less memory).
-   -  Added PDO support for ``list_fields()`` in :doc:`Database Results <database/results>`.
-   -  Added capability for packages to hold *database.php* config files
-   -  Added subdrivers support (currently only used by PDO).
-   -  Added MySQL client compression support.
-   -  Added encrypted connections support (for *mysql*, *sqlsrv* and PDO with *sqlsrv*).
-   -  Removed :doc:`Loader Class <libraries/loader>` from Database error tracing to better find the likely culprit.
-   -  Added an optional second parameter to ``drop_table()`` in :doc:`Database Forge <database/forge>` that allows adding the IF EXISTS condition.
-   -  Removed the optional AFTER clause from :doc:`Database Forge <database/forge>` method ``add_column()``.
+   -  :doc:`Database Forge <database/forge>` changes include:
+	 - Added an optional second parameter to ``drop_table()`` that allows adding the **IF EXISTS** condition, which is no longer the default.
+	 - Added support for passing a custom database object to the loader.
+	 - Removed the optional AFTER clause from method ``add_column()``.
+	 - Overall improved support for all of the drivers.
+   -  :doc:`Database Utility <database/utilities>` chages include:
+	 - Added support for passing a custom database object to the loader.
+	 - Modified the class to no longer extend :doc:`Database Forge <database/forge>`, which has been a deprecated behavior for awhile.
+	 - Overall improved support for all of the drivers.
 
 -  Libraries
 
diff --git a/user_guide_src/source/database/forge.rst b/user_guide_src/source/database/forge.rst
index 1d6b847b4..de5748b45 100644
--- a/user_guide_src/source/database/forge.rst
+++ b/user_guide_src/source/database/forge.rst
@@ -2,7 +2,7 @@
 Database Forge Class
 ####################
 
-The Database Forge Class contains functions that help you manage your
+The Database Forge Class contains methods that help you manage your
 database.
 
 .. contents:: Table of Contents
@@ -18,13 +18,25 @@ Load the Forge Class as follows::
 
 	$this->load->dbforge()
 
-Once initialized you will access the functions using the $this->dbforge
+You can also pass another database object to the DB Forge loader, in case
+the database you want to manage isn't the default one::
+
+	$this->myforge = $this->load->dbforge($this->other_db, TRUE);
+
+In the above example, we're passing a custom database object as the first
+parameter and then tell it to return the dbforge object, instead of
+assigning it directly to ``$this->dbforge``.
+
+.. note:: Both of the parameters can be used individually, just pass an empty
+	value as the first one if you wish to skip it.
+
+Once initialized you will access the methods using the ``$this->dbforge``
 object::
 
-	$this->dbforge->some_function()
+	$this->dbforge->some_method();
 
 $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::
@@ -108,13 +120,13 @@ Additionally, the following key/values can be used:
 
 
 After the fields have been defined, they can be added using
-$this->dbforge->add_field($fields); followed by a call to the
-create_table() function.
+``$this->dbforge->add_field($fields);`` followed by a call to the
+``create_table()`` method.
 
 $this->dbforge->add_field()
-----------------------------
+---------------------------
 
-The add fields function will accept the above array.
+The add fields method will accept the above array.
 
 Passing strings as fields
 -------------------------
@@ -221,7 +233,7 @@ Modifying Tables
 $this->dbforge->add_column()
 =============================
 
-The add_column() function is used to modify an existing table. It
+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
 number of additional fields.
 
@@ -246,7 +258,7 @@ Used to remove a column from a table.
 $this->dbforge->modify_column()
 ================================
 
-The usage of this function is identical to add_column(), except it
+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
 change the name you can add a "name" key into the field defining array.
 
diff --git a/user_guide_src/source/database/utilities.rst b/user_guide_src/source/database/utilities.rst
index 4e83929b2..06ecb2da1 100644
--- a/user_guide_src/source/database/utilities.rst
+++ b/user_guide_src/source/database/utilities.rst
@@ -2,7 +2,7 @@
 Database Utility Class
 ######################
 
-The Database Utility Class contains functions that help you manage your
+The Database Utility Class contains methods that help you manage your
 database.
 
 .. contents:: Table of Contents
@@ -22,12 +22,24 @@ Load the Utility Class as follows::
 
 	$this->load->dbutil()
 
-Once initialized you will access the functions using the $this->dbutil
+You can also pass another database object to the DB Utility loader, in case
+the database you want to manage isn't the default one::
+
+	$this->myutil = $this->load->dbutil($this->other_db, TRUE);
+
+In the above example, we're passing a custom database object as the first
+parameter and then tell it to return the dbutil object, instead of
+assigning it directly to ``$this->dbutil``.
+
+.. note:: Both of the parameters can be used individually, just pass an empty
+	value as the first one if you wish to skip it.
+
+Once initialized you will access the methods using the ``$this->dbutil``
 object::
 
-	$this->dbutil->some_function()
+	$this->dbutil->some_method()
 
-$this->dbutil->list_databases()
+$this->dbutil->list_databases();
 ================================
 
 Returns an array of database names::
@@ -40,7 +52,7 @@ Returns an array of database names::
 	}
 
 $this->dbutil->database_exists();
-==================================
+=================================
 
 Sometimes it's helpful to know whether a particular database exists.
 Returns a boolean TRUE/FALSE. Usage example::
@@ -50,13 +62,11 @@ Returns a boolean TRUE/FALSE. Usage example::
 		// some code...
 	}
 
-Note: Replace *database_name* with the name of the table you are
-looking for. This function is case sensitive.
+.. 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');
-==============================================
-
-.. note:: This features is only available for MySQL/MySQLi databases.
+============================================
 
 Permits you to optimize a table using the table name specified in the
 first parameter. Returns TRUE/FALSE based on success or failure::
@@ -66,12 +76,11 @@ first parameter. Returns TRUE/FALSE based on success or failure::
 		echo 'Success!';
 	}
 
-.. note:: Not all database platforms support table optimization.
+.. note:: Not all database platforms support table optimization. It is
+	mostly for use with MySQL.
 
 $this->dbutil->repair_table('table_name');
-============================================
-
-.. note:: This features is only available for MySQL/MySQLi databases.
+==========================================
 
 Permits you to repair a table using the table name specified in the
 first parameter. Returns TRUE/FALSE based on success or failure::
@@ -86,8 +95,6 @@ first parameter. Returns TRUE/FALSE based on success or failure::
 $this->dbutil->optimize_database();
 ====================================
 
-.. note:: This features is only available for MySQL/MySQLi databases.
-
 Permits you to optimize the database your DB class is currently
 connected to. Returns an array containing the DB status messages or
 FALSE on failure.
@@ -101,13 +108,14 @@ FALSE on failure.
 		print_r($result);
 	}
 
-.. note:: Not all database platforms support table optimization.
+.. note:: Not all database platforms support table optimization. It
+	it is mostly for use with MySQL.
 
-$this->dbutil->csv_from_result($db_result)
-=============================================
+$this->dbutil->csv_from_result($db_result);
+===========================================
 
 Permits you to generate a CSV file from a query result. The first
-parameter of the function must contain the result object from your
+parameter of the method must contain the result object from your
 query. Example::
 
 	$this->load->dbutil();
@@ -127,12 +135,12 @@ is used as the enclosure. Example::
 
 	echo $this->dbutil->csv_from_result($query, $delimiter, $newline, $enclosure);
 
-.. important:: This function will NOT write the CSV file for you. It
+.. important:: This method will NOT write the CSV file for you. It
 	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)
-=============================================
+$this->dbutil->xml_from_result($db_result);
+===========================================
 
 Permits you to generate an XML file from a query result. The first
 parameter expects a query result object, the second may contain an
@@ -151,17 +159,17 @@ optional array of config parameters. Example::
 	
 	echo $this->dbutil->xml_from_result($query, $config);
 
-.. important:: This function will NOT write the XML file for you. It
+.. important:: This method will NOT write the XML file for you. It
 	simply creates the XML layout. If you need to write the file
 	use the :doc:`File Helper <../helpers/file_helper>`.
 
-$this->dbutil->backup()
-=======================
+$this->dbutil->backup();
+========================
 
 Permits you to backup your full database or individual tables. The
 backup data can be compressed in either Zip or Gzip format.
 
-.. note:: This features is only available for MySQL and Interbase/Firebird databases.
+.. note:: This feature is only available for MySQL and Interbase/Firebird databases.
 
 .. note:: For Interbase/Firebird databases, the backup file name is the only parameter.
 	
@@ -196,16 +204,16 @@ Setting Backup Preferences
 --------------------------
 
 Backup preferences are set by submitting an array of values to the first
-parameter of the backup function. Example::
+parameter of the ``backup()`` method. Example::
 
 	$prefs = array(
-		'tables'		=> array('table1', 'table2'),	// Array of tables to backup.
-		'ignore'		=> array(),						// List of tables to omit from the backup
-		'format'		=> 'txt',						// gzip, zip, txt
-		'filename'		=> 'mybackup.sql',				// File name - NEEDED ONLY WITH ZIP FILES
-		'add_drop'		=> TRUE,						// Whether to add DROP TABLE statements to backup file
-		'add_insert'	=> TRUE,						// Whether to add INSERT data to backup file
-		'newline'		=> "\n"							// Newline character used in backup file
+		'tables'	=> array('table1', 'table2'),	// Array of tables to backup.
+		'ignore'	=> array(),			// List of tables to omit from the backup
+		'format'	=> 'txt',			// gzip, zip, txt
+		'filename'	=> 'mybackup.sql',		// File name - NEEDED ONLY WITH ZIP FILES
+		'add_drop'	=> TRUE,			// Whether to add DROP TABLE statements to backup file
+		'add_insert'	=> TRUE,			// Whether to add INSERT data to backup file
+		'newline'	=> "\n"				// Newline character used in backup file
 	);
 	
 	$this->dbutil->backup($prefs);
diff --git a/user_guide_src/source/installation/upgrade_300.rst b/user_guide_src/source/installation/upgrade_300.rst
index 4e0b952d5..c06dab793 100644
--- a/user_guide_src/source/installation/upgrade_300.rst
+++ b/user_guide_src/source/installation/upgrade_300.rst
@@ -99,7 +99,7 @@ Step 9: Update usage of Database Forge's drop_table() method
 
 Up until now, ``drop_table()`` added an IF EXISTS clause by default or it didn't work
 at all with some drivers. In CodeIgniter 3.0, the IF EXISTS condition is no longer added
-by deafault and has an optional second parameter that allows that instead and is set to
+by default and has an optional second parameter that allows that instead and is set to
 FALSE by default.
 
 If your application relies on IF EXISTS, you'll have to change its usage.