diff options
Diffstat (limited to 'user_guide_src/source/database/connecting.rst')
| -rw-r--r-- | user_guide_src/source/database/connecting.rst | 147 |
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(); + |