Metadata-Version: 2.1
Name: django_probes
Version: 1.7.0
Summary: Make Django wait until database is ready. Probes for Docker and Kubernetes.
Home-page: https://github.com/painless-software/django-probes
Author: Peter Bittner
Author-email: django@bittner.it
Keywords: django,database,probes,docker,kubernetes
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Framework :: Django
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Django :: 4.0
Classifier: Framework :: Django :: 4.1
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Description-Content-Type: text/x-rst
License-File: LICENSE

Django-probes |latest-version|
==============================

|checks-status| |tests-status| |python-support| |license|

Provides a Django management command to check whether the primary database
is ready to accept connections.

Run this command in a Kubernetes or OpenShift `Init Container`_ to make
your Django application wait until the database is available (e.g. to run
database migrations).

Why Should I Use This App?
--------------------------

``wait_for_database`` is a *single* command for *all* database engines
Django supports. It automatically checks the database you have configured
in your Django project settings. No need to code a specific wait command
for Postgres, MariaDB, Oracle, etc., no need to pull a database engine
specific container just for running the database readiness check.

.. |latest-version| image:: https://img.shields.io/pypi/v/django-probes.svg
   :alt: Latest version on PyPI
   :target: https://pypi.org/project/django-probes
.. |checks-status| image:: https://img.shields.io/github/workflow/status/painless-software/django-probes/Checks/main?label=Checks&logo=github
   :alt: GitHub Workflow Status
   :target: https://github.com/painless-software/django-probes/actions/workflows/check.yml
.. |tests-status| image:: https://img.shields.io/github/workflow/status/painless-software/django-probes/Tests/main?label=Tests&logo=github
   :alt: GitHub Workflow Status
   :target: https://github.com/painless-software/django-probes/actions/workflows/test.yml
.. |python-support| image:: https://img.shields.io/pypi/pyversions/django-probes.svg
   :alt: Python versions
   :target: https://pypi.org/project/django-probes
.. |license| image:: https://img.shields.io/pypi/l/django-probes.svg
   :alt: Software license
   :target: https://github.com/painless-software/django-probes/blob/main/LICENSE

.. _Init Container: https://kubernetes.io/docs/concepts/workloads/pods/init-containers/

Installation
============

The easiest way to install django-probes is with pip

.. code:: console

    $ pip install django-probes

Basic Usage
===========

1. Add django-probes to your Django application:

.. code:: python

    INSTALLED_APPS = [
        ...
        'django_probes',
    ]

2. Add an `Init Container`_ to your Kubernetes/OpenShift deployment
configuration, which calls the ``wait_for_database`` management command:

.. code:: yaml

    - kind: Deployment
      apiVersion: apps/v1
      spec:
        template:
          spec:
            initContainers:
            - name: wait-for-database
              image: my-django-app:latest
              envFrom:
              - secretRef:
                  name: django
              command: ['python', 'manage.py', 'wait_for_database']

Use with Your Own Command
-------------------------

Alternatively, you can integrate the ``wait_for_database`` command in your
own management command, and do things like database migration, load initial
data, etc. with roughly the same Kubernetes setup as above.

.. code:: python

    from django.core.management import call_command

    # ...
    call_command('wait_for_database')

Command Line Options
--------------------

The management command comes with sane defaults, which you can override
if needed:

:--timeout, -t:
    how long to wait for the database before timing out (seconds), default: ``180``
:--stable, -s:
    how long to observe whether connection is stable (seconds), default: ``5``
:--wait-when-down, -d:
    delay between checks when database is down (seconds), default: ``2``
:--wait-when-alive, -a:
    delay between checks when database is up (seconds), default: ``1``
:--database:
    which database of ``settings.DATABASES`` to wait for, default: ``default``
