From b906149a2e6b4d607294b12d4a690ed3af84eed0 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Thu, 4 Dec 2014 16:33:24 +0200 Subject: DB forge/utilities polishing (docs) following #3375, #3378 --- user_guide_src/source/database/forge.rst | 111 ++++++++++++--------------- user_guide_src/source/database/utilities.rst | 75 +++++++++--------- 2 files changed, 88 insertions(+), 98 deletions(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/forge.rst b/user_guide_src/source/database/forge.rst index 371397d26..59a6591b7 100644 --- a/user_guide_src/source/database/forge.rst +++ b/user_guide_src/source/database/forge.rst @@ -185,7 +185,6 @@ below is for MySQL. // gives KEY `blog_name_blog_label` (`blog_name`, `blog_label`) - Creating a table ================ @@ -242,7 +241,6 @@ Executes a TABLE rename // gives ALTER TABLE old_table_name RENAME TO new_table_name - **************** Modifying Tables **************** @@ -318,104 +316,93 @@ change the name you can add a "name" key into the field defining array. Class Reference *************** -.. class:: DB_forge - - .. method:: __construct(&$db) - - :param object $db: Database object - :returns: DB_forge object for the specified database - :rtype: DB_forge - - Initializes a database forge. +.. class:: CI_DB_forge - .. method:: add_column($table = '', $field = array(), $_after = NULL) + .. method:: add_column($table[, $field = array()[, $_after = NULL]]) - :param string $table: Table name - :param array $field: Column definitions + :param string $table: Table name to add the column to + :param array $field: Column definition(s) :param string $_after: Column for AFTER clause (deprecated) - :returns: TRUE on success, FALSE on failure - :rtype: boolean + :returns: TRUE on success, FALSE on failure + :rtype: bool - Add a column to a table. Usage: See `Adding a Column to a Table`_. + Adds a column to a table. Usage: See `Adding a Column to a Table`_. - .. method:: add_field($field = '') + .. method:: add_field($field) - :param array $field: Field to add - :returns: DB_forge instance - :rtype: object + :param array $field: Field definition to add + :returns: CI_DB_forge instance (method chaining) + :rtype: CI_DB_forge - Add a field to the set that will be used to create a table. Usage: See `Adding fields`_. + Adds a field to the set that will be used to create a table. Usage: See `Adding fields`_. - .. method:: add_key($key = '', $primary = FALSE) + .. method:: add_key($key[, $primary = FALSE]) :param array $key: Name of a key field - :param boolean $primary: TRUE if this key is to be a primary key - :returns: DB_forge instance - :rtype: object + :param bool $primary: Set to TRUE if it should be a primary key or a regular one + :returns: CI_DB_forge instance (method chaining) + :rtype: CI_DB_forge - Specify a key field to be used to create a table. Usage: See `Adding Keys`_. + Adds a key to the set that will be used to create a table. Usage: See `Adding Keys`_. .. method:: create_database($db_name) :param string $db_name: Name of the database to create - :returns: TRUE on success, FALSE on failure - :rtype: boolean + :returns: TRUE on success, FALSE on failure + :rtype: bool - Create a new database. Usage: See `Creating and Dropping Databases`_. + Creates a new database. Usage: See `Creating and Dropping Databases`_. - .. method:: create_table($table = '', $if_not_exists = FALSE, array $attributes = array()) + .. method:: create_table($table[, $if_not_exists = FALSE[, array $attributes = array()]]) :param string $table: Name of the table to create - :param string $if_not_exists: TRUE to add an 'IF NOT EXISTS' clause - :param string $attributes: Associative array of table attributes - :returns: DB_driver on success, FALSE on failure - :rtype: mixed + :param string $if_not_exists: Set to TRUE to add an 'IF NOT EXISTS' clause + :param string $attributes: An associative array of table attributes + :returns: TRUE on success, FALSE on failure + :rtype: bool - Create a new table. Usage: See `Creating a table`_. + Creates a new table. Usage: See `Creating a table`_. - .. method:: drop_column($table = '', $column_name = '') + .. method:: drop_column($table, $column_name) :param string $table: Table name - :param array $column_name: Column to drop - :returns: DB_driver on success, FALSE on failure - :rtype: mixed + :param array $column_name: The column name to drop + :returns: TRUE on success, FALSE on failure + :rtype: bool - Drop a column from a table. Usage: See `Dropping a Column From a Table`_. + Drops a column from a table. Usage: See `Dropping a Column From a Table`_. .. method:: drop_database($db_name) :param string $db_name: Name of the database to drop - :returns: TRUE on success, FALSE on failure - :rtype: boolean + :returns: TRUE on success, FALSE on failure + :rtype: bool - Drop a database. Usage: See `Creating and Dropping Databases`_. + Drops a database. Usage: See `Creating and Dropping Databases`_. - .. method:: drop_table($table_name, $if_exists = FALSE) + .. method:: drop_table($table_name[, $if_exists = FALSE]) - :param string $table: Name of the table to create - :param string $if_exists: TRUE to add an 'IF EXISTS' clause - :returns: DB_driver on success, FALSE on failure - :rtype: mixed + :param string $table: Name of the table to drop + :param string $if_exists: Set to TRUE to add an 'IF EXISTS' clause + :returns: TRUE on success, FALSE on failure + :rtype: bool - Drop a table. Usage: See `Dropping a table`_. + Drops a table. Usage: See `Dropping a table`_. - .. method:: modify_column($table = '', $field = array()) + .. method:: modify_column($table, $field) :param string $table: Table name - :param array $field: Column definitions - :returns: TRUE on success, FALSE on failure - :rtype: boolean + :param array $field: Column definition(s) + :returns: TRUE on success, FALSE on failure + :rtype: bool - Modify a column in a table. Usage: See `Modifying a Column in a Table`_. + Modifies a table column. Usage: See `Modifying a Column in a Table`_. .. method:: rename_table($table_name, $new_table_name) - :param string $table: Name of the table + :param string $table: Current of the table :param string $new_table_name: New name of the table - :returns: DB_driver on success, FALSE on failure - :rtype: mixed - - Rename a table. Usage: See `Renaming a table`_. - - + :returns: TRUE on success, FALSE on failure + :rtype: bool + Renames a table. Usage: See `Renaming a table`_. \ No newline at end of file diff --git a/user_guide_src/source/database/utilities.rst b/user_guide_src/source/database/utilities.rst index d15cef06d..0d8137dd7 100644 --- a/user_guide_src/source/database/utilities.rst +++ b/user_guide_src/source/database/utilities.rst @@ -9,7 +9,6 @@ database. :local: :depth: 2 - ****************************** Initializing the Utility Class ****************************** @@ -248,66 +247,70 @@ Preference Default Value Options Descript Class Reference *************** -.. class:: DB_utility +.. class:: CI_DB_utility - .. method:: backup($params) + .. method:: backup([$params = array()]) - :param array $params: associative array of backup preferences + :param array $params: An associative array of options :returns: void - :rtype: void - - Perform a database backup, per user preferences + :rtype: void - .. method:: csv_from_results($query, $delim = ',', $newline = "\n", $enclosure = '"') - - :param object $query: DB_result with data to backup - :param string $delim: Delimniter character for the CSV file, default is ',' - :param string $newline: Character to use for newlines, default is "\n" - :param string $enclosure: Delimiter used for enclosure, default is '"' - :returns: The generated CSV file as a string - :rtype: string + Perform a database backup, per user preferences. .. method:: database_exists($database_name) - :param string $database_name: name of the database to check for + :param string $database_name: Database name :returns: TRUE if the database exists, FALSE otherwise - :rtype: boolean + :rtype: bool - Check for the existence of a database + Check for the existence of a database. .. method:: list_databases() :returns: Array of database names found - :rtype: array + :rtype: array - Retrieve all the database names + Retrieve a list of all the database names. .. method:: optimize_database() - :returns: Array of optimization messages, FALSE on failure - :rtype: array + :returns: Array of optimization messages or FALSE on failure + :rtype: array - Optimizes a database + Optimizes the database. .. method:: optimize_table($table_name) - :param string $table_name: Name of the table to optimize - :returns: Array of optimization messages, FALSE on failure - :rtype: array + :param string $table_name: Name of the table to optimize + :returns: Array of optimization messages or FALSE on failure + :rtype: array - Optimizes a database table + Optimizes a database table. .. method:: repair_table($table_name) - :param string $table_name: Name of the table to repair - :returns: Array of repair messages, FALSE on failure - :rtype: array + :param string $table_name: Name of the table to repair + :returns: Array of repair messages or FALSE on failure + :rtype: array + + Repairs a database table. + + .. method:: csv_from_results($query[, $delim = ','[, $newline = "\n"[, $enclosure = '"']]]) + + :param object $query: A database result object + :param string $delim: The CSV field delimiter to use + :param string $newline: The newline character to use + :param string $enclosure: The enclosure delimiter to use + :returns: The generated CSV file as a string + :rtype: string + + Translates a database result object into a CSV document. - Repairs a database table + .. method:: xml_from_results($query[, $params = array()]) - .. method:: xml_from_results($query, $params) + :param object $query: A database result object + :param array $params: An associative array of preferences + :returns: The generated XML document as a string + :rtype: string - :param object $query: DB_result with data to backup - :param array $params: Associative array of preferences - :returns: The generated XML document as a string - :rtype: string + Translates a database result object into an XML document. \ No newline at end of file -- cgit v1.2.3-24-g4f1b