diff options
Diffstat (limited to 'user_guide_src/source/database')
| -rw-r--r-- | user_guide_src/source/database/configuration.rst | 2 | ||||
| -rw-r--r-- | user_guide_src/source/database/db_driver_reference.rst | 41 | ||||
| -rw-r--r-- | user_guide_src/source/database/examples.rst | 17 | ||||
| -rw-r--r-- | user_guide_src/source/database/forge.rst | 10 | ||||
| -rw-r--r-- | user_guide_src/source/database/queries.rst | 10 | ||||
| -rw-r--r-- | user_guide_src/source/database/query_builder.rst | 20 | ||||
| -rw-r--r-- | user_guide_src/source/database/transactions.rst | 14 |
7 files changed, 63 insertions, 51 deletions
diff --git a/user_guide_src/source/database/configuration.rst b/user_guide_src/source/database/configuration.rst index 8026be63a..e231a7d6a 100644 --- a/user_guide_src/source/database/configuration.rst +++ b/user_guide_src/source/database/configuration.rst @@ -7,7 +7,7 @@ connection values (username, password, database name, etc.). The config file is located at application/config/database.php. You can also set database connection values for specific :doc:`environments <../libraries/config>` by placing **database.php** -it the respective environment config folder. +in the respective environment config folder. The config settings are stored in a multi-dimensional array with this prototype:: diff --git a/user_guide_src/source/database/db_driver_reference.rst b/user_guide_src/source/database/db_driver_reference.rst index 005e6b3dc..6f2fa5fb1 100644 --- a/user_guide_src/source/database/db_driver_reference.rst +++ b/user_guide_src/source/database/db_driver_reference.rst @@ -17,8 +17,8 @@ This article is intended to be a reference for them. .. php:method:: initialize() - :returns: TRUE on success, FALSE on failure - :rtype: bool + :rtype: void + :throws: RuntimeException In case of failure Initialize database settings, establish a connection to the database. @@ -61,14 +61,6 @@ This article is intended to be a reference for them. Select / switch the current database. - .. php:method:: db_set_charset($charset) - - :param string $charset: Character set name - :returns: TRUE on success, FALSE on failure - :rtype: bool - - Set client character set. - .. php:method:: platform() :returns: Platform name @@ -83,7 +75,7 @@ This article is intended to be a reference for them. Database version number. - .. php:method:: query($sql[, $binds = FALSE[, $return_object = NULL]]]) + .. php:method:: query($sql[, $binds = FALSE[, $return_object = NULL]]) :param string $sql: The SQL statement to execute :param array $binds: An array of binding data @@ -116,6 +108,16 @@ This article is intended to be a reference for them. for use when you don't need to get a result object or to just send a query to the database and not care for the result. + .. php:method:: affected_rows() + + :returns: Number of rows affected + :rtype: int + + Returns the number of rows *changed* by the last executed query. + + Useful for checking how much rows were created, updated or deleted + during the last executed query. + .. php:method:: trans_strict([$mode = TRUE]) :param bool $mode: Strict mode flag @@ -124,8 +126,8 @@ This article is intended to be a reference for them. Enable/disable transaction "strict" mode. When strict mode is enabled, if you are running multiple - groups of transactions and one group fails, all groups - will be rolled back. + groups of transactions and one group fails, all subsequent + groups will be rolled back. If strict mode is disabled, each group is treated autonomously, meaning a failure of one group will not @@ -140,13 +142,15 @@ This article is intended to be a reference for them. .. php:method:: trans_start([$test_mode = FALSE]) :param bool $test_mode: Test mode flag - :rtype: void + :returns: TRUE on success, FALSE on failure + :rtype: bool Start a transaction. .. php:method:: trans_complete() - :rtype: void + :returns: TRUE on success, FALSE on failure + :rtype: bool Complete Transaction. @@ -232,6 +236,13 @@ This article is intended to be a reference for them. and ``_`` wildcard characters, so that they don't cause false-positives in LIKE conditions. + .. important:: The ``escape_like_str()`` method uses '!' (exclamation mark) + to escape special characters for *LIKE* conditions. Because this + method escapes partial strings that you would wrap in quotes + yourself, it cannot automatically add the ``ESCAPE '!'`` + condition for you, and so you'll have to manually do that. + + .. php:method:: primary($table) :param string $table: Table name diff --git a/user_guide_src/source/database/examples.rst b/user_guide_src/source/database/examples.rst index 8b3cc4701..5fd7fccfa 100644 --- a/user_guide_src/source/database/examples.rst +++ b/user_guide_src/source/database/examples.rst @@ -55,23 +55,6 @@ Standard Query With Multiple Results (Array Version) The above result_array() function returns an array of standard array indexes. Example: $row['title'] -Testing for Results -=================== - -If you run queries that might **not** produce a result, you are -encouraged to test for a result first using the num_rows() function:: - - $query = $this->db->query("YOUR QUERY"); - if ($query->num_rows() > 0) - { - foreach ($query->result() as $row) - { - echo $row->title; - echo $row->name; - echo $row->body; - } - } - Standard Query With Single Result ================================= diff --git a/user_guide_src/source/database/forge.rst b/user_guide_src/source/database/forge.rst index 646e3a56e..5af4f2248 100644 --- a/user_guide_src/source/database/forge.rst +++ b/user_guide_src/source/database/forge.rst @@ -97,6 +97,7 @@ Additionally, the following key/values can be used: - 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. +- unique/true : to generate a unique key for the field definition. :: @@ -110,6 +111,7 @@ Additionally, the following key/values can be used: 'blog_title' => array( 'type' => 'VARCHAR', 'constraint' => '100', + 'unique' => TRUE, ), 'blog_author' => array( 'type' =>'VARCHAR', @@ -175,14 +177,14 @@ below is for MySQL. $this->dbforge->add_key('blog_id', TRUE); // gives PRIMARY KEY `blog_id` (`blog_id`) - + $this->dbforge->add_key('blog_id', TRUE); $this->dbforge->add_key('site_id', TRUE); // gives PRIMARY KEY `blog_id_site_id` (`blog_id`, `site_id`) - + $this->dbforge->add_key('blog_name'); // gives KEY `blog_name` (`blog_name`) - + $this->dbforge->add_key(array('blog_name', 'blog_label')); // gives KEY `blog_name_blog_label` (`blog_name`, `blog_label`) @@ -261,7 +263,7 @@ number of additional fields. $fields = array( 'preferences' => array('type' => 'TEXT') ); - $this->dbforge->add_column('table_name', $fields); + $this->dbforge->add_column('table_name', $fields); // Executes: ALTER TABLE table_name ADD preferences TEXT If you are using MySQL or CUBIRD, then you can take advantage of their diff --git a/user_guide_src/source/database/queries.rst b/user_guide_src/source/database/queries.rst index 43a0a30bf..f626f1e83 100644 --- a/user_guide_src/source/database/queries.rst +++ b/user_guide_src/source/database/queries.rst @@ -123,7 +123,13 @@ this: $search = '20% raise'; $sql = "SELECT id FROM table WHERE column LIKE '%" . - $this->db->escape_like_str($search)."%'"; + $this->db->escape_like_str($search)."%' ESCAPE '!'"; + +.. important:: The ``escape_like_str()`` method uses '!' (exclamation mark) + to escape special characters for *LIKE* conditions. Because this + method escapes partial strings that you would wrap in quotes + yourself, it cannot automatically add the ``ESCAPE '!'`` + condition for you, and so you'll have to manually do that. ************** @@ -159,7 +165,7 @@ Handling Errors **$this->db->error();** -If you need to get the last error that has occured, the error() method +If you need to get the last error that has occurred, the error() method will return an array containing its code and message. Here's a quick example:: diff --git a/user_guide_src/source/database/query_builder.rst b/user_guide_src/source/database/query_builder.rst index 9c3ff306f..3135f76da 100644 --- a/user_guide_src/source/database/query_builder.rst +++ b/user_guide_src/source/database/query_builder.rst @@ -1018,7 +1018,7 @@ Here's a usage example:: .. note:: The following statements can be cached: select, from, join, - where, like, group_by, having, order_by, set + where, like, group_by, having, order_by *********************** @@ -1433,15 +1433,20 @@ Class Reference Compiles and executes an INSERT statement. - .. php:method:: insert_batch([$table = ''[, $set = NULL[, $escape = NULL]]]) + .. php:method:: insert_batch($table[, $set = NULL[, $escape = NULL[, $batch_size = 100]]]) :param string $table: Table name :param array $set: Data to insert :param bool $escape: Whether to escape values and identifiers + :param int $batch_size: Count of rows to insert at once :returns: Number of rows inserted or FALSE on failure :rtype: mixed - Compiles and executes batch INSERT statements. + Compiles and executes batch ``INSERT`` statements. + + .. note:: When more than ``$batch_size`` rows are provided, multiple + ``INSERT`` queries will be executed, each trying to insert + up to ``$batch_size`` rows. .. php:method:: set_insert_batch($key[, $value = ''[, $escape = NULL]]) @@ -1464,15 +1469,20 @@ Class Reference Compiles and executes an UPDATE statement. - .. php:method:: update_batch([$table = ''[, $set = NULL[, $value = NULL]]]) + .. php:method:: update_batch($table[, $set = NULL[, $value = NULL[, $batch_size = 100]]]) :param string $table: Table name :param array $set: Field name, or an associative array of field/value pairs :param string $value: Field value, if $set is a single field + :param int $batch_size: Count of conditions to group in a single query :returns: Number of rows updated or FALSE on failure :rtype: mixed - Compiles and executes batch UPDATE statements. + Compiles and executes batch ``UPDATE`` statements. + + .. note:: When more than ``$batch_size`` field/value pairs are provided, + multiple queries will be executed, each handling up to + ``$batch_size`` field/value pairs. .. php:method:: set_update_batch($key[, $value = ''[, $escape = NULL]]) diff --git a/user_guide_src/source/database/transactions.rst b/user_guide_src/source/database/transactions.rst index 2e6d4b477..cfd6a566d 100644 --- a/user_guide_src/source/database/transactions.rst +++ b/user_guide_src/source/database/transactions.rst @@ -75,12 +75,11 @@ debugging is turned off, you can manage your own errors like this:: // generate an error... or use the log_message() function to log your error } -Enabling Transactions -===================== +Disabling Transactions +====================== -Transactions are enabled automatically the moment you use -$this->db->trans_start(). If you would like to disable transactions you -can do so using $this->db->trans_off():: +If you would like to disable transactions you can do so using +``$this->db->trans_off()``:: $this->db->trans_off(); @@ -88,8 +87,9 @@ can do so using $this->db->trans_off():: $this->db->query('AN SQL QUERY...'); $this->db->trans_complete(); -When transactions are disabled, your queries will be auto-commited, just -as they are when running queries without transactions. +When transactions are disabled, your queries will be auto-committed, just as +they are when running queries without transactions, practically ignoring +any calls to ``trans_start()``, ``trans_complete()``, etc. Test Mode ========= |