diff --git a/docs/api.rst b/docs/api.rst index ed043e7..4b77294 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -4,7 +4,7 @@ API --- Use these tools to interact with django-cachalot, especially if you face -:ref:`Raw queries limits` or if you need to create a cache key from the +:ref:`raw queries limits ` or if you need to create a cache key from the last table invalidation timestamp. .. automodule:: cachalot.api diff --git a/docs/conf.py b/docs/conf.py index 3904289..1d292d7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -112,7 +112,7 @@ pygments_style = 'sphinx' # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'default' +html_theme = 'sphinx_rtd_theme' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/docs/index.rst b/docs/index.rst index 10a39c8..ae2e8a3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -24,6 +24,7 @@ Caches your Django ORM queries and automatically invalidates them. .. toctree:: :maxdepth: 2 + introduction quickstart limits api diff --git a/docs/introduction.rst b/docs/introduction.rst new file mode 100644 index 0000000..7194b50 --- /dev/null +++ b/docs/introduction.rst @@ -0,0 +1,210 @@ +Introduction +------------ + +Should you use it? +.................. + +Django-cachalot is the perfect speedup tool for most Django projects. +It will speedup a website of 100 000 visits per month without any problem. +In fact, **the more visitors you have, the faster the website becomes**. +That’s because every possible SQL query on the project ends up being cached. + +Django-cachalot is especially efficient in the Django administration website +since it’s unfortunately badly optimised (use foreign keys in list_editable +if you need to be convinced). + +However, it’s not suited for projects where there is **a high number +of modifications per minute** on each table, like a social network with +more than a 30 messages per minute. Django-cachalot may still give a small +speedup in such cases, but it may also slow things a bit +(in the worst case scenario, a 20% slowdown, +according to :ref:`the benchmark `). +If you have a website like that, optimising your SQL database and queries +is the number one thing you have to do. + +There is also an obvious case where you don’t need django-cachalot: +when the project is already fast enough (all pages load in less than 300 ms). +Like any other dependency, django-cachalot is a potential source of problems +(even though it’s currently bug free). +Don’t use dependencies you can avoid, a “future you” may thank you for that. + +Features +........ + +- **Saves in cache the results of any SQL query** generated by the Django ORM + that reads data. These saved results are then returned instead + of executing the same SQL query, which is faster. +- The first time a query is executed is about 10% slower, then the following + times are way faster (7× faster being the average). +- Automatically invalidates saved results, + so that **you never get stale results**. +- **Invalidates per table, not per object**: if you change an object, + all the queries done on other objects of the same model are also invalidated. + This is unfortunately technically impossible to make a reliable + per-object cache. Don’t be fooled by packages pretending having + that per-object feature, they are unreliable and dangerous for your data. +- **Handles everything in the ORM**. You can use the most advanced features + from the ORM without a single issue, django-cachalot is extremely robust. +- An easy control thanks to :ref:`settings` and :ref:`a simple API `. + But that’s only required if you have a complex infrastructure. Most people + will never use settings or the API. +- A few bonus features like + :ref:`a signal triggered at each database change ` + (including bulk changes) and + :ref:`a template tag for a better template fragment caching