Documentation/database/utilities.html

   1 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   2 <head>
   3         <title>CarbonPHP Documentation</title>
   4         <style type="text/css">
   5                 * {
   6                         margin: 0;
   7                         padding: 0;
   8                 }
   9
  10                 html {
  11                         font-family: "Lucida Sans Unicode", "Lucida Grande";
  12                         font-size: 12px;
  13                 }
  14
  15                 body {
  16                         background: #fff;
  17                         color: #666;
  18                 }
  19
  20                 h1 {
  21                         font-size: 15px;
  22                         font-weight: bold;
  23                         margin: 0 0 5px 0;
  24                 }
  25
  26                 h2 {
  27                         font-size: 13px;
  28                         font-weight: bold;
  29                         margin: 5px 0 5px 0;
  30                 }
  31
  32                 ol, ul {
  33                         margin: 10px 0 10px 0;
  34                         list-style-position: inside;
  35                 }
  36
  37                 p {
  38                         margin: 5px 0 5px 0;
  39                 }
  40
  41                 .content {
  42                         border: 1px dotted #444;
  43                         margin: 10px;
  44                         padding: 10px;
  45                         text-align: justify;
  46                         width: 700px;
  47                 }
  48
  49                 .example {
  50                         border: 1px solid #ccc;
  51                         background: #eee;
  52                         margin: 10px;
  53                         padding: 10px;
  54                         text-align: left;
  55                 }
  56         </style>
  57 </head>
  58
  59 <body>
  60         <div class="content">
  61                 <h1>Database Utilities</h1>
  62
  63                 <p>The database utilities class contains methods that help you manage your databases.</p>
  64         </div>
  65
  66         <div class="content">
  67                 <h1>Intialising the Class</h1>
  68
  69                 <p>In order for you to use this class your database class must already be loaded since this class relies on
  70                 it.  You can load the class by doing the following.</p>
  71
  72                 <div class="example">
  73                         $this->load->dbutil();
  74                 </div>
  75
  76                 <p>Once this class is initialised you can access it via the <b>$this->dbutil</b> object.</p>
  77
  78                 <div class="example">
  79                         $this->dbutil->some_method();
  80                 </div>
  81         </div>
  82
  83         <div class="content">
  84                 <h1>$this->dbutil->create_database('db_name')</h1>
  85
  86                 <p>This allows you to create a database as specified in the first parameter.  It will return true or false
  87                 based on its success or failure.</p>
  88
  89                 <div class="example">
  90                         if ($this->dbutil->create_database('some_database'))<br />
  91                         &#123;<br />
  92                         &nbsp;&nbsp;&nbsp;&nbsp;echo 'Database has been created.';<br />
  93                         &#125;
  94                 </div>
  95         </div>
  96
  97         <div class="content">
  98                 <h1>$this->dbutil->drop_database('db_name')</h1>
  99
 100                 <p>This allows you to drop a database as specified in the first parameter.  It will return true or false
 101                 based on its success or failure.</p>
 102
 103                 <div class="example">
 104                         if ($this->dbutil->drop_database('some_database'))<br />
 105                         &#123;<br />
 106                         &nbsp;&nbsp;&nbsp;&nbsp;echo 'Database has been dropped.';<br />
 107                         &#125;
 108                 </div>
 109         </div>
 110
 111         <div class="content">
 112                 <h1>$this->dbutil->list_databases()</h1>
 113
 114                 <p>This method returns an array of database names.</p>
 115
 116                 <div class="example">
 117                         $dbs = $this->dbutil->list_databases();<br />
 118                         <br />
 119                         foreach ($dbs as $db)<br />
 120                         &#123;<br />
 121                         &nbsp;&nbsp;&nbsp;&nbsp;echo $db;<br />
 122                         &#125;
 123                 </div>
 124         </div>
 125
 126         <div class="content">
 127                 <h1>$this->dbutil->optimise_table('table_name')</h1>
 128
 129                 <p>This method allows you to optimise a table using the table named passed as a parameter.  This method
 130                 returns true or false based on success or failure.  <i>Note</i>: this method is only available for
 131                 MySQL and MySQLi databases.</p>
 132
 133                 <div class="example">
 134                         if ($this->dbutil->optimise_table('table_name'))<br />
 135                         &#123;<br />
 136                         &nbsp;&nbsp;&nbsp;&nbsp;echo 'Optimised that database.';<br />
 137                         &#125;
 138                 </div>
 139         </div>
 140
 141         <div class="content">
 142                 <h1>$this->dbutil->repair_table('table_name')</h1>
 143
 144                 <p>This method allows you to repair a table using a table named passed as a parameter.  This method returns
 145                 true or false based on success or failure.  <i>Note</i>: this method is only available for MySQL and MySQLi
 146                 databases.</p>
 147
 148                 <div class="example">
 149                         if ($this->dbutil->repair_table('table_name'))<br />
 150                         &#123;<br />
 151                         &nbsp;&nbsp;&nbsp;&nbsp;echo 'Repaired the database.';<br />
 152                         &#125;
 153                 </div>
 154         </div>
 155
 156         <div class="content">
 157                 <h1>$this->dbutil->optimise_database()</h1>
 158
 159                 <p>This method allows you to optimise a database that the database class is currently connected to.  This
 160                 method returns an array containing the database status messages or false.  <i>Note</i>: this method is only
 161                 available for MySQL and MySQLi databases.</p>
 162
 163                 <div class="example">
 164                         $result = $this->dbutil->optimise_database();<br />
 165                         <br />
 166                         if ($result !=== false)<br />
 167                         &#123;<br />
 168                         &nbsp;&nbsp;&nbsp;&nbsp;print_r($result);<br />
 169                         &#125;
 170                 </div>
 171         </div>
 172
 173         <div class="content">
 174                 <h1>$this->dbutil->csv_from_result($result)</h1>
 175
 176                 <p>This method allows you to create a CSV file from a query result.  The first parameter is the result object
 177                 from the query.</p>
 178
 179                 <div class="example">
 180                         $this->load->dbutil();<br />
 181                         <br />
 182                         $query = $this->db->query('SELECT * FROM `some_table`');<br />
 183                         <br />
 184                         echo $this->dbutil->csv_from_result($query);
 185                 </div>
 186
 187                 <p>The second and third parameters allow you to set the delimeter and newline characters.  By default tabs
 188                 are used as the delimeter and '\n' as a newline.</p>
 189
 190                 <div class="example">
 191                         $delimeter = ",";<br />
 192                         $newlien = "\r\n";<br />
 193                         <br />
 194                         echo $this->dbutil->csv_from_result($query, $delimeter, $newline);
 195                 </div>
 196
 197                 <p>This method will not write the CSV file for you, only produce the contents of the file.</p>
 198         </div>
 199
 200         <div class="content">
 201                 <h1>$this->dbutil->xml_from_result($result)</h1>
 202
 203                 <p>This method allows you to generate an XML file from a query result.  The first parameter is a query result
 204                 object, the second may contain an optional array configuration.</p>
 205
 206                 <div class="example">
 207                         $this->load->dbutil();<br />
 208                         <br />
 209                         $query = $this->db->query('SELECT * FROM `some_table`');<br />
 210                         <br />
 211                         $config = array(<br />
 212                         &nbsp;&nbsp;&nbsp;&nbsp;'root' => 'root',<br />
 213                         &nbsp;&nbsp;&nbsp;&nbsp;'element' => 'element',<br />
 214                         &nbsp;&nbsp;&nbsp;&nbsp;'newline' => "\n",<br />
 215                         &nbsp;&nbsp;&nbsp;&nbsp;'tab' => "\t"<br />
 216                         );<br />
 217                         <br />
 218                         echo $this->dbutil->xml_from_result($query);
 219                 </div>
 220
 221                 <p>This method will not create the XML file you for, only the contents of the XML file.</p>
 222         </div>
 223
 224         <div class="content">
 225                 <h1>$this->dbutil->backup()</h1>
 226
 227                 <p>This method allows you to backup your full database or individual tables.  The backup data can be
 228                 compressed in either zip or gzip format.  This method is only available for MySQL and MySQLi databases.</p>
 229
 230                 <p>Due to the limited execution time and memory available to PHP, backing up a very large database may not
 231                 be possible.</p>
 232
 233                 <div class="example">
 234                         $this->load->dbutil();<br />
 235                         <br />
 236                         $backup =&amp; $this->dbutil->backup();<br />
 237                         <br />
 238                         $this->load->utility('filesystem');<br />
 239                         write_file('/path/to/backups/backup.gz', $backup);<br />
 240                 </div>
 241
 242                 <p>Backup preferences are set by submitting an array of values to the first parameter of the backup method.</p>
 243
 244                 <div class="example">
 245                         $pref = array(<br />
 246                         &nbsp;&nbsp;&nbsp;&nbsp;'tables' => array('table1', 'table2'),<br />
 247                         &nbsp;&nbsp;&nbsp;&nbsp;'ignore' => array(),<br />
 248                         &nbsp;&nbsp;&nbsp;&nbsp;'format' => 'txt',<br />
 249                         &nbsp;&nbsp;&nbsp;&nbsp;'filename' => 'backup.sql',<br />
 250                         &nbsp;&nbsp;&nbsp;&nbsp;'add_drop' => true,<br />
 251                         &nbsp;&nbsp;&nbsp;&nbsp;'add_insert' => true,<br />
 252                         &nbsp;&nbsp;&nbsp;&nbsp;'newline' => "\n"<br />
 253                         );<br />
 254                         <br />
 255                         $this->dbutil->backup($pref);
 256                 </div>
 257         </div>
 258
 259         <div class="content">
 260                 <h1>Backup Preferences</h1>
 261
 262                 <ul>
 263                         <li>'tables' - default value empty array() - An array of tables you want backed up.</li>
 264                         <li>'ignore' - default value empty array() - An array of tables you don't want backed up.</li>
 265                         <li>'format' - default value gzip - The file format of the backup txt, gzip, or zip.</li>
 266                         <li>'filename' - default value current date/time - The name of the backup file.</li>
 267                         <li>'add_drop' - default value true - Whether to include the drop table statements in your SQL.</li>
 268                         <li>'add_insert' - default value true - Whether to include INSERT statements in your SQL.</li>
 269                         <li>'newline' - default value "\n" - Type of newline to use in your SQL.</li>
 270                 </ul>
 271         </div>
 272 </body>
 273
 274 </html>