1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Database Forge Class : CodeIgniter User Guide</title>
<style type='text/css' media='all'>@import url('../userguide.css');</style>
<link rel='stylesheet' type='text/css' media='all' href='../userguide.css' />
<script type="text/javascript" src="../nav/nav.js"></script>
<script type="text/javascript" src="../nav/prototype.lite.js"></script>
<script type="text/javascript" src="../nav/moo.fx.js"></script>
<script type="text/javascript" src="../nav/user_guide_menu.js"></script>
<meta http-equiv='expires' content='-1' />
<meta http-equiv= 'pragma' content='no-cache' />
<meta name='robots' content='all' />
<meta name='author' content='ExpressionEngine Dev Team' />
<meta name='description' content='CodeIgniter User Guide' />
</head>
<body>
<!-- START NAVIGATION -->
<div id="nav"><div id="nav_inner"><script type="text/javascript">create_menu('../');</script></div></div>
<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>
<div id="masthead">
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td><h1>CodeIgniter User Guide Version 1.7.1</h1></td>
<td id="breadcrumb_right"><a href="../toc.html">Table of Contents Page</a></td>
</tr>
</table>
</div>
<!-- END NAVIGATION -->
<!-- START BREADCRUMB -->
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td id="breadcrumb">
<a href="http://codeigniter.com/">CodeIgniter Home</a> ›
<a href="../index.html">User Guide Home</a> ›
<a href="index.html">Database Library</a> ›
Database Forge Class
</td>
<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 <input type="text" class="input" style="width:200px;" name="q" id="q" size="31" maxlength="255" value="" /> <input type="submit" class="submit" name="sa" value="Go" /></form></td>
</tr>
</table>
<!-- END BREADCRUMB -->
<br clear="all" />
<!-- START CONTENT -->
<div id="content">
<h1>Database Forge Class</h1>
<p>The Database Forge Class contains functions that help you manage your database.</p>
<h3>Table of Contents</h3>
<ul>
<li><a href="#init">Initializing the Forge Class</a></li>
<li><a href="#create">Creating a Database</a></li>
<li><a href="#drop">Dropping a Database</a></li>
<li><a href="#add_field">Adding Fields</a></li>
<li><a href="#add_key">Adding Keys</a></li>
<li><a href="#create_table">Creating a Table</a></li>
<li><a href="#drop_table">Dropping a Table</a></li>
<li><a href="#rename_table">Renaming a Table</a></li>
<li><a href="#modifying_tables">Modifying a Table</a></li>
</ul>
<h2><a name="init"></a>Initializing the Forge Class</h2>
<p class="important"><strong>Important:</strong> In order to initialize the Forge class, your database driver must
already be running, since the forge class relies on it.</p>
<p>Load the Forge Class as follows:</p>
<code>$this->load->dbforge()</code>
<p>Once initialized you will access the functions using the <dfn>$this->dbforge</dfn> object:</p>
<code>$this->dbforge->some_function()</code>
<h2><a name="create"></a>$this->dbforge->create_database('db_name')</h2>
<p>Permits you to create the database specified in the first parameter. Returns TRUE/FALSE based on success or failure:</p>
<code>if ($this->dbforge->create_database('my_db'))<br />
{<br />
echo 'Database created!';<br />
}</code>
<h2><a name="drop"></a>$this->dbforge->drop_database('db_name')</h2>
<p>Permits you to drop the database specified in the first parameter. Returns TRUE/FALSE based on success or failure:</p>
<code>if ($this->dbforge->drop_database('my_db'))<br />
{<br />
echo 'Database deleted!';<br />
}</code>
<h1>Creating and Dropping Tables</h1>
<p>There are several things you may wish to do when creating tables. Add fields, add keys to the table, alter columns. CodeIgniter provides a mechanism for this.</p>
<h2><a name="add_field" id="add_field"></a>Adding fields</h2>
<p>Fields are created via an associative array. Within the array you must include a 'type' key that relates to the datatype of the field. For example, INT, VARCHAR, TEXT, etc. Many datatypes (for example VARCHAR) also require a 'constraint' key.</p>
<p><code>$fields = array(<br />
'users' => array(<br />
'type' => 'VARCHAR',<br />
'constraint' => '100',<br />
),<br />
);<br />
<br />
// will translate to "users VARCHAR(100)" when the field is added.</code></p>
<p>Additionally, the following key/values can be used:</p>
<ul>
<li>unsigned/true : to generate "UNSIGNED" in the field definition.</li>
<li>default/value : to generate a default value in the field definition.</li>
<li>null/true : to generate "NULL" in the field definition. Without this, the field will default to "NOT NULL".</li>
<li>auto_increment/true : generates an auto_increment flag on the field. Note that the field type must be a type that supports this, such as integer.</li>
</ul>
<p><code>$fields = array(<br />
'blog_id' => array(<br />
'type' => 'INT',<br />
'constraint' => 5, <br />
'unsigned' => TRUE,<br />
'auto_increment' => TRUE<br />
),<br />
'blog_title' => array(<br />
'type' => 'VARCHAR',<br />
'constraint' => '100',<br />
),<br />
'blog_author' => array(<br />
'type' =>'VARCHAR',<br />
'constraint' => '100',<br />
'default' => 'King of Town',<br />
),<br />
'blog_description' => array(<br />
'type' => 'TEXT',<br />
'null' => TRUE,<br />
),<br />
);<br />
</code></p>
<p>After the fields have been defined, they can be added using <dfn>$this->dbforge->add_field($fields);</dfn> followed by a call to the <dfn>create_table()</dfn> function.</p>
<h3>$this->dbforge->add_field()</h3>
<p>The add fields function will accept the above array.</p>
<h3>Passing strings as fields</h3>
<p>If you know exactly how you want a field to be created, you can pass the string into the field definitions with add_field()</p>
<p><code>$this->dbforge->add_field("label varchar(100) NOT NULL DEFAULT 'default label'");</code></p>
<p class="important">Note: Multiple calls to <dfn>add_field()</dfn> are cumulative.</p>
<h3>Creating an id field</h3>
<p>There is a special exception for creating id fields. A field with type id will automatically be assinged as an INT(9) auto_incrementing Primary Key.</p>
<p><code>$this->dbforge->add_field('id');<br />
// gives id INT(9) NOT NULL AUTO_INCREMENT</code></p>
<h2><a name="add_key" id="add_key"></a>Adding Keys</h2>
<p>Generally speaking, you'll want your table to have Keys. This is accomplished with <dfn>$this->dbforge->add_key('field')</dfn>. An optional second parameter set to TRUE will make it a primary key. Note that <dfn>add_key()</dfn> must be followed by a call to <dfn>create_table()</dfn>.</p>
<p>Multiple column non-primary keys must be sent as an array. Sample output below is for MySQL.</p>
<p><code>$this->dbforge->add_key('blog_id', TRUE);<br />
// gives PRIMARY KEY `blog_id` (`blog_id`)<br />
<br />
$this->dbforge->add_key('blog_id', TRUE);<br />
$this->dbforge->add_key('site_id', TRUE);<br />
// gives PRIMARY KEY `blog_id_site_id` (`blog_id`, `site_id`)<br />
<br />
$this->dbforge->add_key('blog_name');<br />
// gives KEY `blog_name` (`blog_name`)<br />
<br />
$this->dbforge->add_key(array('blog_name', 'blog_label'));<br />
// gives KEY `blog_name_blog_label` (`blog_name`, `blog_label`)</code></p>
<h2><a name="create_table" id="create_table"></a>Creating a table</h2>
<p>After fields and keys have been declared, you can create a new table with</p>
<p><code>$this->dbforge->create_table('table_name');<br />
// gives CREATE TABLE table_name</code></p>
<p>An optional second parameter set to TRUE adds an "IF NOT EXISTS" clause into the definition</p>
<p><code>$this->dbforge->create_table('table_name', TRUE);<br />
// gives CREATE TABLE IF NOT EXISTS table_name</code></p>
<h2><a name="drop_table" id="drop_table"></a>Dropping a table</h2>
<p>Executes a DROP TABLE sql</p>
<p><code>$this->dbforge->drop_table('table_name');<br />
// gives DROP TABLE IF EXISTS table_name</code></p>
<h2><a name="rename_table" id="rename_table"></a>Renaming a table</h2>
<p>Executes a TABLE rename</p>
<p><code>$this->dbforge->rename_table('old_table_name', 'new_table_name');<br />
// gives ALTER TABLE old_table_name RENAME TO new_table_name</code></p>
<h1><a name="modifying_tables" id="modifying_tables"></a>Modifying Tables</h1>
<h2>$this->dbforge->add_column()</h2>
<p>The add_column() function is used to modify an existing table. It accepts the same field array as above, and can be used for an unlimited number of additional fields.</p>
<p><code>$fields = array(<br />
'preferences' => array('type' => 'TEXT')<br />
);<br />
$this->dbforge->add_column('table_name', $fields);<br />
<br />
// gives ALTER TABLE table_name ADD preferences TEXT</code></p>
<h2>$this->dbforge->drop_column()</h2>
<p>Used to remove a column from a table. </p>
<p><code>$this->dbforge->drop_column('table_name', 'column_to_drop');</code></p>
<h2>$this->dbforge->modify_column()</h2>
<p>The usage of this function is identical to add_column(), except it alters an existing column rather than adding a new one. In order to use it you must add a "name" key into the field defining array.</p>
<p><code>$fields = array(<br />
'old_name' => array(<br />
'name' => 'new_name',<br />
'type' => 'TEXT',<br />
),<br />
);<br />
$this->dbforge->modify_column('table_name', $fields);<br />
<br />
// gives ALTER TABLE table_name CHANGE old_name new_name TEXT </code></p>
<p> </p>
</div>
<!-- END CONTENT -->
<div id="footer">
<p>
Previous Topic: <a href="caching.html">DB Caching Class</a>
·
<a href="#top">Top of Page</a> ·
<a href="../index.html">User Guide Home</a> ·
Next Topic: <a href="utilities.html">Database Utilities Class</a><a href="../libraries/email.html"></a></p>
<p><a href="http://codeigniter.com">CodeIgniter</a> · Copyright © 2006-2009 · <a href="http://ellislab.com/">Ellislab, Inc.</a></p>
</div>
</body>
</html>
|
