Python ORM example application

The following tutorial implements a REST API server using the Django ORM. The scenario is that of an e-commerce application where database access is managed using the ORM.

The source for the above application can be found in the python/django directory of Yugabyte's Using ORMs with YugabyteDB repository.

Prerequisites

This tutorial assumes that you have:

YugabyteDB up and running. Download and install YugabyteDB by following the steps in Quick start.
Python 3 or later is installed.
Django 2.2 or later is installed.

Clone the orm-examples repository

$ git clone https://github.com/YugabyteDB-Samples/orm-examples.git

Set up the database connection

Customize the database connection setting according to your environment in the ybstore/settings.py file. This file is in the orm-examples/python/django directory.

DATABASES =
{
    'default':
    {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'ysql_django',
        'USER': 'yugabyte',
        'PASSWORD': '',
        'HOST': '127.0.0.1',
        'PORT': '5433',
    }
}

Generate a Django secret key and paste the generated key in the following line of the settings.py file:
```
SECRET_KEY = 'YOUR-SECRET-KEY'
```
Create a database using the YugabyteDB YSQL shell (ysqlsh). From the location of your local YugabyteDB cluster, run the following shell command:
```
bin/ysqlsh -c "CREATE DATABASE ysql_django"
```
From the orm-examples/python/django directory, run the following command to create the migrations and migrate the changes to the database:
```
python3 manage.py makemigrations && python3 manage.py migrate
```

Start the REST API server

Run the following Python script to start the REST API server at port 8080, or specify a port of your own choice.

python3 manage.py runserver 8080

The REST API server starts and listens for your requests at http://localhost:8080.

Send requests to the application

Create 2 users.

$ curl --data '{ "firstName" : "John", "lastName" : "Smith", "email" : "jsmith@example.com" }' \
   -v -X POST -H 'Content-Type:application/json' http://localhost:8080/users

$ curl --data '{ "firstName" : "Tom", "lastName" : "Stewart", "email" : "tstewart@example.com" }' \
   -v -X POST -H 'Content-Type:application/json' http://localhost:8080/users

Create 2 products.

$ curl \
  --data '{ "productName": "Notebook", "description": "200 page notebook", "price": 7.50 }' \
  -v -X POST -H 'Content-Type:application/json' http://localhost:8080/products

$ curl \
  --data '{ "productName": "Pencil", "description": "Mechanical pencil", "price": 2.50 }' \
  -v -X POST -H 'Content-Type:application/json' http://localhost:8080/products

Create 2 orders.

$ curl \
  --data '{ "userId": "2", "products": [ { "productId": 1, "units": 2 } ] }' \
  -v -X POST -H 'Content-Type:application/json' http://localhost:8080/orders

$ curl \
  --data '{ "userId": "2", "products": [ { "productId": 1, "units": 2 }, { "productId": 2, "units": 4 } ] }' \
  -v -X POST -H 'Content-Type:application/json' http://localhost:8080/orders

Query results

Using the YSQL shell

$ ./bin/ysqlsh

ysqlsh (11.2)
Type "help" for help.

yugabyte=#

yugabyte=# SELECT count(*) FROM users;

 count
-------
     2
(1 row)

yugabyte=# SELECT count(*) FROM products;

 count
-------
     2
(1 row)

yugabyte=# SELECT count(*) FROM orders;

 count
-------
     2
(1 row)

Using the REST API

$ curl http://localhost:8080/users

{
  "content": [
    {
      "userId": 2,
      "firstName": "Tom",
      "lastName": "Stewart",
      "email": "tstewart@example.com"
    },
    {
      "userId": 1,
      "firstName": "John",
      "lastName": "Smith",
      "email": "jsmith@example.com"
    }
  ],
  ...
}

$ curl http://localhost:8080/products

{
  "content": [
    {
      "productId": 2,
      "productName": "Pencil",
      "description": "Mechanical pencil",
      "price": 2.5
    },
    {
      "productId": 1,
      "productName": "Notebook",
      "description": "200 page notebook",
      "price": 7.5
    }
  ],
  ...
}

$ curl http://localhost:8080/orders

{
  "content": [
    {
      "orderTime": "2019-05-10T04:26:54.590+0000",
      "orderId": "999ae272-f2f4-46a1-bede-5ab765bb27fe",
      "user": {
        "userId": 2,
        "firstName": "Tom",
        "lastName": "Stewart",
        "email": "tstewart@example.com"
      },
      "userId": null,
      "orderTotal": 25,
      "products": []
    },
    {
      "orderTime": "2019-05-10T04:26:48.074+0000",
      "orderId": "1598c8d4-1857-4725-a9ab-14deb089ab4e",
      "user": {
        "userId": 2,
        "firstName": "Tom",
        "lastName": "Stewart",
        "email": "tstewart@example.com"
      },
      "userId": null,
      "orderTotal": 15,
      "products": []
    }
  ],
  ...
}