DatabaseRouter¶
Please, see the release notes
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
.
-
class
rapidsms.router.db.models.
Message
(id, status, date, updated, sent, delivered, direction, text, external_id, in_response_to)¶ -
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
-
date
¶ Required. Date/time when message was created.
-
delivered
¶ Date/time when all associated transmissions were delivered (requires backend functionality).
-
direction
¶ Required. Either
'I'
or'O'
.
-
external_id
¶ Optional. ID of message as defined by the associated backend.
-
in_response_to
¶ Optional. Foreign key to
Message
that generated this reply.
-
sent
¶ Date/time when all associated transmissions were sent.
-
status
¶ Required. See Message status values.
-
text
¶ Required. Message text.
-
updated
¶ Required. Last date/time the message was updated.
-
exception
Transmission¶
A Transmission
represents the instance of a particular Message
and Connection
.
-
class
rapidsms.router.db.models.
Transmission
(id, message, connection, status, date, updated, sent, delivered)¶ -
exception
DoesNotExist
¶
-
exception
MultipleObjectsReturned
¶
-
connection
¶ Required. Foreign key to associated
Connection
.
-
date
¶ Required. Date/time when transmission was created.
-
delivered
¶ Date/time when transmission was delivered (requires backend functionality).
-
message
¶ Required. Foreign key to associated
Message
.
-
sent
¶ Date/time when transmission was sent.
-
status
¶ Required. See Message status values.
-
updated
¶ Required. Last date/time when transmission was updated.
-
exception
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