diff options
Diffstat (limited to 'user_guide_src/source/database/caching.rst')
| -rw-r--r-- | user_guide_src/source/database/caching.rst | 152 |
1 files changed, 152 insertions, 0 deletions
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(); + |