diff --git a/README.md b/README.md index dddc5b5..52e4330 100644 --- a/README.md +++ b/README.md @@ -135,17 +135,15 @@ def my_job(): pass -# The `ensure_old_connections_are_closed` decorator ensures that database connections, that -# have become unusable or are obsolete, are closed before and after our job has run. -# -# It is only required when your job needs to access the database and you are NOT making use -# of a database connection pooler. -@util.ensure_old_connections_are_closed +# The `close_old_connections` decorator ensures that database connections, that have become unusable or are obsolete, +# are closed before and after our job has run. +@util.close_old_connections def delete_old_job_executions(max_age=604_800): """ - This job deletes all APScheduler job executions older than `max_age` from the database. + This job deletes APScheduler job execution entries older than `max_age` from the database. It helps to prevent the + database from filling up with old historical records that are no longer useful. - :param max_age: The maximum length of time to retain old job execution records. Defaults + :param max_age: The maximum length of time to retain historical job execution records. Defaults to 7 days. """ DjangoJobExecution.objects.delete_old_job_executions(max_age) @@ -229,10 +227,10 @@ database [configuration settings](https://docs.djangoproject.com/en/dev/ref/data in combination with how your database server has been configured, determine how connection management will be performed for your specific deployment. -If your APScheduler jobs require database access, and you are **not** making use of a connection pooler and persistent -connections, then it is probably a good idea to wrap those jobs in a `ensure_old_connections_are_closed` decorator to -ensure that Django's [CONN_MAX_AGE](https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-CONN_MAX_AGE) -configuration setting is enforced before and after your job is run. +The `close_old_connections` decorator should be applied to APScheduler jobs that require database access. Doing so +ensures that Django's [CONN_MAX_AGE](https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-CONN_MAX_AGE) +configuration setting is enforced before and after your job is run. This mirrors the standard Django functionality of +doing the same before and after handling each HTTP request. If you still encounter any kind of 'lost database connection' errors then it probably means that: diff --git a/django_apscheduler/util.py b/django_apscheduler/util.py index 64fdf2c..dac4600 100644 --- a/django_apscheduler/util.py +++ b/django_apscheduler/util.py @@ -109,7 +109,7 @@ def func_wrapper(*args, **kwargs): return func_wrapper -def ensure_old_connections_are_closed(func): +def close_old_connections(func): """ A decorator that ensures that Django database connections that have become unusable, or are obsolete, are closed before and after a method is executed (see: https://docs.djangoproject.com/en/dev/ref/databases/#general-notes diff --git a/docs/changelog.md b/docs/changelog.md index 336ee18..47b73c2 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -17,8 +17,8 @@ This changelog is used to track all major changes to django-apscheduler. - Introduce a `retry_on_db_operational_error` utility decorator for retrying database-related operations when a `django.db.OperationalError` is encountered (Partial resolution of [#145](https://github.com/jcass77/django-apscheduler/issues/145)). -- Introduce a `ensure_old_connections_are_closed` utility decorator that can be used in jobs that require a fresh - connection to the database to always be available (Partial resolution +- Introduce a `close_old_connections` utility decorator that can be used in jobs that require a fresh connection to the + database to always be available (Partial resolution of [#145](https://github.com/jcass77/django-apscheduler/issues/145)). ## v0.5.2 (2021-01-28) diff --git a/tests/test_util.py b/tests/test_util.py index 413c6da..167a3d2 100644 --- a/tests/test_util.py +++ b/tests/test_util.py @@ -147,8 +147,8 @@ def func(): ) -def test_ensure_old_connections_are_closed_calls_close_old_connections(): - @util.ensure_old_connections_are_closed +def test_close_old_connections_calls_close_old_connections(): + @util.close_old_connections def job_mock(): pass @@ -160,8 +160,8 @@ def job_mock(): assert close_old_connections_mock.call_count == 2 -def test_ensure_old_connections_are_closed_even_if_exception_is_raised(): - @util.ensure_old_connections_are_closed +def test_close_old_connections_even_if_exception_is_raised(): + @util.close_old_connections def job_mock(): raise RuntimeError("some error")