summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source
diff options
context:
space:
mode:
authorAndrey Andreev <narf@devilix.net>2015-12-14 16:56:14 +0100
committerAndrey Andreev <narf@devilix.net>2015-12-14 16:56:14 +0100
commit85bc9fc53e4c3e46b2f4e1b1eac7e2828d4869e6 (patch)
tree78abe651f52c39be43a3e22ba38c1e83160a7bc8 /user_guide_src/source
parent788fb4aa823179e7c4401f5384207d916697bb7e (diff)
Change DB charset handling
Close #4311
Diffstat (limited to 'user_guide_src/source')
-rw-r--r--user_guide_src/source/changelog.rst5
-rw-r--r--user_guide_src/source/database/db_driver_reference.rst11
-rw-r--r--user_guide_src/source/installation/upgrade_310.rst45
3 files changed, 49 insertions, 12 deletions
diff --git a/user_guide_src/source/changelog.rst b/user_guide_src/source/changelog.rst
index 6d7474765..3c0dc8a72 100644
--- a/user_guide_src/source/changelog.rst
+++ b/user_guide_src/source/changelog.rst
@@ -13,8 +13,9 @@ Release Date: Not Released
- Database
- - Failure to initialize a database connection will now throw a ``RuntimeException``.
-
+ - Changed method ``initialize()`` to return void and instead throw a ``RuntimeException`` in case of failure.
+ - Changed method ``db_connect()`` to always set the connection character set (if supported by the driver) and to fail if it can't.
+ - Removed method ``db_set_charset()`` and the ability to change a connection character set at runtime.
Version 3.0.4
=============
diff --git a/user_guide_src/source/database/db_driver_reference.rst b/user_guide_src/source/database/db_driver_reference.rst
index f0a438883..75d1538bd 100644
--- a/user_guide_src/source/database/db_driver_reference.rst
+++ b/user_guide_src/source/database/db_driver_reference.rst
@@ -17,8 +17,7 @@ This article is intended to be a reference for them.
.. php:method:: initialize()
- :returns: TRUE on success, FALSE on failure
- :rtype: bool
+ :rtype: void
:throws: RuntimeException In case of failure
Initialize database settings, establish a connection to
@@ -62,14 +61,6 @@ This article is intended to be a reference for them.
Select / switch the current database.
- .. php:method:: db_set_charset($charset)
-
- :param string $charset: Character set name
- :returns: TRUE on success, FALSE on failure
- :rtype: bool
-
- Set client character set.
-
.. php:method:: platform()
:returns: Platform name
diff --git a/user_guide_src/source/installation/upgrade_310.rst b/user_guide_src/source/installation/upgrade_310.rst
index 7060ebc4c..37772cd4f 100644
--- a/user_guide_src/source/installation/upgrade_310.rst
+++ b/user_guide_src/source/installation/upgrade_310.rst
@@ -12,3 +12,48 @@ Replace all files and directories in your *system/* directory.
.. note:: If you have any custom developed files in these directories,
please make copies of them first.
+
+Step 2: Change database connection handling
+===========================================
+
+"Loading" a database, whether by using the *config/autoload.php* settings
+or manually via calling ``$this->load->database()`` or the less-known
+``DB()`` function, will now throw a ``RuntimeException`` in case of a
+failure.
+
+In addition, being unable to set the configured character set is now also
+considered a connection failure.
+
+.. note:: This has been the case for most database drivers in the in the
+ past as well (i.e. all but the 'mysql', 'mysqli' and 'postgre'
+ drivers).
+
+What this means is that if you're unable to connect to a database, or
+have an erroneous character set configured, CodeIgniter will no longer
+fail silently, but will throw an exception instead.
+
+You may choose to explicitly catch it (and for that purpose you can't use
+*config/autoload.php* to load the :doc:`Database Class <../database/index>`)
+::
+
+ try
+ {
+ $this->load->database();
+ }
+ catch (RuntimeException $e)
+ {
+ // Handle the failure
+ }
+
+Or you may leave it to CodeIgniter's default exception handler, which would
+log the error message and display an error screen if you're running in
+development mode.
+
+Remove db_set_charset() calls
+-----------------------------
+
+With the above-mentioned changes, the purpose of the ``db_set_charset()``
+method would now only be to change the connection character set at runtime.
+That doesn't make sense and that's the reason why most database drivers
+don't support it at all.
+Thus, ``db_set_charset()`` is no longer necessary and is removed.