DatabaseRouter¶
DatabaseRouter
provides the following functionality:
- All inbound and outbound messages are stored in the database.
- Inbound and outbound messages are processed asynchronously with Celery.
- Outbound messages are automatically split into batches for sending.
- Use of Django’s bulk create to optimize database inserts.
- Messages that fail to send will use Celery’s retry mechanism.
Similar to CeleryRouter
, DatabaseRouter
is designed for
projects that require high messages volumes.
How it works¶
- Before doing any processing, an inbound message is loaded into the
Message
andTransmission
models. A celery task is then queued to process the message asynchronously. - The celery task reconstructs the message object, fires up the router, and passes it off for inbound processing.
- Any replies are loaded into the
Message
andTransmission
models. - The router then divides the outbound messages by backend and queues tasks for sending chunks of messages to their respective backends.
- As tasks complete, the status of the messages are updated in the database, including any errors that occurred.
Installation¶
Note
DatabaseRouter
depends on django-celery 3.0+. Please follow
the django-celery setup instructions before proceeding.
Add rapidsms.router.db
to INSTALLED_APPS
, then import djcelery and
invoke setup_loader()
:
INSTALLED_APPS = (
# Other apps here
"rapidsms.router.db",
)
import djcelery
djcelery.setup_loader()
This will register Celery tasks in rapidsms.router.db.tasks
.
Set RAPIDSMS_ROUTER
to use DatabaseRouter
:
RAPIDSMS_ROUTER = "rapidsms.router.db.DatabaseRouter"
Run syncdb
to create the necessary database tables:
python manage.py syncdb
That’s it!
Configuration¶
The database router has one optional setting,
DB_ROUTER_DEFAULT_BATCH_SIZE
, to change the default
maximum size of a batch of messages from 200.
Celery workers¶
Finally, you’ll need to run the celery worker command (in a separate shell from
runserver
) to begin consuming queued tasks:
python manage.py celery worker --loglevel=info
Now your messages will be handled asynchronously with DatabaseRouter
.
Database models¶
DatabaseRouter
utilizes two database models, Message
and
Transmission
.
Message¶
The Message
model contains the context of a text message. For every associated Connection
, a Message
has an associated Transmission
.
Transmission¶
A Transmission
represents the instance of a particular Message
and Connection
.
Message status values¶
Message
and Transmission
objects can have the following status values:
- Inbound values:
Q
- Queued: Message is queued and awaiting processingR
- Received: Message has been processed and responses are queuedE
- Errored: An error occurred during processing
- Outbound values:
Q
- Queued: Message is queued and awaiting processingP
- Processing: Message is sendingS
- Sent: All associated transmissions have been sentD
- Delivered: All associated transmissions have been delivered (requires backend functionality)E
- Errored: An error occurred during processing