---
title: "Python ORM example application"
url: "https://docs.yugabyte.com/stable/develop/drivers-orms/orms/python/ysql-django/"
---

# Python ORM example application

Python ORM example application with Django that uses YSQL.

- [SQLAlchemy ORM](/stable/develop/drivers-orms/orms/python/ysql-sqlalchemy/)
- [Django ORM](/stable/develop/drivers-orms/orms/python/ysql-django/)

The following tutorial implements a REST API server using the [Django](https://www.djangoproject.com/ "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](https://github.com/yugabyte/orm-examples "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](/stable/quick-start/macos/ "Quick start").
- [Python 3](https://www.python.org/downloads/ "Python 3") or later is installed.
- [Django 2.2](https://www.djangoproject.com/download/ "Django 2.2") or later is installed.

## Clone the orm-examples repository

```sh
$ 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.
  
  ```python
  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](https://docs.djangoproject.com/en/dev/ref/settings/#secret-key "Django secret key") and paste the generated key in the following line of the `settings.py` file:
  
  ```python
  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:
  
  ```sh
  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:
  
  ```sh
  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.

```sh
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.

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

```sh
$ 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.

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

```sh
$ 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.

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

```sh
$ 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

```sh
$ ./bin/ysqlsh
```

```output
ysqlsh (15.2-YB-2026.1.2.0-b0)
Type "help" for help.

yugabyte=#
```

```plpgsql
yugabyte=# SELECT count(*) FROM users;
```

```output
 count
-------
     2
(1 row)
```

```plpgsql
yugabyte=# SELECT count(*) FROM products;
```

```output
 count
-------
     2
(1 row)
```

```plpgsql
yugabyte=# SELECT count(*) FROM orders;
```

```output
 count
-------
     2
(1 row)
```

### Using the REST API

```sh
$ curl http://localhost:8080/users
```

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

```sh
$ curl http://localhost:8080/products
```

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

```sh
$ curl http://localhost:8080/orders
```

```output.json
{
  "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": []
    }
  ],
  ...
}
```