From 654b10dd13155b2f49447efbd441f2f3ccf1c045 Mon Sep 17 00:00:00 2001 From: David Seddon Date: Thu, 15 Aug 2024 12:04:08 +0100 Subject: [PATCH 1/3] Tweak a few places in the docs --- README.md | 6 ++---- docs/index.rst | 12 ++++-------- docs/usage/management_commands.rst | 13 +++++++------ docs/usage/operations.rst | 11 +++++------ docs/usage/timeouts.rst | 16 ++++++---------- 5 files changed, 24 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 8290eae..060d653 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,7 @@ # Django Postgres Migration Tools -Django Postgres Migration Tools provides extra functionalities to make Django -migrations safer and more scalable. +Tools to make Django migrations safer and more scalable. ## Documentation -For a full view of the latest documentation, please refer to -[https://django-pg-migration-tools.readthedocs.io/en/latest/](https://django-pg-migration-tools.readthedocs.io/en/latest/) +[Full documentation](https://django-pg-migration-tools.readthedocs.io/en/latest/). diff --git a/docs/index.rst b/docs/index.rst index 6ec40b6..3c6570a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,14 +1,10 @@ -Django Postgres Migration Tools Documentation -============================================= +Django Postgres Migration Tools +=============================== Django Postgres Migration Tools provides extra functionalities to make Django migrations safer and more scalable. -This package supports: - -- Python 3.10 -- Python 3.11 -- Python 3.12 +Supports Python 3.10 - 3.12. Installation ============ @@ -19,7 +15,7 @@ Install from pypi:: .. toctree:: :maxdepth: 3 - :caption: Contents: + :caption: Contents usage/timeouts usage/operations diff --git a/docs/usage/management_commands.rst b/docs/usage/management_commands.rst index c0318d1..a1ed5df 100644 --- a/docs/usage/management_commands.rst +++ b/docs/usage/management_commands.rst @@ -4,6 +4,8 @@ Management Commands migrate_with_timeouts --------------------- +Runs database migrations with timeouts. + This command wraps the :ref:`apply_timeouts() ` around Django's ``migrate`` command, exposing two extra arguments: @@ -17,12 +19,11 @@ Django's ``migrate`` command, exposing two extra arguments: These arguments will set the value of Postgres' ``lock_timeout`` and ``statement_timeout`` for the duration of the migration. -==================== -Example: Basic usage -==================== +========== +How to use +========== -Firstly, make sure to include ``django_pg_migration_tools`` in your -``INSTALLED_APPS``. +1. Include ``django_pg_migration_tools`` in your ``INSTALLED_APPS``. .. code-block:: python @@ -32,7 +33,7 @@ Firstly, make sure to include ``django_pg_migration_tools`` in your ... ] -Now you are all set to run the management command: +2. Run the management command: .. code-block:: bash diff --git a/docs/usage/operations.rst b/docs/usage/operations.rst index 5a3d612..b7bcbee 100644 --- a/docs/usage/operations.rst +++ b/docs/usage/operations.rst @@ -1,8 +1,7 @@ Operations ========== -The `operations` module provides custom migration operations that help -developers perform idempotent and safe schema changes. +Provides custom migration operations that help developers perform idempotent and safe schema changes. Class Definitions ----------------- @@ -69,8 +68,8 @@ Class Definitions -- Reset lock_timeout to its original value ("1s" as an example). SET lock_timeout = '1s'; - Example 1: Basic Usage of ``SaferAddIndexConcurrently`` - ------------------------------------------------------- + How to use + ---------- 1. Add the index to the relevant model: @@ -83,13 +82,13 @@ Class Definitions # existing index models.Index(fields=["bar"], name="bar_idx"), - Make the new migration + 2. Make the new migration: .. code-block:: bash ./manage.py makemigrations - Swap the AddIndex class for our own SaferAddIndexConcurrently class. + 3. Swap the ``AddIndex`` class for our own ``SaferAddIndexConcurrently`` class. Remember to use a non-atomic migration. .. code-block:: diff diff --git a/docs/usage/timeouts.rst b/docs/usage/timeouts.rst index 67957e3..7e74912 100644 --- a/docs/usage/timeouts.rst +++ b/docs/usage/timeouts.rst @@ -1,7 +1,7 @@ Timeouts ======== -The ``timeouts`` facility provides users with the ability to set Postgres +Provides the ability to set Postgres `lock_timeout `_ and `statement_timeout @@ -12,14 +12,10 @@ values. **Why use database timeouts?** - Queries that change the database schema can get blocked because of - long-running transactions and queries. These blocked migration queries, in - turn, block subsequent queries as well. This is the basic ingredient for an - outage. + Timeouts are a way of preventing queries / transactions running for too long. - Using responsible values of ``lock_timeout`` and ``statement_timeout`` in - places where you might have a long-running transaction or query will help - preventing this type of situation in the first place. + Why are long-running queries a problem? It's because they can block queries that change the database schema. + These blocked migration queries, in turn, block subsequent queries as well, potentially causing an outage. Function Definitions -------------------- @@ -62,7 +58,7 @@ Function Definitions Example Usage ------------- -Here are some examples of how to use the ``apply_sync`` function. +Here are some examples of how to use the ``apply_timeouts`` function. ====================== Example 1: Basic Usage @@ -83,7 +79,7 @@ Example 1: Basic Usage using="default", lock_timeout=datetime.timedelta(seconds=5), ): - # Code inside this block will have a lock timeout of 5s + # Code inside this block will have a lock timeout of 5s. ... # We are back to the parent block, so lock timeout is 10s again. From 47995da193ae7256c1122ab6af1104226241d2b6 Mon Sep 17 00:00:00 2001 From: David Seddon Date: Thu, 15 Aug 2024 12:04:45 +0100 Subject: [PATCH 2/3] Remove redundant examples These examples show how not to use it. If someone does this, they'll get helpful error messages anyway, so they are of limited benefit as examples. --- docs/usage/timeouts.rst | 55 ++--------------------------------------- 1 file changed, 2 insertions(+), 53 deletions(-) diff --git a/docs/usage/timeouts.rst b/docs/usage/timeouts.rst index 7e74912..341e563 100644 --- a/docs/usage/timeouts.rst +++ b/docs/usage/timeouts.rst @@ -55,14 +55,8 @@ Function Definitions :return: yields the result. :rtype: Iterator[None] -Example Usage -------------- - -Here are some examples of how to use the ``apply_timeouts`` function. - -====================== -Example 1: Basic Usage -====================== +Example +------- .. code-block:: python @@ -84,48 +78,3 @@ Example 1: Basic Usage # We are back to the parent block, so lock timeout is 10s again. ... - -===================================================== -Example 2: Invalid Parameters: Missing timeout values -===================================================== - -.. code-block:: python - - import datetime - from django_pg_migration_tools import timeouts - - with timeouts.apply_timeouts( - using="default", - ): - pass - -**Output:** - -.. code-block:: text - - django_pg_migration_tools.timeouts.TimeoutNotProvided: Caller must set at least one of `lock_timeout` or `statement_timeout`. - - -============================================================= -Example 3: Invalid Parameters: Negative timeout not permitted -============================================================= - -.. code-block:: python - - import datetime - from django_pg_migration_tools import timeouts - - with timeouts.apply_timeouts( - using="default", - lock_timeout=datetime.timedelta(seconds=-5), - # Either lock_timeout or statement_timeout negative. - # The following would've raised an error as well. - # statement_timeout=datetime.timedelta(seconds=-5), - ): - pass - -**Output:** - -.. code-block:: text - - django_pg_migration_tools.timeouts.TimeoutWasNotPositive: Timeouts must be greater than zero. From 93303b658f72d59cc154c3c4e71997b2591d9ddd Mon Sep 17 00:00:00 2001 From: David Seddon Date: Fri, 16 Aug 2024 09:37:17 +0100 Subject: [PATCH 3/3] Add badges for package and python versions This looks nicer, and means we don't need to remember to update the Python versions as it gets it from the pypi metadata. --- docs/index.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 3c6570a..744ed50 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,11 +1,16 @@ Django Postgres Migration Tools =============================== +.. image:: https://img.shields.io/pypi/v/django-pg-migration-tools.svg + :target: https://pypi.org/project/django-pg-migration-tools + +.. image:: https://img.shields.io/pypi/pyversions/django-pg-migration-tools.svg + :alt: Python versions + :target: https://pypi.org/project/django-pg-migration-tools/ + Django Postgres Migration Tools provides extra functionalities to make Django migrations safer and more scalable. -Supports Python 3.10 - 3.12. - Installation ============