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/active_record.rst | 856 +++++++++++++++++++++++ user_guide_src/source/database/caching.rst | 152 ++++ user_guide_src/source/database/call_function.rst | 38 + user_guide_src/source/database/configuration.rst | 107 +++ user_guide_src/source/database/connecting.rst | 131 ++++ user_guide_src/source/database/examples.rst | 94 +++ user_guide_src/source/database/fields.rst | 59 ++ user_guide_src/source/database/forge.rst | 212 ++++++ user_guide_src/source/database/helpers.rst | 88 +++ user_guide_src/source/database/index.rst | 29 + user_guide_src/source/database/queries.rst | 112 +++ user_guide_src/source/database/results.rst | 124 ++++ user_guide_src/source/database/table_data.rst | 24 + user_guide_src/source/database/transactions.rst | 96 +++ user_guide_src/source/database/utilities.rst | 189 +++++ 15 files changed, 2311 insertions(+) create mode 100644 user_guide_src/source/database/active_record.rst create mode 100644 user_guide_src/source/database/caching.rst create mode 100644 user_guide_src/source/database/call_function.rst create mode 100644 user_guide_src/source/database/configuration.rst create mode 100644 user_guide_src/source/database/connecting.rst create mode 100644 user_guide_src/source/database/examples.rst create mode 100644 user_guide_src/source/database/fields.rst create mode 100644 user_guide_src/source/database/forge.rst create mode 100644 user_guide_src/source/database/helpers.rst create mode 100644 user_guide_src/source/database/index.rst create mode 100644 user_guide_src/source/database/queries.rst create mode 100644 user_guide_src/source/database/results.rst create mode 100644 user_guide_src/source/database/table_data.rst create mode 100644 user_guide_src/source/database/transactions.rst create mode 100644 user_guide_src/source/database/utilities.rst (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/active_record.rst b/user_guide_src/source/database/active_record.rst new file mode 100644 index 000000000..e1fc00bc5 --- /dev/null +++ b/user_guide_src/source/database/active_record.rst @@ -0,0 +1,856 @@ +################### +Active Record Class +################### + +CodeIgniter uses a modified version of the Active Record Database +Pattern. This pattern allows information to be retrieved, inserted, and +updated in your database with minimal scripting. In some cases only one +or two lines of code are necessary to perform a database action. +CodeIgniter does not require that each database table be its own class +file. It instead provides a more simplified interface. + +Beyond simplicity, a major benefit to using the Active Record features +is that it allows you to create database independent applications, since +the query syntax is generated by each database adapter. It also allows +for safer queries, since the values are escaped automatically by the +system. + +.. note:: If you intend to write your own queries you can disable this + class in your database config file, allowing the core database library + and adapter to utilize fewer resources. + +.. contents:: Page Contents + +************** +Selecting Data +************** + +The following functions allow you to build SQL **SELECT** statements. + +$this->db->get() +================ + +Runs the selection query and returns the result. Can be used by itself +to retrieve all records from a table:: + + $query = $this->db->get('mytable'); // Produces: SELECT * FROM mytable + +The second and third parameters enable you to set a limit and offset +clause:: + + $query = $this->db->get('mytable', 10, 20); + // Produces: SELECT * FROM mytable LIMIT 20, 10 (in MySQL. Other databases have slightly different syntax) + +You'll notice that the above function is assigned to a variable named +$query, which can be used to show the results:: + + $query = $this->db->get('mytable'); + + foreach ($query->result() as $row) + { + echo $row->title; + } + +Please visit the :doc:`result functions ` page for a full +discussion regarding result generation. + +$this->db->get_where() +====================== + +Identical to the above function except that it permits you to add a +"where" clause in the second parameter, instead of using the db->where() +function:: + + $query = $this->db->get_where('mytable', array('id' => $id), $limit, $offset); + +Please read the about the where function below for more information. + +Note: get_where() was formerly known as getwhere(), which has been +removed + +$this->db->select() +=================== + +Permits you to write the SELECT portion of your query:: + + $this->db->select('title, content, date'); + $query = $this->db->get('mytable'); // Produces: SELECT title, content, date FROM mytable + + +.. note:: If you are selecting all (\*) from a table you do not need to + use this function. When omitted, CodeIgniter assumes you wish to SELECT * + +$this->db->select() accepts an optional second parameter. If you set it +to FALSE, CodeIgniter will not try to protect your field or table names +with backticks. This is useful if you need a compound select statement. + +:: + + $this->db->select('(SELECT SUM(payments.amount) FROM payments WHERE payments.invoice_id=4') AS amount_paid', FALSE); + $query = $this->db->get('mytable'); + + +$this->db->select_max() +======================= + +Writes a "SELECT MAX(field)" portion for your query. You can optionally +include a second parameter to rename the resulting field. + +:: + + $this->db->select_max('age'); + $query = $this->db->get('members'); // Produces: SELECT MAX(age) as age FROM members + + $this->db->select_max('age', 'member_age'); + $query = $this->db->get('members'); // Produces: SELECT MAX(age) as member_age FROM members + + +$this->db->select_min() +======================= + +Writes a "SELECT MIN(field)" portion for your query. As with +select_max(), You can optionally include a second parameter to rename +the resulting field. + +:: + + $this->db->select_min('age'); + $query = $this->db->get('members'); // Produces: SELECT MIN(age) as age FROM members + + +$this->db->select_avg() +======================= + +Writes a "SELECT AVG(field)" portion for your query. As with +select_max(), You can optionally include a second parameter to rename +the resulting field. + +:: + + $this->db->select_avg('age'); + $query = $this->db->get('members'); // Produces: SELECT AVG(age) as age FROM members + + +$this->db->select_sum() +======================= + +Writes a "SELECT SUM(field)" portion for your query. As with +select_max(), You can optionally include a second parameter to rename +the resulting field. + +:: + + $this->db->select_sum('age'); + $query = $this->db->get('members'); // Produces: SELECT SUM(age) as age FROM members + + +$this->db->from() +================= + +Permits you to write the FROM portion of your query:: + + $this->db->select('title, content, date'); + $this->db->from('mytable'); + $query = $this->db->get(); // Produces: SELECT title, content, date FROM mytable + +.. note:: As shown earlier, the FROM portion of your query can be specified + in the $this->db->get() function, so use whichever method you prefer. + +$this->db->join() +================= + +Permits you to write the JOIN portion of your query:: + + $this->db->select('*'); + $this->db->from('blogs'); + $this->db->join('comments', 'comments.id = blogs.id'); + $query = $this->db->get(); + + // Produces: + // SELECT * FROM blogs // JOIN comments ON comments.id = blogs.id + +Multiple function calls can be made if you need several joins in one +query. + +If you need a specific type of JOIN you can specify it via the third +parameter of the function. Options are: left, right, outer, inner, left +outer, and right outer. + +:: + + $this->db->join('comments', 'comments.id = blogs.id', 'left'); + // Produces: LEFT JOIN comments ON comments.id = blogs.id + +$this->db->where() +================== + +This function enables you to set **WHERE** clauses using one of four +methods: + +.. note:: All values passed to this function are escaped automatically, + producing safer queries. + +#. **Simple key/value method:** + + :: + + $this->db->where('name', $name); // Produces: WHERE name = 'Joe' + + Notice that the equal sign is added for you. + + If you use multiple function calls they will be chained together with + AND between them: + + :: + + $this->db->where('name', $name); + $this->db->where('title', $title); + $this->db->where('status', $status); + // WHERE name = 'Joe' AND title = 'boss' AND status = 'active' + +#. **Custom key/value method:** + You can include an operator in the first parameter in order to + control the comparison: + + :: + + $this->db->where('name !=', $name); + $this->db->where('id <', $id); // Produces: WHERE name != 'Joe' AND id < 45 + +#. **Associative array method:** + + :: + + $array = array('name' => $name, 'title' => $title, 'status' => $status); + $this->db->where($array); + // Produces: WHERE name = 'Joe' AND title = 'boss' AND status = 'active' + + You can include your own operators using this method as well: + + :: + + $array = array('name !=' => $name, 'id <' => $id, 'date >' => $date); + $this->db->where($array); + +#. **Custom string:** + You can write your own clauses manually:: + + $where = "name='Joe' AND status='boss' OR status='active'"; + $this->db->where($where); + + +$this->db->where() accepts an optional third parameter. If you set it to +FALSE, CodeIgniter will not try to protect your field or table names +with backticks. + +:: + + $this->db->where('MATCH (field) AGAINST ("value")', NULL, FALSE); + + +$this->db->or_where() +===================== + +This function is identical to the one above, except that multiple +instances are joined by OR:: + + $this->db->where('name !=', $name); + $this->db->or_where('id >', $id); // Produces: WHERE name != 'Joe' OR id > 50 + +.. note:: or_where() was formerly known as orwhere(), which has been + removed. + +$this->db->where_in() +===================== + +Generates a WHERE field IN ('item', 'item') SQL query joined with AND if +appropriate + +:: + + $names = array('Frank', 'Todd', 'James'); + $this->db->where_in('username', $names); + // Produces: WHERE username IN ('Frank', 'Todd', 'James') + + +$this->db->or_where_in() +======================== + +Generates a WHERE field IN ('item', 'item') SQL query joined with OR if +appropriate + +:: + + $names = array('Frank', 'Todd', 'James'); + $this->db->or_where_in('username', $names); + // Produces: OR username IN ('Frank', 'Todd', 'James') + + +$this->db->where_not_in() +========================= + +Generates a WHERE field NOT IN ('item', 'item') SQL query joined with +AND if appropriate + +:: + + $names = array('Frank', 'Todd', 'James'); + $this->db->where_not_in('username', $names); + // Produces: WHERE username NOT IN ('Frank', 'Todd', 'James') + + +$this->db->or_where_not_in() +============================ + +Generates a WHERE field NOT IN ('item', 'item') SQL query joined with OR +if appropriate + +:: + + $names = array('Frank', 'Todd', 'James'); + $this->db->or_where_not_in('username', $names); + // Produces: OR username NOT IN ('Frank', 'Todd', 'James') + + +$this->db->like() +================= + +This function enables you to generate **LIKE** clauses, useful for doing +searches. + +.. note:: All values passed to this function are escaped automatically. + +#. **Simple key/value method:** + + :: + + $this->db->like('title', 'match'); // Produces: WHERE title LIKE '%match%' + + If you use multiple function calls they will be chained together with + AND between them:: + + $this->db->like('title', 'match'); + $this->db->like('body', 'match'); + // WHERE title LIKE '%match%' AND body LIKE '%match% + + If you want to control where the wildcard (%) is placed, you can use + an optional third argument. Your options are 'before', 'after' and + 'both' (which is the default). + + :: + + $this->db->like('title', 'match', 'before'); // Produces: WHERE title LIKE '%match' + $this->db->like('title', 'match', 'after'); // Produces: WHERE title LIKE 'match%' + $this->db->like('title', 'match', 'both'); // Produces: WHERE title LIKE '%match%' + +#. **Associative array method:** + + :: + + $array = array('title' => $match, 'page1' => $match, 'page2' => $match); + $this->db->like($array); + // WHERE title LIKE '%match%' AND page1 LIKE '%match%' AND page2 LIKE '%match%' + + +$this->db->or_like() +==================== + +This function is identical to the one above, except that multiple +instances are joined by OR:: + + $this->db->like('title', 'match'); $this->db->or_like('body', $match); + // WHERE title LIKE '%match%' OR body LIKE '%match%' + +.. note:: or_like() was formerly known as orlike(), which has been removed. + +$this->db->not_like() +===================== + +This function is identical to **like()**, except that it generates NOT +LIKE statements:: + + $this->db->not_like('title', 'match'); // WHERE title NOT LIKE '%match% + +$this->db->or_not_like() +======================== + +This function is identical to **not_like()**, except that multiple +instances are joined by OR:: + + $this->db->like('title', 'match'); + $this->db->or_not_like('body', 'match'); + // WHERE title LIKE '%match% OR body NOT LIKE '%match%' + +$this->db->group_by() +===================== + +Permits you to write the GROUP BY portion of your query:: + + $this->db->group_by("title"); // Produces: GROUP BY title + +You can also pass an array of multiple values as well:: + + $this->db->group_by(array("title", "date")); // Produces: GROUP BY title, date + +.. note:: group_by() was formerly known as groupby(), which has been + removed. + +$this->db->distinct() +===================== + +Adds the "DISTINCT" keyword to a query + +:: + + $this->db->distinct(); + $this->db->get('table'); // Produces: SELECT DISTINCT * FROM table + + +$this->db->having() +=================== + +Permits you to write the HAVING portion of your query. There are 2 +possible syntaxes, 1 argument or 2:: + + $this->db->having('user_id = 45'); // Produces: HAVING user_id = 45 + $this->db->having('user_id', 45); // Produces: HAVING user_id = 45 + +You can also pass an array of multiple values as well:: + + $this->db->having(array('title =' => 'My Title', 'id <' => $id)); + // Produces: HAVING title = 'My Title', id < 45 + + +If you are using a database that CodeIgniter escapes queries for, you +can prevent escaping content by passing an optional third argument, and +setting it to FALSE. + +:: + + $this->db->having('user_id', 45); // Produces: HAVING `user_id` = 45 in some databases such as MySQL + $this->db->having('user_id', 45, FALSE); // Produces: HAVING user_id = 45 + + +$this->db->or_having() +====================== + +Identical to having(), only separates multiple clauses with "OR". + +$this->db->order_by() +===================== + +Lets you set an ORDER BY clause. The first parameter contains the name +of the column you would like to order by. The second parameter lets you +set the direction of the result. Options are asc or desc, or random. + +:: + + $this->db->order_by("title", "desc"); // Produces: ORDER BY title DESC + +You can also pass your own string in the first parameter:: + + $this->db->order_by('title desc, name asc'); // Produces: ORDER BY title DESC, name ASC + +Or multiple function calls can be made if you need multiple fields. + +:: + + $this->db->order_by("title", "desc"); + $this->db->order_by("name", "asc"); // Produces: ORDER BY title DESC, name ASC + + +.. note:: order_by() was formerly known as orderby(), which has been + removed. + +.. note:: random ordering is not currently supported in Oracle or MSSQL + drivers. These will default to 'ASC'. + +$this->db->limit() +================== + +Lets you limit the number of rows you would like returned by the query:: + + $this->db->limit(10); // Produces: LIMIT 10 + +The second parameter lets you set a result offset. + +:: + + $this->db->limit(10, 20); // Produces: LIMIT 20, 10 (in MySQL. Other databases have slightly different syntax) + +$this->db->count_all_results() +============================== + +Permits you to determine the number of rows in a particular Active +Record query. Queries will accept Active Record restrictors such as +where(), or_where(), like(), or_like(), etc. Example:: + + echo $this->db->count_all_results('my_table'); // Produces an integer, like 25 + $this->db->like('title', 'match'); + $this->db->from('my_table'); + echo $this->db->count_all_results(); // Produces an integer, like 17 + +$this->db->count_all() +====================== + +Permits you to determine the number of rows in a particular table. +Submit the table name in the first parameter. Example:: + + echo $this->db->count_all('my_table'); // Produces an integer, like 25 + +************** +Inserting Data +************** + +$this->db->insert() +=================== + +Generates an insert string based on the data you supply, and runs the +query. You can either pass an **array** or an **object** to the +function. Here is an example using an array:: + + $data = array( + 'title' => 'My title', + 'name' => 'My Name', + 'date' => 'My date' + ); + + $this->db->insert('mytable', $data); + // Produces: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date') + +The first parameter will contain the table name, the second is an +associative array of values. + +Here is an example using an object:: + + /* + class Myclass { + var $title = 'My Title'; + var $content = 'My Content'; + var $date = 'My Date'; + } + */ + + $object = new Myclass; + $this->db->insert('mytable', $object); + // Produces: INSERT INTO mytable (title, content, date) VALUES ('My Title', 'My Content', 'My Date') + +The first parameter will contain the table name, the second is an +object. + +.. note:: All values are escaped automatically producing safer queries. + +$this->db->insert_batch() +========================= + +Generates an insert string based on the data you supply, and runs the +query. You can either pass an **array** or an **object** to the +function. Here is an example using an array:: + + $data = array( + array( + 'title' => 'My title', + 'name' => 'My Name', + 'date' => 'My date' + ), + array( + 'title' => 'Another title', + 'name' => 'Another Name', + 'date' => 'Another date' + ) + ); + + $this->db->insert_batch('mytable', $data); + // Produces: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date'), ('Another title', 'Another name', 'Another date') + +The first parameter will contain the table name, the second is an +associative array of values. + +.. note:: All values are escaped automatically producing safer queries. + +$this->db->set() +================ + +This function enables you to set values for inserts or updates. + +**It can be used instead of passing a data array directly to the insert +or update functions:** + +:: + + $this->db->set('name', $name); + $this->db->insert('mytable'); // Produces: INSERT INTO mytable (name) VALUES ('{$name}') + +If you use multiple function called they will be assembled properly +based on whether you are doing an insert or an update:: + + $this->db->set('name', $name); + $this->db->set('title', $title); + $this->db->set('status', $status); + $this->db->insert('mytable'); + +**set()** will also accept an optional third parameter ($escape), that +will prevent data from being escaped if set to FALSE. To illustrate the +difference, here is set() used both with and without the escape +parameter. + +:: + + $this->db->set('field', 'field+1', FALSE); + $this->db->insert('mytable'); // gives INSERT INTO mytable (field) VALUES (field+1) + $this->db->set('field', 'field+1'); + $this->db->insert('mytable'); // gives INSERT INTO mytable (field) VALUES ('field+1') + + +You can also pass an associative array to this function:: + + $array = array( + 'name' => $name, + 'title' => $title, + 'status' => $status + ); + + $this->db->set($array); + $this->db->insert('mytable'); + +Or an object:: + + /* + class Myclass { + var $title = 'My Title'; + var $content = 'My Content'; + var $date = 'My Date'; + } + */ + + $object = new Myclass; + $this->db->set($object); + $this->db->insert('mytable'); + + +************* +Updating Data +************* + +$this->db->update() +=================== + +Generates an update string and runs the query based on the data you +supply. You can pass an **array** or an **object** to the function. Here +is an example using an array:: + + $data = array( + 'title' => $title, + 'name' => $name, + 'date' => $date + ); + + $this->db->where('id', $id); + $this->db->update('mytable', $data); + // Produces: // UPDATE mytable // SET title = '{$title}', name = '{$name}', date = '{$date}' // WHERE id = $id + +Or you can supply an object:: + + /* + class Myclass { + var $title = 'My Title'; + var $content = 'My Content'; + var $date = 'My Date'; + } + */ + + $object = new Myclass; + $this->db->where('id', $id); + $this->db->update('mytable', $object); + // Produces: // UPDATE mytable // SET title = '{$title}', name = '{$name}', date = '{$date}' // WHERE id = $id + +.. note:: All values are escaped automatically producing safer queries. + +You'll notice the use of the $this->db->where() function, enabling you +to set the WHERE clause. You can optionally pass this information +directly into the update function as a string:: + + $this->db->update('mytable', $data, "id = 4"); + +Or as an array:: + + $this->db->update('mytable', $data, array('id' => $id)); + +You may also use the $this->db->set() function described above when +performing updates. + +$this->db->update_batch() +========================= + +Generates an update string based on the data you supply, and runs the query. +You can either pass an **array** or an **object** to the function. +Here is an example using an array:: + + $data = array( + array( + 'title' => 'My title' , + 'name' => 'My Name 2' , + 'date' => 'My date 2' + ), + array( + 'title' => 'Another title' , + 'name' => 'Another Name 2' , + 'date' => 'Another date 2' + ) + ); + + $this->db->update_batch('mytable', $data, 'title'); + + // Produces: + // UPDATE `mytable` SET `name` = CASE + // WHEN `title` = 'My title' THEN 'My Name 2' + // WHEN `title` = 'Another title' THEN 'Another Name 2' + // ELSE `name` END, + // `date` = CASE + // WHEN `title` = 'My title' THEN 'My date 2' + // WHEN `title` = 'Another title' THEN 'Another date 2' + // ELSE `date` END + // WHERE `title` IN ('My title','Another title') + +The first parameter will contain the table name, the second is an associative +array of values, the third parameter is the where key. + +.. note:: All values are escaped automatically producing safer queries. + + +************* +Deleting Data +************* + +$this->db->delete() +=================== + +Generates a delete SQL string and runs the query. + +:: + + $this->db->delete('mytable', array('id' => $id)); // Produces: // DELETE FROM mytable // WHERE id = $id + +The first parameter is the table name, the second is the where clause. +You can also use the where() or or_where() functions instead of passing +the data to the second parameter of the function:: + + $this->db->where('id', $id); + $this->db->delete('mytable'); + + // Produces: + // DELETE FROM mytable + // WHERE id = $id + + +An array of table names can be passed into delete() if you would like to +delete data from more than 1 table. + +:: + + $tables = array('table1', 'table2', 'table3'); + $this->db->where('id', '5'); + $this->db->delete($tables); + + +If you want to delete all data from a table, you can use the truncate() +function, or empty_table(). + +$this->db->empty_table() +======================== + +Generates a delete SQL string and runs the +query.:: + + $this->db->empty_table('mytable'); // Produces // DELETE FROM mytable + + +$this->db->truncate() +===================== + +Generates a truncate SQL string and runs the query. + +:: + + $this->db->from('mytable'); + $this->db->truncate(); + + // or + + $this->db->truncate('mytable'); + + // Produce: + // TRUNCATE mytable + +.. note:: If the TRUNCATE command isn't available, truncate() will + execute as "DELETE FROM table". + +*************** +Method Chaining +*************** + +Method chaining allows you to simplify your syntax by connecting +multiple functions. Consider this example:: + + $query = $this->db->select('title') + ->where('id', $id) + ->limit(10, 20) + ->get('mytable'); + +.. note:: Method chaining only works with PHP 5. + +.. _ar-caching: + +********************* +Active Record Caching +********************* + +While not "true" caching, Active Record enables you to save (or "cache") +certain parts of your queries for reuse at a later point in your +script's execution. Normally, when an Active Record call is completed, +all stored information is reset for the next call. With caching, you can +prevent this reset, and reuse information easily. + +Cached calls are cumulative. If you make 2 cached select() calls, and +then 2 uncached select() calls, this will result in 4 select() calls. +There are three Caching functions available: + +$this->db->start_cache() +======================== + +This function must be called to begin caching. All Active Record queries +of the correct type (see below for supported queries) are stored for +later use. + +$this->db->stop_cache() +======================= + +This function can be called to stop caching. + +$this->db->flush_cache() +======================== + +This function deletes all items from the Active Record cache. + +Here's a usage example:: + + $this->db->start_cache(); + $this->db->select('field1'); + $this->db->stop_cache(); + $this->db->get('tablename'); + //Generates: SELECT `field1` FROM (`tablename`) + + $this->db->select('field2'); + $this->db->get('tablename'); + //Generates: SELECT `field1`, `field2` FROM (`tablename`) + + $this->db->flush_cache(); + $this->db->select('field2'); + $this->db->get('tablename'); + //Generates: SELECT `field2` FROM (`tablename`) + + +.. note:: The following statements can be cached: select, from, join, + where, like, group_by, having, order_by, set + + diff --git a/user_guide_src/source/database/caching.rst b/user_guide_src/source/database/caching.rst new file mode 100644 index 000000000..7a195a7a1 --- /dev/null +++ b/user_guide_src/source/database/caching.rst @@ -0,0 +1,152 @@ +###################### +Database Caching Class +###################### + +The Database Caching Class permits you to cache your queries as text +files for reduced database load. + +.. important:: This class is initialized automatically by the database + driver when caching is enabled. Do NOT load this class manually. + +.. important:: Not all query result functions are available when you + use caching. Please read this page carefully. + +Enabling Caching +================ + +Caching is enabled in three steps: + +- Create a writable directory on your server where the cache files can + be stored. +- Set the path to your cache folder in your + application/config/database.php file. +- Enable the caching feature, either globally by setting the preference + in your application/config/database.php file, or manually as + described below. + +Once enabled, caching will happen automatically whenever a page is +loaded that contains database queries. + +How Does Caching Work? +====================== + +CodeIgniter's query caching system happens dynamically when your pages +are viewed. When caching is enabled, the first time a web page is +loaded, the query result object will be serialized and stored in a text +file on your server. The next time the page is loaded the cache file +will be used instead of accessing your database. Your database usage can +effectively be reduced to zero for any pages that have been cached. + +Only read-type (SELECT) queries can be cached, since these are the only +type of queries that produce a result. Write-type (INSERT, UPDATE, etc.) +queries, since they don't generate a result, will not be cached by the +system. + +Cache files DO NOT expire. Any queries that have been cached will remain +cached until you delete them. The caching system permits you clear +caches associated with individual pages, or you can delete the entire +collection of cache files. Typically you'll want to use the housekeeping +functions described below to delete cache files after certain events +take place, like when you've added new information to your database. + +Will Caching Improve Your Site's Performance? +============================================= + +Getting a performance gain as a result of caching depends on many +factors. If you have a highly optimized database under very little load, +you probably won't see a performance boost. If your database is under +heavy use you probably will see an improved response, assuming your +file-system is not overly taxed. Remember that caching simply changes +how your information is retrieved, shifting it from being a database +operation to a file-system one. + +In some clustered server environments, for example, caching may be +detrimental since file-system operations are so intense. On single +servers in shared environments, caching will probably be beneficial. +Unfortunately there is no single answer to the question of whether you +should cache your database. It really depends on your situation. + +How are Cache Files Stored? +=========================== + +CodeIgniter places the result of EACH query into its own cache file. +Sets of cache files are further organized into sub-folders corresponding +to your controller functions. To be precise, the sub-folders are named +identically to the first two segments of your URI (the controller class +name and function name). + +For example, let's say you have a controller called blog with a function +called comments that contains three queries. The caching system will +create a cache folder called blog+comments, into which it will write +three cache files. + +If you use dynamic queries that change based on information in your URI +(when using pagination, for example), each instance of the query will +produce its own cache file. It's possible, therefore, to end up with +many times more cache files than you have queries. + +Managing your Cache Files +========================= + +Since cache files do not expire, you'll need to build deletion routines +into your application. For example, let's say you have a blog that +allows user commenting. Whenever a new comment is submitted you'll want +to delete the cache files associated with the controller function that +serves up your comments. You'll find two delete functions described +below that help you clear data. + +Not All Database Functions Work with Caching +============================================ + +Lastly, we need to point out that the result object that is cached is a +simplified version of the full result object. For that reason, some of +the query result functions are not available for use. + +The following functions ARE NOT available when using a cached result +object: + +- num_fields() +- field_names() +- field_data() +- free_result() + +Also, the two database resources (result_id and conn_id) are not +available when caching, since result resources only pertain to run-time +operations. + +****************** +Function Reference +****************** + +$this->db->cache_on() / $this->db->cache_off() +================================================ + +Manually enables/disables caching. This can be useful if you want to +keep certain queries from being cached. Example:: + + // Turn caching on $this->db->cache_on(); $query = $this->db->query("SELECT * FROM mytable"); // Turn caching off for this one query $this->db->cache_off(); $query = $this->db->query("SELECT * FROM members WHERE member_id = '$current_user'"); // Turn caching back on $this->db->cache_on(); $query = $this->db->query("SELECT * FROM another_table"); + +$this->db->cache_delete() +========================== + +Deletes the cache files associated with a particular page. This is +useful if you need to clear caching after you update your database. + +The caching system saves your cache files to folders that correspond to +the URI of the page you are viewing. For example, if you are viewing a +page at example.com/index.php/blog/comments, the caching system will put +all cache files associated with it in a folder called blog+comments. To +delete those particular cache files you will use:: + + $this->db->cache_delete('blog', 'comments'); + +If you do not use any parameters the current URI will be used when +determining what should be cleared. + +$this->db->cache_delete_all() +=============================== + +Clears all existing cache files. Example:: + + $this->db->cache_delete_all(); + diff --git a/user_guide_src/source/database/call_function.rst b/user_guide_src/source/database/call_function.rst new file mode 100644 index 000000000..bdc5be0a5 --- /dev/null +++ b/user_guide_src/source/database/call_function.rst @@ -0,0 +1,38 @@ +##################### +Custom Function Calls +##################### + +$this->db->call_function(); +============================ + +This function enables you to call PHP database functions that are not +natively included in CodeIgniter, in a platform independent manner. For +example, lets say you want to call the mysql_get_client_info() +function, which is **not** natively supported by CodeIgniter. You could +do so like this:: + + $this->db->call_function('get_client_info'); + +You must supply the name of the function, **without** the mysql\_ +prefix, in the first parameter. The prefix is added automatically based +on which database driver is currently being used. This permits you to +run the same function on different database platforms. Obviously not all +function calls are identical between platforms, so there are limits to +how useful this function can be in terms of portability. + +Any parameters needed by the function you are calling will be added to +the second parameter. + +:: + + $this->db->call_function('some_function', $param1, $param2, etc..); + +Often, you will either need to supply a database connection ID or a +database result ID. The connection ID can be accessed using:: + + $this->db->conn_id; + +The result ID can be accessed from within your result object, like this:: + + $query = $this->db->query("SOME QUERY"); $query->result_id; + diff --git a/user_guide_src/source/database/configuration.rst b/user_guide_src/source/database/configuration.rst new file mode 100644 index 000000000..77b4994a3 --- /dev/null +++ b/user_guide_src/source/database/configuration.rst @@ -0,0 +1,107 @@ +###################### +Database Configuration +###################### + +CodeIgniter has a config file that lets you store your database +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. + +The config settings are stored in a multi-dimensional array with this +prototype:: + + $db['default']['hostname'] = "localhost"; $db['default']['username'] = "root"; $db['default']['password'] = ""; $db['default']['database'] = "database_name"; $db['default']['dbdriver'] = "mysql"; $db['default']['dbprefix'] = ""; $db['default']['pconnect'] = TRUE; $db['default']['db_debug'] = FALSE; $db['default']['cache_on'] = FALSE; $db['default']['cachedir'] = ""; $db['default']['char_set'] = "utf8"; $db['default']['dbcollat'] = "utf8_general_ci"; $db['default']['swap_pre'] = ""; $db['default']['autoinit'] = TRUE; $db['default']['stricton'] = FALSE; + +The reason we use a multi-dimensional array rather than a more simple +one is to permit you to optionally store multiple sets of connection +values. If, for example, you run multiple environments (development, +production, test, etc.) under a single installation, you can set up a +connection group for each, then switch between groups as needed. For +example, to set up a "test" environment you would do this:: + + $db['test']['hostname'] = "localhost"; $db['test']['username'] = "root"; $db['test']['password'] = ""; $db['test']['database'] = "database_name"; $db['test']['dbdriver'] = "mysql"; $db['test']['dbprefix'] = ""; $db['test']['pconnect'] = TRUE; $db['test']['db_debug'] = FALSE; $db['test']['cache_on'] = FALSE; $db['test']['cachedir'] = ""; $db['test']['char_set'] = "utf8"; $db['test']['dbcollat'] = "utf8_general_ci"; $db['test']['swap_pre'] = ""; $db['test']['autoinit'] = TRUE; $db['test']['stricton'] = FALSE; + +Then, to globally tell the system to use that group you would set this +variable located in the config file:: + + $active_group = "test"; + +Note: The name "test" is arbitrary. It can be anything you want. By +default we've used the word "default" for the primary connection, but it +too can be renamed to something more relevant to your project. + +Active Record +------------- + +The :doc:`Active Record Class ` is globally enabled or +disabled by setting the $active_record variable in the database +configuration file to TRUE/FALSE (boolean). If you are not using the +active record class, setting it to FALSE will utilize fewer resources +when the database classes are initialized. + +:: + + $active_record = TRUE; + +.. note:: that some CodeIgniter classes such as Sessions require Active + Records be enabled to access certain functionality. + +Explanation of Values: +---------------------- + +- **hostname** - The hostname of your database server. Often this is + "localhost". +- **username** - The username used to connect to the database. +- **password** - The password used to connect to the database. +- **database** - The name of the database you want to connect to. +- **dbdriver** - The database type. ie: mysql, postgres, odbc, etc. + Must be specified in lower case. +- **dbprefix** - An optional table prefix which will added to the table + name when running :doc:`Active Record ` queries. This + permits multiple CodeIgniter installations to share one database. +- **pconnect** - TRUE/FALSE (boolean) - Whether to use a persistent + connection. +- **db_debug** - TRUE/FALSE (boolean) - Whether database errors should + be displayed. +- **cache_on** - TRUE/FALSE (boolean) - Whether database query caching + is enabled, see also :doc:`Database Caching Class `. +- **cachedir** - The absolute server path to your database query cache + directory. +- **char_set** - The character set used in communicating with the + database. +- **dbcollat** - The character collation used in communicating with the + database. + +.. note:: For MySQL and MySQLi databases, this setting is only used + as a backup if your server is running PHP < 5.2.3 or MySQL < 5.0.7 + (and in table creation queries made with DB Forge). There is an + incompatibility in PHP with mysql_real_escape_string() which can + make your site vulnerable to SQL injection if you are using a + multi-byte character set and are running versions lower than these. + Sites using Latin-1 or UTF-8 database character set and collation are + unaffected. + +- **swap_pre** - A default table prefix that should be swapped with + dbprefix. This is useful for distributed applications where you might + run manually written queries, and need the prefix to still be + customizable by the end user. +- **autoinit** - Whether or not to automatically connect to the + database when the library loads. If set to false, the connection will + take place prior to executing the first query. +- **stricton** - TRUE/FALSE (boolean) - Whether to force "Strict Mode" + connections, good for ensuring strict SQL while developing an + application. +- **port** - The database port number. To use this value you have to + add a line to the database config + array.:: + + $db['default']['port'] = 5432; + + +.. note:: Depending on what database platform you are using (MySQL, + Postgres, etc.) not all values will be needed. For example, when using + SQLite you will not need to supply a username or password, and the + database name will be the path to your database file. The information + above assumes you are using MySQL. diff --git a/user_guide_src/source/database/connecting.rst b/user_guide_src/source/database/connecting.rst new file mode 100644 index 000000000..6c549434d --- /dev/null +++ b/user_guide_src/source/database/connecting.rst @@ -0,0 +1,131 @@ +########################### +Connecting to your Database +########################### + +There are two ways to connect to a database: + +Automatically Connecting +======================== + +The "auto connect" feature will load and instantiate the database class +with every page load. To enable "auto connecting", add the word database +to the library array, as indicated in the following file: + +application/config/autoload.php + +Manually Connecting +=================== + +If only some of your pages require database connectivity you can +manually connect to your database by adding this line of code in any +function where it is needed, or in your class constructor to make the +database available globally in that class. + +:: + + $this->load->database(); + +If the above function does **not** contain any information in the first +parameter it will connect to the group specified in your database config +file. For most people, this is the preferred method of use. + +Available Parameters +-------------------- + +#. The database connection values, passed either as an array or a DSN + string. +#. TRUE/FALSE (boolean). Whether to return the connection ID (see + Connecting to Multiple Databases below). +#. TRUE/FALSE (boolean). Whether to enable the Active Record class. Set + to TRUE by default. + +Manually Connecting to a Database +--------------------------------- + +The first parameter of this function can **optionally** be used to +specify a particular database group from your config file, or you can +even submit connection values for a database that is not specified in +your config file. Examples: + +To choose a specific group from your config file you can do this:: + + $this->load->database('group_name'); + +Where group_name is the name of the connection group from your config +file. + +To connect manually to a desired database you can pass an array of +values:: + + $config['hostname'] = "localhost"; $config['username'] = "myusername"; $config['password'] = "mypassword"; $config['database'] = "mydatabase"; $config['dbdriver'] = "mysql"; $config['dbprefix'] = ""; $config['pconnect'] = FALSE; $config['db_debug'] = TRUE; $config['cache_on'] = FALSE; $config['cachedir'] = ""; $config['char_set'] = "utf8"; $config['dbcollat'] = "utf8_general_ci"; $this->load->database($config); + +For information on each of these values please see the :doc:`configuration +page `. + +.. note:: For the PDO driver, $config['hostname'] should look like + this: 'mysql:host=localhost' + +Or you can submit your database values as a Data Source Name. DSNs must +have this prototype:: + + $dsn = 'dbdriver://username:password@hostname/database'; $this->load->database($dsn); + +To override default config values when connecting with a DSN string, add +the config variables as a query string. + +:: + + $dsn = 'dbdriver://username:password@hostname/database?char_set=utf8&dbcollat=utf8_general_ci&cache_on=true&cachedir=/path/to/cache'; $this->load->database($dsn); + +Connecting to Multiple Databases +================================ + +If you need to connect to more than one database simultaneously you can +do so as follows:: + + $DB1 = $this->load->database('group_one', TRUE); $DB2 = $this->load->database('group_two', TRUE); + +Note: Change the words "group_one" and "group_two" to the specific +group names you are connecting to (or you can pass the connection values +as indicated above). + +By setting the second parameter to TRUE (boolean) the function will +return the database object. + +When you connect this way, you will use your object name to issue +commands rather than the syntax used throughout this guide. In other +words, rather than issuing commands with: + +$this->db->query(); +$this->db->result(); +etc... + +You will instead use: + +$DB1->query(); +$DB1->result(); +etc... + +Reconnecting / Keeping the Connection Alive +=========================================== + +If the database server's idle timeout is exceeded while you're doing +some heavy PHP lifting (processing an image, for instance), you should +consider pinging the server by using the reconnect() method before +sending further queries, which can gracefully keep the connection alive +or re-establish it. + +:: + + $this->db->reconnect(); + +Manually closing the Connection +=============================== + +While CodeIgniter intelligently takes care of closing your database +connections, you can explicitly close the connection. + +:: + + $this->db->close(); + diff --git a/user_guide_src/source/database/examples.rst b/user_guide_src/source/database/examples.rst new file mode 100644 index 000000000..bd2cc4d96 --- /dev/null +++ b/user_guide_src/source/database/examples.rst @@ -0,0 +1,94 @@ +################################## +Database Quick Start: Example Code +################################## + +The following page contains example code showing how the database class +is used. For complete details please read the individual pages +describing each function. + +Initializing the Database Class +=============================== + +The following code loads and initializes the database class based on +your :doc:`configuration ` settings:: + + $this->load->database(); + +Once loaded the class is ready to be used as described below. + +Note: If all your pages require database access you can connect +automatically. See the :doc:`connecting ` page for details. + +Standard Query With Multiple Results (Object Version) +===================================================== + +:: + + $query = $this->db->query('SELECT name, title, email FROM my_table'); foreach ($query->result() as $row) {     echo $row->title;     echo $row->name;     echo $row->email; } echo 'Total Results: ' . $query->num_rows(); + +The above result() function returns an array of **objects**. Example: +$row->title + +Standard Query With Multiple Results (Array Version) +==================================================== + +:: + + $query = $this->db->query('SELECT name, title, email FROM my_table'); foreach ($query->result_array() as $row) {     echo $row['title'];     echo $row['name'];     echo $row['email']; } + +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 +================================= + +:: + + $query = $this->db->query('SELECT name FROM my_table LIMIT 1'); $row = $query->row(); echo $row->name; + +The above row() function returns an **object**. Example: $row->name + +Standard Query With Single Result (Array version) +================================================= + +:: + + $query = $this->db->query('SELECT name FROM my_table LIMIT 1'); $row = $query->row_array(); echo $row['name']; + +The above row_array() function returns an **array**. Example: +$row['name'] + +Standard Insert +=============== + +:: + + $sql = "INSERT INTO mytable (title, name)         VALUES (".$this->db->escape($title).", ".$this->db->escape($name).")"; $this->db->query($sql); echo $this->db->affected_rows(); + +Active Record Query +=================== + +The :doc:`Active Record Pattern ` gives you a simplified +means of retrieving data:: + + $query = $this->db->get('table_name'); foreach ($query->result() as $row) {     echo $row->title; } + +The above get() function retrieves all the results from the supplied +table. The :doc:`Active Record ` class contains a full +compliment of functions for working with data. + +Active Record Insert +==================== + +:: + + $data = array(                'title' => $title,                'name' => $name,                'date' => $date             ); $this->db->insert('mytable', $data); // Produces: INSERT INTO mytable (title, name, date) VALUES ('{$title}', '{$name}', '{$date}') + diff --git a/user_guide_src/source/database/fields.rst b/user_guide_src/source/database/fields.rst new file mode 100644 index 000000000..07730f5d3 --- /dev/null +++ b/user_guide_src/source/database/fields.rst @@ -0,0 +1,59 @@ +########## +Field Data +########## + +$this->db->list_fields() +========================= + +Returns an array containing the field names. This query can be called +two ways: + +1. You can supply the table name and call it from the $this->db-> +object:: + + $fields = $this->db->list_fields('table_name'); foreach ($fields as $field) {    echo $field; } + +2. You can gather the field names associated with any query you run by +calling the function from your query result object:: + + $query = $this->db->query('SELECT * FROM some_table'); foreach ($query->list_fields() as $field) {    echo $field; } + +$this->db->field_exists() +========================== + +Sometimes it's helpful to know whether a particular field exists before +performing an action. Returns a boolean TRUE/FALSE. Usage example:: + + if ($this->db->field_exists('field_name', 'table_name')) {    // some code... } + +Note: Replace *field_name* with the name of the column you are looking +for, and replace *table_name* with the name of the table you are +looking for. + +$this->db->field_data() +======================== + +Returns an array of objects containing field information. + +Sometimes it's helpful to gather the field names or other metadata, like +the column type, max length, etc. + +Note: Not all databases provide meta-data. + +Usage example:: + + $fields = $this->db->field_data('table_name'); foreach ($fields as $field) {    echo $field->name;    echo $field->type;    echo $field->max_length;    echo $field->primary_key; } + +If you have run a query already you can use the result object instead of +supplying the table name:: + + $query = $this->db->query("YOUR QUERY"); $fields = $query->field_data(); + +The following data is available from this function if supported by your +database: + +- name - column name +- max_length - maximum length of the column +- primary_key - 1 if the column is a primary key +- type - the type of the column + diff --git a/user_guide_src/source/database/forge.rst b/user_guide_src/source/database/forge.rst new file mode 100644 index 000000000..ee033248c --- /dev/null +++ b/user_guide_src/source/database/forge.rst @@ -0,0 +1,212 @@ +#################### +Database Forge Class +#################### + +The Database Forge Class contains functions that help you manage your +database. + +.. contents:: Table of Contents + +**************************** +Initializing the Forge Class +**************************** + +.. important:: In order to initialize the Forge class, your database + driver must already be running, since the forge class relies on it. + +Load the Forge Class as follows:: + + $this->load->dbforge() + +Once initialized you will access the functions using the $this->dbforge +object:: + + $this->dbforge->some_function() + +$this->dbforge->create_database('db_name') +============================================ + +Permits you to create the database specified in the first parameter. +Returns TRUE/FALSE based on success or failure:: + + if ($this->dbforge->create_database('my_db')) {     echo 'Database created!'; } + +$this->dbforge->drop_database('db_name') +========================================== + +Permits you to drop the database specified in the first parameter. +Returns TRUE/FALSE based on success or failure:: + + if ($this->dbforge->drop_database('my_db')) {     echo 'Database deleted!'; } + +**************************** +Creating and Dropping Tables +**************************** + +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. + +Adding fields +============= + +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. + +:: + + $fields = array(                         'users' => array(                                                  'type' => 'VARCHAR',                                                  'constraint' => '100',                                           ),                 ); // will translate to "users VARCHAR(100)" when the field is added. + + +Additionally, the following key/values can be used: + +- unsigned/true : to generate "UNSIGNED" in the field definition. +- default/value : to generate a default value in the field definition. +- null/true : to generate "NULL" in the field definition. Without this, + the field will default to "NOT NULL". +- 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. + +:: + + $fields = array(                         'blog_id' => array(                                                  'type' => 'INT',                                                  'constraint' => 5,                                                  'unsigned' => TRUE,                                                  'auto_increment' => TRUE                                           ),                         'blog_title' => array(                                                  'type' => 'VARCHAR',                                                  'constraint' => '100',                                           ),                         'blog_author' => array(                                                  'type' =>'VARCHAR',                                                  'constraint' => '100',                                                  'default' => 'King of Town',                                           ),                         'blog_description' => array(                                                  'type' => 'TEXT',                                                  'null' => TRUE,                                           ),                 ); + + +After the fields have been defined, they can be added using +$this->dbforge->add_field($fields); followed by a call to the +create_table() function. + +$this->dbforge->add_field() +---------------------------- + +The add fields function will accept the above array. + +Passing strings as fields +------------------------- + +If you know exactly how you want a field to be created, you can pass the +string into the field definitions with add_field() + +:: + + $this->dbforge->add_field("label varchar(100) NOT NULL DEFAULT 'default label'"); + + +Note: Multiple calls to add_field() are cumulative. + +Creating an id field +-------------------- + +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. + +:: + + $this->dbforge->add_field('id'); // gives id INT(9) NOT NULL AUTO_INCREMENT + + +Adding Keys +=========== + +Generally speaking, you'll want your table to have Keys. This is +accomplished with $this->dbforge->add_key('field'). An optional second +parameter set to TRUE will make it a primary key. Note that add_key() +must be followed by a call to create_table(). + +Multiple column non-primary keys must be sent as an array. Sample output +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`) + + +Creating a table +================ + +After fields and keys have been declared, you can create a new table +with + +:: + + $this->dbforge->create_table('table_name'); // gives CREATE TABLE table_name + + +An optional second parameter set to TRUE adds an "IF NOT EXISTS" clause +into the definition + +:: + + $this->dbforge->create_table('table_name', TRUE); // gives CREATE TABLE IF NOT EXISTS table_name + + +Dropping a table +================ + +Executes a DROP TABLE sql + +:: + + $this->dbforge->drop_table('table_name'); // gives DROP TABLE IF EXISTS table_name + + +Renaming a table +================ + +Executes a TABLE rename + +:: + + $this->dbforge->rename_table('old_table_name', 'new_table_name'); // gives ALTER TABLE old_table_name RENAME TO new_table_name + + +**************** +Modifying Tables +**************** + +$this->dbforge->add_column() +============================= + +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. + +:: + + $fields = array(                         'preferences' => array('type' => 'TEXT') ); $this->dbforge->add_column('table_name', $fields); // gives ALTER TABLE table_name ADD preferences TEXT + +An optional third parameter can be used to specify which existing column +to add the new column after. + +:: + + $this->dbforge->add_column('table_name', $fields, 'after_field'); + + +$this->dbforge->drop_column() +============================== + +Used to remove a column from a table. + +:: + + $this->dbforge->drop_column('table_name', 'column_to_drop'); + + +$this->dbforge->modify_column() +================================ + +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 +change the name you can add a "name" key into the field defining array. + +:: + + $fields = array(                         'old_name' => array(                                                          'name' => 'new_name',                                                          'type' => 'TEXT',                                                 ), ); $this->dbforge->modify_column('table_name', $fields); // gives ALTER TABLE table_name CHANGE old_name new_name TEXT + + + diff --git a/user_guide_src/source/database/helpers.rst b/user_guide_src/source/database/helpers.rst new file mode 100644 index 000000000..b0a5ce97b --- /dev/null +++ b/user_guide_src/source/database/helpers.rst @@ -0,0 +1,88 @@ +###################### +Query Helper Functions +###################### + +$this->db->insert_id() +======================= + +The insert ID number when performing database inserts. + +.. note:: If using the PDO driver with PostgreSQL, this function requires + a $name parameter, which specifies the appropriate sequence to check + for the insert id. + +$this->db->affected_rows() +=========================== + +Displays the number of affected rows, when doing "write" type queries +(insert, update, etc.). + +.. note:: In MySQL "DELETE FROM TABLE" returns 0 affected rows. The database + class has a small hack that allows it to return the correct number of + affected rows. By default this hack is enabled but it can be turned off + in the database driver file. + +$this->db->count_all(); +======================== + +Permits you to determine the number of rows in a particular table. +Submit the table name in the first parameter. Example:: + + echo $this->db->count_all('my_table'); // Produces an integer, like 25 + +$this->db->platform() +===================== + +Outputs the database platform you are running (MySQL, MS SQL, Postgres, +etc...):: + + echo $this->db->platform(); + +$this->db->version() +==================== + +Outputs the database version you are running:: + + echo $this->db->version(); + +$this->db->last_query(); +========================= + +Returns the last query that was run (the query string, not the result). +Example:: + + $str = $this->db->last_query(); // Produces: SELECT * FROM sometable.... + +The following two functions help simplify the process of writing +database INSERTs and UPDATEs. + +$this->db->insert_string(); +============================ + +This function simplifies the process of writing database inserts. It +returns a correctly formatted SQL insert string. Example:: + + $data = array('name' => $name, 'email' => $email, 'url' => $url); $str = $this->db->insert_string('table_name', $data); + +The first parameter is the table name, the second is an associative +array with the data to be inserted. The above example produces:: + + INSERT INTO table_name (name, email, url) VALUES ('Rick', 'rick@example.com', 'example.com') + +Note: Values are automatically escaped, producing safer queries. + +$this->db->update_string(); +============================ + +This function simplifies the process of writing database updates. It +returns a correctly formatted SQL update string. Example:: + + $data = array('name' => $name, 'email' => $email, 'url' => $url); $where = "author_id = 1 AND status = 'active'"; $str = $this->db->update_string('table_name', $data, $where); + +The first parameter is the table name, the second is an associative +array with the data to be updated, and the third parameter is the +"where" clause. The above example produces:: + + UPDATE table_name SET name = 'Rick', email = 'rick@example.com', url = 'example.com' WHERE author_id = 1 AND status = 'active' + +Note: Values are automatically escaped, producing safer queries. diff --git a/user_guide_src/source/database/index.rst b/user_guide_src/source/database/index.rst new file mode 100644 index 000000000..3b59986be --- /dev/null +++ b/user_guide_src/source/database/index.rst @@ -0,0 +1,29 @@ +################## +The Database Class +################## + +CodeIgniter comes with a full-featured and very fast abstracted database +class that supports both traditional structures and Active Record +patterns. The database functions offer clear, simple syntax. + +- :doc:`Quick Start: Usage Examples ` +- :doc:`Database Configuration ` +- :doc:`Connecting to a Database ` +- :doc:`Running Queries ` +- :doc:`Generating Query Results ` +- :doc:`Query Helper Functions ` +- :doc:`Active Record Class ` +- :doc:`Transactions ` +- :doc:`Table MetaData ` +- :doc:`Field MetaData ` +- :doc:`Custom Function Calls ` +- :doc:`Query Caching ` +- :doc:`Database manipulation with Database Forge ` +- :doc:`Database Utilities Class ` + +.. toctree:: + :glob: + :titlesonly: + :hidden: + + * \ No newline at end of file diff --git a/user_guide_src/source/database/queries.rst b/user_guide_src/source/database/queries.rst new file mode 100644 index 000000000..cfc42c4c3 --- /dev/null +++ b/user_guide_src/source/database/queries.rst @@ -0,0 +1,112 @@ +####### +Queries +####### + +$this->db->query(); +=================== + +To submit a query, use the following function:: + + $this->db->query('YOUR QUERY HERE'); + +The query() function returns a database result **object** when "read" +type queries are run, which you can use to :doc:`show your +results `. When "write" type queries are run it simply +returns TRUE or FALSE depending on success or failure. When retrieving +data you will typically assign the query to your own variable, like +this:: + + $query = $this->db->query('YOUR QUERY HERE'); + +$this->db->simple_query(); +=========================== + +This is a simplified version of the $this->db->query() function. It ONLY +returns TRUE/FALSE on success or failure. It DOES NOT return a database +result set, nor does it set the query timer, or compile bind data, or +store your query for debugging. It simply lets you submit a query. Most +users will rarely use this function. + +*************************************** +Working with Database prefixes manually +*************************************** + +If you have configured a database prefix and would like to prepend it to +a table name for use in a native SQL query for example, then you can use +the following:: + + $this->db->dbprefix('tablename'); // outputs prefix_tablename + + +If for any reason you would like to change the prefix programatically +without needing to create a new connection, you can use this method:: + + $this->db->set_dbprefix('newprefix'); $this->db->dbprefix('tablename'); // outputs newprefix_tablename + + +********************** +Protecting identifiers +********************** + +In many databases it is advisable to protect table and field names - for +example with backticks in MySQL. **Active Record queries are +automatically protected**, however if you need to manually protect an +identifier you can use:: + + $this->db->protect_identifiers('table_name'); + + +This function will also add a table prefix to your table, assuming you +have a prefix specified in your database config file. To enable the +prefixing set TRUE (boolen) via the second parameter:: + + $this->db->protect_identifiers('table_name', TRUE); + + +**************** +Escaping Queries +**************** + +It's a very good security practice to escape your data before submitting +it into your database. CodeIgniter has three methods that help you do +this: + +#. **$this->db->escape()** This function determines the data type so + that it can escape only string data. It also automatically adds + single quotes around the data so you don't have to: + :: + + $sql = "INSERT INTO table (title) VALUES(".$this->db->escape($title).")"; + +#. **$this->db->escape_str()** This function escapes the data passed to + it, regardless of type. Most of the time you'll use the above + function rather than this one. Use the function like this: + :: + + $sql = "INSERT INTO table (title) VALUES('".$this->db->escape_str($title)."')"; + +#. **$this->db->escape_like_str()** This method should be used when + strings are to be used in LIKE conditions so that LIKE wildcards + ('%', '\_') in the string are also properly escaped. + +:: + + $search = '20% raise'; $sql = "SELECT id FROM table WHERE column LIKE '%".$this->db->escape_like_str($search)."%'"; + + +************** +Query Bindings +************** + +Bindings enable you to simplify your query syntax by letting the system +put the queries together for you. Consider the following example:: + + $sql = "SELECT * FROM some_table WHERE id = ? AND status = ? AND author = ?"; $this->db->query($sql, array(3, 'live', 'Rick')); + +The question marks in the query are automatically replaced with the +values in the array in the second parameter of the query function. + +The secondary benefit of using binds is that the values are +automatically escaped, producing safer queries. You don't have to +remember to manually escape data; the engine does it automatically for +you. diff --git a/user_guide_src/source/database/results.rst b/user_guide_src/source/database/results.rst new file mode 100644 index 000000000..a85b89bef --- /dev/null +++ b/user_guide_src/source/database/results.rst @@ -0,0 +1,124 @@ +######################## +Generating Query Results +######################## + +There are several ways to generate query results: + +result() +======== + +This function returns the query result as an array of **objects**, or +**an empty array** on failure. Typically you'll use this in a foreach +loop, like this:: + + $query = $this->db->query("YOUR QUERY"); foreach ($query->result() as $row) {    echo $row->title;    echo $row->name;    echo $row->body; } + +The above function is an alias of result_object(). + +If you run queries that might **not** produce a result, you are +encouraged to test the result first:: + + $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;    } } + +You can also pass a string to result() which represents a class to +instantiate for each result object (note: this class must be loaded) + +:: + + $query = $this->db->query("SELECT * FROM users;"); + + foreach ($query->result('User') as $user) + { + echo $user->name; // call attributes + echo $user->reverse_name(); // or methods defined on the 'User' class + } + +result_array() +=============== + +This function returns the query result as a pure array, or an empty +array when no result is produced. Typically you'll use this in a foreach +loop, like this:: + + $query = $this->db->query("YOUR QUERY"); foreach ($query->result_array() as $row) {    echo $row['title'];    echo $row['name'];    echo $row['body']; } + +row() +===== + +This function returns a single result row. If your query has more than +one row, it returns only the first row. The result is returned as an +**object**. Here's a usage example:: + + $query = $this->db->query("YOUR QUERY"); if ($query->num_rows() > 0) {    $row = $query->row();    echo $row->title;    echo $row->name;    echo $row->body; } + +If you want a specific row returned you can submit the row number as a +digit in the first parameter:: + + $row = $query->row(5); + +You can also add a second String parameter, which is the name of a class +to instantiate the row with:: + + $query = $this->db->query("SELECT * FROM users LIMIT 1;"); $query->row(0, 'User') echo $row->name; // call attributes echo $row->reverse_name(); // or methods defined on the 'User' class + +row_array() +============ + +Identical to the above row() function, except it returns an array. +Example:: + + $query = $this->db->query("YOUR QUERY"); if ($query->num_rows() > 0) {    $row = $query->row_array();    echo $row['title'];    echo $row['name'];    echo $row['body']; } + +If you want a specific row returned you can submit the row number as a +digit in the first parameter:: + + $row = $query->row_array(5); + +In addition, you can walk forward/backwards/first/last through your +results using these variations: + +**$row = $query->first_row()** + **$row = $query->last_row()** + **$row = $query->next_row()** + **$row = $query->previous_row()** + +By default they return an object unless you put the word "array" in the +parameter: + +**$row = $query->first_row('array')** + **$row = $query->last_row('array')** + **$row = $query->next_row('array')** + **$row = $query->previous_row('array')** + +*********************** +Result Helper Functions +*********************** + +$query->num_rows() +=================== + +The number of rows returned by the query. Note: In this example, $query +is the variable that the query result object is assigned to:: + + $query = $this->db->query('SELECT * FROM my_table'); echo $query->num_rows(); + +$query->num_fields() +===================== + +The number of FIELDS (columns) returned by the query. Make sure to call +the function using your query result object:: + + $query = $this->db->query('SELECT * FROM my_table'); echo $query->num_fields(); + +$query->free_result() +====================== + +It frees the memory associated with the result and deletes the result +resource ID. Normally PHP frees its memory automatically at the end of +script execution. However, if you are running a lot of queries in a +particular script you might want to free the result after each query +result has been generated in order to cut down on memory consumptions. +Example:: + + $query = $this->db->query('SELECT title FROM my_table'); foreach ($query->result() as $row) {    echo $row->title; } $query->free_result(); // The $query result object will no longer be available $query2 = $this->db->query('SELECT name FROM some_table'); $row = $query2->row(); echo $row->name; $query2->free_result(); // The $query2 result object will no longer be available + diff --git a/user_guide_src/source/database/table_data.rst b/user_guide_src/source/database/table_data.rst new file mode 100644 index 000000000..ec7dbbf6c --- /dev/null +++ b/user_guide_src/source/database/table_data.rst @@ -0,0 +1,24 @@ +########## +Table Data +########## + +These functions let you fetch table information. + +$this->db->list_tables(); +========================== + +Returns an array containing the names of all the tables in the database +you are currently connected to. Example:: + + $tables = $this->db->list_tables(); foreach ($tables as $table) {    echo $table; } + +$this->db->table_exists(); +=========================== + +Sometimes it's helpful to know whether a particular table exists before +running an operation on it. Returns a boolean TRUE/FALSE. Usage example:: + + if ($this->db->table_exists('table_name')) {    // some code... } + +Note: Replace *table_name* with the name of the table you are looking +for. diff --git a/user_guide_src/source/database/transactions.rst b/user_guide_src/source/database/transactions.rst new file mode 100644 index 000000000..e82210b96 --- /dev/null +++ b/user_guide_src/source/database/transactions.rst @@ -0,0 +1,96 @@ +############ +Transactions +############ + +CodeIgniter's database abstraction allows you to use transactions with +databases that support transaction-safe table types. In MySQL, you'll +need to be running InnoDB or BDB table types rather than the more common +MyISAM. Most other database platforms support transactions natively. + +If you are not familiar with transactions we recommend you find a good +online resource to learn about them for your particular database. The +information below assumes you have a basic understanding of +transactions. + +CodeIgniter's Approach to Transactions +====================================== + +CodeIgniter utilizes an approach to transactions that is very similar to +the process used by the popular database class ADODB. We've chosen that +approach because it greatly simplifies the process of running +transactions. In most cases all that is required are two lines of code. + +Traditionally, transactions have required a fair amount of work to +implement since they demand that you to keep track of your queries and +determine whether to commit or rollback based on the success or failure +of your queries. This is particularly cumbersome with nested queries. In +contrast, we've implemented a smart transaction system that does all +this for you automatically (you can also manage your transactions +manually if you choose to, but there's really no benefit). + +Running Transactions +==================== + +To run your queries using transactions you will use the +$this->db->trans_start() and $this->db->trans_complete() functions as +follows:: + + $this->db->trans_start(); $this->db->query('AN SQL QUERY...'); $this->db->query('ANOTHER QUERY...'); $this->db->query('AND YET ANOTHER QUERY...'); $this->db->trans_complete(); + +You can run as many queries as you want between the start/complete +functions and they will all be committed or rolled back based on success +or failure of any given query. + +Strict Mode +=========== + +By default CodeIgniter runs all transactions in Strict Mode. When strict +mode is enabled, if you are running multiple groups of transactions, if +one group fails all groups will be rolled back. If strict mode is +disabled, each group is treated independently, meaning a failure of one +group will not affect any others. + +Strict Mode can be disabled as follows:: + + $this->db->trans_strict(FALSE); + +Managing Errors +=============== + +If you have error reporting enabled in your config/database.php file +you'll see a standard error message if the commit was unsuccessful. If +debugging is turned off, you can manage your own errors like this:: + + $this->db->trans_start(); $this->db->query('AN SQL QUERY...'); $this->db->query('ANOTHER QUERY...'); $this->db->trans_complete(); if ($this->db->trans_status() === FALSE) {     // generate an error... or use the log_message() function to log your error } + +Enabling 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():: + + $this->db->trans_off() $this->db->trans_start(); $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. + +Test Mode +========= + +You can optionally put the transaction system into "test mode", which +will cause your queries to be rolled back -- even if the queries produce +a valid result. To use test mode simply set the first parameter in the +$this->db->trans_start() function to TRUE:: + + $this->db->trans_start(TRUE); // Query will be rolled back $this->db->query('AN SQL QUERY...'); $this->db->trans_complete(); + +Running Transactions Manually +============================= + +If you would like to run transactions manually you can do so as follows:: + + $this->db->trans_begin(); $this->db->query('AN SQL QUERY...'); $this->db->query('ANOTHER QUERY...'); $this->db->query('AND YET ANOTHER QUERY...'); if ($this->db->trans_status() === FALSE) {     $this->db->trans_rollback(); } else {     $this->db->trans_commit(); } + +.. note:: Make sure to use $this->db->trans_begin() when running manual + transactions, **NOT** $this->db->trans_start(). 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') 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 3eed88c91c5605e51548494f1a4cd005196282f6 Mon Sep 17 00:00:00 2001 From: purwandi Date: Fri, 7 Oct 2011 09:47:21 +0700 Subject: Fix Database Configuration on User Guider --- user_guide_src/source/database/configuration.rst | 119 +++++++++++++---------- 1 file changed, 69 insertions(+), 50 deletions(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/configuration.rst b/user_guide_src/source/database/configuration.rst index 77b4994a3..da9cfa2fb 100644 --- a/user_guide_src/source/database/configuration.rst +++ b/user_guide_src/source/database/configuration.rst @@ -12,7 +12,21 @@ it the respective environment config folder. The config settings are stored in a multi-dimensional array with this prototype:: - $db['default']['hostname'] = "localhost"; $db['default']['username'] = "root"; $db['default']['password'] = ""; $db['default']['database'] = "database_name"; $db['default']['dbdriver'] = "mysql"; $db['default']['dbprefix'] = ""; $db['default']['pconnect'] = TRUE; $db['default']['db_debug'] = FALSE; $db['default']['cache_on'] = FALSE; $db['default']['cachedir'] = ""; $db['default']['char_set'] = "utf8"; $db['default']['dbcollat'] = "utf8_general_ci"; $db['default']['swap_pre'] = ""; $db['default']['autoinit'] = TRUE; $db['default']['stricton'] = FALSE; + $db['default']['hostname'] = "localhost"; + $db['default']['username'] = "root"; + $db['default']['password'] = ""; + $db['default']['database'] = "database_name"; + $db['default']['dbdriver'] = "mysql"; + $db['default']['dbprefix'] = ""; + $db['default']['pconnect'] = TRUE; + $db['default']['db_debug'] = FALSE; + $db['default']['cache_on'] = FALSE; + $db['default']['cachedir'] = ""; + $db['default']['char_set'] = "utf8"; + $db['default']['dbcollat'] = "utf8_general_ci"; + $db['default']['swap_pre'] = ""; + $db['default']['autoinit'] = TRUE; + $db['default']['stricton'] = FALSE; The reason we use a multi-dimensional array rather than a more simple one is to permit you to optionally store multiple sets of connection @@ -21,7 +35,21 @@ production, test, etc.) under a single installation, you can set up a connection group for each, then switch between groups as needed. For example, to set up a "test" environment you would do this:: - $db['test']['hostname'] = "localhost"; $db['test']['username'] = "root"; $db['test']['password'] = ""; $db['test']['database'] = "database_name"; $db['test']['dbdriver'] = "mysql"; $db['test']['dbprefix'] = ""; $db['test']['pconnect'] = TRUE; $db['test']['db_debug'] = FALSE; $db['test']['cache_on'] = FALSE; $db['test']['cachedir'] = ""; $db['test']['char_set'] = "utf8"; $db['test']['dbcollat'] = "utf8_general_ci"; $db['test']['swap_pre'] = ""; $db['test']['autoinit'] = TRUE; $db['test']['stricton'] = FALSE; + $db['test']['hostname'] = "localhost"; + $db['test']['username'] = "root"; + $db['test']['password'] = ""; + $db['test']['database'] = "database_name"; + $db['test']['dbdriver'] = "mysql"; + $db['test']['dbprefix'] = ""; + $db['test']['pconnect'] = TRUE; + $db['test']['db_debug'] = FALSE; + $db['test']['cache_on'] = FALSE; + $db['test']['cachedir'] = ""; + $db['test']['char_set'] = "utf8"; + $db['test']['dbcollat'] = "utf8_general_ci"; + $db['test']['swap_pre'] = ""; + $db['test']['autoinit'] = TRUE; + $db['test']['stricton'] = FALSE; Then, to globally tell the system to use that group you would set this variable located in the config file:: @@ -51,54 +79,45 @@ when the database classes are initialized. Explanation of Values: ---------------------- -- **hostname** - The hostname of your database server. Often this is - "localhost". -- **username** - The username used to connect to the database. -- **password** - The password used to connect to the database. -- **database** - The name of the database you want to connect to. -- **dbdriver** - The database type. ie: mysql, postgres, odbc, etc. - Must be specified in lower case. -- **dbprefix** - An optional table prefix which will added to the table - name when running :doc:`Active Record ` queries. This - permits multiple CodeIgniter installations to share one database. -- **pconnect** - TRUE/FALSE (boolean) - Whether to use a persistent - connection. -- **db_debug** - TRUE/FALSE (boolean) - Whether database errors should - be displayed. -- **cache_on** - TRUE/FALSE (boolean) - Whether database query caching - is enabled, see also :doc:`Database Caching Class `. -- **cachedir** - The absolute server path to your database query cache - directory. -- **char_set** - The character set used in communicating with the - database. -- **dbcollat** - The character collation used in communicating with the - database. - -.. note:: For MySQL and MySQLi databases, this setting is only used - as a backup if your server is running PHP < 5.2.3 or MySQL < 5.0.7 - (and in table creation queries made with DB Forge). There is an - incompatibility in PHP with mysql_real_escape_string() which can - make your site vulnerable to SQL injection if you are using a - multi-byte character set and are running versions lower than these. - Sites using Latin-1 or UTF-8 database character set and collation are - unaffected. - -- **swap_pre** - A default table prefix that should be swapped with - dbprefix. This is useful for distributed applications where you might - run manually written queries, and need the prefix to still be - customizable by the end user. -- **autoinit** - Whether or not to automatically connect to the - database when the library loads. If set to false, the connection will - take place prior to executing the first query. -- **stricton** - TRUE/FALSE (boolean) - Whether to force "Strict Mode" - connections, good for ensuring strict SQL while developing an - application. -- **port** - The database port number. To use this value you have to - add a line to the database config - array.:: - - $db['default']['port'] = 5432; - +====================== ================================================================================================== + Name Config Description +====================== ================================================================================================== +**hostname** The hostname of your database server. Often this is "localhost". +**username** The username used to connect to the database. +**password** The password used to connect to the database. +**database** The name of the database you want to connect to. +**dbdriver** The database type. ie: mysql, postgres, odbc, etc. Must be specified in lower case. +**dbprefix** An optional table prefix which will added to the table name when running :doc: + `Active Record ` queries. This permits multiple CodeIgniter installations + to share one database. +**pconnect** TRUE/FALSE (boolean) - Whether to use a persistent connection. +**db_debug** TRUE/FALSE (boolean) - Whether database errors should be displayed. +**cache_on** TRUE/FALSE (boolean) - Whether database query caching is enabled, + see also :doc:`Database Caching Class `. +**cachedir** The absolute server path to your database query cache directory. +**char_set** The character set used in communicating with the database. +**dbcollat** The character collation used in communicating with the database + + .. note:: For MySQL and MySQLi databases, this setting is only used + as a backup if your server is running PHP < 5.2.3 or MySQL < 5.0.7 + (and in table creation queries made with DB Forge). There is an + incompatibility in PHP with mysql_real_escape_string() which can + make your site vulnerable to SQL injection if you are using a + multi-byte character set and are running versions lower than these. + Sites using Latin-1 or UTF-8 database character set and collation are + unaffected. + +**swap_pre** A default table prefix that should be swapped with dbprefix. This is useful for distributed + applications where you might run manually written queries, and need the prefix to still be + customizable by the end user. +**autoinit** Whether or not to automatically connect to the database when the library loads. If set to false, + the connection will take place prior to executing the first query. +**stricton** TRUE/FALSE (boolean) - Whether to force "Strict Mode" connections, good for ensuring strict SQL + while developing an application. +**port** The database port number. To use this value you have to add a line to the database config + :: + $db['default']['port'] = 5432; +====================== ================================================================================================== .. note:: Depending on what database platform you are using (MySQL, Postgres, etc.) not all values will be needed. For example, when using -- cgit v1.2.3-24-g4f1b From abb456abf0108fd429960a2c547df3385bc27b18 Mon Sep 17 00:00:00 2001 From: purwandi Date: Fri, 7 Oct 2011 09:52:46 +0700 Subject: Adding "array" on Database Configuration --- user_guide_src/source/database/configuration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/configuration.rst b/user_guide_src/source/database/configuration.rst index da9cfa2fb..687f0d920 100644 --- a/user_guide_src/source/database/configuration.rst +++ b/user_guide_src/source/database/configuration.rst @@ -114,7 +114,7 @@ Explanation of Values: the connection will take place prior to executing the first query. **stricton** TRUE/FALSE (boolean) - Whether to force "Strict Mode" connections, good for ensuring strict SQL while developing an application. -**port** The database port number. To use this value you have to add a line to the database config +**port** The database port number. To use this value you have to add a line to the database config array. :: $db['default']['port'] = 5432; ====================== ================================================================================================== -- 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/caching.rst | 12 ++- user_guide_src/source/database/call_function.rst | 5 +- user_guide_src/source/database/configuration.rst | 36 ++++----- user_guide_src/source/database/connecting.rst | 27 +++---- user_guide_src/source/database/examples.rst | 58 ++++++++++++-- user_guide_src/source/database/fields.rst | 43 ++++++++--- user_guide_src/source/database/forge.rst | 88 ++++++++++++++++++---- user_guide_src/source/database/helpers.rst | 22 ++++-- user_guide_src/source/database/queries.rst | 6 +- user_guide_src/source/database/results.rst | 96 +++++++++++++++++++----- user_guide_src/source/database/table_data.rst | 15 +++- user_guide_src/source/database/transactions.rst | 41 ++++++++-- user_guide_src/source/database/utilities.rst | 74 +++++++++++++++--- 13 files changed, 412 insertions(+), 111 deletions(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/caching.rst b/user_guide_src/source/database/caching.rst index 7a195a7a1..d73120a93 100644 --- a/user_guide_src/source/database/caching.rst +++ b/user_guide_src/source/database/caching.rst @@ -124,7 +124,17 @@ $this->db->cache_on() / $this->db->cache_off() Manually enables/disables caching. This can be useful if you want to keep certain queries from being cached. Example:: - // Turn caching on $this->db->cache_on(); $query = $this->db->query("SELECT * FROM mytable"); // Turn caching off for this one query $this->db->cache_off(); $query = $this->db->query("SELECT * FROM members WHERE member_id = '$current_user'"); // Turn caching back on $this->db->cache_on(); $query = $this->db->query("SELECT * FROM another_table"); + // Turn caching on + $this->db->cache_on(); + $query = $this->db->query("SELECT * FROM mytable"); + + // Turn caching off for this one query + $this->db->cache_off(); + $query = $this->db->query("SELECT * FROM members WHERE member_id = '$current_user'"); + + // Turn caching back on + $this->db->cache_on(); + $query = $this->db->query("SELECT * FROM another_table"); $this->db->cache_delete() ========================== diff --git a/user_guide_src/source/database/call_function.rst b/user_guide_src/source/database/call_function.rst index bdc5be0a5..9890fc453 100644 --- a/user_guide_src/source/database/call_function.rst +++ b/user_guide_src/source/database/call_function.rst @@ -34,5 +34,6 @@ database result ID. The connection ID can be accessed using:: The result ID can be accessed from within your result object, like this:: - $query = $this->db->query("SOME QUERY"); $query->result_id; - + $query = $this->db->query("SOME QUERY"); + + $query->result_id; \ No newline at end of file diff --git a/user_guide_src/source/database/configuration.rst b/user_guide_src/source/database/configuration.rst index 77b4994a3..c2c5a33ab 100644 --- a/user_guide_src/source/database/configuration.rst +++ b/user_guide_src/source/database/configuration.rst @@ -51,27 +51,27 @@ when the database classes are initialized. Explanation of Values: ---------------------- -- **hostname** - The hostname of your database server. Often this is +- **hostname** - The hostname of your database server. Often this is "localhost". -- **username** - The username used to connect to the database. -- **password** - The password used to connect to the database. -- **database** - The name of the database you want to connect to. -- **dbdriver** - The database type. ie: mysql, postgres, odbc, etc. +- **username** - The username used to connect to the database. +- **password** - The password used to connect to the database. +- **database** - The name of the database you want to connect to. +- **dbdriver** - The database type. ie: mysql, postgres, odbc, etc. Must be specified in lower case. -- **dbprefix** - An optional table prefix which will added to the table +- **dbprefix** - An optional table prefix which will added to the table name when running :doc:`Active Record ` queries. This permits multiple CodeIgniter installations to share one database. -- **pconnect** - TRUE/FALSE (boolean) - Whether to use a persistent +- **pconnect** - TRUE/FALSE (boolean) - Whether to use a persistent connection. -- **db_debug** - TRUE/FALSE (boolean) - Whether database errors should +- **db_debug** - TRUE/FALSE (boolean) - Whether database errors should be displayed. -- **cache_on** - TRUE/FALSE (boolean) - Whether database query caching +- **cache_on** - TRUE/FALSE (boolean) - Whether database query caching is enabled, see also :doc:`Database Caching Class `. -- **cachedir** - The absolute server path to your database query cache +- **cachedir** - The absolute server path to your database query cache directory. -- **char_set** - The character set used in communicating with the +- **char_set** - The character set used in communicating with the database. -- **dbcollat** - The character collation used in communicating with the +- **dbcollat** - The character collation used in communicating with the database. .. note:: For MySQL and MySQLi databases, this setting is only used @@ -83,19 +83,21 @@ Explanation of Values: Sites using Latin-1 or UTF-8 database character set and collation are unaffected. -- **swap_pre** - A default table prefix that should be swapped with +- **swap_pre** - A default table prefix that should be swapped with dbprefix. This is useful for distributed applications where you might run manually written queries, and need the prefix to still be customizable by the end user. -- **autoinit** - Whether or not to automatically connect to the +- **autoinit** - Whether or not to automatically connect to the database when the library loads. If set to false, the connection will take place prior to executing the first query. -- **stricton** - TRUE/FALSE (boolean) - Whether to force "Strict Mode" +- **stricton** - TRUE/FALSE (boolean) - Whether to force "Strict Mode" connections, good for ensuring strict SQL while developing an application. -- **port** - The database port number. To use this value you have to +- **port** - The database port number. To use this value you have to add a line to the database config - array.:: + array. + +:: $db['default']['port'] = 5432; diff --git a/user_guide_src/source/database/connecting.rst b/user_guide_src/source/database/connecting.rst index 6c549434d..64adc3047 100644 --- a/user_guide_src/source/database/connecting.rst +++ b/user_guide_src/source/database/connecting.rst @@ -92,19 +92,20 @@ as indicated above). By setting the second parameter to TRUE (boolean) the function will return the database object. -When you connect this way, you will use your object name to issue -commands rather than the syntax used throughout this guide. In other -words, rather than issuing commands with: - -$this->db->query(); -$this->db->result(); -etc... - -You will instead use: - -$DB1->query(); -$DB1->result(); -etc... +.. note:: When you connect this way, you will use your object name to issue + commands rather than the syntax used throughout this guide. In other + words, rather than issuing commands with: + + | + | $this->db->query(); + | $this->db->result(); + | etc... + | + | You will instead use: + | + | $DB1->query(); + | $DB1->result(); + | etc... Reconnecting / Keeping the Connection Alive =========================================== diff --git a/user_guide_src/source/database/examples.rst b/user_guide_src/source/database/examples.rst index bd2cc4d96..d1cd48837 100644 --- a/user_guide_src/source/database/examples.rst +++ b/user_guide_src/source/database/examples.rst @@ -24,7 +24,16 @@ Standard Query With Multiple Results (Object Version) :: - $query = $this->db->query('SELECT name, title, email FROM my_table'); foreach ($query->result() as $row) {     echo $row->title;     echo $row->name;     echo $row->email; } echo 'Total Results: ' . $query->num_rows(); + $query = $this->db->query('SELECT name, title, email FROM my_table'); + + foreach ($query->result() as $row) + { + echo $row->title; + echo $row->name; + echo $row->email; + } + + echo 'Total Results: ' . $query->num_rows(); The above result() function returns an array of **objects**. Example: $row->title @@ -34,7 +43,14 @@ Standard Query With Multiple Results (Array Version) :: - $query = $this->db->query('SELECT name, title, email FROM my_table'); foreach ($query->result_array() as $row) {     echo $row['title'];     echo $row['name'];     echo $row['email']; } + $query = $this->db->query('SELECT name, title, email FROM my_table'); + + foreach ($query->result_array() as $row) + { + echo $row['title']; + echo $row['name']; + echo $row['email']; + } The above result_array() function returns an array of standard array indexes. Example: $row['title'] @@ -45,14 +61,25 @@ 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;    } } + $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 ================================= :: - $query = $this->db->query('SELECT name FROM my_table LIMIT 1'); $row = $query->row(); echo $row->name; + $query = $this->db->query('SELECT name FROM my_table LIMIT 1'); + $row = $query->row(); + echo $row->name; The above row() function returns an **object**. Example: $row->name @@ -61,7 +88,9 @@ Standard Query With Single Result (Array version) :: - $query = $this->db->query('SELECT name FROM my_table LIMIT 1'); $row = $query->row_array(); echo $row['name']; + $query = $this->db->query('SELECT name FROM my_table LIMIT 1'); + $row = $query->row_array(); + echo $row['name']; The above row_array() function returns an **array**. Example: $row['name'] @@ -71,7 +100,9 @@ Standard Insert :: - $sql = "INSERT INTO mytable (title, name)         VALUES (".$this->db->escape($title).", ".$this->db->escape($name).")"; $this->db->query($sql); echo $this->db->affected_rows(); + $sql = "INSERT INTO mytable (title, name) VALUES (".$this->db->escape($title).", ".$this->db->escape($name).")"; + $this->db->query($sql); + echo $this->db->affected_rows(); Active Record Query =================== @@ -79,7 +110,12 @@ Active Record Query The :doc:`Active Record Pattern ` gives you a simplified means of retrieving data:: - $query = $this->db->get('table_name'); foreach ($query->result() as $row) {     echo $row->title; } + $query = $this->db->get('table_name'); + + foreach ($query->result() as $row) + { + echo $row->title; + } The above get() function retrieves all the results from the supplied table. The :doc:`Active Record ` class contains a full @@ -90,5 +126,11 @@ Active Record Insert :: - $data = array(                'title' => $title,                'name' => $name,                'date' => $date             ); $this->db->insert('mytable', $data); // Produces: INSERT INTO mytable (title, name, date) VALUES ('{$title}', '{$name}', '{$date}') + $data = array( + 'title' => $title, + 'name' => $name, + 'date' => $date + ); + + $this->db->insert('mytable', $data); // Produces: INSERT INTO mytable (title, name, date) VALUES ('{$title}', '{$name}', '{$date}') diff --git a/user_guide_src/source/database/fields.rst b/user_guide_src/source/database/fields.rst index 07730f5d3..b706ace7d 100644 --- a/user_guide_src/source/database/fields.rst +++ b/user_guide_src/source/database/fields.rst @@ -11,12 +11,22 @@ two ways: 1. You can supply the table name and call it from the $this->db-> object:: - $fields = $this->db->list_fields('table_name'); foreach ($fields as $field) {    echo $field; } + $fields = $this->db->list_fields('table_name'); + + foreach ($fields as $field) + { + echo $field; + } 2. You can gather the field names associated with any query you run by calling the function from your query result object:: - $query = $this->db->query('SELECT * FROM some_table'); foreach ($query->list_fields() as $field) {    echo $field; } + $query = $this->db->query('SELECT * FROM some_table'); + + foreach ($query->list_fields() as $field) + { + echo $field; + } $this->db->field_exists() ========================== @@ -24,11 +34,14 @@ $this->db->field_exists() Sometimes it's helpful to know whether a particular field exists before performing an action. Returns a boolean TRUE/FALSE. Usage example:: - if ($this->db->field_exists('field_name', 'table_name')) {    // some code... } + if ($this->db->field_exists('field_name', 'table_name')) + { + // some code... + } -Note: Replace *field_name* with the name of the column you are looking -for, and replace *table_name* with the name of the table you are -looking for. +.. note:: Replace *field_name* with the name of the column you are looking + for, and replace *table_name* with the name of the table you are + looking for. $this->db->field_data() ======================== @@ -38,16 +51,25 @@ Returns an array of objects containing field information. Sometimes it's helpful to gather the field names or other metadata, like the column type, max length, etc. -Note: Not all databases provide meta-data. +.. note:: Not all databases provide meta-data. Usage example:: - $fields = $this->db->field_data('table_name'); foreach ($fields as $field) {    echo $field->name;    echo $field->type;    echo $field->max_length;    echo $field->primary_key; } + $fields = $this->db->field_data('table_name'); + + foreach ($fields as $field) + { + echo $field->name; + echo $field->type; + echo $field->max_length; + echo $field->primary_key; + } If you have run a query already you can use the result object instead of supplying the table name:: - $query = $this->db->query("YOUR QUERY"); $fields = $query->field_data(); + $query = $this->db->query("YOUR QUERY"); + $fields = $query->field_data(); The following data is available from this function if supported by your database: @@ -55,5 +77,4 @@ database: - name - column name - max_length - maximum length of the column - primary_key - 1 if the column is a primary key -- type - the type of the column - +- type - the type of the column \ No newline at end of file diff --git a/user_guide_src/source/database/forge.rst b/user_guide_src/source/database/forge.rst index ee033248c..bf17e2918 100644 --- a/user_guide_src/source/database/forge.rst +++ b/user_guide_src/source/database/forge.rst @@ -29,7 +29,10 @@ $this->dbforge->create_database('db_name') Permits you to create the database specified in the first parameter. Returns TRUE/FALSE based on success or failure:: - if ($this->dbforge->create_database('my_db')) {     echo 'Database created!'; } + if ($this->dbforge->create_database('my_db')) + { + echo 'Database created!'; + } $this->dbforge->drop_database('db_name') ========================================== @@ -37,7 +40,10 @@ $this->dbforge->drop_database('db_name') Permits you to drop the database specified in the first parameter. Returns TRUE/FALSE based on success or failure:: - if ($this->dbforge->drop_database('my_db')) {     echo 'Database deleted!'; } + if ($this->dbforge->drop_database('my_db')) + { + echo 'Database deleted!'; + } **************************** Creating and Dropping Tables @@ -57,7 +63,13 @@ also require a 'constraint' key. :: - $fields = array(                         'users' => array(                                                  'type' => 'VARCHAR',                                                  'constraint' => '100',                                           ),                 ); // will translate to "users VARCHAR(100)" when the field is added. + $fields = array( + 'users' => array( + 'type' => 'VARCHAR', + 'constraint' => '100', + ), + ); + // will translate to "users VARCHAR(100)" when the field is added. Additionally, the following key/values can be used: @@ -72,7 +84,27 @@ Additionally, the following key/values can be used: :: - $fields = array(                         'blog_id' => array(                                                  'type' => 'INT',                                                  'constraint' => 5,                                                  'unsigned' => TRUE,                                                  'auto_increment' => TRUE                                           ),                         'blog_title' => array(                                                  'type' => 'VARCHAR',                                                  'constraint' => '100',                                           ),                         'blog_author' => array(                                                  'type' =>'VARCHAR',                                                  'constraint' => '100',                                                  'default' => 'King of Town',                                           ),                         'blog_description' => array(                                                  'type' => 'TEXT',                                                  'null' => TRUE,                                           ),                 ); + $fields = array( + 'blog_id' => array( + 'type' => 'INT', + 'constraint' => 5, + 'unsigned' => TRUE, + 'auto_increment' => TRUE + ), + 'blog_title' => array( + 'type' => 'VARCHAR', + 'constraint' => '100', + ), + 'blog_author' => array( + 'type' =>'VARCHAR', + 'constraint' => '100', + 'default' => 'King of Town', + ), + 'blog_description' => array( + 'type' => 'TEXT', + 'null' => TRUE, + ), + ); After the fields have been defined, they can be added using @@ -95,7 +127,7 @@ string into the field definitions with add_field() $this->dbforge->add_field("label varchar(100) NOT NULL DEFAULT 'default label'"); -Note: Multiple calls to add_field() are cumulative. +.. note:: Multiple calls to add_field() are cumulative. Creating an id field -------------------- @@ -106,7 +138,8 @@ Primary Key. :: - $this->dbforge->add_field('id'); // gives id INT(9) NOT NULL AUTO_INCREMENT + $this->dbforge->add_field('id'); + // gives id INT(9) NOT NULL AUTO_INCREMENT Adding Keys @@ -122,7 +155,18 @@ 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`) + $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`) Creating a table @@ -133,7 +177,8 @@ with :: - $this->dbforge->create_table('table_name'); // gives CREATE TABLE table_name + $this->dbforge->create_table('table_name'); + // gives CREATE TABLE table_name An optional second parameter set to TRUE adds an "IF NOT EXISTS" clause @@ -141,7 +186,8 @@ into the definition :: - $this->dbforge->create_table('table_name', TRUE); // gives CREATE TABLE IF NOT EXISTS table_name + $this->dbforge->create_table('table_name', TRUE); + // gives CREATE TABLE IF NOT EXISTS table_name Dropping a table @@ -151,7 +197,8 @@ Executes a DROP TABLE sql :: - $this->dbforge->drop_table('table_name'); // gives DROP TABLE IF EXISTS table_name + $this->dbforge->drop_table('table_name'); + // gives DROP TABLE IF EXISTS table_name Renaming a table @@ -161,7 +208,8 @@ Executes a TABLE rename :: - $this->dbforge->rename_table('old_table_name', 'new_table_name'); // gives ALTER TABLE old_table_name RENAME TO new_table_name + $this->dbforge->rename_table('old_table_name', 'new_table_name'); + // gives ALTER TABLE old_table_name RENAME TO new_table_name **************** @@ -177,7 +225,11 @@ number of additional fields. :: - $fields = array(                         'preferences' => array('type' => 'TEXT') ); $this->dbforge->add_column('table_name', $fields); // gives ALTER TABLE table_name ADD preferences TEXT + $fields = array( + 'preferences' => array('type' => 'TEXT') + ); + $this->dbforge->add_column('table_name', $fields); + // gives ALTER TABLE table_name ADD preferences TEXT An optional third parameter can be used to specify which existing column to add the new column after. @@ -206,7 +258,11 @@ change the name you can add a "name" key into the field defining array. :: - $fields = array(                         'old_name' => array(                                                          'name' => 'new_name',                                                          'type' => 'TEXT',                                                 ), ); $this->dbforge->modify_column('table_name', $fields); // gives ALTER TABLE table_name CHANGE old_name new_name TEXT - - - + $fields = array( + 'old_name' => array( + 'name' => 'new_name', + 'type' => 'TEXT', + ), + ); + $this->dbforge->modify_column('table_name', $fields); + // gives ALTER TABLE table_name CHANGE old_name new_name TEXT \ No newline at end of file diff --git a/user_guide_src/source/database/helpers.rst b/user_guide_src/source/database/helpers.rst index b0a5ce97b..7ea19e9f6 100644 --- a/user_guide_src/source/database/helpers.rst +++ b/user_guide_src/source/database/helpers.rst @@ -28,7 +28,9 @@ $this->db->count_all(); Permits you to determine the number of rows in a particular table. Submit the table name in the first parameter. Example:: - echo $this->db->count_all('my_table'); // Produces an integer, like 25 + echo $this->db->count_all('my_table'); + + // Produces an integer, like 25 $this->db->platform() ===================== @@ -51,7 +53,9 @@ $this->db->last_query(); Returns the last query that was run (the query string, not the result). Example:: - $str = $this->db->last_query(); // Produces: SELECT * FROM sometable.... + $str = $this->db->last_query(); + + // Produces: SELECT * FROM sometable.... The following two functions help simplify the process of writing database INSERTs and UPDATEs. @@ -62,14 +66,16 @@ $this->db->insert_string(); This function simplifies the process of writing database inserts. It returns a correctly formatted SQL insert string. Example:: - $data = array('name' => $name, 'email' => $email, 'url' => $url); $str = $this->db->insert_string('table_name', $data); + $data = array('name' => $name, 'email' => $email, 'url' => $url); + + $str = $this->db->insert_string('table_name', $data); The first parameter is the table name, the second is an associative array with the data to be inserted. The above example produces:: INSERT INTO table_name (name, email, url) VALUES ('Rick', 'rick@example.com', 'example.com') -Note: Values are automatically escaped, producing safer queries. +.. note:: Values are automatically escaped, producing safer queries. $this->db->update_string(); ============================ @@ -77,7 +83,11 @@ $this->db->update_string(); This function simplifies the process of writing database updates. It returns a correctly formatted SQL update string. Example:: - $data = array('name' => $name, 'email' => $email, 'url' => $url); $where = "author_id = 1 AND status = 'active'"; $str = $this->db->update_string('table_name', $data, $where); + $data = array('name' => $name, 'email' => $email, 'url' => $url); + + $where = "author_id = 1 AND status = 'active'"; + + $str = $this->db->update_string('table_name', $data, $where); The first parameter is the table name, the second is an associative array with the data to be updated, and the third parameter is the @@ -85,4 +95,4 @@ array with the data to be updated, and the third parameter is the UPDATE table_name SET name = 'Rick', email = 'rick@example.com', url = 'example.com' WHERE author_id = 1 AND status = 'active' -Note: Values are automatically escaped, producing safer queries. +.. note:: Values are automatically escaped, producing safer queries. diff --git a/user_guide_src/source/database/queries.rst b/user_guide_src/source/database/queries.rst index cfc42c4c3..971d5d61d 100644 --- a/user_guide_src/source/database/queries.rst +++ b/user_guide_src/source/database/queries.rst @@ -41,7 +41,8 @@ the following:: If for any reason you would like to change the prefix programatically without needing to create a new connection, you can use this method:: - $this->db->set_dbprefix('newprefix'); $this->db->dbprefix('tablename'); // outputs newprefix_tablename + $this->db->set_dbprefix('newprefix'); + $this->db->dbprefix('tablename'); // outputs newprefix_tablename ********************** @@ -101,7 +102,8 @@ Query Bindings Bindings enable you to simplify your query syntax by letting the system put the queries together for you. Consider the following example:: - $sql = "SELECT * FROM some_table WHERE id = ? AND status = ? AND author = ?"; $this->db->query($sql, array(3, 'live', 'Rick')); + $sql = "SELECT * FROM some_table WHERE id = ? AND status = ? AND author = ?"; + $this->db->query($sql, array(3, 'live', 'Rick')); The question marks in the query are automatically replaced with the values in the array in the second parameter of the query function. diff --git a/user_guide_src/source/database/results.rst b/user_guide_src/source/database/results.rst index a85b89bef..4f93c794d 100644 --- a/user_guide_src/source/database/results.rst +++ b/user_guide_src/source/database/results.rst @@ -11,14 +11,31 @@ This function returns the query result as an array of **objects**, or **an empty array** on failure. Typically you'll use this in a foreach loop, like this:: - $query = $this->db->query("YOUR QUERY"); foreach ($query->result() as $row) {    echo $row->title;    echo $row->name;    echo $row->body; } + $query = $this->db->query("YOUR QUERY"); + + foreach ($query->result() as $row) + { + echo $row->title; + echo $row->name; + echo $row->body; + } The above function is an alias of result_object(). If you run queries that might **not** produce a result, you are encouraged to test the result first:: - $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;    } } + $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; + } + } You can also pass a string to result() which represents a class to instantiate for each result object (note: this class must be loaded) @@ -40,7 +57,14 @@ This function returns the query result as a pure array, or an empty array when no result is produced. Typically you'll use this in a foreach loop, like this:: - $query = $this->db->query("YOUR QUERY"); foreach ($query->result_array() as $row) {    echo $row['title'];    echo $row['name'];    echo $row['body']; } + $query = $this->db->query("YOUR QUERY"); + + foreach ($query->result_array() as $row) + { + echo $row['title']; + echo $row['name']; + echo $row['body']; + } row() ===== @@ -49,7 +73,16 @@ This function returns a single result row. If your query has more than one row, it returns only the first row. The result is returned as an **object**. Here's a usage example:: - $query = $this->db->query("YOUR QUERY"); if ($query->num_rows() > 0) {    $row = $query->row();    echo $row->title;    echo $row->name;    echo $row->body; } + $query = $this->db->query("YOUR QUERY"); + + if ($query->num_rows() > 0) + { + $row = $query->row(); + + echo $row->title; + echo $row->name; + echo $row->body; + } If you want a specific row returned you can submit the row number as a digit in the first parameter:: @@ -59,7 +92,11 @@ digit in the first parameter:: You can also add a second String parameter, which is the name of a class to instantiate the row with:: - $query = $this->db->query("SELECT * FROM users LIMIT 1;"); $query->row(0, 'User') echo $row->name; // call attributes echo $row->reverse_name(); // or methods defined on the 'User' class + $query = $this->db->query("SELECT * FROM users LIMIT 1;"); + $query->row(0, 'User'); + + echo $row->name; // call attributes + echo $row->reverse_name(); // or methods defined on the 'User' class row_array() ============ @@ -67,7 +104,16 @@ row_array() Identical to the above row() function, except it returns an array. Example:: - $query = $this->db->query("YOUR QUERY"); if ($query->num_rows() > 0) {    $row = $query->row_array();    echo $row['title'];    echo $row['name'];    echo $row['body']; } + $query = $this->db->query("YOUR QUERY"); + + if ($query->num_rows() > 0) + { + $row = $query->row_array(); + + echo $row['title']; + echo $row['name']; + echo $row['body']; + } If you want a specific row returned you can submit the row number as a digit in the first parameter:: @@ -77,18 +123,18 @@ digit in the first parameter:: In addition, you can walk forward/backwards/first/last through your results using these variations: -**$row = $query->first_row()** - **$row = $query->last_row()** - **$row = $query->next_row()** - **$row = $query->previous_row()** + | **$row = $query->first_row()** + | **$row = $query->last_row()** + | **$row = $query->next_row()** + | **$row = $query->previous_row()** By default they return an object unless you put the word "array" in the parameter: -**$row = $query->first_row('array')** - **$row = $query->last_row('array')** - **$row = $query->next_row('array')** - **$row = $query->previous_row('array')** + | **$row = $query->first_row('array')** + | **$row = $query->last_row('array')** + | **$row = $query->next_row('array')** + | **$row = $query->previous_row('array')** *********************** Result Helper Functions @@ -100,7 +146,9 @@ $query->num_rows() The number of rows returned by the query. Note: In this example, $query is the variable that the query result object is assigned to:: - $query = $this->db->query('SELECT * FROM my_table'); echo $query->num_rows(); + $query = $this->db->query('SELECT * FROM my_table'); + + echo $query->num_rows(); $query->num_fields() ===================== @@ -108,7 +156,9 @@ $query->num_fields() The number of FIELDS (columns) returned by the query. Make sure to call the function using your query result object:: - $query = $this->db->query('SELECT * FROM my_table'); echo $query->num_fields(); + $query = $this->db->query('SELECT * FROM my_table'); + + echo $query->num_fields(); $query->free_result() ====================== @@ -120,5 +170,17 @@ particular script you might want to free the result after each query result has been generated in order to cut down on memory consumptions. Example:: - $query = $this->db->query('SELECT title FROM my_table'); foreach ($query->result() as $row) {    echo $row->title; } $query->free_result(); // The $query result object will no longer be available $query2 = $this->db->query('SELECT name FROM some_table'); $row = $query2->row(); echo $row->name; $query2->free_result(); // The $query2 result object will no longer be available + $query = $this->db->query('SELECT title FROM my_table'); + + foreach ($query->result() as $row) + { + echo $row->title; + } + $query->free_result(); // The $query result object will no longer be available + + $query2 = $this->db->query('SELECT name FROM some_table'); + + $row = $query2->row(); + echo $row->name; + $query2->free_result();// The $query2 result object will no longer be available diff --git a/user_guide_src/source/database/table_data.rst b/user_guide_src/source/database/table_data.rst index ec7dbbf6c..744a05154 100644 --- a/user_guide_src/source/database/table_data.rst +++ b/user_guide_src/source/database/table_data.rst @@ -10,7 +10,12 @@ $this->db->list_tables(); Returns an array containing the names of all the tables in the database you are currently connected to. Example:: - $tables = $this->db->list_tables(); foreach ($tables as $table) {    echo $table; } + $tables = $this->db->list_tables(); + + foreach ($tables as $table) + { + echo $table; + } $this->db->table_exists(); =========================== @@ -18,7 +23,9 @@ $this->db->table_exists(); Sometimes it's helpful to know whether a particular table exists before running an operation on it. Returns a boolean TRUE/FALSE. Usage example:: - if ($this->db->table_exists('table_name')) {    // some code... } + if ($this->db->table_exists('table_name')) + { + // some code... + } -Note: Replace *table_name* with the name of the table you are looking -for. +.. note:: Replace *table_name* with the name of the table you are looking for. diff --git a/user_guide_src/source/database/transactions.rst b/user_guide_src/source/database/transactions.rst index e82210b96..e9190e59a 100644 --- a/user_guide_src/source/database/transactions.rst +++ b/user_guide_src/source/database/transactions.rst @@ -35,7 +35,11 @@ To run your queries using transactions you will use the $this->db->trans_start() and $this->db->trans_complete() functions as follows:: - $this->db->trans_start(); $this->db->query('AN SQL QUERY...'); $this->db->query('ANOTHER QUERY...'); $this->db->query('AND YET ANOTHER QUERY...'); $this->db->trans_complete(); + $this->db->trans_start(); + $this->db->query('AN SQL QUERY...'); + $this->db->query('ANOTHER QUERY...'); + $this->db->query('AND YET ANOTHER QUERY...'); + $this->db->trans_complete(); You can run as many queries as you want between the start/complete functions and they will all be committed or rolled back based on success @@ -61,7 +65,15 @@ If you have error reporting enabled in your config/database.php file you'll see a standard error message if the commit was unsuccessful. If debugging is turned off, you can manage your own errors like this:: - $this->db->trans_start(); $this->db->query('AN SQL QUERY...'); $this->db->query('ANOTHER QUERY...'); $this->db->trans_complete(); if ($this->db->trans_status() === FALSE) {     // generate an error... or use the log_message() function to log your error } + $this->db->trans_start(); + $this->db->query('AN SQL QUERY...'); + $this->db->query('ANOTHER QUERY...'); + $this->db->trans_complete(); + + if ($this->db->trans_status() === FALSE) + { + // generate an error... or use the log_message() function to log your error + } Enabling Transactions ===================== @@ -70,7 +82,11 @@ 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():: - $this->db->trans_off() $this->db->trans_start(); $this->db->query('AN SQL QUERY...'); $this->db->trans_complete(); + $this->db->trans_off(); + + $this->db->trans_start(); + $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. @@ -83,14 +99,29 @@ will cause your queries to be rolled back -- even if the queries produce a valid result. To use test mode simply set the first parameter in the $this->db->trans_start() function to TRUE:: - $this->db->trans_start(TRUE); // Query will be rolled back $this->db->query('AN SQL QUERY...'); $this->db->trans_complete(); + $this->db->trans_start(TRUE); // Query will be rolled back + $this->db->query('AN SQL QUERY...'); + $this->db->trans_complete(); Running Transactions Manually ============================= If you would like to run transactions manually you can do so as follows:: - $this->db->trans_begin(); $this->db->query('AN SQL QUERY...'); $this->db->query('ANOTHER QUERY...'); $this->db->query('AND YET ANOTHER QUERY...'); if ($this->db->trans_status() === FALSE) {     $this->db->trans_rollback(); } else {     $this->db->trans_commit(); } + $this->db->trans_begin(); + + $this->db->query('AN SQL QUERY...'); + $this->db->query('ANOTHER QUERY...'); + $this->db->query('AND YET ANOTHER QUERY...'); + + if ($this->db->trans_status() === FALSE) + { + $this->db->trans_rollback(); + } + else + { + $this->db->trans_commit(); + } .. note:: Make sure to use $this->db->trans_begin() when running manual transactions, **NOT** $this->db->trans_start(). 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 619b122cc8c213df558838ce9cc1c157a85a65b6 Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Mon, 10 Oct 2011 16:26:27 -0500 Subject: incremental improvement to user guide ToC --- user_guide_src/source/database/index.rst | 32 ++++++++++++++------------------ 1 file changed, 14 insertions(+), 18 deletions(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/index.rst b/user_guide_src/source/database/index.rst index 3b59986be..ab12b7cb7 100644 --- a/user_guide_src/source/database/index.rst +++ b/user_guide_src/source/database/index.rst @@ -6,24 +6,20 @@ CodeIgniter comes with a full-featured and very fast abstracted database class that supports both traditional structures and Active Record patterns. The database functions offer clear, simple syntax. -- :doc:`Quick Start: Usage Examples ` -- :doc:`Database Configuration ` -- :doc:`Connecting to a Database ` -- :doc:`Running Queries ` -- :doc:`Generating Query Results ` -- :doc:`Query Helper Functions ` -- :doc:`Active Record Class ` -- :doc:`Transactions ` -- :doc:`Table MetaData ` -- :doc:`Field MetaData ` -- :doc:`Custom Function Calls ` -- :doc:`Query Caching ` -- :doc:`Database manipulation with Database Forge ` -- :doc:`Database Utilities Class ` - .. toctree:: - :glob: :titlesonly: - :hidden: - * \ No newline at end of file + Quick Start: Usage Examples + Database Configuration + Connecting to a Database + Running Queries + Generating Query Results + Query Helper Functions + Active Record Class + Transactions + Table MetaData + Field MetaData + Custom Function Calls + Query Caching + Database Manipulation with Database Forge + Database Utilities Class \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 48d8fb6e9b58776abc96761dbd18e543418df4d7 Mon Sep 17 00:00:00 2001 From: Kyle Farris Date: Fri, 14 Oct 2011 17:59:49 -0300 Subject: Updated to new documentation for new active record methods. --- user_guide_src/source/database/active_record.rst | 108 +++++++++++++++++++++++ 1 file changed, 108 insertions(+) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/active_record.rst b/user_guide_src/source/database/active_record.rst index e1fc00bc5..7230812de 100644 --- a/user_guide_src/source/database/active_record.rst +++ b/user_guide_src/source/database/active_record.rst @@ -54,6 +54,36 @@ $query, which can be used to show the results:: Please visit the :doc:`result functions ` page for a full discussion regarding result generation. +$this->db->get_compiled_select() +================================ + +Compiles the selection query just like `$this->db->get()`_ but does not *run* +the query. This method simply returns the SQL query as a string. + +Example:: + + $sql = $this->db->get_compiled_select('mytable'); + echo $sql; + + // Produces string: SELECT * FROM mytable + +The second parameter enables you to set whether or not the active record query +will be reset (by default it will be—just like `$this->db->get()`):: + + echo $this->db->limit(10,20)->get_compiled_select('mytable', FALSE); + // Produces string: SELECT * FROM mytable LIMIT 20, 10 + // (in MySQL. Other databases have slightly different syntax) + + echo $this->db->select('title, content, date')->get_compiled_select(); + + // Produces string: SELECT title, content, date FROM mytable + +The key thing to notice in the above example is that the second query did not +utlize `$this->db->from()`_ and did not pass a table name into the first +parameter. The reason for this outcome is because the query has not been +executed using `$this->db->get()`_ which resets values or reset directly +using `$this-db->reset_query()`_. + $this->db->get_where() ====================== @@ -540,6 +570,41 @@ object. .. note:: All values are escaped automatically producing safer queries. +$this->db->get_compiled_insert() +================================ +Compiles the insertion query just like `$this->db->insert()`_ but does not +*run* the query. This method simply returns the SQL query as a string. + +Example:: + + $data = array( + 'title' => 'My title', + 'name' => 'My Name', + 'date' => 'My date' + ); + + $sql = $this->db->set($data)->get_compiled_insert('mytable'); + echo $sql; + + // Produces string: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date') + +The second parameter enables you to set whether or not the active record query +will be reset (by default it will be--just like `$this->db->insert()`_):: + + echo $this->db->set('title', 'My Title')->get_compiled_insert('mytable', FALSE); + + // Produces string: INSERT INTO mytable (title) VALUES ('My Title') + + echo $this->db->set('content', 'My Content')->get_compiled_insert(); + + // Produces string: INSERT INTO mytable (title, content) VALUES ('My Title', 'My Content') + +The key thing to notice in the above example is that the second query did not +utlize `$this->db->from()`_ nor did it pass a table name into the first +parameter. The reason this worked is because the query has not been executed +using `$this->db->insert()`_ which resets values or reset directly using +`$this->db->reset_query()`_. + $this->db->insert_batch() ========================= @@ -717,6 +782,14 @@ array of values, the third parameter is the where key. .. note:: All values are escaped automatically producing safer queries. +$this->db->get_compiled_update() +================================ + +This works exactly the same way as ``$this->db->get_compiled_insert()`` except +that it produces an UPDATE SQL string instead of an INSERT SQL string. + +For more information view documentation for `$this->get_compiled_insert()`_. + ************* Deleting Data @@ -784,6 +857,13 @@ Generates a truncate SQL string and runs the query. .. note:: If the TRUNCATE command isn't available, truncate() will execute as "DELETE FROM table". + +$this->db->get_compiled_delete() +================================ +This works exactly the same way as ``$this->db->get_compiled_insert()`` except +that it produces a DELETE SQL string instead of an INSERT SQL string. + +For more information view documentation for `$this->get_compiled_insert()`_. *************** Method Chaining @@ -854,3 +934,31 @@ Here's a usage example:: where, like, group_by, having, order_by, set + +******************* +Reset Active Record +******************* + +Resetting Active Record allows you to start fresh with your query without +executing it first using a method like $this->db->get() or $this->db->insert(). +Just like the methods that execute a query, this will *not* reset items you've +cached using `Active Record Caching`_. + +This is useful in situations where you are using Active Record to generate SQL +(ex. ``$this->db->get_compiled_select()``) but then choose to, for instance, +run the query:: + + // Note that the second parameter of the get_compiled_select method is FALSE + $sql = $this->db->select(array('field1','field2')) + ->where('field3',5) + ->get_compiled_select('mytable', FALSE); + + // ... + // Do something crazy with the SQL code... like add it to a cron script for + // later execution or something... + // ... + + $data = $this->db->get()->result_array(); + + // Would execute and return an array of results of the following query: + // SELECT field1, field1 from mytable where field3 = 5; -- cgit v1.2.3-24-g4f1b From 84bcc6e9b8b1648d3a52102d2a96d617c60508f0 Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Mon, 17 Oct 2011 21:24:27 -0500 Subject: fixed typo in AR docs. NOTE: Sphinx gives a ReST error for unknown title targets, but they do exist, and links are built properly --- user_guide_src/source/database/active_record.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/active_record.rst b/user_guide_src/source/database/active_record.rst index 7230812de..5555a30bc 100644 --- a/user_guide_src/source/database/active_record.rst +++ b/user_guide_src/source/database/active_record.rst @@ -79,11 +79,12 @@ will be reset (by default it will be—just like `$this->db->get()`):: // Produces string: SELECT title, content, date FROM mytable The key thing to notice in the above example is that the second query did not -utlize `$this->db->from()`_ and did not pass a table name into the first +utilize `$this->db->from()`_ and did not pass a table name into the first parameter. The reason for this outcome is because the query has not been executed using `$this->db->get()`_ which resets values or reset directly using `$this-db->reset_query()`_. + $this->db->get_where() ====================== -- cgit v1.2.3-24-g4f1b From c35d2c90de019c8e474200471f57266c3086be0d Mon Sep 17 00:00:00 2001 From: kenjis Date: Wed, 26 Oct 2011 17:09:17 +0900 Subject: fix user guide active_record.rst formatting, remove old PHP 5 note, now only PHP 5 is supported. --- user_guide_src/source/database/active_record.rst | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/active_record.rst b/user_guide_src/source/database/active_record.rst index 5555a30bc..228d1d509 100644 --- a/user_guide_src/source/database/active_record.rst +++ b/user_guide_src/source/database/active_record.rst @@ -96,7 +96,7 @@ function:: Please read the about the where function below for more information. -Note: get_where() was formerly known as getwhere(), which has been +.. note:: get_where() was formerly known as getwhere(), which has been removed $this->db->select() @@ -198,7 +198,7 @@ Permits you to write the JOIN portion of your query:: $query = $this->db->get(); // Produces: - // SELECT * FROM blogs // JOIN comments ON comments.id = blogs.id + // SELECT * FROM blogs JOIN comments ON comments.id = blogs.id Multiple function calls can be made if you need several joins in one query. @@ -836,7 +836,7 @@ $this->db->empty_table() Generates a delete SQL string and runs the query.:: - $this->db->empty_table('mytable'); // Produces // DELETE FROM mytable + $this->db->empty_table('mytable'); // Produces: DELETE FROM mytable $this->db->truncate() @@ -847,7 +847,7 @@ Generates a truncate SQL string and runs the query. :: $this->db->from('mytable'); - $this->db->truncate(); + $this->db->truncate(); // or @@ -878,8 +878,6 @@ multiple functions. Consider this example:: ->limit(10, 20) ->get('mytable'); -.. note:: Method chaining only works with PHP 5. - .. _ar-caching: ********************* -- cgit v1.2.3-24-g4f1b From 5c3aaca52a32c49fc10613696e8a4826a839e588 Mon Sep 17 00:00:00 2001 From: Timothy Warren Date: Mon, 31 Oct 2011 13:31:30 -0300 Subject: Fixed one-liner code on Database Connection page of userguide --- user_guide_src/source/database/connecting.rst | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/connecting.rst b/user_guide_src/source/database/connecting.rst index 64adc3047..a834cc0f7 100644 --- a/user_guide_src/source/database/connecting.rst +++ b/user_guide_src/source/database/connecting.rst @@ -57,7 +57,19 @@ file. To connect manually to a desired database you can pass an array of values:: - $config['hostname'] = "localhost"; $config['username'] = "myusername"; $config['password'] = "mypassword"; $config['database'] = "mydatabase"; $config['dbdriver'] = "mysql"; $config['dbprefix'] = ""; $config['pconnect'] = FALSE; $config['db_debug'] = TRUE; $config['cache_on'] = FALSE; $config['cachedir'] = ""; $config['char_set'] = "utf8"; $config['dbcollat'] = "utf8_general_ci"; $this->load->database($config); + $config['hostname'] = "localhost"; + $config['username'] = "myusername"; + $config['password'] = "mypassword"; + $config['database'] = "mydatabase"; + $config['dbdriver'] = "mysql"; + $config['dbprefix'] = ""; + $config['pconnect'] = FALSE; + $config['db_debug'] = TRUE; + $config['cache_on'] = FALSE; + $config['cachedir'] = ""; + $config['char_set'] = "utf8"; + $config['dbcollat'] = "utf8_general_ci"; + $this->load->database($config); For information on each of these values please see the :doc:`configuration page `. @@ -68,14 +80,16 @@ page `. Or you can submit your database values as a Data Source Name. DSNs must have this prototype:: - $dsn = 'dbdriver://username:password@hostname/database'; $this->load->database($dsn); + $dsn = 'dbdriver://username:password@hostname/database'; + $this->load->database($dsn); To override default config values when connecting with a DSN string, add the config variables as a query string. :: - $dsn = 'dbdriver://username:password@hostname/database?char_set=utf8&dbcollat=utf8_general_ci&cache_on=true&cachedir=/path/to/cache'; $this->load->database($dsn); + $dsn = 'dbdriver://username:password@hostname/database?char_set=utf8&dbcollat=utf8_general_ci&cache_on=true&cachedir=/path/to/cache'; + $this->load->database($dsn); Connecting to Multiple Databases ================================ @@ -83,7 +97,8 @@ Connecting to Multiple Databases If you need to connect to more than one database simultaneously you can do so as follows:: - $DB1 = $this->load->database('group_one', TRUE); $DB2 = $this->load->database('group_two', TRUE); + $DB1 = $this->load->database('group_one', TRUE); + $DB2 = $this->load->database('group_two', TRUE); Note: Change the words "group_one" and "group_two" to the specific group names you are connecting to (or you can pass the connection values -- cgit v1.2.3-24-g4f1b From 85fe96df4dd7b7e163fae2d7e0420e750559e65c Mon Sep 17 00:00:00 2001 From: Felix Balfoort Date: Tue, 29 Nov 2011 16:27:53 +0100 Subject: Updated change log and and database configuration to include failover --- user_guide_src/source/database/configuration.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/configuration.rst b/user_guide_src/source/database/configuration.rst index 687f0d920..a6bfc8979 100644 --- a/user_guide_src/source/database/configuration.rst +++ b/user_guide_src/source/database/configuration.rst @@ -28,6 +28,28 @@ prototype:: $db['default']['autoinit'] = TRUE; $db['default']['stricton'] = FALSE; +You can also specify failovers for the situation when the main connection cannot connect for some reason. +These failovers can be specified by setting the failover for a connection like this:: + + $db['default']['failover'][0]['hostname'] = 'localhost1'; + $db['default']['failover'][0]['username'] = ''; + $db['default']['failover'][0]['password'] = ''; + $db['default']['failover'][0]['database'] = ''; + $db['default']['failover'][0]['dbdriver'] = 'mysql'; + $db['default']['failover'][0]['dbprefix'] = ''; + $db['default']['failover'][0]['pconnect'] = TRUE; + $db['default']['failover'][0]['db_debug'] = TRUE; + $db['default']['failover'][0]['cache_on'] = FALSE; + $db['default']['failover'][0]['cachedir'] = ''; + $db['default']['failover'][0]['char_set'] = 'utf8'; + $db['default']['failover'][0]['dbcollat'] = 'utf8_general_ci'; + $db['default']['failover'][0]['swap_pre'] = ''; + $db['default']['failover'][0]['autoinit'] = TRUE; + $db['default']['failover'][0]['stricton'] = FALSE; + $db['default']['failover'][0]['failover'] = array(); + +You can specify as much failovers as you like. + The reason we use a multi-dimensional array rather than a more simple one is to permit you to optionally store multiple sets of connection values. If, for example, you run multiple environments (development, -- cgit v1.2.3-24-g4f1b From 68f5d49d838fb2822b0f41e9b270f57e386f3fe4 Mon Sep 17 00:00:00 2001 From: Felix Balfoort Date: Tue, 29 Nov 2011 17:03:23 +0100 Subject: changed much to many in the documentation --- user_guide_src/source/database/configuration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/configuration.rst b/user_guide_src/source/database/configuration.rst index a6bfc8979..60a2026e5 100644 --- a/user_guide_src/source/database/configuration.rst +++ b/user_guide_src/source/database/configuration.rst @@ -48,7 +48,7 @@ These failovers can be specified by setting the failover for a connection like t $db['default']['failover'][0]['stricton'] = FALSE; $db['default']['failover'][0]['failover'] = array(); -You can specify as much failovers as you like. +You can specify as many failovers as you like. The reason we use a multi-dimensional array rather than a more simple one is to permit you to optionally store multiple sets of connection -- cgit v1.2.3-24-g4f1b From 292a0f661baedaa0a2bd61795e564c4195f4b0b8 Mon Sep 17 00:00:00 2001 From: Felix Balfoort Date: Tue, 29 Nov 2011 22:29:33 +0100 Subject: Changed the array structure in the userguide --- user_guide_src/source/database/configuration.rst | 52 ++++++++++++++++-------- 1 file changed, 36 insertions(+), 16 deletions(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/configuration.rst b/user_guide_src/source/database/configuration.rst index 60a2026e5..433c67152 100644 --- a/user_guide_src/source/database/configuration.rst +++ b/user_guide_src/source/database/configuration.rst @@ -31,22 +31,42 @@ prototype:: You can also specify failovers for the situation when the main connection cannot connect for some reason. These failovers can be specified by setting the failover for a connection like this:: - $db['default']['failover'][0]['hostname'] = 'localhost1'; - $db['default']['failover'][0]['username'] = ''; - $db['default']['failover'][0]['password'] = ''; - $db['default']['failover'][0]['database'] = ''; - $db['default']['failover'][0]['dbdriver'] = 'mysql'; - $db['default']['failover'][0]['dbprefix'] = ''; - $db['default']['failover'][0]['pconnect'] = TRUE; - $db['default']['failover'][0]['db_debug'] = TRUE; - $db['default']['failover'][0]['cache_on'] = FALSE; - $db['default']['failover'][0]['cachedir'] = ''; - $db['default']['failover'][0]['char_set'] = 'utf8'; - $db['default']['failover'][0]['dbcollat'] = 'utf8_general_ci'; - $db['default']['failover'][0]['swap_pre'] = ''; - $db['default']['failover'][0]['autoinit'] = TRUE; - $db['default']['failover'][0]['stricton'] = FALSE; - $db['default']['failover'][0]['failover'] = array(); + $db['default']['failover'] = array( + array( + 'hostname' => 'localhost1', + 'username' => '', + 'password' => '', + 'database' => '', + 'dbdriver' => 'mysql', + 'dbprefix' => '', + 'pconnect' => TRUE, + 'db_debug' => TRUE, + 'cache_on' => FALSE, + 'cachedir' => '', + 'char_set' => 'utf8', + 'dbcollat' => 'utf8_general_ci', + 'swap_pre' => '', + 'autoinit' => TRUE, + 'stricton' => FALSE + ), + array( + 'hostname' => 'localhost2', + 'username' => '', + 'password' => '', + 'database' => '', + 'dbdriver' => 'mysql', + 'dbprefix' => '', + 'pconnect' => TRUE, + 'db_debug' => TRUE, + 'cache_on' => FALSE, + 'cachedir' => '', + 'char_set' => 'utf8', + 'dbcollat' => 'utf8_general_ci', + 'swap_pre' => '', + 'autoinit' => TRUE, + 'stricton' => FALSE + ) + ); You can specify as many failovers as you like. -- cgit v1.2.3-24-g4f1b From ffd24a467c1d5ad6e2e4b66b63d4c9248f961b1e Mon Sep 17 00:00:00 2001 From: Greg Aker Date: Sun, 25 Dec 2011 22:27:59 -0600 Subject: Fixing a couple of issues in documentation files that occur when running Sphinx 'make html' --- user_guide_src/source/database/active_record.rst | 15 ++++++--------- user_guide_src/source/database/configuration.rst | 1 + 2 files changed, 7 insertions(+), 9 deletions(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/active_record.rst b/user_guide_src/source/database/active_record.rst index 228d1d509..1600f0bd9 100644 --- a/user_guide_src/source/database/active_record.rst +++ b/user_guide_src/source/database/active_record.rst @@ -82,7 +82,7 @@ The key thing to notice in the above example is that the second query did not utilize `$this->db->from()`_ and did not pass a table name into the first parameter. The reason for this outcome is because the query has not been executed using `$this->db->get()`_ which resets values or reset directly -using `$this-db->reset_query()`_. +using `$this->db->reset_query()`_. $this->db->get_where() @@ -96,8 +96,7 @@ function:: Please read the about the where function below for more information. -.. note:: get_where() was formerly known as getwhere(), which has been -removed +.. note:: get_where() was formerly known as getwhere(), which has been removed $this->db->select() =================== @@ -789,7 +788,7 @@ $this->db->get_compiled_update() This works exactly the same way as ``$this->db->get_compiled_insert()`` except that it produces an UPDATE SQL string instead of an INSERT SQL string. -For more information view documentation for `$this->get_compiled_insert()`_. +For more information view documentation for `$this->db->get_compiled_insert()`_. ************* @@ -864,7 +863,7 @@ $this->db->get_compiled_delete() This works exactly the same way as ``$this->db->get_compiled_insert()`` except that it produces a DELETE SQL string instead of an INSERT SQL string. -For more information view documentation for `$this->get_compiled_insert()`_. +For more information view documentation for `$this->db->get_compiled_insert()`_. *************** Method Chaining @@ -933,10 +932,8 @@ Here's a usage example:: where, like, group_by, having, order_by, set - -******************* -Reset Active Record -******************* +$this->db->reset_query() +======================== Resetting Active Record allows you to start fresh with your query without executing it first using a method like $this->db->get() or $this->db->insert(). diff --git a/user_guide_src/source/database/configuration.rst b/user_guide_src/source/database/configuration.rst index 433c67152..4f88c25ab 100644 --- a/user_guide_src/source/database/configuration.rst +++ b/user_guide_src/source/database/configuration.rst @@ -158,6 +158,7 @@ Explanation of Values: while developing an application. **port** The database port number. To use this value you have to add a line to the database config array. :: + $db['default']['port'] = 5432; ====================== ================================================================================================== -- cgit v1.2.3-24-g4f1b From 7219c07e9e6be839cbf9931a17d587ef4b2895b1 Mon Sep 17 00:00:00 2001 From: WanWizard Date: Wed, 28 Dec 2011 14:09:05 +0100 Subject: added query grouping to Active Record this is a feature that has been lacking for a very long time. lots of people complained about it over the years, but it never got added so you'd have to resort to handcrafted queries when you needed this feature. This is a port of code from DataMapper, in use since CI 1.6. --- user_guide_src/source/database/active_record.rst | 170 +++++++++++++++-------- 1 file changed, 109 insertions(+), 61 deletions(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/active_record.rst b/user_guide_src/source/database/active_record.rst index 1600f0bd9..c04e67d2a 100644 --- a/user_guide_src/source/database/active_record.rst +++ b/user_guide_src/source/database/active_record.rst @@ -45,7 +45,7 @@ You'll notice that the above function is assigned to a variable named $query, which can be used to show the results:: $query = $this->db->get('mytable'); - + foreach ($query->result() as $row) { echo $row->title; @@ -57,31 +57,31 @@ discussion regarding result generation. $this->db->get_compiled_select() ================================ -Compiles the selection query just like `$this->db->get()`_ but does not *run* +Compiles the selection query just like `$this->db->get()`_ but does not *run* the query. This method simply returns the SQL query as a string. Example:: $sql = $this->db->get_compiled_select('mytable'); echo $sql; - + // Produces string: SELECT * FROM mytable - -The second parameter enables you to set whether or not the active record query + +The second parameter enables you to set whether or not the active record query will be reset (by default it will be—just like `$this->db->get()`):: echo $this->db->limit(10,20)->get_compiled_select('mytable', FALSE); - // Produces string: SELECT * FROM mytable LIMIT 20, 10 + // Produces string: SELECT * FROM mytable LIMIT 20, 10 // (in MySQL. Other databases have slightly different syntax) - + echo $this->db->select('title, content, date')->get_compiled_select(); // Produces string: SELECT title, content, date FROM mytable - -The key thing to notice in the above example is that the second query did not -utilize `$this->db->from()`_ and did not pass a table name into the first -parameter. The reason for this outcome is because the query has not been -executed using `$this->db->get()`_ which resets values or reset directly + +The key thing to notice in the above example is that the second query did not +utilize `$this->db->from()`_ and did not pass a table name into the first +parameter. The reason for this outcome is because the query has not been +executed using `$this->db->get()`_ which resets values or reset directly using `$this->db->reset_query()`_. @@ -116,7 +116,7 @@ with backticks. This is useful if you need a compound select statement. :: - $this->db->select('(SELECT SUM(payments.amount) FROM payments WHERE payments.invoice_id=4') AS amount_paid', FALSE); + $this->db->select('(SELECT SUM(payments.amount) FROM payments WHERE payments.invoice_id=4') AS amount_paid', FALSE); $query = $this->db->get('mytable'); @@ -130,7 +130,7 @@ include a second parameter to rename the resulting field. $this->db->select_max('age'); $query = $this->db->get('members'); // Produces: SELECT MAX(age) as age FROM members - + $this->db->select_max('age', 'member_age'); $query = $this->db->get('members'); // Produces: SELECT MAX(age) as member_age FROM members @@ -195,7 +195,7 @@ Permits you to write the JOIN portion of your query:: $this->db->from('blogs'); $this->db->join('comments', 'comments.id = blogs.id'); $query = $this->db->get(); - + // Produces: // SELECT * FROM blogs JOIN comments ON comments.id = blogs.id @@ -224,7 +224,7 @@ methods: :: - $this->db->where('name', $name); // Produces: WHERE name = 'Joe' + $this->db->where('name', $name); // Produces: WHERE name = 'Joe' Notice that the equal sign is added for you. @@ -236,7 +236,7 @@ methods: $this->db->where('name', $name); $this->db->where('title', $title); $this->db->where('status', $status); - // WHERE name = 'Joe' AND title = 'boss' AND status = 'active' + // WHERE name = 'Joe' AND title = 'boss' AND status = 'active' #. **Custom key/value method:** You can include an operator in the first parameter in order to @@ -245,7 +245,7 @@ methods: :: $this->db->where('name !=', $name); - $this->db->where('id <', $id); // Produces: WHERE name != 'Joe' AND id < 45 + $this->db->where('id <', $id); // Produces: WHERE name != 'Joe' AND id < 45 #. **Associative array method:** @@ -253,7 +253,7 @@ methods: $array = array('name' => $name, 'title' => $title, 'status' => $status); $this->db->where($array); - // Produces: WHERE name = 'Joe' AND title = 'boss' AND status = 'active' + // Produces: WHERE name = 'Joe' AND title = 'boss' AND status = 'active' You can include your own operators using this method as well: @@ -354,7 +354,7 @@ searches. :: - $this->db->like('title', 'match'); // Produces: WHERE title LIKE '%match%' + $this->db->like('title', 'match'); // Produces: WHERE title LIKE '%match%' If you use multiple function calls they will be chained together with AND between them:: @@ -371,7 +371,7 @@ searches. $this->db->like('title', 'match', 'before'); // Produces: WHERE title LIKE '%match' $this->db->like('title', 'match', 'after'); // Produces: WHERE title LIKE 'match%' - $this->db->like('title', 'match', 'both'); // Produces: WHERE title LIKE '%match%' + $this->db->like('title', 'match', 'both'); // Produces: WHERE title LIKE '%match%' #. **Associative array method:** @@ -443,7 +443,7 @@ Permits you to write the HAVING portion of your query. There are 2 possible syntaxes, 1 argument or 2:: $this->db->having('user_id = 45'); // Produces: HAVING user_id = 45 - $this->db->having('user_id', 45); // Produces: HAVING user_id = 45 + $this->db->having('user_id', 45); // Produces: HAVING user_id = 45 You can also pass an array of multiple values as well:: @@ -486,7 +486,7 @@ Or multiple function calls can be made if you need multiple fields. :: $this->db->order_by("title", "desc"); - $this->db->order_by("name", "asc"); // Produces: ORDER BY title DESC, name ASC + $this->db->order_by("name", "asc"); // Produces: ORDER BY title DESC, name ASC .. note:: order_by() was formerly known as orderby(), which has been @@ -518,7 +518,7 @@ where(), or_where(), like(), or_like(), etc. Example:: echo $this->db->count_all_results('my_table'); // Produces an integer, like 25 $this->db->like('title', 'match'); $this->db->from('my_table'); - echo $this->db->count_all_results(); // Produces an integer, like 17 + echo $this->db->count_all_results(); // Produces an integer, like 17 $this->db->count_all() ====================== @@ -528,6 +528,54 @@ Submit the table name in the first parameter. Example:: echo $this->db->count_all('my_table'); // Produces an integer, like 25 +************** +Query grouping +************** + +Query grouping allows you to create groups of WHERE clauses by enclosing them in parentheses. This will allow +you to create queries with complex WHERE clauses. Nested groups are supported. Example: + + $this->db->select('*')->from('my_table') + ->group_start() + ->where('a', 'a') + ->or_group_start() + ->where('b', 'b') + ->where('c', 'c') + ->group_end() + ->group_end() + ->where('d', 'd') + ->get(); + + // Generates: + // SELECT * FROM (`my_table`) WHERE ( `a` = 'a' OR ( `b` = 'b' AND `c` = 'c' ) ) AND `d` = 'd' + +.. note:: groups need to be balanced, make sure every group_start() is matched by a group_end(). + +$this->db->group_start() +======================== + +Starts a new group by adding an opening parenthesis to the WHERE clause of the query. + +$this->db->or_group_start() +=========================== + +Starts a new group by adding an opening parenthesis to the WHERE clause of the query, prefixing it with 'OR'. + +$this->db->not_group_start() +============================ + +Starts a new group by adding an opening parenthesis to the WHERE clause of the query, prefixing it with 'NOT'. + +$this->db->or_not_group_start() +=============================== + +Starts a new group by adding an opening parenthesis to the WHERE clause of the query, prefixing it with 'OR NOT'. + +$this->db->group_end() +====================== + +Ends the current group by adding an closing parenthesis to the WHERE clause of the query. + ************** Inserting Data ************** @@ -544,7 +592,7 @@ function. Here is an example using an array:: 'name' => 'My Name', 'date' => 'My date' ); - + $this->db->insert('mytable', $data); // Produces: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date') @@ -560,7 +608,7 @@ Here is an example using an object:: var $date = 'My Date'; } */ - + $object = new Myclass; $this->db->insert('mytable', $object); // Produces: INSERT INTO mytable (title, content, date) VALUES ('My Title', 'My Content', 'My Date') @@ -572,7 +620,7 @@ object. $this->db->get_compiled_insert() ================================ -Compiles the insertion query just like `$this->db->insert()`_ but does not +Compiles the insertion query just like `$this->db->insert()`_ but does not *run* the query. This method simply returns the SQL query as a string. Example:: @@ -582,27 +630,27 @@ Example:: 'name' => 'My Name', 'date' => 'My date' ); - + $sql = $this->db->set($data)->get_compiled_insert('mytable'); echo $sql; - + // Produces string: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date') -The second parameter enables you to set whether or not the active record query +The second parameter enables you to set whether or not the active record query will be reset (by default it will be--just like `$this->db->insert()`_):: - + echo $this->db->set('title', 'My Title')->get_compiled_insert('mytable', FALSE); - + // Produces string: INSERT INTO mytable (title) VALUES ('My Title') - + echo $this->db->set('content', 'My Content')->get_compiled_insert(); // Produces string: INSERT INTO mytable (title, content) VALUES ('My Title', 'My Content') - -The key thing to notice in the above example is that the second query did not -utlize `$this->db->from()`_ nor did it pass a table name into the first -parameter. The reason this worked is because the query has not been executed -using `$this->db->insert()`_ which resets values or reset directly using + +The key thing to notice in the above example is that the second query did not +utlize `$this->db->from()`_ nor did it pass a table name into the first +parameter. The reason this worked is because the query has not been executed +using `$this->db->insert()`_ which resets values or reset directly using `$this->db->reset_query()`_. $this->db->insert_batch() @@ -624,7 +672,7 @@ function. Here is an example using an array:: 'date' => 'Another date' ) ); - + $this->db->insert_batch('mytable', $data); // Produces: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date'), ('Another title', 'Another name', 'Another date') @@ -652,7 +700,7 @@ based on whether you are doing an insert or an update:: $this->db->set('name', $name); $this->db->set('title', $title); $this->db->set('status', $status); - $this->db->insert('mytable'); + $this->db->insert('mytable'); **set()** will also accept an optional third parameter ($escape), that will prevent data from being escaped if set to FALSE. To illustrate the @@ -674,7 +722,7 @@ You can also pass an associative array to this function:: 'title' => $title, 'status' => $status ); - + $this->db->set($array); $this->db->insert('mytable'); @@ -687,7 +735,7 @@ Or an object:: var $date = 'My Date'; } */ - + $object = new Myclass; $this->db->set($object); $this->db->insert('mytable'); @@ -709,7 +757,7 @@ is an example using an array:: 'name' => $name, 'date' => $date ); - + $this->db->where('id', $id); $this->db->update('mytable', $data); // Produces: // UPDATE mytable // SET title = '{$title}', name = '{$name}', date = '{$date}' // WHERE id = $id @@ -723,7 +771,7 @@ Or you can supply an object:: var $date = 'My Date'; } */ - + $object = new Myclass; $this->db->where('id', $id); $this->db->update('mytable', $object); @@ -764,14 +812,14 @@ Here is an example using an array:: ) ); - $this->db->update_batch('mytable', $data, 'title'); + $this->db->update_batch('mytable', $data, 'title'); - // Produces: + // Produces: // UPDATE `mytable` SET `name` = CASE // WHEN `title` = 'My title' THEN 'My Name 2' // WHEN `title` = 'Another title' THEN 'Another Name 2' // ELSE `name` END, - // `date` = CASE + // `date` = CASE // WHEN `title` = 'My title' THEN 'My date 2' // WHEN `title` = 'Another title' THEN 'Another date 2' // ELSE `date` END @@ -810,7 +858,7 @@ the data to the second parameter of the function:: $this->db->where('id', $id); $this->db->delete('mytable'); - + // Produces: // DELETE FROM mytable // WHERE id = $id @@ -847,17 +895,17 @@ Generates a truncate SQL string and runs the query. $this->db->from('mytable'); $this->db->truncate(); - - // or - + + // or + $this->db->truncate('mytable'); - + // Produce: - // TRUNCATE mytable + // TRUNCATE mytable .. note:: If the TRUNCATE command isn't available, truncate() will execute as "DELETE FROM table". - + $this->db->get_compiled_delete() ================================ This works exactly the same way as ``$this->db->get_compiled_insert()`` except @@ -917,11 +965,11 @@ Here's a usage example:: $this->db->stop_cache(); $this->db->get('tablename'); //Generates: SELECT `field1` FROM (`tablename`) - + $this->db->select('field2'); $this->db->get('tablename'); //Generates: SELECT `field1`, `field2` FROM (`tablename`) - + $this->db->flush_cache(); $this->db->select('field2'); $this->db->get('tablename'); @@ -935,13 +983,13 @@ Here's a usage example:: $this->db->reset_query() ======================== -Resetting Active Record allows you to start fresh with your query without -executing it first using a method like $this->db->get() or $this->db->insert(). -Just like the methods that execute a query, this will *not* reset items you've +Resetting Active Record allows you to start fresh with your query without +executing it first using a method like $this->db->get() or $this->db->insert(). +Just like the methods that execute a query, this will *not* reset items you've cached using `Active Record Caching`_. -This is useful in situations where you are using Active Record to generate SQL -(ex. ``$this->db->get_compiled_select()``) but then choose to, for instance, +This is useful in situations where you are using Active Record to generate SQL +(ex. ``$this->db->get_compiled_select()``) but then choose to, for instance, run the query:: // Note that the second parameter of the get_compiled_select method is FALSE -- cgit v1.2.3-24-g4f1b From 8ae24c57a1240a5a5e3fbd5755227e5d42b75390 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Mon, 16 Jan 2012 13:05:23 +0200 Subject: Add SQLite3 database driver --- user_guide_src/source/database/configuration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/configuration.rst b/user_guide_src/source/database/configuration.rst index 4f88c25ab..7d3960f10 100644 --- a/user_guide_src/source/database/configuration.rst +++ b/user_guide_src/source/database/configuration.rst @@ -163,7 +163,7 @@ Explanation of Values: ====================== ================================================================================================== .. note:: Depending on what database platform you are using (MySQL, - Postgres, etc.) not all values will be needed. For example, when using + Postgre, etc.) not all values will be needed. For example, when using SQLite you will not need to supply a username or password, and the database name will be the path to your database file. The information above assumes you are using MySQL. -- cgit v1.2.3-24-g4f1b From 1820933505d6aa8def25d0e74344f878c3ec76ad Mon Sep 17 00:00:00 2001 From: Taufan Aditya Date: Thu, 9 Feb 2012 16:07:27 +0700 Subject: Fixed PDO --- user_guide_src/source/database/configuration.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/configuration.rst b/user_guide_src/source/database/configuration.rst index 4f88c25ab..040e7e33f 100644 --- a/user_guide_src/source/database/configuration.rst +++ b/user_guide_src/source/database/configuration.rst @@ -28,6 +28,10 @@ prototype:: $db['default']['autoinit'] = TRUE; $db['default']['stricton'] = FALSE; +If you use PDO as your dbdriver, you can specify the full DSN string describe a connection to the database like this:: + + $db['default']['dsn'] = 'pgsql:host=localhost;port=5432;dbname=database_name'; + You can also specify failovers for the situation when the main connection cannot connect for some reason. These failovers can be specified by setting the failover for a connection like this:: -- cgit v1.2.3-24-g4f1b From 6e821cecf8ace0e7d721dd946568664c840434aa Mon Sep 17 00:00:00 2001 From: Timothy Warren Date: Wed, 15 Feb 2012 18:40:39 -0500 Subject: Implemented insert_id() method --- user_guide_src/source/database/helpers.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/helpers.rst b/user_guide_src/source/database/helpers.rst index 7ea19e9f6..e8a5ac801 100644 --- a/user_guide_src/source/database/helpers.rst +++ b/user_guide_src/source/database/helpers.rst @@ -7,9 +7,9 @@ $this->db->insert_id() The insert ID number when performing database inserts. -.. note:: If using the PDO driver with PostgreSQL, this function requires - a $name parameter, which specifies the appropriate sequence to check - for the insert id. +.. note:: If using the PDO driver with PostgreSQL, or using the Interbase + driver, this function requires a $name parameter, which specifies the + appropriate sequence to check for the insert id. $this->db->affected_rows() =========================== -- cgit v1.2.3-24-g4f1b From 7efad20597ef7e06f8cf837a9f40918d2d3f2727 Mon Sep 17 00:00:00 2001 From: Jamie Rumbelow Date: Sun, 19 Feb 2012 12:37:00 +0000 Subject: Renaming Active Record to Query Builder across the system --- user_guide_src/source/database/active_record.rst | 1008 ---------------------- user_guide_src/source/database/configuration.rst | 12 +- user_guide_src/source/database/connecting.rst | 2 +- user_guide_src/source/database/examples.rst | 8 +- user_guide_src/source/database/index.rst | 4 +- user_guide_src/source/database/queries.rst | 2 +- user_guide_src/source/database/query_builder.rst | 1008 ++++++++++++++++++++++ 7 files changed, 1022 insertions(+), 1022 deletions(-) delete mode 100644 user_guide_src/source/database/active_record.rst create mode 100644 user_guide_src/source/database/query_builder.rst (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/active_record.rst b/user_guide_src/source/database/active_record.rst deleted file mode 100644 index c04e67d2a..000000000 --- a/user_guide_src/source/database/active_record.rst +++ /dev/null @@ -1,1008 +0,0 @@ -################### -Active Record Class -################### - -CodeIgniter uses a modified version of the Active Record Database -Pattern. This pattern allows information to be retrieved, inserted, and -updated in your database with minimal scripting. In some cases only one -or two lines of code are necessary to perform a database action. -CodeIgniter does not require that each database table be its own class -file. It instead provides a more simplified interface. - -Beyond simplicity, a major benefit to using the Active Record features -is that it allows you to create database independent applications, since -the query syntax is generated by each database adapter. It also allows -for safer queries, since the values are escaped automatically by the -system. - -.. note:: If you intend to write your own queries you can disable this - class in your database config file, allowing the core database library - and adapter to utilize fewer resources. - -.. contents:: Page Contents - -************** -Selecting Data -************** - -The following functions allow you to build SQL **SELECT** statements. - -$this->db->get() -================ - -Runs the selection query and returns the result. Can be used by itself -to retrieve all records from a table:: - - $query = $this->db->get('mytable'); // Produces: SELECT * FROM mytable - -The second and third parameters enable you to set a limit and offset -clause:: - - $query = $this->db->get('mytable', 10, 20); - // Produces: SELECT * FROM mytable LIMIT 20, 10 (in MySQL. Other databases have slightly different syntax) - -You'll notice that the above function is assigned to a variable named -$query, which can be used to show the results:: - - $query = $this->db->get('mytable'); - - foreach ($query->result() as $row) - { - echo $row->title; - } - -Please visit the :doc:`result functions ` page for a full -discussion regarding result generation. - -$this->db->get_compiled_select() -================================ - -Compiles the selection query just like `$this->db->get()`_ but does not *run* -the query. This method simply returns the SQL query as a string. - -Example:: - - $sql = $this->db->get_compiled_select('mytable'); - echo $sql; - - // Produces string: SELECT * FROM mytable - -The second parameter enables you to set whether or not the active record query -will be reset (by default it will be—just like `$this->db->get()`):: - - echo $this->db->limit(10,20)->get_compiled_select('mytable', FALSE); - // Produces string: SELECT * FROM mytable LIMIT 20, 10 - // (in MySQL. Other databases have slightly different syntax) - - echo $this->db->select('title, content, date')->get_compiled_select(); - - // Produces string: SELECT title, content, date FROM mytable - -The key thing to notice in the above example is that the second query did not -utilize `$this->db->from()`_ and did not pass a table name into the first -parameter. The reason for this outcome is because the query has not been -executed using `$this->db->get()`_ which resets values or reset directly -using `$this->db->reset_query()`_. - - -$this->db->get_where() -====================== - -Identical to the above function except that it permits you to add a -"where" clause in the second parameter, instead of using the db->where() -function:: - - $query = $this->db->get_where('mytable', array('id' => $id), $limit, $offset); - -Please read the about the where function below for more information. - -.. note:: get_where() was formerly known as getwhere(), which has been removed - -$this->db->select() -=================== - -Permits you to write the SELECT portion of your query:: - - $this->db->select('title, content, date'); - $query = $this->db->get('mytable'); // Produces: SELECT title, content, date FROM mytable - - -.. note:: If you are selecting all (\*) from a table you do not need to - use this function. When omitted, CodeIgniter assumes you wish to SELECT * - -$this->db->select() accepts an optional second parameter. If you set it -to FALSE, CodeIgniter will not try to protect your field or table names -with backticks. This is useful if you need a compound select statement. - -:: - - $this->db->select('(SELECT SUM(payments.amount) FROM payments WHERE payments.invoice_id=4') AS amount_paid', FALSE); - $query = $this->db->get('mytable'); - - -$this->db->select_max() -======================= - -Writes a "SELECT MAX(field)" portion for your query. You can optionally -include a second parameter to rename the resulting field. - -:: - - $this->db->select_max('age'); - $query = $this->db->get('members'); // Produces: SELECT MAX(age) as age FROM members - - $this->db->select_max('age', 'member_age'); - $query = $this->db->get('members'); // Produces: SELECT MAX(age) as member_age FROM members - - -$this->db->select_min() -======================= - -Writes a "SELECT MIN(field)" portion for your query. As with -select_max(), You can optionally include a second parameter to rename -the resulting field. - -:: - - $this->db->select_min('age'); - $query = $this->db->get('members'); // Produces: SELECT MIN(age) as age FROM members - - -$this->db->select_avg() -======================= - -Writes a "SELECT AVG(field)" portion for your query. As with -select_max(), You can optionally include a second parameter to rename -the resulting field. - -:: - - $this->db->select_avg('age'); - $query = $this->db->get('members'); // Produces: SELECT AVG(age) as age FROM members - - -$this->db->select_sum() -======================= - -Writes a "SELECT SUM(field)" portion for your query. As with -select_max(), You can optionally include a second parameter to rename -the resulting field. - -:: - - $this->db->select_sum('age'); - $query = $this->db->get('members'); // Produces: SELECT SUM(age) as age FROM members - - -$this->db->from() -================= - -Permits you to write the FROM portion of your query:: - - $this->db->select('title, content, date'); - $this->db->from('mytable'); - $query = $this->db->get(); // Produces: SELECT title, content, date FROM mytable - -.. note:: As shown earlier, the FROM portion of your query can be specified - in the $this->db->get() function, so use whichever method you prefer. - -$this->db->join() -================= - -Permits you to write the JOIN portion of your query:: - - $this->db->select('*'); - $this->db->from('blogs'); - $this->db->join('comments', 'comments.id = blogs.id'); - $query = $this->db->get(); - - // Produces: - // SELECT * FROM blogs JOIN comments ON comments.id = blogs.id - -Multiple function calls can be made if you need several joins in one -query. - -If you need a specific type of JOIN you can specify it via the third -parameter of the function. Options are: left, right, outer, inner, left -outer, and right outer. - -:: - - $this->db->join('comments', 'comments.id = blogs.id', 'left'); - // Produces: LEFT JOIN comments ON comments.id = blogs.id - -$this->db->where() -================== - -This function enables you to set **WHERE** clauses using one of four -methods: - -.. note:: All values passed to this function are escaped automatically, - producing safer queries. - -#. **Simple key/value method:** - - :: - - $this->db->where('name', $name); // Produces: WHERE name = 'Joe' - - Notice that the equal sign is added for you. - - If you use multiple function calls they will be chained together with - AND between them: - - :: - - $this->db->where('name', $name); - $this->db->where('title', $title); - $this->db->where('status', $status); - // WHERE name = 'Joe' AND title = 'boss' AND status = 'active' - -#. **Custom key/value method:** - You can include an operator in the first parameter in order to - control the comparison: - - :: - - $this->db->where('name !=', $name); - $this->db->where('id <', $id); // Produces: WHERE name != 'Joe' AND id < 45 - -#. **Associative array method:** - - :: - - $array = array('name' => $name, 'title' => $title, 'status' => $status); - $this->db->where($array); - // Produces: WHERE name = 'Joe' AND title = 'boss' AND status = 'active' - - You can include your own operators using this method as well: - - :: - - $array = array('name !=' => $name, 'id <' => $id, 'date >' => $date); - $this->db->where($array); - -#. **Custom string:** - You can write your own clauses manually:: - - $where = "name='Joe' AND status='boss' OR status='active'"; - $this->db->where($where); - - -$this->db->where() accepts an optional third parameter. If you set it to -FALSE, CodeIgniter will not try to protect your field or table names -with backticks. - -:: - - $this->db->where('MATCH (field) AGAINST ("value")', NULL, FALSE); - - -$this->db->or_where() -===================== - -This function is identical to the one above, except that multiple -instances are joined by OR:: - - $this->db->where('name !=', $name); - $this->db->or_where('id >', $id); // Produces: WHERE name != 'Joe' OR id > 50 - -.. note:: or_where() was formerly known as orwhere(), which has been - removed. - -$this->db->where_in() -===================== - -Generates a WHERE field IN ('item', 'item') SQL query joined with AND if -appropriate - -:: - - $names = array('Frank', 'Todd', 'James'); - $this->db->where_in('username', $names); - // Produces: WHERE username IN ('Frank', 'Todd', 'James') - - -$this->db->or_where_in() -======================== - -Generates a WHERE field IN ('item', 'item') SQL query joined with OR if -appropriate - -:: - - $names = array('Frank', 'Todd', 'James'); - $this->db->or_where_in('username', $names); - // Produces: OR username IN ('Frank', 'Todd', 'James') - - -$this->db->where_not_in() -========================= - -Generates a WHERE field NOT IN ('item', 'item') SQL query joined with -AND if appropriate - -:: - - $names = array('Frank', 'Todd', 'James'); - $this->db->where_not_in('username', $names); - // Produces: WHERE username NOT IN ('Frank', 'Todd', 'James') - - -$this->db->or_where_not_in() -============================ - -Generates a WHERE field NOT IN ('item', 'item') SQL query joined with OR -if appropriate - -:: - - $names = array('Frank', 'Todd', 'James'); - $this->db->or_where_not_in('username', $names); - // Produces: OR username NOT IN ('Frank', 'Todd', 'James') - - -$this->db->like() -================= - -This function enables you to generate **LIKE** clauses, useful for doing -searches. - -.. note:: All values passed to this function are escaped automatically. - -#. **Simple key/value method:** - - :: - - $this->db->like('title', 'match'); // Produces: WHERE title LIKE '%match%' - - If you use multiple function calls they will be chained together with - AND between them:: - - $this->db->like('title', 'match'); - $this->db->like('body', 'match'); - // WHERE title LIKE '%match%' AND body LIKE '%match% - - If you want to control where the wildcard (%) is placed, you can use - an optional third argument. Your options are 'before', 'after' and - 'both' (which is the default). - - :: - - $this->db->like('title', 'match', 'before'); // Produces: WHERE title LIKE '%match' - $this->db->like('title', 'match', 'after'); // Produces: WHERE title LIKE 'match%' - $this->db->like('title', 'match', 'both'); // Produces: WHERE title LIKE '%match%' - -#. **Associative array method:** - - :: - - $array = array('title' => $match, 'page1' => $match, 'page2' => $match); - $this->db->like($array); - // WHERE title LIKE '%match%' AND page1 LIKE '%match%' AND page2 LIKE '%match%' - - -$this->db->or_like() -==================== - -This function is identical to the one above, except that multiple -instances are joined by OR:: - - $this->db->like('title', 'match'); $this->db->or_like('body', $match); - // WHERE title LIKE '%match%' OR body LIKE '%match%' - -.. note:: or_like() was formerly known as orlike(), which has been removed. - -$this->db->not_like() -===================== - -This function is identical to **like()**, except that it generates NOT -LIKE statements:: - - $this->db->not_like('title', 'match'); // WHERE title NOT LIKE '%match% - -$this->db->or_not_like() -======================== - -This function is identical to **not_like()**, except that multiple -instances are joined by OR:: - - $this->db->like('title', 'match'); - $this->db->or_not_like('body', 'match'); - // WHERE title LIKE '%match% OR body NOT LIKE '%match%' - -$this->db->group_by() -===================== - -Permits you to write the GROUP BY portion of your query:: - - $this->db->group_by("title"); // Produces: GROUP BY title - -You can also pass an array of multiple values as well:: - - $this->db->group_by(array("title", "date")); // Produces: GROUP BY title, date - -.. note:: group_by() was formerly known as groupby(), which has been - removed. - -$this->db->distinct() -===================== - -Adds the "DISTINCT" keyword to a query - -:: - - $this->db->distinct(); - $this->db->get('table'); // Produces: SELECT DISTINCT * FROM table - - -$this->db->having() -=================== - -Permits you to write the HAVING portion of your query. There are 2 -possible syntaxes, 1 argument or 2:: - - $this->db->having('user_id = 45'); // Produces: HAVING user_id = 45 - $this->db->having('user_id', 45); // Produces: HAVING user_id = 45 - -You can also pass an array of multiple values as well:: - - $this->db->having(array('title =' => 'My Title', 'id <' => $id)); - // Produces: HAVING title = 'My Title', id < 45 - - -If you are using a database that CodeIgniter escapes queries for, you -can prevent escaping content by passing an optional third argument, and -setting it to FALSE. - -:: - - $this->db->having('user_id', 45); // Produces: HAVING `user_id` = 45 in some databases such as MySQL - $this->db->having('user_id', 45, FALSE); // Produces: HAVING user_id = 45 - - -$this->db->or_having() -====================== - -Identical to having(), only separates multiple clauses with "OR". - -$this->db->order_by() -===================== - -Lets you set an ORDER BY clause. The first parameter contains the name -of the column you would like to order by. The second parameter lets you -set the direction of the result. Options are asc or desc, or random. - -:: - - $this->db->order_by("title", "desc"); // Produces: ORDER BY title DESC - -You can also pass your own string in the first parameter:: - - $this->db->order_by('title desc, name asc'); // Produces: ORDER BY title DESC, name ASC - -Or multiple function calls can be made if you need multiple fields. - -:: - - $this->db->order_by("title", "desc"); - $this->db->order_by("name", "asc"); // Produces: ORDER BY title DESC, name ASC - - -.. note:: order_by() was formerly known as orderby(), which has been - removed. - -.. note:: random ordering is not currently supported in Oracle or MSSQL - drivers. These will default to 'ASC'. - -$this->db->limit() -================== - -Lets you limit the number of rows you would like returned by the query:: - - $this->db->limit(10); // Produces: LIMIT 10 - -The second parameter lets you set a result offset. - -:: - - $this->db->limit(10, 20); // Produces: LIMIT 20, 10 (in MySQL. Other databases have slightly different syntax) - -$this->db->count_all_results() -============================== - -Permits you to determine the number of rows in a particular Active -Record query. Queries will accept Active Record restrictors such as -where(), or_where(), like(), or_like(), etc. Example:: - - echo $this->db->count_all_results('my_table'); // Produces an integer, like 25 - $this->db->like('title', 'match'); - $this->db->from('my_table'); - echo $this->db->count_all_results(); // Produces an integer, like 17 - -$this->db->count_all() -====================== - -Permits you to determine the number of rows in a particular table. -Submit the table name in the first parameter. Example:: - - echo $this->db->count_all('my_table'); // Produces an integer, like 25 - -************** -Query grouping -************** - -Query grouping allows you to create groups of WHERE clauses by enclosing them in parentheses. This will allow -you to create queries with complex WHERE clauses. Nested groups are supported. Example: - - $this->db->select('*')->from('my_table') - ->group_start() - ->where('a', 'a') - ->or_group_start() - ->where('b', 'b') - ->where('c', 'c') - ->group_end() - ->group_end() - ->where('d', 'd') - ->get(); - - // Generates: - // SELECT * FROM (`my_table`) WHERE ( `a` = 'a' OR ( `b` = 'b' AND `c` = 'c' ) ) AND `d` = 'd' - -.. note:: groups need to be balanced, make sure every group_start() is matched by a group_end(). - -$this->db->group_start() -======================== - -Starts a new group by adding an opening parenthesis to the WHERE clause of the query. - -$this->db->or_group_start() -=========================== - -Starts a new group by adding an opening parenthesis to the WHERE clause of the query, prefixing it with 'OR'. - -$this->db->not_group_start() -============================ - -Starts a new group by adding an opening parenthesis to the WHERE clause of the query, prefixing it with 'NOT'. - -$this->db->or_not_group_start() -=============================== - -Starts a new group by adding an opening parenthesis to the WHERE clause of the query, prefixing it with 'OR NOT'. - -$this->db->group_end() -====================== - -Ends the current group by adding an closing parenthesis to the WHERE clause of the query. - -************** -Inserting Data -************** - -$this->db->insert() -=================== - -Generates an insert string based on the data you supply, and runs the -query. You can either pass an **array** or an **object** to the -function. Here is an example using an array:: - - $data = array( - 'title' => 'My title', - 'name' => 'My Name', - 'date' => 'My date' - ); - - $this->db->insert('mytable', $data); - // Produces: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date') - -The first parameter will contain the table name, the second is an -associative array of values. - -Here is an example using an object:: - - /* - class Myclass { - var $title = 'My Title'; - var $content = 'My Content'; - var $date = 'My Date'; - } - */ - - $object = new Myclass; - $this->db->insert('mytable', $object); - // Produces: INSERT INTO mytable (title, content, date) VALUES ('My Title', 'My Content', 'My Date') - -The first parameter will contain the table name, the second is an -object. - -.. note:: All values are escaped automatically producing safer queries. - -$this->db->get_compiled_insert() -================================ -Compiles the insertion query just like `$this->db->insert()`_ but does not -*run* the query. This method simply returns the SQL query as a string. - -Example:: - - $data = array( - 'title' => 'My title', - 'name' => 'My Name', - 'date' => 'My date' - ); - - $sql = $this->db->set($data)->get_compiled_insert('mytable'); - echo $sql; - - // Produces string: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date') - -The second parameter enables you to set whether or not the active record query -will be reset (by default it will be--just like `$this->db->insert()`_):: - - echo $this->db->set('title', 'My Title')->get_compiled_insert('mytable', FALSE); - - // Produces string: INSERT INTO mytable (title) VALUES ('My Title') - - echo $this->db->set('content', 'My Content')->get_compiled_insert(); - - // Produces string: INSERT INTO mytable (title, content) VALUES ('My Title', 'My Content') - -The key thing to notice in the above example is that the second query did not -utlize `$this->db->from()`_ nor did it pass a table name into the first -parameter. The reason this worked is because the query has not been executed -using `$this->db->insert()`_ which resets values or reset directly using -`$this->db->reset_query()`_. - -$this->db->insert_batch() -========================= - -Generates an insert string based on the data you supply, and runs the -query. You can either pass an **array** or an **object** to the -function. Here is an example using an array:: - - $data = array( - array( - 'title' => 'My title', - 'name' => 'My Name', - 'date' => 'My date' - ), - array( - 'title' => 'Another title', - 'name' => 'Another Name', - 'date' => 'Another date' - ) - ); - - $this->db->insert_batch('mytable', $data); - // Produces: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date'), ('Another title', 'Another name', 'Another date') - -The first parameter will contain the table name, the second is an -associative array of values. - -.. note:: All values are escaped automatically producing safer queries. - -$this->db->set() -================ - -This function enables you to set values for inserts or updates. - -**It can be used instead of passing a data array directly to the insert -or update functions:** - -:: - - $this->db->set('name', $name); - $this->db->insert('mytable'); // Produces: INSERT INTO mytable (name) VALUES ('{$name}') - -If you use multiple function called they will be assembled properly -based on whether you are doing an insert or an update:: - - $this->db->set('name', $name); - $this->db->set('title', $title); - $this->db->set('status', $status); - $this->db->insert('mytable'); - -**set()** will also accept an optional third parameter ($escape), that -will prevent data from being escaped if set to FALSE. To illustrate the -difference, here is set() used both with and without the escape -parameter. - -:: - - $this->db->set('field', 'field+1', FALSE); - $this->db->insert('mytable'); // gives INSERT INTO mytable (field) VALUES (field+1) - $this->db->set('field', 'field+1'); - $this->db->insert('mytable'); // gives INSERT INTO mytable (field) VALUES ('field+1') - - -You can also pass an associative array to this function:: - - $array = array( - 'name' => $name, - 'title' => $title, - 'status' => $status - ); - - $this->db->set($array); - $this->db->insert('mytable'); - -Or an object:: - - /* - class Myclass { - var $title = 'My Title'; - var $content = 'My Content'; - var $date = 'My Date'; - } - */ - - $object = new Myclass; - $this->db->set($object); - $this->db->insert('mytable'); - - -************* -Updating Data -************* - -$this->db->update() -=================== - -Generates an update string and runs the query based on the data you -supply. You can pass an **array** or an **object** to the function. Here -is an example using an array:: - - $data = array( - 'title' => $title, - 'name' => $name, - 'date' => $date - ); - - $this->db->where('id', $id); - $this->db->update('mytable', $data); - // Produces: // UPDATE mytable // SET title = '{$title}', name = '{$name}', date = '{$date}' // WHERE id = $id - -Or you can supply an object:: - - /* - class Myclass { - var $title = 'My Title'; - var $content = 'My Content'; - var $date = 'My Date'; - } - */ - - $object = new Myclass; - $this->db->where('id', $id); - $this->db->update('mytable', $object); - // Produces: // UPDATE mytable // SET title = '{$title}', name = '{$name}', date = '{$date}' // WHERE id = $id - -.. note:: All values are escaped automatically producing safer queries. - -You'll notice the use of the $this->db->where() function, enabling you -to set the WHERE clause. You can optionally pass this information -directly into the update function as a string:: - - $this->db->update('mytable', $data, "id = 4"); - -Or as an array:: - - $this->db->update('mytable', $data, array('id' => $id)); - -You may also use the $this->db->set() function described above when -performing updates. - -$this->db->update_batch() -========================= - -Generates an update string based on the data you supply, and runs the query. -You can either pass an **array** or an **object** to the function. -Here is an example using an array:: - - $data = array( - array( - 'title' => 'My title' , - 'name' => 'My Name 2' , - 'date' => 'My date 2' - ), - array( - 'title' => 'Another title' , - 'name' => 'Another Name 2' , - 'date' => 'Another date 2' - ) - ); - - $this->db->update_batch('mytable', $data, 'title'); - - // Produces: - // UPDATE `mytable` SET `name` = CASE - // WHEN `title` = 'My title' THEN 'My Name 2' - // WHEN `title` = 'Another title' THEN 'Another Name 2' - // ELSE `name` END, - // `date` = CASE - // WHEN `title` = 'My title' THEN 'My date 2' - // WHEN `title` = 'Another title' THEN 'Another date 2' - // ELSE `date` END - // WHERE `title` IN ('My title','Another title') - -The first parameter will contain the table name, the second is an associative -array of values, the third parameter is the where key. - -.. note:: All values are escaped automatically producing safer queries. - -$this->db->get_compiled_update() -================================ - -This works exactly the same way as ``$this->db->get_compiled_insert()`` except -that it produces an UPDATE SQL string instead of an INSERT SQL string. - -For more information view documentation for `$this->db->get_compiled_insert()`_. - - -************* -Deleting Data -************* - -$this->db->delete() -=================== - -Generates a delete SQL string and runs the query. - -:: - - $this->db->delete('mytable', array('id' => $id)); // Produces: // DELETE FROM mytable // WHERE id = $id - -The first parameter is the table name, the second is the where clause. -You can also use the where() or or_where() functions instead of passing -the data to the second parameter of the function:: - - $this->db->where('id', $id); - $this->db->delete('mytable'); - - // Produces: - // DELETE FROM mytable - // WHERE id = $id - - -An array of table names can be passed into delete() if you would like to -delete data from more than 1 table. - -:: - - $tables = array('table1', 'table2', 'table3'); - $this->db->where('id', '5'); - $this->db->delete($tables); - - -If you want to delete all data from a table, you can use the truncate() -function, or empty_table(). - -$this->db->empty_table() -======================== - -Generates a delete SQL string and runs the -query.:: - - $this->db->empty_table('mytable'); // Produces: DELETE FROM mytable - - -$this->db->truncate() -===================== - -Generates a truncate SQL string and runs the query. - -:: - - $this->db->from('mytable'); - $this->db->truncate(); - - // or - - $this->db->truncate('mytable'); - - // Produce: - // TRUNCATE mytable - -.. note:: If the TRUNCATE command isn't available, truncate() will - execute as "DELETE FROM table". - -$this->db->get_compiled_delete() -================================ -This works exactly the same way as ``$this->db->get_compiled_insert()`` except -that it produces a DELETE SQL string instead of an INSERT SQL string. - -For more information view documentation for `$this->db->get_compiled_insert()`_. - -*************** -Method Chaining -*************** - -Method chaining allows you to simplify your syntax by connecting -multiple functions. Consider this example:: - - $query = $this->db->select('title') - ->where('id', $id) - ->limit(10, 20) - ->get('mytable'); - -.. _ar-caching: - -********************* -Active Record Caching -********************* - -While not "true" caching, Active Record enables you to save (or "cache") -certain parts of your queries for reuse at a later point in your -script's execution. Normally, when an Active Record call is completed, -all stored information is reset for the next call. With caching, you can -prevent this reset, and reuse information easily. - -Cached calls are cumulative. If you make 2 cached select() calls, and -then 2 uncached select() calls, this will result in 4 select() calls. -There are three Caching functions available: - -$this->db->start_cache() -======================== - -This function must be called to begin caching. All Active Record queries -of the correct type (see below for supported queries) are stored for -later use. - -$this->db->stop_cache() -======================= - -This function can be called to stop caching. - -$this->db->flush_cache() -======================== - -This function deletes all items from the Active Record cache. - -Here's a usage example:: - - $this->db->start_cache(); - $this->db->select('field1'); - $this->db->stop_cache(); - $this->db->get('tablename'); - //Generates: SELECT `field1` FROM (`tablename`) - - $this->db->select('field2'); - $this->db->get('tablename'); - //Generates: SELECT `field1`, `field2` FROM (`tablename`) - - $this->db->flush_cache(); - $this->db->select('field2'); - $this->db->get('tablename'); - //Generates: SELECT `field2` FROM (`tablename`) - - -.. note:: The following statements can be cached: select, from, join, - where, like, group_by, having, order_by, set - - -$this->db->reset_query() -======================== - -Resetting Active Record allows you to start fresh with your query without -executing it first using a method like $this->db->get() or $this->db->insert(). -Just like the methods that execute a query, this will *not* reset items you've -cached using `Active Record Caching`_. - -This is useful in situations where you are using Active Record to generate SQL -(ex. ``$this->db->get_compiled_select()``) but then choose to, for instance, -run the query:: - - // Note that the second parameter of the get_compiled_select method is FALSE - $sql = $this->db->select(array('field1','field2')) - ->where('field3',5) - ->get_compiled_select('mytable', FALSE); - - // ... - // Do something crazy with the SQL code... like add it to a cron script for - // later execution or something... - // ... - - $data = $this->db->get()->result_array(); - - // Would execute and return an array of results of the following query: - // SELECT field1, field1 from mytable where field3 = 5; diff --git a/user_guide_src/source/database/configuration.rst b/user_guide_src/source/database/configuration.rst index 040e7e33f..953bbfbcb 100644 --- a/user_guide_src/source/database/configuration.rst +++ b/user_guide_src/source/database/configuration.rst @@ -106,18 +106,18 @@ Note: The name "test" is arbitrary. It can be anything you want. By default we've used the word "default" for the primary connection, but it too can be renamed to something more relevant to your project. -Active Record +Query Builder ------------- -The :doc:`Active Record Class ` is globally enabled or -disabled by setting the $active_record variable in the database +The :doc:`Query Builder Class ` is globally enabled or +disabled by setting the $query_builder variable in the database configuration file to TRUE/FALSE (boolean). If you are not using the -active record class, setting it to FALSE will utilize fewer resources +query builder class, setting it to FALSE will utilize fewer resources when the database classes are initialized. :: - $active_record = TRUE; + $query_builder = TRUE; .. note:: that some CodeIgniter classes such as Sessions require Active Records be enabled to access certain functionality. @@ -134,7 +134,7 @@ Explanation of Values: **database** The name of the database you want to connect to. **dbdriver** The database type. ie: mysql, postgres, odbc, etc. Must be specified in lower case. **dbprefix** An optional table prefix which will added to the table name when running :doc: - `Active Record ` queries. This permits multiple CodeIgniter installations + `Query Builder ` queries. This permits multiple CodeIgniter installations to share one database. **pconnect** TRUE/FALSE (boolean) - Whether to use a persistent connection. **db_debug** TRUE/FALSE (boolean) - Whether database errors should be displayed. diff --git a/user_guide_src/source/database/connecting.rst b/user_guide_src/source/database/connecting.rst index a834cc0f7..4db038e1e 100644 --- a/user_guide_src/source/database/connecting.rst +++ b/user_guide_src/source/database/connecting.rst @@ -36,7 +36,7 @@ Available Parameters string. #. TRUE/FALSE (boolean). Whether to return the connection ID (see Connecting to Multiple Databases below). -#. TRUE/FALSE (boolean). Whether to enable the Active Record class. Set +#. TRUE/FALSE (boolean). Whether to enable the Query Builder class. Set to TRUE by default. Manually Connecting to a Database diff --git a/user_guide_src/source/database/examples.rst b/user_guide_src/source/database/examples.rst index d1cd48837..8b3cc4701 100644 --- a/user_guide_src/source/database/examples.rst +++ b/user_guide_src/source/database/examples.rst @@ -104,10 +104,10 @@ Standard Insert $this->db->query($sql); echo $this->db->affected_rows(); -Active Record Query +Query Builder Query =================== -The :doc:`Active Record Pattern ` gives you a simplified +The :doc:`Query Builder Pattern ` gives you a simplified means of retrieving data:: $query = $this->db->get('table_name'); @@ -118,10 +118,10 @@ means of retrieving data:: } The above get() function retrieves all the results from the supplied -table. The :doc:`Active Record ` class contains a full +table. The :doc:`Query Builder ` class contains a full compliment of functions for working with data. -Active Record Insert +Query Builder Insert ==================== :: diff --git a/user_guide_src/source/database/index.rst b/user_guide_src/source/database/index.rst index ab12b7cb7..7ccb8fb00 100644 --- a/user_guide_src/source/database/index.rst +++ b/user_guide_src/source/database/index.rst @@ -3,7 +3,7 @@ The Database Class ################## CodeIgniter comes with a full-featured and very fast abstracted database -class that supports both traditional structures and Active Record +class that supports both traditional structures and Query Builder patterns. The database functions offer clear, simple syntax. .. toctree:: @@ -15,7 +15,7 @@ patterns. The database functions offer clear, simple syntax. Running Queries Generating Query Results Query Helper Functions - Active Record Class + Query Builder Class Transactions Table MetaData Field MetaData diff --git a/user_guide_src/source/database/queries.rst b/user_guide_src/source/database/queries.rst index 971d5d61d..2ba3d3f4a 100644 --- a/user_guide_src/source/database/queries.rst +++ b/user_guide_src/source/database/queries.rst @@ -50,7 +50,7 @@ Protecting identifiers ********************** In many databases it is advisable to protect table and field names - for -example with backticks in MySQL. **Active Record queries are +example with backticks in MySQL. **Query Builder queries are automatically protected**, however if you need to manually protect an identifier you can use:: diff --git a/user_guide_src/source/database/query_builder.rst b/user_guide_src/source/database/query_builder.rst new file mode 100644 index 000000000..f55d8e2f7 --- /dev/null +++ b/user_guide_src/source/database/query_builder.rst @@ -0,0 +1,1008 @@ +################### +Query Builder Class +################### + +CodeIgniter gives you access to a Query Builder class. This pattern +allows information to be retrieved, inserted, and updated in your +database with minimal scripting. In some cases only one or two lines +of code are necessary to perform a database action. +CodeIgniter does not require that each database table be its own class +file. It instead provides a more simplified interface. + +Beyond simplicity, a major benefit to using the Query Builder features +is that it allows you to create database independent applications, since +the query syntax is generated by each database adapter. It also allows +for safer queries, since the values are escaped automatically by the +system. + +.. note:: If you intend to write your own queries you can disable this + class in your database config file, allowing the core database library + and adapter to utilize fewer resources. + +.. contents:: Page Contents + +************** +Selecting Data +************** + +The following functions allow you to build SQL **SELECT** statements. + +$this->db->get() +================ + +Runs the selection query and returns the result. Can be used by itself +to retrieve all records from a table:: + + $query = $this->db->get('mytable'); // Produces: SELECT * FROM mytable + +The second and third parameters enable you to set a limit and offset +clause:: + + $query = $this->db->get('mytable', 10, 20); + // Produces: SELECT * FROM mytable LIMIT 20, 10 (in MySQL. Other databases have slightly different syntax) + +You'll notice that the above function is assigned to a variable named +$query, which can be used to show the results:: + + $query = $this->db->get('mytable'); + + foreach ($query->result() as $row) + { + echo $row->title; + } + +Please visit the :doc:`result functions ` page for a full +discussion regarding result generation. + +$this->db->get_compiled_select() +================================ + +Compiles the selection query just like `$this->db->get()`_ but does not *run* +the query. This method simply returns the SQL query as a string. + +Example:: + + $sql = $this->db->get_compiled_select('mytable'); + echo $sql; + + // Produces string: SELECT * FROM mytable + +The second parameter enables you to set whether or not the query builder query +will be reset (by default it will be—just like `$this->db->get()`):: + + echo $this->db->limit(10,20)->get_compiled_select('mytable', FALSE); + // Produces string: SELECT * FROM mytable LIMIT 20, 10 + // (in MySQL. Other databases have slightly different syntax) + + echo $this->db->select('title, content, date')->get_compiled_select(); + + // Produces string: SELECT title, content, date FROM mytable + +The key thing to notice in the above example is that the second query did not +utilize `$this->db->from()`_ and did not pass a table name into the first +parameter. The reason for this outcome is because the query has not been +executed using `$this->db->get()`_ which resets values or reset directly +using `$this->db->reset_query()`_. + + +$this->db->get_where() +====================== + +Identical to the above function except that it permits you to add a +"where" clause in the second parameter, instead of using the db->where() +function:: + + $query = $this->db->get_where('mytable', array('id' => $id), $limit, $offset); + +Please read the about the where function below for more information. + +.. note:: get_where() was formerly known as getwhere(), which has been removed + +$this->db->select() +=================== + +Permits you to write the SELECT portion of your query:: + + $this->db->select('title, content, date'); + $query = $this->db->get('mytable'); // Produces: SELECT title, content, date FROM mytable + + +.. note:: If you are selecting all (\*) from a table you do not need to + use this function. When omitted, CodeIgniter assumes you wish to SELECT * + +$this->db->select() accepts an optional second parameter. If you set it +to FALSE, CodeIgniter will not try to protect your field or table names +with backticks. This is useful if you need a compound select statement. + +:: + + $this->db->select('(SELECT SUM(payments.amount) FROM payments WHERE payments.invoice_id=4') AS amount_paid', FALSE); + $query = $this->db->get('mytable'); + + +$this->db->select_max() +======================= + +Writes a "SELECT MAX(field)" portion for your query. You can optionally +include a second parameter to rename the resulting field. + +:: + + $this->db->select_max('age'); + $query = $this->db->get('members'); // Produces: SELECT MAX(age) as age FROM members + + $this->db->select_max('age', 'member_age'); + $query = $this->db->get('members'); // Produces: SELECT MAX(age) as member_age FROM members + + +$this->db->select_min() +======================= + +Writes a "SELECT MIN(field)" portion for your query. As with +select_max(), You can optionally include a second parameter to rename +the resulting field. + +:: + + $this->db->select_min('age'); + $query = $this->db->get('members'); // Produces: SELECT MIN(age) as age FROM members + + +$this->db->select_avg() +======================= + +Writes a "SELECT AVG(field)" portion for your query. As with +select_max(), You can optionally include a second parameter to rename +the resulting field. + +:: + + $this->db->select_avg('age'); + $query = $this->db->get('members'); // Produces: SELECT AVG(age) as age FROM members + + +$this->db->select_sum() +======================= + +Writes a "SELECT SUM(field)" portion for your query. As with +select_max(), You can optionally include a second parameter to rename +the resulting field. + +:: + + $this->db->select_sum('age'); + $query = $this->db->get('members'); // Produces: SELECT SUM(age) as age FROM members + + +$this->db->from() +================= + +Permits you to write the FROM portion of your query:: + + $this->db->select('title, content, date'); + $this->db->from('mytable'); + $query = $this->db->get(); // Produces: SELECT title, content, date FROM mytable + +.. note:: As shown earlier, the FROM portion of your query can be specified + in the $this->db->get() function, so use whichever method you prefer. + +$this->db->join() +================= + +Permits you to write the JOIN portion of your query:: + + $this->db->select('*'); + $this->db->from('blogs'); + $this->db->join('comments', 'comments.id = blogs.id'); + $query = $this->db->get(); + + // Produces: + // SELECT * FROM blogs JOIN comments ON comments.id = blogs.id + +Multiple function calls can be made if you need several joins in one +query. + +If you need a specific type of JOIN you can specify it via the third +parameter of the function. Options are: left, right, outer, inner, left +outer, and right outer. + +:: + + $this->db->join('comments', 'comments.id = blogs.id', 'left'); + // Produces: LEFT JOIN comments ON comments.id = blogs.id + +$this->db->where() +================== + +This function enables you to set **WHERE** clauses using one of four +methods: + +.. note:: All values passed to this function are escaped automatically, + producing safer queries. + +#. **Simple key/value method:** + + :: + + $this->db->where('name', $name); // Produces: WHERE name = 'Joe' + + Notice that the equal sign is added for you. + + If you use multiple function calls they will be chained together with + AND between them: + + :: + + $this->db->where('name', $name); + $this->db->where('title', $title); + $this->db->where('status', $status); + // WHERE name = 'Joe' AND title = 'boss' AND status = 'active' + +#. **Custom key/value method:** + You can include an operator in the first parameter in order to + control the comparison: + + :: + + $this->db->where('name !=', $name); + $this->db->where('id <', $id); // Produces: WHERE name != 'Joe' AND id < 45 + +#. **Associative array method:** + + :: + + $array = array('name' => $name, 'title' => $title, 'status' => $status); + $this->db->where($array); + // Produces: WHERE name = 'Joe' AND title = 'boss' AND status = 'active' + + You can include your own operators using this method as well: + + :: + + $array = array('name !=' => $name, 'id <' => $id, 'date >' => $date); + $this->db->where($array); + +#. **Custom string:** + You can write your own clauses manually:: + + $where = "name='Joe' AND status='boss' OR status='active'"; + $this->db->where($where); + + +$this->db->where() accepts an optional third parameter. If you set it to +FALSE, CodeIgniter will not try to protect your field or table names +with backticks. + +:: + + $this->db->where('MATCH (field) AGAINST ("value")', NULL, FALSE); + + +$this->db->or_where() +===================== + +This function is identical to the one above, except that multiple +instances are joined by OR:: + + $this->db->where('name !=', $name); + $this->db->or_where('id >', $id); // Produces: WHERE name != 'Joe' OR id > 50 + +.. note:: or_where() was formerly known as orwhere(), which has been + removed. + +$this->db->where_in() +===================== + +Generates a WHERE field IN ('item', 'item') SQL query joined with AND if +appropriate + +:: + + $names = array('Frank', 'Todd', 'James'); + $this->db->where_in('username', $names); + // Produces: WHERE username IN ('Frank', 'Todd', 'James') + + +$this->db->or_where_in() +======================== + +Generates a WHERE field IN ('item', 'item') SQL query joined with OR if +appropriate + +:: + + $names = array('Frank', 'Todd', 'James'); + $this->db->or_where_in('username', $names); + // Produces: OR username IN ('Frank', 'Todd', 'James') + + +$this->db->where_not_in() +========================= + +Generates a WHERE field NOT IN ('item', 'item') SQL query joined with +AND if appropriate + +:: + + $names = array('Frank', 'Todd', 'James'); + $this->db->where_not_in('username', $names); + // Produces: WHERE username NOT IN ('Frank', 'Todd', 'James') + + +$this->db->or_where_not_in() +============================ + +Generates a WHERE field NOT IN ('item', 'item') SQL query joined with OR +if appropriate + +:: + + $names = array('Frank', 'Todd', 'James'); + $this->db->or_where_not_in('username', $names); + // Produces: OR username NOT IN ('Frank', 'Todd', 'James') + + +$this->db->like() +================= + +This function enables you to generate **LIKE** clauses, useful for doing +searches. + +.. note:: All values passed to this function are escaped automatically. + +#. **Simple key/value method:** + + :: + + $this->db->like('title', 'match'); // Produces: WHERE title LIKE '%match%' + + If you use multiple function calls they will be chained together with + AND between them:: + + $this->db->like('title', 'match'); + $this->db->like('body', 'match'); + // WHERE title LIKE '%match%' AND body LIKE '%match% + + If you want to control where the wildcard (%) is placed, you can use + an optional third argument. Your options are 'before', 'after' and + 'both' (which is the default). + + :: + + $this->db->like('title', 'match', 'before'); // Produces: WHERE title LIKE '%match' + $this->db->like('title', 'match', 'after'); // Produces: WHERE title LIKE 'match%' + $this->db->like('title', 'match', 'both'); // Produces: WHERE title LIKE '%match%' + +#. **Associative array method:** + + :: + + $array = array('title' => $match, 'page1' => $match, 'page2' => $match); + $this->db->like($array); + // WHERE title LIKE '%match%' AND page1 LIKE '%match%' AND page2 LIKE '%match%' + + +$this->db->or_like() +==================== + +This function is identical to the one above, except that multiple +instances are joined by OR:: + + $this->db->like('title', 'match'); $this->db->or_like('body', $match); + // WHERE title LIKE '%match%' OR body LIKE '%match%' + +.. note:: or_like() was formerly known as orlike(), which has been removed. + +$this->db->not_like() +===================== + +This function is identical to **like()**, except that it generates NOT +LIKE statements:: + + $this->db->not_like('title', 'match'); // WHERE title NOT LIKE '%match% + +$this->db->or_not_like() +======================== + +This function is identical to **not_like()**, except that multiple +instances are joined by OR:: + + $this->db->like('title', 'match'); + $this->db->or_not_like('body', 'match'); + // WHERE title LIKE '%match% OR body NOT LIKE '%match%' + +$this->db->group_by() +===================== + +Permits you to write the GROUP BY portion of your query:: + + $this->db->group_by("title"); // Produces: GROUP BY title + +You can also pass an array of multiple values as well:: + + $this->db->group_by(array("title", "date")); // Produces: GROUP BY title, date + +.. note:: group_by() was formerly known as groupby(), which has been + removed. + +$this->db->distinct() +===================== + +Adds the "DISTINCT" keyword to a query + +:: + + $this->db->distinct(); + $this->db->get('table'); // Produces: SELECT DISTINCT * FROM table + + +$this->db->having() +=================== + +Permits you to write the HAVING portion of your query. There are 2 +possible syntaxes, 1 argument or 2:: + + $this->db->having('user_id = 45'); // Produces: HAVING user_id = 45 + $this->db->having('user_id', 45); // Produces: HAVING user_id = 45 + +You can also pass an array of multiple values as well:: + + $this->db->having(array('title =' => 'My Title', 'id <' => $id)); + // Produces: HAVING title = 'My Title', id < 45 + + +If you are using a database that CodeIgniter escapes queries for, you +can prevent escaping content by passing an optional third argument, and +setting it to FALSE. + +:: + + $this->db->having('user_id', 45); // Produces: HAVING `user_id` = 45 in some databases such as MySQL + $this->db->having('user_id', 45, FALSE); // Produces: HAVING user_id = 45 + + +$this->db->or_having() +====================== + +Identical to having(), only separates multiple clauses with "OR". + +$this->db->order_by() +===================== + +Lets you set an ORDER BY clause. The first parameter contains the name +of the column you would like to order by. The second parameter lets you +set the direction of the result. Options are asc or desc, or random. + +:: + + $this->db->order_by("title", "desc"); // Produces: ORDER BY title DESC + +You can also pass your own string in the first parameter:: + + $this->db->order_by('title desc, name asc'); // Produces: ORDER BY title DESC, name ASC + +Or multiple function calls can be made if you need multiple fields. + +:: + + $this->db->order_by("title", "desc"); + $this->db->order_by("name", "asc"); // Produces: ORDER BY title DESC, name ASC + + +.. note:: order_by() was formerly known as orderby(), which has been + removed. + +.. note:: random ordering is not currently supported in Oracle or MSSQL + drivers. These will default to 'ASC'. + +$this->db->limit() +================== + +Lets you limit the number of rows you would like returned by the query:: + + $this->db->limit(10); // Produces: LIMIT 10 + +The second parameter lets you set a result offset. + +:: + + $this->db->limit(10, 20); // Produces: LIMIT 20, 10 (in MySQL. Other databases have slightly different syntax) + +$this->db->count_all_results() +============================== + +Permits you to determine the number of rows in a particular Active +Record query. Queries will accept Query Builder restrictors such as +where(), or_where(), like(), or_like(), etc. Example:: + + echo $this->db->count_all_results('my_table'); // Produces an integer, like 25 + $this->db->like('title', 'match'); + $this->db->from('my_table'); + echo $this->db->count_all_results(); // Produces an integer, like 17 + +$this->db->count_all() +====================== + +Permits you to determine the number of rows in a particular table. +Submit the table name in the first parameter. Example:: + + echo $this->db->count_all('my_table'); // Produces an integer, like 25 + +************** +Query grouping +************** + +Query grouping allows you to create groups of WHERE clauses by enclosing them in parentheses. This will allow +you to create queries with complex WHERE clauses. Nested groups are supported. Example: + + $this->db->select('*')->from('my_table') + ->group_start() + ->where('a', 'a') + ->or_group_start() + ->where('b', 'b') + ->where('c', 'c') + ->group_end() + ->group_end() + ->where('d', 'd') + ->get(); + + // Generates: + // SELECT * FROM (`my_table`) WHERE ( `a` = 'a' OR ( `b` = 'b' AND `c` = 'c' ) ) AND `d` = 'd' + +.. note:: groups need to be balanced, make sure every group_start() is matched by a group_end(). + +$this->db->group_start() +======================== + +Starts a new group by adding an opening parenthesis to the WHERE clause of the query. + +$this->db->or_group_start() +=========================== + +Starts a new group by adding an opening parenthesis to the WHERE clause of the query, prefixing it with 'OR'. + +$this->db->not_group_start() +============================ + +Starts a new group by adding an opening parenthesis to the WHERE clause of the query, prefixing it with 'NOT'. + +$this->db->or_not_group_start() +=============================== + +Starts a new group by adding an opening parenthesis to the WHERE clause of the query, prefixing it with 'OR NOT'. + +$this->db->group_end() +====================== + +Ends the current group by adding an closing parenthesis to the WHERE clause of the query. + +************** +Inserting Data +************** + +$this->db->insert() +=================== + +Generates an insert string based on the data you supply, and runs the +query. You can either pass an **array** or an **object** to the +function. Here is an example using an array:: + + $data = array( + 'title' => 'My title', + 'name' => 'My Name', + 'date' => 'My date' + ); + + $this->db->insert('mytable', $data); + // Produces: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date') + +The first parameter will contain the table name, the second is an +associative array of values. + +Here is an example using an object:: + + /* + class Myclass { + var $title = 'My Title'; + var $content = 'My Content'; + var $date = 'My Date'; + } + */ + + $object = new Myclass; + $this->db->insert('mytable', $object); + // Produces: INSERT INTO mytable (title, content, date) VALUES ('My Title', 'My Content', 'My Date') + +The first parameter will contain the table name, the second is an +object. + +.. note:: All values are escaped automatically producing safer queries. + +$this->db->get_compiled_insert() +================================ +Compiles the insertion query just like `$this->db->insert()`_ but does not +*run* the query. This method simply returns the SQL query as a string. + +Example:: + + $data = array( + 'title' => 'My title', + 'name' => 'My Name', + 'date' => 'My date' + ); + + $sql = $this->db->set($data)->get_compiled_insert('mytable'); + echo $sql; + + // Produces string: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date') + +The second parameter enables you to set whether or not the query builder query +will be reset (by default it will be--just like `$this->db->insert()`_):: + + echo $this->db->set('title', 'My Title')->get_compiled_insert('mytable', FALSE); + + // Produces string: INSERT INTO mytable (title) VALUES ('My Title') + + echo $this->db->set('content', 'My Content')->get_compiled_insert(); + + // Produces string: INSERT INTO mytable (title, content) VALUES ('My Title', 'My Content') + +The key thing to notice in the above example is that the second query did not +utlize `$this->db->from()`_ nor did it pass a table name into the first +parameter. The reason this worked is because the query has not been executed +using `$this->db->insert()`_ which resets values or reset directly using +`$this->db->reset_query()`_. + +$this->db->insert_batch() +========================= + +Generates an insert string based on the data you supply, and runs the +query. You can either pass an **array** or an **object** to the +function. Here is an example using an array:: + + $data = array( + array( + 'title' => 'My title', + 'name' => 'My Name', + 'date' => 'My date' + ), + array( + 'title' => 'Another title', + 'name' => 'Another Name', + 'date' => 'Another date' + ) + ); + + $this->db->insert_batch('mytable', $data); + // Produces: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date'), ('Another title', 'Another name', 'Another date') + +The first parameter will contain the table name, the second is an +associative array of values. + +.. note:: All values are escaped automatically producing safer queries. + +$this->db->set() +================ + +This function enables you to set values for inserts or updates. + +**It can be used instead of passing a data array directly to the insert +or update functions:** + +:: + + $this->db->set('name', $name); + $this->db->insert('mytable'); // Produces: INSERT INTO mytable (name) VALUES ('{$name}') + +If you use multiple function called they will be assembled properly +based on whether you are doing an insert or an update:: + + $this->db->set('name', $name); + $this->db->set('title', $title); + $this->db->set('status', $status); + $this->db->insert('mytable'); + +**set()** will also accept an optional third parameter ($escape), that +will prevent data from being escaped if set to FALSE. To illustrate the +difference, here is set() used both with and without the escape +parameter. + +:: + + $this->db->set('field', 'field+1', FALSE); + $this->db->insert('mytable'); // gives INSERT INTO mytable (field) VALUES (field+1) + $this->db->set('field', 'field+1'); + $this->db->insert('mytable'); // gives INSERT INTO mytable (field) VALUES ('field+1') + + +You can also pass an associative array to this function:: + + $array = array( + 'name' => $name, + 'title' => $title, + 'status' => $status + ); + + $this->db->set($array); + $this->db->insert('mytable'); + +Or an object:: + + /* + class Myclass { + var $title = 'My Title'; + var $content = 'My Content'; + var $date = 'My Date'; + } + */ + + $object = new Myclass; + $this->db->set($object); + $this->db->insert('mytable'); + + +************* +Updating Data +************* + +$this->db->update() +=================== + +Generates an update string and runs the query based on the data you +supply. You can pass an **array** or an **object** to the function. Here +is an example using an array:: + + $data = array( + 'title' => $title, + 'name' => $name, + 'date' => $date + ); + + $this->db->where('id', $id); + $this->db->update('mytable', $data); + // Produces: // UPDATE mytable // SET title = '{$title}', name = '{$name}', date = '{$date}' // WHERE id = $id + +Or you can supply an object:: + + /* + class Myclass { + var $title = 'My Title'; + var $content = 'My Content'; + var $date = 'My Date'; + } + */ + + $object = new Myclass; + $this->db->where('id', $id); + $this->db->update('mytable', $object); + // Produces: // UPDATE mytable // SET title = '{$title}', name = '{$name}', date = '{$date}' // WHERE id = $id + +.. note:: All values are escaped automatically producing safer queries. + +You'll notice the use of the $this->db->where() function, enabling you +to set the WHERE clause. You can optionally pass this information +directly into the update function as a string:: + + $this->db->update('mytable', $data, "id = 4"); + +Or as an array:: + + $this->db->update('mytable', $data, array('id' => $id)); + +You may also use the $this->db->set() function described above when +performing updates. + +$this->db->update_batch() +========================= + +Generates an update string based on the data you supply, and runs the query. +You can either pass an **array** or an **object** to the function. +Here is an example using an array:: + + $data = array( + array( + 'title' => 'My title' , + 'name' => 'My Name 2' , + 'date' => 'My date 2' + ), + array( + 'title' => 'Another title' , + 'name' => 'Another Name 2' , + 'date' => 'Another date 2' + ) + ); + + $this->db->update_batch('mytable', $data, 'title'); + + // Produces: + // UPDATE `mytable` SET `name` = CASE + // WHEN `title` = 'My title' THEN 'My Name 2' + // WHEN `title` = 'Another title' THEN 'Another Name 2' + // ELSE `name` END, + // `date` = CASE + // WHEN `title` = 'My title' THEN 'My date 2' + // WHEN `title` = 'Another title' THEN 'Another date 2' + // ELSE `date` END + // WHERE `title` IN ('My title','Another title') + +The first parameter will contain the table name, the second is an associative +array of values, the third parameter is the where key. + +.. note:: All values are escaped automatically producing safer queries. + +$this->db->get_compiled_update() +================================ + +This works exactly the same way as ``$this->db->get_compiled_insert()`` except +that it produces an UPDATE SQL string instead of an INSERT SQL string. + +For more information view documentation for `$this->db->get_compiled_insert()`_. + + +************* +Deleting Data +************* + +$this->db->delete() +=================== + +Generates a delete SQL string and runs the query. + +:: + + $this->db->delete('mytable', array('id' => $id)); // Produces: // DELETE FROM mytable // WHERE id = $id + +The first parameter is the table name, the second is the where clause. +You can also use the where() or or_where() functions instead of passing +the data to the second parameter of the function:: + + $this->db->where('id', $id); + $this->db->delete('mytable'); + + // Produces: + // DELETE FROM mytable + // WHERE id = $id + + +An array of table names can be passed into delete() if you would like to +delete data from more than 1 table. + +:: + + $tables = array('table1', 'table2', 'table3'); + $this->db->where('id', '5'); + $this->db->delete($tables); + + +If you want to delete all data from a table, you can use the truncate() +function, or empty_table(). + +$this->db->empty_table() +======================== + +Generates a delete SQL string and runs the +query.:: + + $this->db->empty_table('mytable'); // Produces: DELETE FROM mytable + + +$this->db->truncate() +===================== + +Generates a truncate SQL string and runs the query. + +:: + + $this->db->from('mytable'); + $this->db->truncate(); + + // or + + $this->db->truncate('mytable'); + + // Produce: + // TRUNCATE mytable + +.. note:: If the TRUNCATE command isn't available, truncate() will + execute as "DELETE FROM table". + +$this->db->get_compiled_delete() +================================ +This works exactly the same way as ``$this->db->get_compiled_insert()`` except +that it produces a DELETE SQL string instead of an INSERT SQL string. + +For more information view documentation for `$this->db->get_compiled_insert()`_. + +*************** +Method Chaining +*************** + +Method chaining allows you to simplify your syntax by connecting +multiple functions. Consider this example:: + + $query = $this->db->select('title') + ->where('id', $id) + ->limit(10, 20) + ->get('mytable'); + +.. _ar-caching: + +********************* +Query Builder Caching +********************* + +While not "true" caching, Query Builder enables you to save (or "cache") +certain parts of your queries for reuse at a later point in your +script's execution. Normally, when an Query Builder call is completed, +all stored information is reset for the next call. With caching, you can +prevent this reset, and reuse information easily. + +Cached calls are cumulative. If you make 2 cached select() calls, and +then 2 uncached select() calls, this will result in 4 select() calls. +There are three Caching functions available: + +$this->db->start_cache() +======================== + +This function must be called to begin caching. All Query Builder queries +of the correct type (see below for supported queries) are stored for +later use. + +$this->db->stop_cache() +======================= + +This function can be called to stop caching. + +$this->db->flush_cache() +======================== + +This function deletes all items from the Query Builder cache. + +Here's a usage example:: + + $this->db->start_cache(); + $this->db->select('field1'); + $this->db->stop_cache(); + $this->db->get('tablename'); + //Generates: SELECT `field1` FROM (`tablename`) + + $this->db->select('field2'); + $this->db->get('tablename'); + //Generates: SELECT `field1`, `field2` FROM (`tablename`) + + $this->db->flush_cache(); + $this->db->select('field2'); + $this->db->get('tablename'); + //Generates: SELECT `field2` FROM (`tablename`) + + +.. note:: The following statements can be cached: select, from, join, + where, like, group_by, having, order_by, set + + +$this->db->reset_query() +======================== + +Resetting Query Builder allows you to start fresh with your query without +executing it first using a method like $this->db->get() or $this->db->insert(). +Just like the methods that execute a query, this will *not* reset items you've +cached using `Query Builder Caching`_. + +This is useful in situations where you are using Query Builder to generate SQL +(ex. ``$this->db->get_compiled_select()``) but then choose to, for instance, +run the query:: + + // Note that the second parameter of the get_compiled_select method is FALSE + $sql = $this->db->select(array('field1','field2')) + ->where('field3',5) + ->get_compiled_select('mytable', FALSE); + + // ... + // Do something crazy with the SQL code... like add it to a cron script for + // later execution or something... + // ... + + $data = $this->db->get()->result_array(); + + // Would execute and return an array of results of the following query: + // SELECT field1, field1 from mytable where field3 = 5; -- cgit v1.2.3-24-g4f1b From 11454e039fd82f2fd4ee2f186ad0317e3435f187 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Wed, 22 Feb 2012 16:05:47 +0200 Subject: Add an optional database name parameter to db_select() --- user_guide_src/source/database/connecting.rst | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/connecting.rst b/user_guide_src/source/database/connecting.rst index a834cc0f7..fb4524116 100644 --- a/user_guide_src/source/database/connecting.rst +++ b/user_guide_src/source/database/connecting.rst @@ -122,6 +122,12 @@ return the database object. | $DB1->result(); | etc... +.. note:: You don't need to create separate database configurations if you + only need to use a different database on the same connection. You + can switch to a different database when you need to, like this: + + | $this->db->db_select($database2_name); + Reconnecting / Keeping the Connection Alive =========================================== -- 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') 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 4be5de1d11eefd9f0b7cf0589a2942f067cefe35 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 2 Mar 2012 15:45:41 +0200 Subject: Replaced DB methods _error_message() and _error_number() with error() (issue #1097) --- user_guide_src/source/database/queries.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/queries.rst b/user_guide_src/source/database/queries.rst index 971d5d61d..15a73614a 100644 --- a/user_guide_src/source/database/queries.rst +++ b/user_guide_src/source/database/queries.rst @@ -112,3 +112,20 @@ The secondary benefit of using binds is that the values are automatically escaped, producing safer queries. You don't have to remember to manually escape data; the engine does it automatically for you. + +*************** +Handling Errors +*************** + +$this->db->error(); +=================== + +If you need to get the last error that has occured, the error() method +will return an array containing its code and message. Here's a quick +example:: + + if ( ! $this->db->simple_query('SELECT `example_field` FROM `example_table`')) + { + $error = $this->db->error(); // Has keys 'code' and 'message' + } + -- cgit v1.2.3-24-g4f1b From fdb75418c9c4b87e9d7f15f1b59fe8d55739c8f3 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Mon, 5 Mar 2012 16:32:17 +0200 Subject: Add a note to the num_rows() documentation --- user_guide_src/source/database/results.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/results.rst b/user_guide_src/source/database/results.rst index 4f93c794d..90d2efce3 100644 --- a/user_guide_src/source/database/results.rst +++ b/user_guide_src/source/database/results.rst @@ -150,6 +150,12 @@ is the variable that the query result object is assigned to:: echo $query->num_rows(); +..note:: + Not all database drivers have a native way of getting the total + number of rows for a result set. When this is the case, all of + the data is prefetched and count() is manually called on the + resulting array in order to achieve the same functionality. + $query->num_fields() ===================== @@ -182,5 +188,4 @@ Example:: $row = $query2->row(); echo $row->name; - $query2->free_result();// The $query2 result object will no longer be available - + $query2->free_result(); // The $query2 result object will no longer be available -- cgit v1.2.3-24-g4f1b From 69bb408cefe7ae496353f0d81692699f6ef83353 Mon Sep 17 00:00:00 2001 From: Timothy Warren Date: Mon, 5 Mar 2012 12:49:55 -0500 Subject: Fixed note in documentation --- user_guide_src/source/database/results.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/results.rst b/user_guide_src/source/database/results.rst index 90d2efce3..865345762 100644 --- a/user_guide_src/source/database/results.rst +++ b/user_guide_src/source/database/results.rst @@ -150,7 +150,7 @@ is the variable that the query result object is assigned to:: echo $query->num_rows(); -..note:: +.. note:: Not all database drivers have a native way of getting the total number of rows for a result set. When this is the case, all of the data is prefetched and count() is manually called on the -- cgit v1.2.3-24-g4f1b From 4c4740ec492b30aeb47cb1829525247053e4adfe Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Mon, 12 Mar 2012 16:09:15 +0200 Subject: Postgre to Postgres --- user_guide_src/source/database/configuration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/configuration.rst b/user_guide_src/source/database/configuration.rst index a58492ccc..040e7e33f 100644 --- a/user_guide_src/source/database/configuration.rst +++ b/user_guide_src/source/database/configuration.rst @@ -167,7 +167,7 @@ Explanation of Values: ====================== ================================================================================================== .. note:: Depending on what database platform you are using (MySQL, - Postgre, etc.) not all values will be needed. For example, when using + Postgres, etc.) not all values will be needed. For example, when using SQLite you will not need to supply a username or password, and the database name will be the path to your database file. The information above assumes you are using MySQL. -- cgit v1.2.3-24-g4f1b From 2f3beb258aa291155610579d86a2277d31ce323c Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Mon, 12 Mar 2012 16:34:15 +0200 Subject: Postgres to PostgreSQL --- user_guide_src/source/database/configuration.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/configuration.rst b/user_guide_src/source/database/configuration.rst index 040e7e33f..3f3bae336 100644 --- a/user_guide_src/source/database/configuration.rst +++ b/user_guide_src/source/database/configuration.rst @@ -132,7 +132,7 @@ Explanation of Values: **username** The username used to connect to the database. **password** The password used to connect to the database. **database** The name of the database you want to connect to. -**dbdriver** The database type. ie: mysql, postgres, odbc, etc. Must be specified in lower case. +**dbdriver** The database type. ie: mysql, postgre, odbc, etc. Must be specified in lower case. **dbprefix** An optional table prefix which will added to the table name when running :doc: `Active Record ` queries. This permits multiple CodeIgniter installations to share one database. @@ -166,8 +166,8 @@ Explanation of Values: $db['default']['port'] = 5432; ====================== ================================================================================================== -.. note:: Depending on what database platform you are using (MySQL, - Postgres, etc.) not all values will be needed. For example, when using - SQLite you will not need to supply a username or password, and the - database name will be the path to your database file. The information - above assumes you are using MySQL. +.. note:: Depending on what database platform you are using (MySQL, PostgreSQL, + etc.) not all values will be needed. For example, when using SQLite you + will not need to supply a username or password, and the database name + will be the path to your database file. The information above assumes + you are using MySQL. -- cgit v1.2.3-24-g4f1b From e464b39b8594ef317cf5b47b4e130ee9f63e7bd5 Mon Sep 17 00:00:00 2001 From: Timothy Warren Date: Tue, 13 Mar 2012 14:09:31 -0400 Subject: Active Record documentation cleanup --- user_guide_src/source/database/active_record.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/active_record.rst b/user_guide_src/source/database/active_record.rst index c04e67d2a..e328c11e2 100644 --- a/user_guide_src/source/database/active_record.rst +++ b/user_guide_src/source/database/active_record.rst @@ -68,7 +68,7 @@ Example:: // Produces string: SELECT * FROM mytable The second parameter enables you to set whether or not the active record query -will be reset (by default it will be—just like `$this->db->get()`):: +will be reset (by default it will be just like `$this->db->get()`):: echo $this->db->limit(10,20)->get_compiled_select('mytable', FALSE); // Produces string: SELECT * FROM mytable LIMIT 20, 10 @@ -533,7 +533,7 @@ Query grouping ************** Query grouping allows you to create groups of WHERE clauses by enclosing them in parentheses. This will allow -you to create queries with complex WHERE clauses. Nested groups are supported. Example: +you to create queries with complex WHERE clauses. Nested groups are supported. Example:: $this->db->select('*')->from('my_table') ->group_start() @@ -921,9 +921,9 @@ Method chaining allows you to simplify your syntax by connecting multiple functions. Consider this example:: $query = $this->db->select('title') - ->where('id', $id) - ->limit(10, 20) - ->get('mytable'); + ->where('id', $id) + ->limit(10, 20) + ->get('mytable'); .. _ar-caching: -- 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') 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 From d981e2915cbd37f866e6f74c3a86a41e8a43e02e Mon Sep 17 00:00:00 2001 From: Juan Ignacio Borda Date: Fri, 18 May 2012 18:29:24 -0300 Subject: Added doc notes for unbuffered_row() function --- user_guide_src/source/database/results.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/results.rst b/user_guide_src/source/database/results.rst index 865345762..6a0dbf92a 100644 --- a/user_guide_src/source/database/results.rst +++ b/user_guide_src/source/database/results.rst @@ -136,6 +136,26 @@ parameter: | **$row = $query->next_row('array')** | **$row = $query->previous_row('array')** +.. note:: all the functions above will load the whole result into memory (prefetching) use unbuffered_row() for processing large result sets. + +unbuffered_row($type) +===== + +This function returns a single result row without prefetching the whole result in memory as row() does. +If your query has more than one row, it returns the current row and moves the internal data pointer ahead. +The result is returned as $type could be 'object' (default) or 'array' that will return an associative array. + + + + $query = $this->db->query("YOUR QUERY"); + + while ($row=$query->unbuffered_rows()) + { + echo $row->title; + echo $row->name; + echo $row->body; + } + *********************** Result Helper Functions *********************** -- cgit v1.2.3-24-g4f1b From 49cbec5870612c30b6e5bd0582616d519d1ea515 Mon Sep 17 00:00:00 2001 From: Juan Ignacio Borda Date: Sat, 19 May 2012 09:34:53 -0300 Subject: Fixed some spaces --- user_guide_src/source/database/results.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/results.rst b/user_guide_src/source/database/results.rst index 6a0dbf92a..2158c6df6 100644 --- a/user_guide_src/source/database/results.rst +++ b/user_guide_src/source/database/results.rst @@ -149,7 +149,7 @@ The result is returned as $type could be 'object' (default) or 'array' that will $query = $this->db->query("YOUR QUERY"); - while ($row=$query->unbuffered_rows()) + while ($row = $query->unbuffered_rows()) { echo $row->title; echo $row->name; -- cgit v1.2.3-24-g4f1b From da7c9e033bd33ba27b549dface68e17177115963 Mon Sep 17 00:00:00 2001 From: Juan Ignacio Borda Date: Sat, 19 May 2012 09:42:40 -0300 Subject: Fixed typo --- user_guide_src/source/database/results.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/results.rst b/user_guide_src/source/database/results.rst index 2158c6df6..ac4fc3733 100644 --- a/user_guide_src/source/database/results.rst +++ b/user_guide_src/source/database/results.rst @@ -149,7 +149,7 @@ The result is returned as $type could be 'object' (default) or 'array' that will $query = $this->db->query("YOUR QUERY"); - while ($row = $query->unbuffered_rows()) + while ($row = $query->unbuffered_row()) { echo $row->title; echo $row->name; -- cgit v1.2.3-24-g4f1b From 1922a885b40ef63cf0a5141eb8377d04e3bee172 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 15 Jun 2012 15:16:51 +0300 Subject: Update simple_query() documentation (issue #1484) --- user_guide_src/source/database/queries.rst | 30 +++++++++++++++++++++++++----- 1 file changed, 25 insertions(+), 5 deletions(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/queries.rst b/user_guide_src/source/database/queries.rst index d23efecb3..11dd78392 100644 --- a/user_guide_src/source/database/queries.rst +++ b/user_guide_src/source/database/queries.rst @@ -21,11 +21,31 @@ this:: $this->db->simple_query(); =========================== -This is a simplified version of the $this->db->query() function. It ONLY -returns TRUE/FALSE on success or failure. It DOES NOT return a database -result set, nor does it set the query timer, or compile bind data, or -store your query for debugging. It simply lets you submit a query. Most -users will rarely use this function. +This is a simplified version of the $this->db->query() method. It DOES +NOT return a database result set, nor does it set the query timer, or +compile bind data, or store your query for debugging. It simply lets you +submit a query. Most users will rarely use this function. + +It returns whatever the database drivers' "execute" function returns. +That typically is TRUE/FALSE on success or failure for write type queries +such as INSERT, DELETE or UPDATE statements (which is what it really +should be used for) and a resource/object on success for queries with +fetchable results. + +:: + + if ($this->db->simple_query('YOUR QUERY')) + { + echo "Success!"; + } + else + { + echo "Query failed!"; + } + +.. note:: PostgreSQL's pg_exec() function always returns a resource on + success, even for write type queries. So take that in mind if + you're looking for a boolean value. *************************************** Working with Database prefixes manually -- cgit v1.2.3-24-g4f1b From ff3f7dea40e8fae81dd586b340d30d24154cf5ab Mon Sep 17 00:00:00 2001 From: vlakoff Date: Sat, 16 Jun 2012 14:21:32 +0200 Subject: Documentation: remaining PHP "var" declarations changed to "public" Since PHP 4 isn't supported anymore, let's clean up these few PHP "var" declarations which were remaining in the documentation. According to my checks, there is no more PHP "var" left. --- user_guide_src/source/database/query_builder.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/query_builder.rst b/user_guide_src/source/database/query_builder.rst index 54e8df6b5..b86a0c8db 100644 --- a/user_guide_src/source/database/query_builder.rst +++ b/user_guide_src/source/database/query_builder.rst @@ -603,9 +603,9 @@ Here is an example using an object:: /* class Myclass { - var $title = 'My Title'; - var $content = 'My Content'; - var $date = 'My Date'; + public $title = 'My Title'; + public $content = 'My Content'; + public $date = 'My Date'; } */ @@ -730,9 +730,9 @@ Or an object:: /* class Myclass { - var $title = 'My Title'; - var $content = 'My Content'; - var $date = 'My Date'; + public $title = 'My Title'; + public $content = 'My Content'; + public $date = 'My Date'; } */ @@ -766,9 +766,9 @@ Or you can supply an object:: /* class Myclass { - var $title = 'My Title'; - var $content = 'My Content'; - var $date = 'My Date'; + public $title = 'My Title'; + public $content = 'My Content'; + public $date = 'My Date'; } */ -- cgit v1.2.3-24-g4f1b From ce79be0b5ffc9d5754c93771a8c289a252ec437b Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Mon, 25 Jun 2012 23:23:46 -0700 Subject: Fixing various Sphinx bugs and syntax errors in docs --- user_guide_src/source/database/results.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/results.rst b/user_guide_src/source/database/results.rst index ac4fc3733..d032f734e 100644 --- a/user_guide_src/source/database/results.rst +++ b/user_guide_src/source/database/results.rst @@ -139,13 +139,13 @@ parameter: .. note:: all the functions above will load the whole result into memory (prefetching) use unbuffered_row() for processing large result sets. unbuffered_row($type) -===== +===================== This function returns a single result row without prefetching the whole result in memory as row() does. If your query has more than one row, it returns the current row and moves the internal data pointer ahead. The result is returned as $type could be 'object' (default) or 'array' that will return an associative array. - +:: $query = $this->db->query("YOUR QUERY"); -- cgit v1.2.3-24-g4f1b From b94b91afc77bcc133ff282559015933602bb2d3f Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Wed, 4 Jul 2012 12:32:14 +0300 Subject: Some user guide updates --- user_guide_src/source/database/configuration.rst | 122 +++++++++++++---------- user_guide_src/source/database/connecting.rst | 34 ++++--- 2 files changed, 87 insertions(+), 69 deletions(-) (limited to 'user_guide_src/source/database') diff --git a/user_guide_src/source/database/configuration.rst b/user_guide_src/source/database/configuration.rst index 7a19c840f..c17de600a 100644 --- a/user_guide_src/source/database/configuration.rst +++ b/user_guide_src/source/database/configuration.rst @@ -12,26 +12,44 @@ it the respective environment config folder. The config settings are stored in a multi-dimensional array with this prototype:: - $db['default']['hostname'] = "localhost"; - $db['default']['username'] = "root"; - $db['default']['password'] = ""; - $db['default']['database'] = "database_name"; - $db['default']['dbdriver'] = "mysql"; - $db['default']['dbprefix'] = ""; - $db['default']['pconnect'] = TRUE; - $db['default']['db_debug'] = FALSE; - $db['default']['cache_on'] = FALSE; - $db['default']['cachedir'] = ""; - $db['default']['char_set'] = "utf8"; - $db['default']['dbcollat'] = "utf8_general_ci"; - $db['default']['swap_pre'] = ""; - $db['default']['autoinit'] = TRUE; - $db['default']['stricton'] = FALSE; - -If you use PDO as your dbdriver, you can specify the full DSN string describe a connection to the database like this:: - + $db['default'] = array( + 'dsn' => '', + 'hostname' => 'localhost', + 'username' => 'root', + 'password' => '', + 'database' => 'database_name', + 'dbdriver' => 'mysqli', + 'dbprefix' => '', + 'pconnect' => TRUE, + 'db_debug' => TRUE, + 'cache_on' => FALSE, + 'cachedir' => '', + 'char_set' => 'utf8', + 'dbcollat' => 'utf8_general_ci', + 'swap_pre' => '', + 'autoinit' => TRUE, + 'stricton' => FALSE, + 'failover' => array() + ); + +Some database drivers (such as PDO, PostgreSQL, Oracle, ODBC) might +require a full DSN string to be provided. If that is the case, you +should use the 'dsn' configuration setting, as if you're using the +driver's underlying native PHP extension, like this:: + + // PDO $db['default']['dsn'] = 'pgsql:host=localhost;port=5432;dbname=database_name'; + // Oracle + $db['default']['dsn'] = '//localhost/XE'; + +.. note:: If you do not specify a DSN string for a driver that requires it, CodeIgniter + will try to build it with the rest of the provided settings. + +.. note:: If you provide a DSN string and it is missing some valid settings (e.g. the + database character set), which are present in the rest of the configuration + fields, CodeIgniter will append them. + You can also specify failovers for the situation when the main connection cannot connect for some reason. These failovers can be specified by setting the failover for a connection like this:: @@ -41,7 +59,7 @@ These failovers can be specified by setting the failover for a connection like t 'username' => '', 'password' => '', 'database' => '', - 'dbdriver' => 'mysql', + 'dbdriver' => 'mysqli', 'dbprefix' => '', 'pconnect' => TRUE, 'db_debug' => TRUE, @@ -58,7 +76,7 @@ These failovers can be specified by setting the failover for a connection like t 'username' => '', 'password' => '', 'database' => '', - 'dbdriver' => 'mysql', + 'dbdriver' => 'mysqli', 'dbprefix' => '', 'pconnect' => TRUE, 'db_debug' => TRUE, @@ -81,30 +99,34 @@ production, test, etc.) under a single installation, you can set up a connection group for each, then switch between groups as needed. For example, to set up a "test" environment you would do this:: - $db['test']['hostname'] = "localhost"; - $db['test']['username'] = "root"; - $db['test']['password'] = ""; - $db['test']['database'] = "database_name"; - $db['test']['dbdriver'] = "mysql"; - $db['test']['dbprefix'] = ""; - $db['test']['pconnect'] = TRUE; - $db['test']['db_debug'] = FALSE; - $db['test']['cache_on'] = FALSE; - $db['test']['cachedir'] = ""; - $db['test']['char_set'] = "utf8"; - $db['test']['dbcollat'] = "utf8_general_ci"; - $db['test']['swap_pre'] = ""; - $db['test']['autoinit'] = TRUE; - $db['test']['stricton'] = FALSE; + $db['test'] = array( + 'dsn' => '', + 'hostname' => 'localhost', + 'username' => 'root', + 'password' => '', + 'database' => 'database_name', + 'dbdriver' => 'mysqli', + 'dbprefix' => '', + 'pconnect' => TRUE, + 'db_debug' => TRUE, + 'cache_on' => FALSE, + 'cachedir' => '', + 'char_set' => 'utf8', + 'dbcollat' => 'utf8_general_ci', + 'swap_pre' => '', + 'autoinit' => TRUE, + 'stricton' => FALSE, + 'failover' => array() + ); Then, to globally tell the system to use that group you would set this variable located in the config file:: - $active_group = "test"; + $active_group = 'test'; -Note: The name "test" is arbitrary. It can be anything you want. By -default we've used the word "default" for the primary connection, but it -too can be renamed to something more relevant to your project. +.. note:: The name 'test' is arbitrary. It can be anything you want. By + default we've used the word "default" for the primary connection, + but it too can be renamed to something more relevant to your project. Query Builder ------------- @@ -119,8 +141,8 @@ when the database classes are initialized. $query_builder = TRUE; -.. note:: that some CodeIgniter classes such as Sessions require Active - Records be enabled to access certain functionality. +.. note:: that some CodeIgniter classes such as Sessions require Query + Builder to be enabled to access certain functionality. Explanation of Values: ---------------------- @@ -128,11 +150,12 @@ Explanation of Values: ====================== ================================================================================================== Name Config Description ====================== ================================================================================================== -**hostname** The hostname of your database server. Often this is "localhost". +**dsn** The DSN connect string (an all-in-one configuration sequence). +**hostname** The hostname of your database server. Often this is 'localhost'. **username** The username used to connect to the database. **password** The password used to connect to the database. **database** The name of the database you want to connect to. -**dbdriver** The database type. ie: mysql, postgre, odbc, etc. Must be specified in lower case. +**dbdriver** The database type. ie: mysqli, postgre, odbc, etc. Must be specified in lower case. **dbprefix** An optional table prefix which will added to the table name when running :doc: `Query Builder ` queries. This permits multiple CodeIgniter installations to share one database. @@ -144,14 +167,7 @@ Explanation of Values: **char_set** The character set used in communicating with the database. **dbcollat** The character collation used in communicating with the database - .. note:: For MySQL and MySQLi databases, this setting is only used - as a backup if your server is running PHP < 5.2.3 or MySQL < 5.0.7 - (and in table creation queries made with DB Forge). There is an - incompatibility in PHP with mysql_real_escape_string() which can - make your site vulnerable to SQL injection if you are using a - multi-byte character set and are running versions lower than these. - Sites using Latin-1 or UTF-8 database character set and collation are - unaffected. + .. note:: Only used in the 'mysql' and 'mysqli' drivers. **swap_pre** A default table prefix that should be swapped with dbprefix. This is useful for distributed applications where you might run manually written queries, and need the prefix to still be @@ -163,11 +179,11 @@ Explanation of Values: **port** The database port number. To use this value you have to add a line to the database config array. :: - $db['default']['port'] = 5432; + $db['default']['port'] = 5432; ====================== ================================================================================================== .. note:: Depending on what database platform you are using (MySQL, PostgreSQL, etc.) not all values will be needed. For example, when using SQLite you will not need to supply a username or password, and the database name will be the path to your database file. The information above assumes - you are using MySQL. + you are using MySQL. \ No newline at end of file diff --git a/user_guide_src/source/database/connecting.rst b/user_guide_src/source/database/connecting.rst index 5822ca62c..9b8117076 100644 --- a/user_guide_src/source/database/connecting.rst +++ b/user_guide_src/source/database/connecting.rst @@ -57,25 +57,28 @@ file. To connect manually to a desired database you can pass an array of values:: - $config['hostname'] = "localhost"; - $config['username'] = "myusername"; - $config['password'] = "mypassword"; - $config['database'] = "mydatabase"; - $config['dbdriver'] = "mysql"; - $config['dbprefix'] = ""; - $config['pconnect'] = FALSE; - $config['db_debug'] = TRUE; - $config['cache_on'] = FALSE; - $config['cachedir'] = ""; - $config['char_set'] = "utf8"; - $config['dbcollat'] = "utf8_general_ci"; + $config['hostname'] = 'localhost'; + $config['username'] = 'myusername'; + $config['password'] = 'mypassword'; + $config['database'] = 'mydatabase'; + $config['dbdriver'] = 'mysqli'; + $config['dbprefix'] = ''; + $config['pconnect'] = FALSE; + $config['db_debug'] = TRUE; + $config['cache_on'] = FALSE; + $config['cachedir'] = ''; + $config['char_set'] = 'utf8'; + $config['dbcollat'] = 'utf8_general_ci'; $this->load->database($config); For information on each of these values please see the :doc:`configuration page `. -.. note:: For the PDO driver, $config['hostname'] should look like - this: 'mysql:host=localhost' +.. note:: For the PDO driver, you should use the $config['dsn'] setting + instead of 'hostname' and 'database': + + | + | $config['dsn'] = 'mysql:host=localhost;dbname=mydatabase'; Or you can submit your database values as a Data Source Name. DSNs must have this prototype:: @@ -149,5 +152,4 @@ connections, you can explicitly close the connection. :: - $this->db->close(); - + $this->db->close(); \ No newline at end of file -- cgit v1.2.3-24-g4f1b