django-database-task 0.2.3__tar.gz → 0.3.0__tar.gz

{django_database_task-0.2.3/django_database_task.egg-info → django_database_task-0.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: django-database-task
-Version: 0.2.3
-Summary: A database-backed task queue backend for Django 6.0's built-in task framework
+Version: 0.3.0
+Summary: A database-backed task queue backend for Django's built-in task framework
 Author-email: Shinya Okano <tokibito@gmail.com>
 Maintainer-email: Shinya Okano <tokibito@gmail.com>
 License-Expression: MIT
@@ -9,10 +9,11 @@ Project-URL: Homepage, https://github.com/tokibito/django-database-task
 Project-URL: Repository, https://github.com/tokibito/django-database-task
 Project-URL: Issues, https://github.com/tokibito/django-database-task/issues
 Keywords: django,task,queue,background,database,async
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Web Environment
 Classifier: Framework :: Django
 Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
@@ -31,7 +32,7 @@ Requires-Dist: google-auth>=2.0.0; extra == "cloudtasks"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-django>=4.5; extra == "dev"
-Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: ruff<0.17,>=0.16; extra == "dev"
 Dynamic: license-file
 
 # django-database-task
@@ -41,7 +42,7 @@ Dynamic: license-file
 [![Python versions](https://img.shields.io/pypi/pyversions/django-database-task.svg)](https://pypi.org/project/django-database-task/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A database-backed task queue backend for Django 6.0's built-in task framework.
+A database-backed task queue backend for Django's built-in task framework.
 
 ## Features
 
@@ -51,6 +52,7 @@ A database-backed task queue backend for Django 6.0's built-in task framework.
 - **Exclusive locking** - Prevents duplicate task execution with `SELECT FOR UPDATE SKIP LOCKED`
 - **Django Admin integration** - View and manage tasks from the admin interface
 - **Async support** - Supports async task functions
+- **Graceful shutdown** - Workers finish the running task before exiting on `SIGTERM`
 - **Google Cloud Tasks integration** - Optional backend for GAE/Cloud Run with auto-detection
 
 ## Architecture
@@ -94,15 +96,16 @@ sequenceDiagram
 
 ### Supported Databases
 
-Django 6.0 officially supports the following database versions:
+The minimum database versions are the ones Django itself requires, and Django
+6.1 raised most of them:
 
-| Database | Minimum Version | Notes |
-|----------|-----------------|-------|
-| PostgreSQL | 14+ | Recommended for production. Full `SELECT FOR UPDATE SKIP LOCKED` support. |
-| MySQL | 8.0.11+ | Full `SELECT FOR UPDATE SKIP LOCKED` support. |
-| MariaDB | 10.6+ | Full `SELECT FOR UPDATE SKIP LOCKED` support. |
-| SQLite | 3.31.0+ | Works for development/testing, but no row-level locking. |
-| Oracle | 19c+ | Supported but not tested with this package. |
+| Database | Django 6.0 | Django 6.1 | Notes |
+|----------|------------|------------|-------|
+| PostgreSQL | 14+ | 15+ | Recommended for production. Full `SELECT FOR UPDATE SKIP LOCKED` support. |
+| MySQL | 8.0.11+ | 8.4+ | Full `SELECT FOR UPDATE SKIP LOCKED` support. |
+| MariaDB | 10.6+ | 10.11+ | Full `SELECT FOR UPDATE SKIP LOCKED` support. |
+| SQLite | 3.31.0+ | 3.37.0+ | Works for development/testing, but no row-level locking. |
+| Oracle | 19c+ | 19c+ | Supported but not tested with this package. |
 
 **Note**: `SELECT FOR UPDATE SKIP LOCKED` is used to prevent duplicate task execution in multi-worker environments. SQLite does not support row-level locking, so it is only recommended for development or single-worker deployments.
 
@@ -279,6 +282,24 @@ python manage.py run_database_tasks [options]
 | `--continuous` | Keep polling even when no tasks |
 | `--interval` | Polling interval in seconds (default: 5) |
 | `--max-tasks` | Maximum number of tasks to process (0=unlimited) |
+| `--shutdown-timeout` | Maximum seconds to wait for the running task after `SIGTERM`/`SIGINT` before forcing exit (0=wait indefinitely, default: 0) |
+| `--no-graceful-shutdown` | Do not install signal handlers (terminate immediately, even while a task is running) |
+| `--verbosity` | Output level: `0` silent (errors only), `1` normal (default), `2` also print an idle heartbeat dot per poll |
+
+See [Graceful Shutdown](#graceful-shutdown) for details.
+
+#### Output verbosity
+
+At the default verbosity the worker only prints the startup banner and one
+block per task, so its output stays readable in a log aggregator. Idle polls in
+`--continuous` mode print nothing.
+
+Pass `-v 2` to print a `.` for every poll that found no task - useful when
+watching a worker interactively to confirm it is alive, but it buries real log
+output if left on in production.
+
+Pass `-v 0` to suppress the informational output entirely; task failures and
+errors are still reported.
 
 ### purge_completed_database_tasks
 
@@ -295,6 +316,177 @@ python manage.py purge_completed_database_tasks [options]
 | `--batch-size` | Number of tasks to delete at once (default: 1000) |
 | `--dry-run` | Show count only without deleting |
 
+## Graceful Shutdown
+
+When a worker is redeployed, the orchestrator (Kubernetes, Cloud Run, systemd,
+Docker, supervisord, ...) sends `SIGTERM` and kills the process with `SIGKILL`
+after a grace period. Without any handling, a task that happens to be running
+at that moment is killed halfway through and stays in `RUNNING` status forever.
+
+`run_database_tasks` installs `SIGTERM` and `SIGINT` handlers by default:
+
+1. On the first signal the worker stops fetching new tasks.
+2. The task currently being executed keeps running until it finishes and its
+   result is written to the database.
+3. The worker then exits with status code 0.
+
+While no task is running (the polling sleep in `--continuous` mode), the signal
+is handled immediately - the worker does not wait out the remaining interval.
+
+```console
+$ python manage.py run_database_tasks --continuous
+Worker ID: worker-1-3f2a9c11
+Backend: default
+Continuous mode: interval=5.0s
+Graceful shutdown: enabled (timeout=unlimited)
+
+Processing task: 1e2d... (myapp.tasks.send_report)
+^C
+Received SIGINT: no new tasks will be started. Waiting for the running task to finish (send the signal again to force exit).
+  Task completed successfully
+
+Shutdown complete (no task was interrupted).
+
+Total tasks processed: 1
+```
+
+### Shutdown timeout
+
+By default the worker waits as long as the running task needs. Use
+`--shutdown-timeout` to put an upper bound on it, so the process exits on its
+own terms instead of being `SIGKILL`ed by the platform:
+
+```bash
+python manage.py run_database_tasks --continuous --shutdown-timeout 25
+```
+
+If the task is still running when the timeout expires, the process exits
+immediately with status code 1 and the task stays in `RUNNING` status.
+Set this to a value slightly below the platform's termination grace period,
+and keep the grace period longer than your longest task whenever possible.
+
+Sending the signal a second time (for example pressing Ctrl-C twice) also
+forces an immediate exit.
+
+### Cooperating from inside a task
+
+Long running tasks can check whether a shutdown was requested and stop early,
+so the worker does not have to wait for the whole task to complete:
+
+```python
+from django.tasks import task
+
+from django_database_task import is_shutdown_requested
+
+
+@task
+def import_rows(row_ids):
+    processed = []
+    for row_id in row_ids:
+        if is_shutdown_requested():
+            # Requeue the remaining work and return early
+            import_rows.enqueue([i for i in row_ids if i not in processed])
+            break
+        handle(row_id)
+        processed.append(row_id)
+    return len(processed)
+```
+
+`is_shutdown_requested()` returns `False` when no worker with graceful shutdown
+is active, so tasks using it stay safe to call from a web request, a test, or
+the HTTP endpoints.
+
+### Deployment examples
+
+**Kubernetes** - set `terminationGracePeriodSeconds` longer than the worker's
+shutdown timeout:
+
+```yaml
+spec:
+  terminationGracePeriodSeconds: 60
+  containers:
+    - name: worker
+      command:
+        - python
+        - manage.py
+        - run_database_tasks
+        - --continuous
+        - --shutdown-timeout=50
+```
+
+**systemd** - `TimeoutStopSec` controls how long systemd waits before
+`SIGKILL`:
+
+```ini
+[Service]
+ExecStart=/srv/app/venv/bin/python manage.py run_database_tasks --continuous --shutdown-timeout=50
+KillSignal=SIGTERM
+TimeoutStopSec=60
+Restart=always
+```
+
+**Docker / Docker Compose** - `docker stop` sends `SIGTERM` and waits for
+`--time` (10 seconds by default):
+
+```yaml
+services:
+  worker:
+    command: python manage.py run_database_tasks --continuous --shutdown-timeout=25
+    stop_grace_period: 30s
+```
+
+Make sure the worker is PID 1 or that the signal reaches it (use the exec form
+of `CMD`, or an init such as `tini`, rather than wrapping the command in a
+shell script that swallows signals).
+
+### Tasks left in RUNNING status
+
+If a worker is killed with `SIGKILL` (grace period exceeded, node failure,
+`--no-graceful-shutdown`), the task it was running stays in `RUNNING` status
+because no process is left to update it. Such tasks are not picked up again by
+other workers. They can be found and requeued from the Django admin, or with a
+query like:
+
+```python
+from datetime import timedelta
+
+from django.tasks.base import TaskResultStatus
+from django.utils import timezone
+
+from django_database_task.models import DatabaseTask
+
+stale = DatabaseTask.objects.filter(
+    status=TaskResultStatus.RUNNING,
+    last_attempted_at__lt=timezone.now() - timedelta(hours=1),
+)
+stale.update(status=TaskResultStatus.READY)
+```
+
+Only requeue tasks that are safe to run twice (idempotent).
+
+### Using it in your own worker loop
+
+The shutdown handling is available as a public API, for custom worker loops:
+
+```python
+from django_database_task import GracefulShutdown, process_tasks
+
+with GracefulShutdown(timeout=50) as shutdown:
+    while not shutdown.is_set():
+        results = process_tasks(max_tasks=10, stop_event=shutdown)
+        if not results and shutdown.wait(5):  # interruptible sleep
+            break
+```
+
+| API | Description |
+|-----|-------------|
+| `GracefulShutdown(signals=None, timeout=0, on_signal=None, force_on_repeat=True)` | Context manager that installs the signal handlers |
+| `shutdown.is_set()` | True once a shutdown has been requested |
+| `shutdown.wait(seconds)` | Sleep, returning early (True) when a shutdown is requested |
+| `shutdown.set()` | Request a shutdown programmatically |
+| `process_tasks(..., stop_event=...)` | Stop starting new tasks once the event is set |
+| `is_shutdown_requested()` | True if the active worker was asked to shut down |
+
 ## Programmatic API
 
 You can also process tasks programmatically without management commands:
@@ -330,8 +522,17 @@ if result:
 
 # Retry a failed task
 result = run_task_by_id("...", allow_retry=True)
+
+# Stop starting new tasks when the process receives SIGTERM/SIGINT
+from django_database_task import GracefulShutdown
+
+with GracefulShutdown() as shutdown:
+    results = process_tasks(stop_event=shutdown)
 ```
 
+See [Graceful Shutdown](#graceful-shutdown) for details on `stop_event` and
+`GracefulShutdown`.
+
 ## HTTP Endpoints (Optional)
 
 For environments where cron or direct command execution is not available
@@ -358,7 +559,7 @@ urlpatterns = [
 | `/tasks/run-one/` | POST | Process a single pending task |
 | `/tasks/status/` | GET | Get pending task count |
 | `/tasks/execute/<uuid>/` | POST | Execute a specific task by ID |
-| `/tasks/purge/` | POST | Delete completed tasks |
+| `/tasks/purge/` | GET, POST | Delete completed tasks |
 
 ### Request Parameters
 
@@ -434,10 +635,14 @@ Response (task not found):
 {"error": "Task not found"}  // HTTP 404
 ```
 
-#### POST `/tasks/purge/`
+#### GET/POST `/tasks/purge/`
 
 Delete completed tasks from the database. Useful for cron-based cleanup.
 
+**Note:** GET method is supported for GAE cron compatibility (GAE cron only supports GET requests).
+
+**POST parameters (JSON body):**
+
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `days` | int | 0 | Delete tasks completed more than N days ago (0=all) |
@@ -445,6 +650,15 @@ Delete completed tasks from the database. Useful for cron-based cleanup.
 | `batch_size` | int | 1000 | Number of tasks to delete at once (max: 10000) |
 | `dry_run` | bool | false | If true, return count without deleting |
 
+**GET query parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `days` | int | 0 | Delete tasks completed more than N days ago (0=all) |
+| `status` | string | "SUCCESSFUL,FAILED" | Target statuses, comma-separated |
+| `batch_size` | int | 1000 | Number of tasks to delete at once (max: 10000) |
+| `dry_run` | string | "false" | If "true", return count without deleting |
+
 Response:
 ```json
 {"deleted": 150, "dry_run": false}
@@ -471,15 +685,21 @@ curl -X POST http://localhost:8000/tasks/run/ \
 # Get pending task count
 curl http://localhost:8000/tasks/status/
 
-# Delete tasks completed more than 7 days ago
+# Delete tasks completed more than 7 days ago (POST)
 curl -X POST http://localhost:8000/tasks/purge/ \
   -H "Content-Type: application/json" \
   -d '{"days": 7}'
 
+# Delete tasks completed more than 7 days ago (GET - for GAE cron)
+curl "http://localhost:8000/tasks/purge/?days=7"
+
 # Dry run to check how many tasks would be deleted
 curl -X POST http://localhost:8000/tasks/purge/ \
   -H "Content-Type: application/json" \
   -d '{"days": 30, "dry_run": true}'
+
+# Dry run via GET
+curl "http://localhost:8000/tasks/purge/?days=30&dry_run=true"
 ```
 
 ### Use Cases

{django_database_task-0.2.3 → django_database_task-0.3.0}/README.md

@@ -5,7 +5,7 @@
 [![Python versions](https://img.shields.io/pypi/pyversions/django-database-task.svg)](https://pypi.org/project/django-database-task/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A database-backed task queue backend for Django 6.0's built-in task framework.
+A database-backed task queue backend for Django's built-in task framework.
 
 ## Features
 
@@ -15,6 +15,7 @@ A database-backed task queue backend for Django 6.0's built-in task framework.
 - **Exclusive locking** - Prevents duplicate task execution with `SELECT FOR UPDATE SKIP LOCKED`
 - **Django Admin integration** - View and manage tasks from the admin interface
 - **Async support** - Supports async task functions
+- **Graceful shutdown** - Workers finish the running task before exiting on `SIGTERM`
 - **Google Cloud Tasks integration** - Optional backend for GAE/Cloud Run with auto-detection
 
 ## Architecture
@@ -58,15 +59,16 @@ sequenceDiagram
 
 ### Supported Databases
 
-Django 6.0 officially supports the following database versions:
+The minimum database versions are the ones Django itself requires, and Django
+6.1 raised most of them:
 
-| Database | Minimum Version | Notes |
-|----------|-----------------|-------|
-| PostgreSQL | 14+ | Recommended for production. Full `SELECT FOR UPDATE SKIP LOCKED` support. |
-| MySQL | 8.0.11+ | Full `SELECT FOR UPDATE SKIP LOCKED` support. |
-| MariaDB | 10.6+ | Full `SELECT FOR UPDATE SKIP LOCKED` support. |
-| SQLite | 3.31.0+ | Works for development/testing, but no row-level locking. |
-| Oracle | 19c+ | Supported but not tested with this package. |
+| Database | Django 6.0 | Django 6.1 | Notes |
+|----------|------------|------------|-------|
+| PostgreSQL | 14+ | 15+ | Recommended for production. Full `SELECT FOR UPDATE SKIP LOCKED` support. |
+| MySQL | 8.0.11+ | 8.4+ | Full `SELECT FOR UPDATE SKIP LOCKED` support. |
+| MariaDB | 10.6+ | 10.11+ | Full `SELECT FOR UPDATE SKIP LOCKED` support. |
+| SQLite | 3.31.0+ | 3.37.0+ | Works for development/testing, but no row-level locking. |
+| Oracle | 19c+ | 19c+ | Supported but not tested with this package. |
 
 **Note**: `SELECT FOR UPDATE SKIP LOCKED` is used to prevent duplicate task execution in multi-worker environments. SQLite does not support row-level locking, so it is only recommended for development or single-worker deployments.
 
@@ -243,6 +245,24 @@ python manage.py run_database_tasks [options]
 | `--continuous` | Keep polling even when no tasks |
 | `--interval` | Polling interval in seconds (default: 5) |
 | `--max-tasks` | Maximum number of tasks to process (0=unlimited) |
+| `--shutdown-timeout` | Maximum seconds to wait for the running task after `SIGTERM`/`SIGINT` before forcing exit (0=wait indefinitely, default: 0) |
+| `--no-graceful-shutdown` | Do not install signal handlers (terminate immediately, even while a task is running) |
+| `--verbosity` | Output level: `0` silent (errors only), `1` normal (default), `2` also print an idle heartbeat dot per poll |
+
+See [Graceful Shutdown](#graceful-shutdown) for details.
+
+#### Output verbosity
+
+At the default verbosity the worker only prints the startup banner and one
+block per task, so its output stays readable in a log aggregator. Idle polls in
+`--continuous` mode print nothing.
+
+Pass `-v 2` to print a `.` for every poll that found no task - useful when
+watching a worker interactively to confirm it is alive, but it buries real log
+output if left on in production.
+
+Pass `-v 0` to suppress the informational output entirely; task failures and
+errors are still reported.
 
 ### purge_completed_database_tasks
 
@@ -259,6 +279,177 @@ python manage.py purge_completed_database_tasks [options]
 | `--batch-size` | Number of tasks to delete at once (default: 1000) |
 | `--dry-run` | Show count only without deleting |
 
+## Graceful Shutdown
+
+When a worker is redeployed, the orchestrator (Kubernetes, Cloud Run, systemd,
+Docker, supervisord, ...) sends `SIGTERM` and kills the process with `SIGKILL`
+after a grace period. Without any handling, a task that happens to be running
+at that moment is killed halfway through and stays in `RUNNING` status forever.
+
+`run_database_tasks` installs `SIGTERM` and `SIGINT` handlers by default:
+
+1. On the first signal the worker stops fetching new tasks.
+2. The task currently being executed keeps running until it finishes and its
+   result is written to the database.
+3. The worker then exits with status code 0.
+
+While no task is running (the polling sleep in `--continuous` mode), the signal
+is handled immediately - the worker does not wait out the remaining interval.
+
+```console
+$ python manage.py run_database_tasks --continuous
+Worker ID: worker-1-3f2a9c11
+Backend: default
+Continuous mode: interval=5.0s
+Graceful shutdown: enabled (timeout=unlimited)
+
+Processing task: 1e2d... (myapp.tasks.send_report)
+^C
+Received SIGINT: no new tasks will be started. Waiting for the running task to finish (send the signal again to force exit).
+  Task completed successfully
+
+Shutdown complete (no task was interrupted).
+
+Total tasks processed: 1
+```
+
+### Shutdown timeout
+
+By default the worker waits as long as the running task needs. Use
+`--shutdown-timeout` to put an upper bound on it, so the process exits on its
+own terms instead of being `SIGKILL`ed by the platform:
+
+```bash
+python manage.py run_database_tasks --continuous --shutdown-timeout 25
+```
+
+If the task is still running when the timeout expires, the process exits
+immediately with status code 1 and the task stays in `RUNNING` status.
+Set this to a value slightly below the platform's termination grace period,
+and keep the grace period longer than your longest task whenever possible.
+
+Sending the signal a second time (for example pressing Ctrl-C twice) also
+forces an immediate exit.
+
+### Cooperating from inside a task
+
+Long running tasks can check whether a shutdown was requested and stop early,
+so the worker does not have to wait for the whole task to complete:
+
+```python
+from django.tasks import task
+
+from django_database_task import is_shutdown_requested
+
+
+@task
+def import_rows(row_ids):
+    processed = []
+    for row_id in row_ids:
+        if is_shutdown_requested():
+            # Requeue the remaining work and return early
+            import_rows.enqueue([i for i in row_ids if i not in processed])
+            break
+        handle(row_id)
+        processed.append(row_id)
+    return len(processed)
+```
+
+`is_shutdown_requested()` returns `False` when no worker with graceful shutdown
+is active, so tasks using it stay safe to call from a web request, a test, or
+the HTTP endpoints.
+
+### Deployment examples
+
+**Kubernetes** - set `terminationGracePeriodSeconds` longer than the worker's
+shutdown timeout:
+
+```yaml
+spec:
+  terminationGracePeriodSeconds: 60
+  containers:
+    - name: worker
+      command:
+        - python
+        - manage.py
+        - run_database_tasks
+        - --continuous
+        - --shutdown-timeout=50
+```
+
+**systemd** - `TimeoutStopSec` controls how long systemd waits before
+`SIGKILL`:
+
+```ini
+[Service]
+ExecStart=/srv/app/venv/bin/python manage.py run_database_tasks --continuous --shutdown-timeout=50
+KillSignal=SIGTERM
+TimeoutStopSec=60
+Restart=always
+```
+
+**Docker / Docker Compose** - `docker stop` sends `SIGTERM` and waits for
+`--time` (10 seconds by default):
+
+```yaml
+services:
+  worker:
+    command: python manage.py run_database_tasks --continuous --shutdown-timeout=25
+    stop_grace_period: 30s
+```
+
+Make sure the worker is PID 1 or that the signal reaches it (use the exec form
+of `CMD`, or an init such as `tini`, rather than wrapping the command in a
+shell script that swallows signals).
+
+### Tasks left in RUNNING status
+
+If a worker is killed with `SIGKILL` (grace period exceeded, node failure,
+`--no-graceful-shutdown`), the task it was running stays in `RUNNING` status
+because no process is left to update it. Such tasks are not picked up again by
+other workers. They can be found and requeued from the Django admin, or with a
+query like:
+
+```python
+from datetime import timedelta
+
+from django.tasks.base import TaskResultStatus
+from django.utils import timezone
+
+from django_database_task.models import DatabaseTask
+
+stale = DatabaseTask.objects.filter(
+    status=TaskResultStatus.RUNNING,
+    last_attempted_at__lt=timezone.now() - timedelta(hours=1),
+)
+stale.update(status=TaskResultStatus.READY)
+```
+
+Only requeue tasks that are safe to run twice (idempotent).
+
+### Using it in your own worker loop
+
+The shutdown handling is available as a public API, for custom worker loops:
+
+```python
+from django_database_task import GracefulShutdown, process_tasks
+
+with GracefulShutdown(timeout=50) as shutdown:
+    while not shutdown.is_set():
+        results = process_tasks(max_tasks=10, stop_event=shutdown)
+        if not results and shutdown.wait(5):  # interruptible sleep
+            break
+```
+
+| API | Description |
+|-----|-------------|
+| `GracefulShutdown(signals=None, timeout=0, on_signal=None, force_on_repeat=True)` | Context manager that installs the signal handlers |
+| `shutdown.is_set()` | True once a shutdown has been requested |
+| `shutdown.wait(seconds)` | Sleep, returning early (True) when a shutdown is requested |
+| `shutdown.set()` | Request a shutdown programmatically |
+| `process_tasks(..., stop_event=...)` | Stop starting new tasks once the event is set |
+| `is_shutdown_requested()` | True if the active worker was asked to shut down |
+
 ## Programmatic API
 
 You can also process tasks programmatically without management commands:
@@ -294,8 +485,17 @@ if result:
 
 # Retry a failed task
 result = run_task_by_id("...", allow_retry=True)
+
+# Stop starting new tasks when the process receives SIGTERM/SIGINT
+from django_database_task import GracefulShutdown
+
+with GracefulShutdown() as shutdown:
+    results = process_tasks(stop_event=shutdown)
 ```
 
+See [Graceful Shutdown](#graceful-shutdown) for details on `stop_event` and
+`GracefulShutdown`.
+
 ## HTTP Endpoints (Optional)
 
 For environments where cron or direct command execution is not available
@@ -322,7 +522,7 @@ urlpatterns = [
 | `/tasks/run-one/` | POST | Process a single pending task |
 | `/tasks/status/` | GET | Get pending task count |
 | `/tasks/execute/<uuid>/` | POST | Execute a specific task by ID |
-| `/tasks/purge/` | POST | Delete completed tasks |
+| `/tasks/purge/` | GET, POST | Delete completed tasks |
 
 ### Request Parameters
 
@@ -398,10 +598,14 @@ Response (task not found):
 {"error": "Task not found"}  // HTTP 404
 ```
 
-#### POST `/tasks/purge/`
+#### GET/POST `/tasks/purge/`
 
 Delete completed tasks from the database. Useful for cron-based cleanup.
 
+**Note:** GET method is supported for GAE cron compatibility (GAE cron only supports GET requests).
+
+**POST parameters (JSON body):**
+
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `days` | int | 0 | Delete tasks completed more than N days ago (0=all) |
@@ -409,6 +613,15 @@ Delete completed tasks from the database. Useful for cron-based cleanup.
 | `batch_size` | int | 1000 | Number of tasks to delete at once (max: 10000) |
 | `dry_run` | bool | false | If true, return count without deleting |
 
+**GET query parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `days` | int | 0 | Delete tasks completed more than N days ago (0=all) |
+| `status` | string | "SUCCESSFUL,FAILED" | Target statuses, comma-separated |
+| `batch_size` | int | 1000 | Number of tasks to delete at once (max: 10000) |
+| `dry_run` | string | "false" | If "true", return count without deleting |
+
 Response:
 ```json
 {"deleted": 150, "dry_run": false}
@@ -435,15 +648,21 @@ curl -X POST http://localhost:8000/tasks/run/ \
 # Get pending task count
 curl http://localhost:8000/tasks/status/
 
-# Delete tasks completed more than 7 days ago
+# Delete tasks completed more than 7 days ago (POST)
 curl -X POST http://localhost:8000/tasks/purge/ \
   -H "Content-Type: application/json" \
   -d '{"days": 7}'
 
+# Delete tasks completed more than 7 days ago (GET - for GAE cron)
+curl "http://localhost:8000/tasks/purge/?days=7"
+
 # Dry run to check how many tasks would be deleted
 curl -X POST http://localhost:8000/tasks/purge/ \
   -H "Content-Type: application/json" \
   -d '{"days": 30, "dry_run": true}'
+
+# Dry run via GET
+curl "http://localhost:8000/tasks/purge/?days=30&dry_run=true"
 ```
 
 ### Use Cases