summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/database/connecting.rst
diff options
context:
space:
mode:
Diffstat (limited to 'user_guide_src/source/database/connecting.rst')
-rw-r--r--user_guide_src/source/database/connecting.rst147
1 files changed, 147 insertions, 0 deletions
diff --git a/user_guide_src/source/database/connecting.rst b/user_guide_src/source/database/connecting.rst
new file mode 100644
index 000000000..a834cc0f7
--- /dev/null
+++ b/user_guide_src/source/database/connecting.rst
@@ -0,0 +1,147 @@
+###########################
+Connecting to your Database
+###########################
+
+There are two ways to connect to a database:
+
+Automatically Connecting
+========================
+
+The "auto connect" feature will load and instantiate the database class
+with every page load. To enable "auto connecting", add the word database
+to the library array, as indicated in the following file:
+
+application/config/autoload.php
+
+Manually Connecting
+===================
+
+If only some of your pages require database connectivity you can
+manually connect to your database by adding this line of code in any
+function where it is needed, or in your class constructor to make the
+database available globally in that class.
+
+::
+
+ $this->load->database();
+
+If the above function does **not** contain any information in the first
+parameter it will connect to the group specified in your database config
+file. For most people, this is the preferred method of use.
+
+Available Parameters
+--------------------
+
+#. The database connection values, passed either as an array or a DSN
+ string.
+#. TRUE/FALSE (boolean). Whether to return the connection ID (see
+ Connecting to Multiple Databases below).
+#. TRUE/FALSE (boolean). Whether to enable the Active Record class. Set
+ to TRUE by default.
+
+Manually Connecting to a Database
+---------------------------------
+
+The first parameter of this function can **optionally** be used to
+specify a particular database group from your config file, or you can
+even submit connection values for a database that is not specified in
+your config file. Examples:
+
+To choose a specific group from your config file you can do this::
+
+ $this->load->database('group_name');
+
+Where group_name is the name of the connection group from your config
+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";
+ $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'
+
+Or you can submit your database values as a Data Source Name. DSNs must
+have this prototype::
+
+ $dsn = 'dbdriver://username:password@hostname/database';
+ $this->load->database($dsn);
+
+To override default config values when connecting with a DSN string, add
+the config variables as a query string.
+
+::
+
+ $dsn = 'dbdriver://username:password@hostname/database?char_set=utf8&dbcollat=utf8_general_ci&cache_on=true&cachedir=/path/to/cache';
+ $this->load->database($dsn);
+
+Connecting to Multiple Databases
+================================
+
+If you need to connect to more than one database simultaneously you can
+do so as follows::
+
+ $DB1 = $this->load->database('group_one', TRUE);
+ $DB2 = $this->load->database('group_two', TRUE);
+
+Note: Change the words "group_one" and "group_two" to the specific
+group names you are connecting to (or you can pass the connection values
+as indicated above).
+
+By setting the second parameter to TRUE (boolean) the function will
+return the database object.
+
+.. note:: When you connect this way, you will use your object name to issue
+ commands rather than the syntax used throughout this guide. In other
+ words, rather than issuing commands with:
+
+ |
+ | $this->db->query();
+ | $this->db->result();
+ | etc...
+ |
+ | You will instead use:
+ |
+ | $DB1->query();
+ | $DB1->result();
+ | etc...
+
+Reconnecting / Keeping the Connection Alive
+===========================================
+
+If the database server's idle timeout is exceeded while you're doing
+some heavy PHP lifting (processing an image, for instance), you should
+consider pinging the server by using the reconnect() method before
+sending further queries, which can gracefully keep the connection alive
+or re-establish it.
+
+::
+
+ $this->db->reconnect();
+
+Manually closing the Connection
+===============================
+
+While CodeIgniter intelligently takes care of closing your database
+connections, you can explicitly close the connection.
+
+::
+
+ $this->db->close();
+