Django REST framework

This document describes how to use Django REST framework, an ORM library in Python, with YugabyteDB.

Prerequisites

Before you can start using Django, ensure that you have the following installed and configured:

pip3 install djangorestframework
  • psycopg2 by executing the following command:
pip3 install psycopg2

Use Django REST framework

You can start using Django REST framework with YugabyteDB as follows:

  • Create a new Django project using the following command:
django-admin startproject yugabyteTest && cd yugabyteTest/
  • Set up a new Django application using the following command:
python manage.py startapp testdb
  • Create a model by adding the following code in testdb/models.py:
from django.db import models

class Users(models.Model):
    userId = models.AutoField(db_column='user_id', primary_key=True, serialize=False)
    firstName = models.CharField(max_length=50, db_column='first_name')
    lastName = models.CharField(max_length=50, db_column='last_name')
    email = models.CharField(max_length=100, db_column='user_email')

    class Meta:
        db_table = "users"

    def __str__(self):
        return '%d %s %s %s' % (self.userId, self.firstName, self.lastName, self.email)
  • Create a Serializer in testdb\serializers.py which manages serialization and deserialization from JSON and add the following code to it:
from rest_framework import serializers, status
from testdb.models import Users
from django.core.exceptions import ValidationError

class UserSerializer(serializers.ModelSerializer):
    class Meta:
        model = Users
        fields = ('userId', 'firstName', 'lastName', 'email')
  • Create a ViewSet in testdb/views.py and add the following code:
from django.shortcuts import render
from testdb.models import Users
from rest_framework import viewsets
from testdb.serializers import UserSerializer

class UserViewSet(viewsets.ModelViewSet):
    queryset = Users.objects.all()
    serializer_class = UserSerializer

The application now has all the elements and is ready to be configured as follows:

  • Map the URLs in yugabyteTest/urls.py by adding the following code:
from django.urls import include, re_path
from rest_framework import routers
from testdb.views import UserViewSet

router = routers.SimpleRouter(trailing_slash=False)
router.register(r'users', UserViewSet)
urlpatterns = [
    re_path(r'^', include(router.urls))
]

For Django versions earlier than 4.0, add the following code in urls.py instead, since you can import the urls using django.conf.urls:

from django.urls import path, include
from django.conf.urls import url, include
from rest_framework import routers
from testdb.views import UserViewSet

router = routers.SimpleRouter(trailing_slash=False)
router.register(r'users', UserViewSet)

urlpatterns = [
    url(r'^', include(router.urls))
]
  • Configure yugabyteTest/settings.py to use YugabyteDB by updating the value of DATABASES field.
DATABASES = {
    'default': {
        'ENGINE': 'yb_backend',
        'NAME': 'yugabyte',
        'HOST': 'localhost',
        'PORT': 5433,
        'USER': 'yugabyte',
        'PASSWORD': 'yugabyte',
        'CONN_MAX_AGE': None
    }
}

We recommend using persistent connections (setting CONN_MAX_AGE), for a much better performance with YugabyteDB.

You also need the application and rest framework in the INSTALLED_APPS field. Replace the existing code with the following:

INSTALLED_APPS = [
    'rest_framework',
    'testdb.apps.TestdbConfig',
    'django.contrib.contenttypes',
    'django.contrib.auth',
]

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [],
    'DEFAULT_PERMISSION_CLASSES': [],
    'UNAUTHENTICATED_USER': None,
}
  • Create the migrations using the following command:
python3 manage.py makemigrations
  • Migrate the changes to the database using the following command:
python3 manage.py migrate
  • A users table should be created in your database. Use the ysqlsh client shell to verify that the users table has been created in your database.

Run the application

To run the application and insert a new row, execute the following steps:

  • Run the django project using the following command:
python3 manage.py runserver 8080
  • Insert a row using the following command:
$ curl --data '{ "firstName" : "John", "lastName" : "Smith", "email" : "jsmith@yb.com" }' \
       -v -X POST -H 'Content-Type:application/json' http://localhost:8080/users
  • Verify that the new row is inserted by executing the following command:
$ curl http://localhost:8080/users

[{"userId":1,"firstName":"John","lastName":"Smith","email":"jsmith@yb.com"}]

Alternatively, you can verify it in the ysqlsh client shell.