Merge branch 'develop' of https://github.com/EllisLab/CodeIgniter into develop

2 files changed, 87 insertions, 69 deletions

diff --git a/user_guide_src/source/database/configuration.rst b/user_guide_src/source/database/configuration.rst
index 7a19c840f..c17de600a 100644
--- a/user_guide_src/source/database/configuration.rst
+++ b/user_guide_src/source/database/configuration.rst
@@ -12,26 +12,44 @@ it the respective environment config folder.
 The config settings are stored in a multi-dimensional array with this
 prototype::
 
-	$db['default']['hostname'] = "localhost";
-	$db['default']['username'] = "root";
-	$db['default']['password'] = "";
-	$db['default']['database'] = "database_name";
-	$db['default']['dbdriver'] = "mysql";
-	$db['default']['dbprefix'] = "";
-	$db['default']['pconnect'] = TRUE;
-	$db['default']['db_debug'] = FALSE;
-	$db['default']['cache_on'] = FALSE;
-	$db['default']['cachedir'] =  "";
-	$db['default']['char_set'] = "utf8";
-	$db['default']['dbcollat'] = "utf8_general_ci";
-	$db['default']['swap_pre'] = "";
-	$db['default']['autoinit'] = TRUE;
-	$db['default']['stricton'] = FALSE;
-
-If you use PDO as your dbdriver, you can specify the full DSN string describe a connection to the database like this::
-
+	$db['default'] = array(
+		'dsn'	=> '',
+		'hostname' => 'localhost',
+		'username' => 'root',
+		'password' => '',
+		'database' => 'database_name',
+		'dbdriver' => 'mysqli',
+		'dbprefix' => '',
+		'pconnect' => TRUE,
+		'db_debug' => TRUE,
+		'cache_on' => FALSE,
+		'cachedir' => '',
+		'char_set' => 'utf8',
+		'dbcollat' => 'utf8_general_ci',
+		'swap_pre' => '',
+		'autoinit' => TRUE,
+		'stricton' => FALSE,
+		'failover' => array()
+	);
+
+Some database drivers (such as PDO, PostgreSQL, Oracle, ODBC) might
+require a full DSN string to be provided. If that is the case, you
+should use the 'dsn' configuration setting, as if you're using the
+driver's underlying native PHP extension, like this::
+
+	// PDO
 	$db['default']['dsn'] = 'pgsql:host=localhost;port=5432;dbname=database_name';
 
+	// Oracle
+	$db['default']['dsn'] = '//localhost/XE';
+
+.. note:: If you do not specify a DSN string for a driver that requires it, CodeIgniter
+	will try to build it with the rest of the provided settings.
+
+.. note:: If you provide a DSN string and it is missing some valid settings (e.g. the
+	database character set), which are present in the rest of the configuration
+	fields, CodeIgniter will append them.
+
 You can also specify failovers for the situation when the main connection cannot connect for some reason.
 These failovers can be specified by setting the failover for a connection like this::
 
@@ -41,7 +59,7 @@ These failovers can be specified by setting the failover for a connection like t
 				'username' => '',
 				'password' => '',
 				'database' => '',
-				'dbdriver' => 'mysql',
+				'dbdriver' => 'mysqli',
 				'dbprefix' => '',
 				'pconnect' => TRUE,
 				'db_debug' => TRUE,
@@ -58,7 +76,7 @@ These failovers can be specified by setting the failover for a connection like t
 				'username' => '',
 				'password' => '',
 				'database' => '',
-				'dbdriver' => 'mysql',
+				'dbdriver' => 'mysqli',
 				'dbprefix' => '',
 				'pconnect' => TRUE,
 				'db_debug' => TRUE,
@@ -81,30 +99,34 @@ production, test, etc.) under a single installation, you can set up a
 connection group for each, then switch between groups as needed. For
 example, to set up a "test" environment you would do this::
 
-	$db['test']['hostname'] = "localhost";
-	$db['test']['username'] = "root";
-	$db['test']['password'] = "";
-	$db['test']['database'] = "database_name";
-	$db['test']['dbdriver'] = "mysql";
-	$db['test']['dbprefix'] = "";
-	$db['test']['pconnect'] = TRUE;
-	$db['test']['db_debug'] = FALSE;
-	$db['test']['cache_on'] = FALSE;
-	$db['test']['cachedir'] =  "";
-	$db['test']['char_set'] = "utf8";
-	$db['test']['dbcollat'] = "utf8_general_ci";
-	$db['test']['swap_pre'] = "";
-	$db['test']['autoinit'] = TRUE;
-	$db['test']['stricton'] = FALSE;
+	$db['test'] = array(
+		'dsn'	=> '',
+		'hostname' => 'localhost',
+		'username' => 'root',
+		'password' => '',
+		'database' => 'database_name',
+		'dbdriver' => 'mysqli',
+		'dbprefix' => '',
+		'pconnect' => TRUE,
+		'db_debug' => TRUE,
+		'cache_on' => FALSE,
+		'cachedir' => '',
+		'char_set' => 'utf8',
+		'dbcollat' => 'utf8_general_ci',
+		'swap_pre' => '',
+		'autoinit' => TRUE,
+		'stricton' => FALSE,
+		'failover' => array()
+	);
 
 Then, to globally tell the system to use that group you would set this
 variable located in the config file::
 
-	$active_group = "test";
+	$active_group = 'test';
 
-Note: The name "test" is arbitrary. It can be anything you want. By
-default we've used the word "default" for the primary connection, but it
-too can be renamed to something more relevant to your project.
+.. note:: The name 'test' is arbitrary. It can be anything you want. By
+	default we've used the word "default" for the primary connection,
+	but it too can be renamed to something more relevant to your project.
 
 Query Builder
 -------------
@@ -119,8 +141,8 @@ when the database classes are initialized.
 
 	$query_builder = TRUE;
 
-.. note:: that some CodeIgniter classes such as Sessions require Active
-	Records be enabled to access certain functionality.
+.. note:: that some CodeIgniter classes such as Sessions require Query
+	Builder to be enabled to access certain functionality.
 
 Explanation of Values:
 ----------------------
@@ -128,11 +150,12 @@ Explanation of Values:
 ======================  ==================================================================================================
  Name Config             Description
 ======================  ==================================================================================================
-**hostname** 		The hostname of your database server. Often this is "localhost".
+**dsn**			The DSN connect string (an all-in-one configuration sequence).
+**hostname** 		The hostname of your database server. Often this is 'localhost'.
 **username**		The username used to connect to the database.
 **password**		The password used to connect to the database.
 **database**		The name of the database you want to connect to.
-**dbdriver**		The database type. ie: mysql, postgre, odbc, etc. Must be specified in lower case.
+**dbdriver**		The database type. ie: mysqli, postgre, odbc, etc. Must be specified in lower case.
 **dbprefix**		An optional table prefix which will added to the table name when running :doc:
 			`Query Builder <query_builder>` queries. This permits multiple CodeIgniter installations
 			to share one database.
@@ -144,14 +167,7 @@ Explanation of Values:
 **char_set**		The character set used in communicating with the database.
 **dbcollat**		The character collation used in communicating with the database
 
-			.. note:: For MySQL and MySQLi databases, this setting is only used
-				as a backup if your server is running PHP < 5.2.3 or MySQL < 5.0.7
-				(and in table creation queries made with DB Forge). There is an
-				incompatibility in PHP with mysql_real_escape_string() which can
-				make your site vulnerable to SQL injection if you are using a
-				multi-byte character set and are running versions lower than these.
-				Sites using Latin-1 or UTF-8 database character set and collation are
-				unaffected.
+			.. note:: Only used in the 'mysql' and 'mysqli' drivers.
 
 **swap_pre**		A default table prefix that should be swapped with dbprefix. This is useful for distributed
 			applications where you might run manually written queries, and need the prefix to still be
@@ -163,11 +179,11 @@ Explanation of Values:
 **port**		The database port number. To use this value you have to add a line to the database config array.
 			::
 			
-				$db['default']['port'] =  5432;
+				$db['default']['port'] = 5432;
 ======================  ==================================================================================================
 
 .. note:: Depending on what database platform you are using (MySQL, PostgreSQL,
 	etc.) not all values will be needed. For example, when using SQLite you
 	will not need to supply a username or password, and the database name
 	will be the path to your database file. The information above assumes
-	you are using MySQL.
+	you are using MySQL.
\ No newline at end of file
diff --git a/user_guide_src/source/database/connecting.rst b/user_guide_src/source/database/connecting.rst
index 5822ca62c..9b8117076 100644
--- a/user_guide_src/source/database/connecting.rst
+++ b/user_guide_src/source/database/connecting.rst
@@ -57,25 +57,28 @@ file.
 To connect manually to a desired database you can pass an array of
 values::
 
-	$config['hostname'] = "localhost"; 
-	$config['username'] = "myusername"; 
-	$config['password'] = "mypassword"; 
-	$config['database'] = "mydatabase"; 
-	$config['dbdriver'] = "mysql"; 
-	$config['dbprefix'] = ""; 
-	$config['pconnect'] = FALSE; 
-	$config['db_debug'] = TRUE; 
-	$config['cache_on'] = FALSE; 
-	$config['cachedir'] = ""; 
-	$config['char_set'] = "utf8"; 
-	$config['dbcollat'] = "utf8_general_ci";  
+	$config['hostname'] = 'localhost';
+	$config['username'] = 'myusername';
+	$config['password'] = 'mypassword';
+	$config['database'] = 'mydatabase';
+	$config['dbdriver'] = 'mysqli';
+	$config['dbprefix'] = '';
+	$config['pconnect'] = FALSE;
+	$config['db_debug'] = TRUE;
+	$config['cache_on'] = FALSE;
+	$config['cachedir'] = '';
+	$config['char_set'] = 'utf8';
+	$config['dbcollat'] = 'utf8_general_ci';
 	$this->load->database($config);
 
 For information on each of these values please see the :doc:`configuration
 page <configuration>`.
 
-.. note:: For the PDO driver, $config['hostname'] should look like
-	this: 'mysql:host=localhost'
+.. note:: For the PDO driver, you should use the $config['dsn'] setting
+	instead of 'hostname' and 'database':
+
+	|
+	| $config['dsn'] = 'mysql:host=localhost;dbname=mydatabase';
 
 Or you can submit your database values as a Data Source Name. DSNs must
 have this prototype::
@@ -149,5 +152,4 @@ connections, you can explicitly close the connection.
 
 ::
 
-	$this->db->close();
-
+	$this->db->close();
\ No newline at end of file