From 8ede1a2ecbb62577afd32996956c5feaf7ddf9b6 Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Wed, 5 Oct 2011 13:34:52 -0500 Subject: replacing the old HTML user guide with a Sphinx-managed user guide --- user_guide_src/source/database/utilities.rst | 189 +++++++++++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 user_guide_src/source/database/utilities.rst (limited to 'user_guide_src/source/database/utilities.rst') diff --git a/user_guide_src/source/database/utilities.rst b/user_guide_src/source/database/utilities.rst new file mode 100644 index 000000000..7dcf1df9c --- /dev/null +++ b/user_guide_src/source/database/utilities.rst @@ -0,0 +1,189 @@ +###################### +Database Utility Class +###################### + +The Database Utility Class contains functions that help you manage your +database. + +.. contents:: Table of Contents + + +****************** +Function Reference +****************** + +Initializing the Utility Class +============================== + +.. important:: In order to initialize the Utility class, your database + driver must already be running, since the utilities class relies on it. + +Load the Utility Class as follows:: + + $this->load->dbutil() + +Once initialized you will access the functions using the $this->dbutil +object:: + + $this->dbutil->some_function() + +$this->dbutil->list_databases() +================================ + +Returns an array of database names:: + + $dbs = $this->dbutil->list_databases(); foreach ($dbs as $db) {     echo $db; } + +$this->dbutil->database_exists(); +================================== + +Sometimes it's helpful to know whether a particular database exists. +Returns a boolean TRUE/FALSE. Usage example:: + + if ($this->dbutil->database_exists('database_name')) {    // some code... } + +Note: Replace *database_name* with the name of the table you are +looking for. This function is case sensitive. + +$this->dbutil->optimize_table('table_name'); +============================================== + +.. note:: This features is only available for MySQL/MySQLi databases. + +Permits you to optimize a table using the table name specified in the +first parameter. Returns TRUE/FALSE based on success or failure:: + + if ($this->dbutil->optimize_table('table_name')) {     echo 'Success!'; } + +.. note:: Not all database platforms support table optimization. + +$this->dbutil->repair_table('table_name'); +============================================ + +.. note:: This features is only available for MySQL/MySQLi databases. + +Permits you to repair a table using the table name specified in the +first parameter. Returns TRUE/FALSE based on success or failure:: + + if ($this->dbutil->repair_table('table_name')) {     echo 'Success!'; } + +.. note:: Not all database platforms support table repairs. + +$this->dbutil->optimize_database(); +==================================== + +.. note:: This features is only available for MySQL/MySQLi databases. + +Permits you to optimize the database your DB class is currently +connected to. Returns an array containing the DB status messages or +FALSE on failure. + +:: + + $result = $this->dbutil->optimize_database(); if ($result !== FALSE) {     print_r($result); } + +.. note:: Not all database platforms support table optimization. + +$this->dbutil->csv_from_result($db_result) +============================================= + +Permits you to generate a CSV file from a query result. The first +parameter of the function must contain the result object from your +query. Example:: + + $this->load->dbutil(); $query = $this->db->query("SELECT * FROM mytable"); echo $this->dbutil->csv_from_result($query); + +The second, third, and fourth parameters allow you to set the delimiter +newline, and enclosure characters respectively. By default tabs are +used as the delimiter, "\n" is used as a new line, and a double-quote +is used as the enclosure. Example:: + + $delimiter = ","; + $newline = "\r\n"; + $enclosure = '"'; + + echo $this->dbutil->csv_from_result($query, $delimiter, $newline, $enclosure); + +.. important:: This function will NOT write the CSV file for you. It + simply creates the CSV layout. If you need to write the file + use the :doc:`File Helper <../helpers/file_helper>`. + +$this->dbutil->xml_from_result($db_result) +============================================= + +Permits you to generate an XML file from a query result. The first +parameter expects a query result object, the second may contain an +optional array of config parameters. Example:: + + $this->load->dbutil(); $query = $this->db->query("SELECT * FROM mytable"); $config = array (                   'root'    => 'root',                   'element' => 'element',                   'newline' => "\n",                   'tab'    => "\t"                 ); echo $this->dbutil->xml_from_result($query, $config); + +.. important:: This function will NOT write the XML file for you. It + simply creates the XML layout. If you need to write the file + use the :doc:`File Helper <../helpers/file_helper>`. + +$this->dbutil->backup() +======================= + +Permits you to backup your full database or individual tables. The +backup data can be compressed in either Zip or Gzip format. + +.. note:: This features is only available for MySQL databases. + +.. note:: Due to the limited execution time and memory available to PHP, + backing up very large databases may not be possible. If your database is + very large you might need to backup directly from your SQL server via + the command line, or have your server admin do it for you if you do not + have root privileges. + +Usage Example +------------- + +:: + + // Load the DB utility class $this->load->dbutil(); // Backup your entire database and assign it to a variable $backup =& $this->dbutil->backup(); // Load the file helper and write the file to your server $this->load->helper('file'); write_file('/path/to/mybackup.gz', $backup); // Load the download helper and send the file to your desktop $this->load->helper('download'); force_download('mybackup.gz', $backup); + +Setting Backup Preferences +-------------------------- + +Backup preferences are set by submitting an array of values to the first +parameter of the backup function. Example:: + + $prefs = array(                 'tables'      => array('table1', 'table2'),  // Array of tables to backup.                 'ignore'      => array(),           // List of tables to omit from the backup                 'format'      => 'txt',             // gzip, zip, txt                 'filename'    => 'mybackup.sql',    // File name - NEEDED ONLY WITH ZIP FILES                 'add_drop'    => TRUE,              // Whether to add DROP TABLE statements to backup file                 'add_insert'  => TRUE,              // Whether to add INSERT data to backup file                 'newline'     => "\n"               // Newline character used in backup file               ); $this->dbutil->backup($prefs); + +Description of Backup Preferences +--------------------------------- + +Preference +Default Value +Options +Description +**tables** +empty array +None +An array of tables you want backed up. If left blank all tables will be +exported. +**ignore** +empty array +None +An array of tables you want the backup routine to ignore. +**format** +gzip +gzip, zip, txt +The file format of the export file. +**filename** +the current date/time +None +The name of the backed-up file. The name is needed only if you are using +zip compression. +**add_drop** +TRUE +TRUE/FALSE +Whether to include DROP TABLE statements in your SQL export file. +**add_insert** +TRUE +TRUE/FALSE +Whether to include INSERT statements in your SQL export file. +**newline** +"\\n" +"\\n", "\\r", "\\r\\n" +Type of newline to use in your SQL export file. -- cgit v1.2.3-24-g4f1b From 5b3ea1ac070882c09eb6cb93f2ca6628ec42d64d Mon Sep 17 00:00:00 2001 From: Joseph Wensley Date: Thu, 6 Oct 2011 20:54:32 -0400 Subject: change hardcoded page docs to use generated ones escape "http://" that was getting linked formatting some tables --- user_guide_src/source/database/utilities.rst | 47 ++++++++-------------------- 1 file changed, 13 insertions(+), 34 deletions(-) (limited to 'user_guide_src/source/database/utilities.rst') diff --git a/user_guide_src/source/database/utilities.rst b/user_guide_src/source/database/utilities.rst index 7dcf1df9c..ab7d6a149 100644 --- a/user_guide_src/source/database/utilities.rst +++ b/user_guide_src/source/database/utilities.rst @@ -153,37 +153,16 @@ parameter of the backup function. Example:: Description of Backup Preferences --------------------------------- -Preference -Default Value -Options -Description -**tables** -empty array -None -An array of tables you want backed up. If left blank all tables will be -exported. -**ignore** -empty array -None -An array of tables you want the backup routine to ignore. -**format** -gzip -gzip, zip, txt -The file format of the export file. -**filename** -the current date/time -None -The name of the backed-up file. The name is needed only if you are using -zip compression. -**add_drop** -TRUE -TRUE/FALSE -Whether to include DROP TABLE statements in your SQL export file. -**add_insert** -TRUE -TRUE/FALSE -Whether to include INSERT statements in your SQL export file. -**newline** -"\\n" -"\\n", "\\r", "\\r\\n" -Type of newline to use in your SQL export file. +=============== ======================= ======================= ======================================================================== +Preference Default Value Options Description +=============== ======================= ======================= ======================================================================== +**tables** empty array None An array of tables you want backed up. If left blank all tables will be + exported. +**ignore** empty array None An array of tables you want the backup routine to ignore. +**format** gzip gzip, zip, txt The file format of the export file. +**filename** the current date/time None The name of the backed-up file. The name is needed only if you are using + zip compression. +**add_drop** TRUE TRUE/FALSE Whether to include DROP TABLE statements in your SQL export file. +**add_insert** TRUE TRUE/FALSE Whether to include INSERT statements in your SQL export file. +**newline** "\\n" "\\n", "\\r", "\\r\\n" Type of newline to use in your SQL export file. +=============== ======================= ======================= ======================================================================== \ No newline at end of file -- cgit v1.2.3-24-g4f1b From f24f404a34081241c1398f568b506e2c9d9bec5b Mon Sep 17 00:00:00 2001 From: Joseph Wensley Date: Thu, 6 Oct 2011 22:53:29 -0400 Subject: cleaning up and formatting database pages --- user_guide_src/source/database/utilities.rst | 74 ++++++++++++++++++++++++---- 1 file changed, 65 insertions(+), 9 deletions(-) (limited to 'user_guide_src/source/database/utilities.rst') diff --git a/user_guide_src/source/database/utilities.rst b/user_guide_src/source/database/utilities.rst index ab7d6a149..b0920109f 100644 --- a/user_guide_src/source/database/utilities.rst +++ b/user_guide_src/source/database/utilities.rst @@ -32,7 +32,12 @@ $this->dbutil->list_databases() Returns an array of database names:: - $dbs = $this->dbutil->list_databases(); foreach ($dbs as $db) {     echo $db; } + $dbs = $this->dbutil->list_databases(); + + foreach ($dbs as $db) + { + echo $db; + } $this->dbutil->database_exists(); ================================== @@ -40,7 +45,10 @@ $this->dbutil->database_exists(); Sometimes it's helpful to know whether a particular database exists. Returns a boolean TRUE/FALSE. Usage example:: - if ($this->dbutil->database_exists('database_name')) {    // some code... } + if ($this->dbutil->database_exists('database_name')) + { + // some code... + } Note: Replace *database_name* with the name of the table you are looking for. This function is case sensitive. @@ -53,7 +61,10 @@ $this->dbutil->optimize_table('table_name'); Permits you to optimize a table using the table name specified in the first parameter. Returns TRUE/FALSE based on success or failure:: - if ($this->dbutil->optimize_table('table_name')) {     echo 'Success!'; } + if ($this->dbutil->optimize_table('table_name')) + { + echo 'Success!'; + } .. note:: Not all database platforms support table optimization. @@ -65,7 +76,10 @@ $this->dbutil->repair_table('table_name'); Permits you to repair a table using the table name specified in the first parameter. Returns TRUE/FALSE based on success or failure:: - if ($this->dbutil->repair_table('table_name')) {     echo 'Success!'; } + if ($this->dbutil->repair_table('table_name')) + { + echo 'Success!'; + } .. note:: Not all database platforms support table repairs. @@ -80,7 +94,12 @@ FALSE on failure. :: - $result = $this->dbutil->optimize_database(); if ($result !== FALSE) {     print_r($result); } + $result = $this->dbutil->optimize_database(); + + if ($result !== FALSE) + { + print_r($result); + } .. note:: Not all database platforms support table optimization. @@ -91,7 +110,11 @@ Permits you to generate a CSV file from a query result. The first parameter of the function must contain the result object from your query. Example:: - $this->load->dbutil(); $query = $this->db->query("SELECT * FROM mytable"); echo $this->dbutil->csv_from_result($query); + $this->load->dbutil(); + + $query = $this->db->query("SELECT * FROM mytable"); + + echo $this->dbutil->csv_from_result($query); The second, third, and fourth parameters allow you to set the delimiter newline, and enclosure characters respectively. By default tabs are @@ -115,7 +138,18 @@ Permits you to generate an XML file from a query result. The first parameter expects a query result object, the second may contain an optional array of config parameters. Example:: - $this->load->dbutil(); $query = $this->db->query("SELECT * FROM mytable"); $config = array (                   'root'    => 'root',                   'element' => 'element',                   'newline' => "\n",                   'tab'    => "\t"                 ); echo $this->dbutil->xml_from_result($query, $config); + $this->load->dbutil(); + + $query = $this->db->query("SELECT * FROM mytable"); + + $config = array ( + 'root' => 'root', + 'element' => 'element', + 'newline' => "\n", + 'tab' => "\t" + ); + + echo $this->dbutil->xml_from_result($query, $config); .. important:: This function will NOT write the XML file for you. It simply creates the XML layout. If you need to write the file @@ -140,7 +174,19 @@ Usage Example :: - // Load the DB utility class $this->load->dbutil(); // Backup your entire database and assign it to a variable $backup =& $this->dbutil->backup(); // Load the file helper and write the file to your server $this->load->helper('file'); write_file('/path/to/mybackup.gz', $backup); // Load the download helper and send the file to your desktop $this->load->helper('download'); force_download('mybackup.gz', $backup); + // Load the DB utility class + $this->load->dbutil(); + + // Backup your entire database and assign it to a variable + $backup =& $this->dbutil->backup(); + + // Load the file helper and write the file to your server + $this->load->helper('file'); + write_file('/path/to/mybackup.gz', $backup); + + // Load the download helper and send the file to your desktop + $this->load->helper('download'); + force_download('mybackup.gz', $backup); Setting Backup Preferences -------------------------- @@ -148,7 +194,17 @@ Setting Backup Preferences Backup preferences are set by submitting an array of values to the first parameter of the backup function. Example:: - $prefs = array(                 'tables'      => array('table1', 'table2'),  // Array of tables to backup.                 'ignore'      => array(),           // List of tables to omit from the backup                 'format'      => 'txt',             // gzip, zip, txt                 'filename'    => 'mybackup.sql',    // File name - NEEDED ONLY WITH ZIP FILES                 'add_drop'    => TRUE,              // Whether to add DROP TABLE statements to backup file                 'add_insert'  => TRUE,              // Whether to add INSERT data to backup file                 'newline'     => "\n"               // Newline character used in backup file               ); $this->dbutil->backup($prefs); + $prefs = array( + 'tables' => array('table1', 'table2'), // Array of tables to backup. + 'ignore' => array(), // List of tables to omit from the backup + 'format' => 'txt', // gzip, zip, txt + 'filename' => 'mybackup.sql', // File name - NEEDED ONLY WITH ZIP FILES + 'add_drop' => TRUE, // Whether to add DROP TABLE statements to backup file + 'add_insert' => TRUE, // Whether to add INSERT data to backup file + 'newline' => "\n" // Newline character used in backup file + ); + + $this->dbutil->backup($prefs); Description of Backup Preferences --------------------------------- -- cgit v1.2.3-24-g4f1b From ab189e162f20f1a7daae8bfd2b921e694c3f9df3 Mon Sep 17 00:00:00 2001 From: Timothy Warren Date: Wed, 22 Feb 2012 10:34:23 -0500 Subject: Close services after using them, added dbutil->backup() method --- user_guide_src/source/database/utilities.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'user_guide_src/source/database/utilities.rst') diff --git a/user_guide_src/source/database/utilities.rst b/user_guide_src/source/database/utilities.rst index b0920109f..3805ffb87 100644 --- a/user_guide_src/source/database/utilities.rst +++ b/user_guide_src/source/database/utilities.rst @@ -161,7 +161,11 @@ $this->dbutil->backup() Permits you to backup your full database or individual tables. The backup data can be compressed in either Zip or Gzip format. -.. note:: This features is only available for MySQL databases. +.. note:: This features is only available for MySQL and Interbase/Firebird databases. + +.. note:: For Interbase/Firebird databases, the backup file name is the only parameter. + + Eg. $this->dbutil->backup('db_backup_filename'); .. note:: Due to the limited execution time and memory available to PHP, backing up very large databases may not be possible. If your database is -- cgit v1.2.3-24-g4f1b From 7310e85e92e38459b50addd9ce749c115c86da11 Mon Sep 17 00:00:00 2001 From: mrw Date: Mon, 26 Mar 2012 11:25:26 -0300 Subject: Commas, not tabs, are the default delimiter in dbutil->csv_from_result. --- user_guide_src/source/database/utilities.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'user_guide_src/source/database/utilities.rst') diff --git a/user_guide_src/source/database/utilities.rst b/user_guide_src/source/database/utilities.rst index 3805ffb87..4e83929b2 100644 --- a/user_guide_src/source/database/utilities.rst +++ b/user_guide_src/source/database/utilities.rst @@ -117,7 +117,7 @@ query. Example:: echo $this->dbutil->csv_from_result($query); The second, third, and fourth parameters allow you to set the delimiter -newline, and enclosure characters respectively. By default tabs are +newline, and enclosure characters respectively. By default commas are used as the delimiter, "\n" is used as a new line, and a double-quote is used as the enclosure. Example:: -- cgit v1.2.3-24-g4f1b