DatabaseRouter

New in version 0.13.0.

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 and Transmission 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 and Transmission 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.

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.

Message status values

Message and Transmission objects can have the following status values:

  • Inbound values:
    • Q - Queued: Message is queued and awaiting processing
    • R - Received: Message has been processed and responses are queued
    • E - Errored: An error occurred during processing
  • Outbound values:
    • Q - Queued: Message is queued and awaiting processing
    • P - Processing: Message is sending
    • S - Sent: All associated transmissions have been sent
    • D - Delivered: All associated transmissions have been delivered (requires backend functionality)
    • E - Errored: An error occurred during processing