Last night I had a buddy of mine ask me how I would approach a particular database design problem. I get similar questions quite often from my peers--suggests there is something important lacking from the database classes out there. Instead of answering him directly, I decided to come up with this tutorial for using Django to design your database schema.
For those of you new to Django, this article might seem a bit advanced. In time I will have more introductory-level Django tutorials, but I hope this one is easy enough.
Create a Django Project
The first step is to create a Django project. If you already have a project that you can play with, you can skip this step. To create a project, go to a place where you want to keep your code (like C:\projects or /home/me/projects) in a command prompt/terminal and run the following command:
django-admin.py startproject myproject
This will create a new directory in your current location called myproject (you can replace myproject with whatever you'd like so long as you're consistent). This new directory will contain a few files:
- __init__.py
- manage.py
- settings.py
- urls.py
If you get an error message when running the above command, you might not have Django installed properly. See Step-by-Step: Installing Django for details on installing Django.
Create An Application
Once you have a Django project setup, you should create a new application.
Note: If you're using Windows, you will probably need to omit the ./ on the ./manage.py commands. I will include them here for everyone else who's using Linux or a Mac.
cd myproject
./manage.py startapp specialapp
This will create a new directory in your myproject directory. This new directory will contain three files: __init__.py, models.py, and views.py. We are only concerned with the models.py file in this article.
Create Your Models
Models are usually a direct representation of what your database will be. Django makes creating these models extremely easy, and Python's syntax makes them quite readable. The Django framework asks for models to be defined in the models.py file that was created in the last step. Here's an example (for my buddy who prompted the creation of this article):
|
from django.db import models
class Component(models.Model):
item_number = models.CharField(max_length=20)
name = models.CharField(max_length=50)
size = models.CharField(max_length=10)
quantity = models.IntegerField(default=1)
price = models.DecimalField(max_digits=8, decimal_places=2)
class Project(models.Model):
name = models.CharField(max_length=50)
components = models.ManyToManyField(Component)
instructions = models.TextField()
|
(for more information about models, see the Django Model API Reference)
I don't know about you, but that code seems pretty straightforward to me. I'll spare you all the details about what's going on (that can be a future article).
Install Your New Application
Once you have your models setup, we need to add our specialapp to our list of INSTALLED_APPS in order for Django to register these models. To do that, open up settings.py in your myproject directory, go to the bottom of the file, until you see something like
|
INSTALLED_APPS = (
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.sites',
)
|
When you find that, add your specialapp to the list
|
INSTALLED_APPS = (
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.sites',
'specialapp'
)
|
Setup Your Database
Now you need to let Django know what kind of database you're using. Django currently supports MySQL, SQLite3, PostgreSQL, and Oracle natively, but you can get third-party tools that allow you to use other database (like SQL Server).
Still in your settings.py, go to the top until you see DATABASE_ENGINE and DATABASE_NAME. Set that to whatever type of database you are using:
|
DATABASE_ENGINE = 'sqlite3'
DATABASE_NAME = 'myproject.db'
|
Save your settings.py and go back to your command prompt/terminal.
Get Django's Opinion For Your Schema
Make sure you're in your myproject directory and run the following command:
./manage.py sqlall specialapp
This command will examine the models that we created previously and will generate the appropriate SQL to create the tables for your particular database. For SQLite, we get something like this for output:
|
BEGIN;
CREATE TABLE "specialapp_component" (
"id" integer NOT NULL PRIMARY KEY,
"item_number" varchar(20) NOT NULL,
"name" varchar(50) NOT NULL,
"size" varchar(10) NOT NULL,
"quantity" integer NOT NULL,
"price" decimal NOT NULL
)
;
CREATE TABLE "specialapp_project" (
"id" integer NOT NULL PRIMARY KEY,
"name" varchar(50) NOT NULL,
"instructions" text NOT NULL
)
;
CREATE TABLE "specialapp_project_components" (
"id" integer NOT NULL PRIMARY KEY,
"project_id" integer NOT NULL REFERENCES "specialapp_project" ("id"),
"component_id" integer NOT NULL REFERENCES "specialapp_component" ("id"),
UNIQUE ("project_id", "component_id")
)
;
COMMIT;
|
Notice how Django does all sorts of nifty things, like wrapping the table creation queries in a transaction, setting up indexes, unique keys, and defining relationships between tables. The output also offers a solution to the original problem my buddy had: an intermediate table that just keeps track of relationships between projects and components (the specialapp_project_components table).
Notice that the SQL above may not work with database servers other than SQLite.
Using This SQL
There are several ways you can use the SQL generated by Django. If you want to make your life really easy, you can have Django create the tables for you directly. Assuming that you have specified all of the appropriate database information in your settings.py file, you can simply run the following command:
./manage.py syncdb
This will execute the queries generated earlier directly on your database, creating the tables (if they don't already exist). Please note that this command currently will not update your schema if the table exists but is missing a column or two. You must either do that manually or drop the table in question and then execute the syncdb command.
Another option, if you want to keep your DDL(Data Definition Language) in a separate script (maybe if you want to keep it in some sort of version control) is something like:
./manage.py sqlall specialapp > specialapp-ddl-080813.sql
This just puts the output of the sqlall command into a file called specialapp-ddl-080813.sql for later use.
Benefits of Using Django To Create Your Schema
-
Simple: I personally find the syntax of Django models to be very simple and direct. There is a comprehensive API that explains and demonstrates what Django models are capable of.
-
Fast: Being that the syntax is so simple, I find that it makes designing and defining your schema much faster than trying to do it with raw SQL or using a database administration GUI.
-
Understandable: Looking at the model code in Django is not nearly as intimidating as similar solutions in other frameworks (think about Java Persistence API models).
-
Intelligent: Using the same model code, Django can generate proper Data Definition Language SQL for several popular database servers. It handles indexes, keys, relationships, transactions, etc. and can tell the difference between server types.
Downfalls of Using Django To Create Your Schema
-
The Table Prefix: Notice how all of the tables in the SQL above were prefixed with specialapp_. That's Django's safe way of making sure models from different applications in the same Django project do not interfere with each other. However, if you don't plan on using Django for your end project, the prefix could be a major annoyance. There are a couple solutions:
- A simple "search and replace" before executing the SQL in your database
- Define the db_table option in your models
-
Another Technology: Django (or even Python) may or may not be in your organization's current development stack. If it's not, using the methods described in this article would just become one more thing to support.
Other Thoughts
I first thought about doing the things mentioned in this application when I was working on a personal Java application. I like to use JPA when developing database-backed applications in Java because it abstracts away a lot of the database operations. However, I don't like coming up with the model classes directly, so I usually reverse engineer them from existing database tables.
Before thinking about the things discussed in this article, I created the tables by hand, making several modifications to the schema before I was satisfied with my JPA models. This proved to be quite bothersome and time-consuming.
After using Django to develop my tables, the JPA models turned out to be a lot more reliable, and they were usually designed properly from the get-go. I haven't created tables manually ever since.
If you find yourself designing database schemas often, and you find that you have to make several changes to your tables before you/the project requirements are satisfied, you might consider using Django to do the grunt work. It's worked for me, and I'm sure it will work for you too.
Good luck!