DatabaseRouter

New in version 0.13.0: 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 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(*args, **kwargs)

Message(id, status, date, updated, sent, delivered, direction, text, external_id, in_response_to_id)

date = None

Required. Date/time when message was created.

delivered = None

Date/time when all associated transmissions were delivered (requires backend functionality).

direction = None

Required. Either 'I' or 'O'.

external_id = None

Optional. ID of message as defined by the associated backend.

in_response_to

Optional. Foreign key to Message that generated this reply.

sent = None

Date/time when all associated transmissions were sent.

status = None

Required. See Message status values.

text = None

Required. Message text.

updated = None

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(*args, **kwargs)

Transmission(id, message_id, connection_id, status, date, updated, sent, delivered)

connection

Required. Foreign key to associated Connection.

date = None

Required. Date/time when transmission was created.

delivered = None

Date/time when transmission was delivered (requires backend functionality).

message

Required. Foreign key to associated Message.

sent = None

Date/time when transmission was sent.

status = None

Required. See Message status values.

updated = None

Required. Last date/time when transmission was updated.

 

Message status values

Message and Transmission objects can have the following status values:

  • Inbound values:
    • QQueued: Message is queued and awaiting processing
    • RReceived: Message has been processed and responses are queued
    • EErrored: An error occurred during processing
  • Outbound values:
    • QQueued: Message is queued and awaiting processing
    • PProcessing: Message is sending
    • SSent: All associated transmissions have been sent
    • DDelivered: All associated transmissions have been delivered (requires backend functionality)
    • EErrored: An error occurred during processing

Previous topic

Frequently Asked Questions

This Page