0
# Scheduling
1

2
Job scheduling functionality for delayed execution, periodic tasks, and scheduler management using RQ's built-in scheduler or the optional rq-scheduler package.
3

4
## Capabilities
5

6
### Scheduler Access
7

8
Get scheduler instances for managing delayed and periodic jobs.
9

10
```python { .api }
11
def get_scheduler(name='default', queue=None, interval=60, connection=None):
12
    """
13
    Get RQ Scheduler instance for delayed/periodic jobs.
14
    
15
    Args:
16
        name: Queue name for scheduler
17
        queue: Queue instance (optional)
18
        interval: Scheduler polling interval in seconds
19
        connection: Redis connection (optional)
20
        
21
    Returns:
22
        DjangoScheduler: Scheduler instance
23
        
24
    Raises:
25
        ImproperlyConfigured: If rq-scheduler not installed
26
    """
27
```
28

29
Usage examples:
30

31
```python
32
import django_rq
33
from datetime import datetime, timedelta
34

35
# Get scheduler for default queue
36
scheduler = django_rq.get_scheduler()
37

38
# Get scheduler for specific queue
39
scheduler = django_rq.get_scheduler('high')
40

41
# Schedule job for specific time
42
def my_task():
43
    return "Scheduled task executed"
44

45
# Schedule for specific datetime
46
run_time = datetime.now() + timedelta(hours=1)
47
job = scheduler.enqueue_at(run_time, my_task)
48

49
# Schedule with delay
50
job = scheduler.enqueue_in(timedelta(minutes=30), my_task)
51
```
52

53
### Built-in RQ Scheduler
54

55
RQ 1.2.0+ includes built-in scheduling support.
56

57
```python
58
# Using queue methods for built-in scheduler
59
queue = django_rq.get_queue('default')
60

61
# Schedule job for specific time
62
from datetime import datetime
63
run_time = datetime(2024, 12, 25, 9, 0, 0)
64
job = queue.enqueue_at(run_time, my_task)
65

66
# Schedule with delay
67
from datetime import timedelta
68
job = queue.enqueue_in(timedelta(hours=2), my_task)
69
```
70

71
### Django-Specific Scheduler
72

73
Enhanced scheduler class with Django settings integration.
74

75
```python { .api }
76
class DjangoScheduler:
77
    """
78
    Django-specific Scheduler extending rq-scheduler.
79
    
80
    Features:
81
    - Automatic timeout configuration from RQ_QUEUES
82
    - Result TTL configuration from RQ settings
83
    - Integration with Django queue configuration
84
    """
85
    
86
    def _create_job(self, *args, **kwargs):
87
        """
88
        Create scheduled job with Django settings integration.
89
        
90
        Automatically applies:
91
        - DEFAULT_TIMEOUT from queue configuration
92
        - DEFAULT_RESULT_TTL from RQ settings
93
        """
94
```
95

96
### Scheduler Management Commands
97

98
Django management commands for scheduler control.
99

100
```python { .api }
101
# Management commands (via manage.py)
102
# python manage.py rqscheduler [--interval=60] [--queue=default]
103
```
104

105
The `rqscheduler` command:
106
- Starts the RQ scheduler daemon
107
- Processes scheduled jobs at configured intervals
108
- Supports custom scheduler classes via settings
109
- Handles graceful shutdown and error recovery
110

111
### Periodic Jobs
112

113
Create recurring jobs with various scheduling patterns.
114

115
```python
116
import django_rq
117
from datetime import datetime, timedelta
118

119
scheduler = django_rq.get_scheduler()
120

121
def maintenance_task():
122
    return "Maintenance completed"
123

124
# Schedule recurring job
125
from rq_scheduler import Scheduler
126

127
# Daily at 2 AM
128
scheduler.schedule(
129
    scheduled_time=datetime.now().replace(hour=2, minute=0, second=0),
130
    func=maintenance_task,
131
    interval=86400,  # 24 hours in seconds
132
    repeat=None      # Repeat indefinitely
133
)
134

135
# Weekly backup
136
scheduler.schedule(
137
    scheduled_time=datetime.now() + timedelta(days=7),
138
    func=maintenance_task,
139
    interval=604800,  # 1 week in seconds
140
    repeat=10        # Repeat 10 times
141
)
142
```
143

144
### Cron-style Scheduling
145

146
Using the `rq-cron` package for cron-like scheduling:
147

148
```python
149
from rq_cron import cron
150

151
# Register cron job
152
@cron('0 2 * * *')  # Daily at 2 AM
153
def daily_cleanup():
154
    return "Daily cleanup completed"
155

156
# Register with specific queue
157
@cron('0 */6 * * *', queue='maintenance')  # Every 6 hours
158
def periodic_maintenance():
159
    return "Maintenance completed"
160
```
161

162
## Scheduler Configuration
163

164
Configure scheduler behavior through Django settings:
165

166
```python
167
# settings.py
168
RQ = {
169
    'SCHEDULER_CLASS': 'myapp.schedulers.CustomScheduler',
170
    'DEFAULT_RESULT_TTL': 3600,
171
}
172

173
RQ_QUEUES = {
174
    'default': {
175
        'HOST': 'localhost',
176
        'PORT': 6379,
177
        'DB': 0,
178
        'DEFAULT_TIMEOUT': 360,
179
    }
180
}
181
```
182

183
## Scheduler Statistics
184

185
Monitor scheduled jobs and scheduler status:
186

187
```python { .api }
188
def get_scheduler_statistics():
189
    """
190
    Get scheduler statistics across all Redis connections.
191
    
192
    Returns:
193
        dict: Scheduler statistics including job counts
194
    """
195
```
196

197
Statistics include:
198
- Number of scheduled jobs per connection
199
- Scheduler status and configuration
200
- Connection information for each scheduler
201

202
## Working with Scheduled Jobs
203

204
### Job Management
205

206
```python
207
import django_rq
208

209
scheduler = django_rq.get_scheduler()
210

211
# List scheduled jobs
212
jobs = scheduler.get_jobs()
213

214
# Cancel scheduled job
215
scheduler.cancel(job)
216

217
# Reschedule job
218
scheduler.cancel(job)
219
new_job = scheduler.enqueue_at(new_time, job.func, *job.args, **job.kwargs)
220
```
221

222
### Job Persistence
223

224
Scheduled jobs are persisted in Redis and survive:
225
- Worker restarts
226
- Application restarts
227
- Redis restarts (with persistence enabled)
228

229
### Error Handling
230

231
Scheduled jobs follow standard RQ error handling:
232
- Failed jobs moved to failed registry
233
- Retry mechanisms available
234
- Exception handlers apply to scheduled jobs
235
- Monitoring integration works with scheduled jobs
236

237
## Built-in vs rq-scheduler
238

239
### Built-in Scheduler (RQ 1.2.0+)
240
- Simpler setup, no additional dependencies
241
- Basic scheduling functionality
242
- Worker-based scheduling (requires `--with-scheduler` flag)
243
- Good for simple delayed jobs
244

245
### rq-scheduler Package
246
- More advanced scheduling features
247
- Separate scheduler daemon process
248
- Cron-like scheduling support
249
- Better for complex periodic tasks
250
- Requires additional installation: `pip install rq-scheduler`
251

252
## Performance Considerations
253

254
- Use appropriate polling intervals for scheduler daemon
255
- Consider Redis memory usage for large numbers of scheduled jobs
256
- Monitor scheduler process health in production
257
- Use separate Redis database for scheduled jobs if needed
258
- Consider timezone handling for scheduled jobs