Python ORM example application
This page documents the preview version (v2.23). Preview includes features under active development and is for development and testing only. For production, use the stable version (v2024.1). To learn more, see Versioning.
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 theorm-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": []
}
],
...
}