Gitiles
Code Review Sign In
www.giggi.me / code-igniter-v3-giggi / 5f13efe24a86833cb66d967a791e0eb215c22bfc / . / user_guide / database / connecting.html
blob: b18088132a274ecaceee8d226dc563a53ddf400e [file] [log] [blame]
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
3<head>
4
5<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6<title>Connecting to your Database : CodeIgniter User Guide</title>
7
8<style type='text/css' media='all'>@import url('../userguide.css');</style>
9<link rel='stylesheet' type='text/css' media='all' href='../userguide.css' />
10
11<script type="text/javascript" src="../nav/nav.js"></script>
12<script type="text/javascript" src="../nav/prototype.lite.js"></script>
13<script type="text/javascript" src="../nav/moo.fx.js"></script>
14<script type="text/javascript" src="../nav/user_guide_menu.js"></script>
15
16<meta http-equiv='expires' content='-1' />
17<meta http-equiv= 'pragma' content='no-cache' />
18<meta name='robots' content='all' />
19<meta name='author' content='ExpressionEngine Dev Team' />
20<meta name='description' content='CodeIgniter User Guide' />
21
22</head>
23<body>
24
25<!-- START NAVIGATION -->
26<div id="nav"><div id="nav_inner"><script type="text/javascript">create_menu('../');</script></div></div>
27<div id="nav2"><a name="top"></a><a href="javascript:void(0);" onclick="myHeight.toggle();"><img src="../images/nav_toggle_darker.jpg" width="154" height="43" border="0" title="Toggle Table of Contents" alt="Toggle Table of Contents" /></a></div>
28<div id="masthead">
29<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
30<tr>
Derek Jonesb8c038a2011-08-20 08:57:14 -0500[diff] [blame]31<td><h1>CodeIgniter User Guide Version 2.0.3</h1></td>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]32<td id="breadcrumb_right"><a href="../toc.html">Table of Contents Page</a></td>
33</tr>
34</table>
35</div>
36<!-- END NAVIGATION -->
37
38
39<!-- START BREADCRUMB -->
40<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
41<tr>
42<td id="breadcrumb">
43<a href="http://codeigniter.com/">CodeIgniter Home</a> &nbsp;&#8250;&nbsp;
44<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
45<a href="index.html">Database Library</a> &nbsp;&#8250;&nbsp;
46Connecting
47</td>
48<td id="searchbox"><form method="get" action="http://www.google.com/search"><input type="hidden" name="as_sitesearch" id="as_sitesearch" value="codeigniter.com/user_guide/" />Search User Guide&nbsp; <input type="text" class="input" style="width:200px;" name="q" id="q" size="31" maxlength="255" value="" />&nbsp;<input type="submit" class="submit" name="sa" value="Go" /></form></td>
49</tr>
50</table>
51<!-- END BREADCRUMB -->
52
53
54<br clear="all" />
55
56
57<!-- START CONTENT -->
58<div id="content">
59
60
61<h1>Connecting to your Database</h1>
62
63<p>There are two ways to connect to a database:</p>
64
65<h2>Automatically Connecting</h2>
66
67<p>The "auto connect" feature will load and instantiate the database class with every page load.
68To enable "auto connecting", add the word <var>database</var> to the library array, as indicated in the following file:</p>
69
70<p><kbd>application/config/autoload.php</kbd></p>
71
72<h2>Manually Connecting</h2>
73
74<p>If only some of your pages require database connectivity you can manually connect to your database by adding this
75line of code in any function where it is needed, or in your class constructor to make the database
76available globally in that class.</p>
77
78<code>$this->load->database();</code>
79
80<p class="important">If the above function does <strong>not</strong> contain any information in the first parameter it will connect
81to the group specified in your database config file. For most people, this is the preferred method of use.</p>
82
83<h3>Available Parameters</h3>
84
85<ol>
86 <li>The database connection values, passed either as an array or a DSN string.</li>
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]87 <li>TRUE/FALSE (boolean). Whether to return the connection ID (see Connecting to Multiple Databases below).</li>
88 <li>TRUE/FALSE (boolean). Whether to enable the Active Record class. Set to TRUE by default.</li>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]89</ol>
90
91
Derek Allard3f45bbd2008-12-07 17:00:09 +0000[diff] [blame]92<h3>Manually Connecting to a Database</h3>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]93
94<p>The first parameter of this function can <strong>optionally</strong> be used to specify a particular database group
95from your config file, or you can even submit connection values for a database that is not specified in your config file.
96Examples:</p>
97
98<p>To choose a specific group from your config file you can do this:</p>
99
100<code>$this->load->database('<samp>group_name</samp>');</code>
101
102<p>Where <samp>group_name</samp> is the name of the connection group from your config file.</p>
103
104
105<p>To connect manually to a desired database you can pass an array of values:</p>
106
107<code>$config['hostname'] = "localhost";<br />
108$config['username'] = "myusername";<br />
109$config['password'] = "mypassword";<br />
110$config['database'] = "mydatabase";<br />
111$config['dbdriver'] = "mysql";<br />
112$config['dbprefix'] = "";<br />
113$config['pconnect'] = FALSE;<br />
114$config['db_debug'] = TRUE;<br />
115$config['cache_on'] = FALSE;<br />
116$config['cachedir'] = "";<br />
117$config['char_set'] = "utf8";<br />
118$config['dbcollat'] = "utf8_general_ci";<br />
119<br />
120$this->load->database(<samp>$config</samp>);</code>
121
122<p>For information on each of these values please see the <a href="configuration.html">configuration page</a>.</p>
123
Timothy Warren9d9fe162011-09-14 11:03:32 -0400[diff] [blame]124<p class="important"><strong>Note:</strong> For the PDO driver, $config['hostname'] should look like this: 'mysql:host=localhost'</p>
125
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]126<p>Or you can submit your database values as a Data Source Name. DSNs must have this prototype:</p>
127
128<code>$dsn = 'dbdriver://username:password@hostname/database';<br />
129<br />
130$this->load->database(<samp>$dsn</samp>);</code>
131
132<p>To override default config values when connecting with a DSN string, add the config variables as a query string.</p>
133
134<code>$dsn = 'dbdriver://username:password@hostname/database?char_set=utf8&amp;dbcollat=utf8_general_ci&amp;cache_on=true&amp;cachedir=/path/to/cache';<br />
135<br />
136$this->load->database(<samp>$dsn</samp>);</code>
137
138<h2>Connecting to Multiple Databases</h2>
139
140<p>If you need to connect to more than one database simultaneously you can do so as follows:</p>
141
142
143<code>$DB1 = $this->load->database('group_one', TRUE);<br />
144$DB2 = $this->load->database('group_two', TRUE);
145</code>
146
147<p>Note: Change the words "group_one" and "group_two" to the specific group names you are connecting to (or
148you can pass the connection values as indicated above).</p>
149
150<p>By setting the second parameter to TRUE (boolean) the function will return the database object.</p>
151
152<div class="important">
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]153<p>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:</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]154
155<p>$this->db->query();<br />$this->db->result();<br /> etc...</p>
156
157<p>You will instead use:</p>
158
159<p>$DB1->query();<br />$DB1->result();<br /> etc...</p>
160
161</div>
162
Derek Jones87cbafc2009-02-27 16:29:59 +0000[diff] [blame]163<h2>Reconnecting / Keeping the Connection Alive</h2>
164
165<p>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 <dfn>reconnect()</dfn> method before sending further queries, which can gracefully keep the connection alive or re-establish it.</p>
166
167<code>$this->db->reconnect();</code>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]168
Derek Allard04eb0702010-01-17 07:07:13 +0000[diff] [blame]169<h2>Manually closing the Connection</h2>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]170
Derek Allard04eb0702010-01-17 07:07:13 +0000[diff] [blame]171<p>While CodeIgniter intelligently takes care of closing your database connections, you can explicitly close the connection.</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]172
Derek Allard04eb0702010-01-17 07:07:13 +0000[diff] [blame]173<code>$this->db->close();</code>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]174</div>
175<!-- END CONTENT -->
176
177
178<div id="footer">
179<p>
180Previous Topic:&nbsp;&nbsp;<a href="configuration.html">Database Configuration</a>
181&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
182<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
183<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
184Next Topic:&nbsp;&nbsp;<a href="queries.html">Queries</a>
185</p>
Derek Jones898949f2011-01-28 07:42:16 -0600[diff] [blame]186<p><a href="http://codeigniter.com">CodeIgniter</a> &nbsp;&middot;&nbsp; Copyright &#169; 2006 - 2011 &nbsp;&middot;&nbsp; <a href="http://ellislab.com/">EllisLab, Inc.</a></p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]187</div>
188
189</body>
adminfb28bb82006-09-24 17:59:33 +0000[diff] [blame]190</html>