Django REST framework

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

Prerequisites

To use Django with YugabyteDB, you need the following:

• YugabyteDB version 2.7 or later; see Quick Start.

• Python3.

• Django backend for YugabyteDB.

• Django REST framework by executing the following command:

  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
  

Configure the application

The application now has all the elements and is ready to be configured.

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, as 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
    }
}

For better performance with YugabyteDB, use persistent connections (setting CONN_MAX_AGE).

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

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 using the ysqlsh client shell.