Setting Up the Database
If you don’t have a database server installed and running, we recommend SQLite as the fastest and easiest way to get going. It’s fast, widely available, and stores its database as a single file in the filesystem. Access controls are simply file permissions. For more on how to set up a a database for use with Django, see Appendix B.
If you do have a database server—PostgreSQL, MySQL, Oracle, MSSQL—and want to use it rather than SQLite, then use your database’s administration tools to create a new database for your Django project. We name this database “djangodb” in our examples, but you can name it whatever you like.
Either way, with your (empty) database in place, all that remains is to tell Django how to use it. This is where your project’s settings.py file comes in.
Using a Database Server
Many people use Django with a relational database server such as PostgreSQL or MySQL. There are six potentially relevant settings here (though you may need only two): DATABASE_ENGINE, DATABASE_NAME, DATABASE_HOST, DATABASE_PORT, DATABASE_USER, and DATABASE_PASSWORD. Their names make their respective purposes pretty obvious. Just plug in the correct values corresponding to the database server you are using with Django. For example, settings for MySQL look something like this:
DATABASE_ENGINE = "mysql" DATABASE_NAME = "djangodb" DATABASE_HOST = "localhost" DATABASE_USER = "paul" DATABASE_PASSWORD = "pony" # secret!
For details on creating a new database and database user (which is required for database servers), see Appendix B.
SQLite is a popular choice for testing and even for deployment in scenarios where there isn’t a great deal of simultaneous writing going on. No host, port, user, or password information is needed because SQLite uses the local filesystem for storage and the native filesystem permissions for access control. So only two settings are needed to tell Django to use your SQLite database.
DATABASE_ENGINE = "sqlite3" DATABASE_NAME = "/var/db/django.db"
SQLite is also one of the most popular choices on Win32 platforms because it comes free with the Python distribution. Given we have already created a C:\py\django directory with our project (and application), let’s create a db directory as well.
DATABASE_ENGINE = 'sqlite3' DATABASE_NAME = r'C:\py\django\db\django.db'
If you are new to Python, you notice the subtle difference in the first example; we used double quotes around sqlite3, whereas in the Win32 version, we used single quotes. Rest assured it has nothing to do with differing platforms—Python does not have a character type, so single quotes and double quotes are treated the same. Just make sure you open and close a string with the same type of quote!
You should also have noticed a small “r” in front of the folder name. If you’ve read Chapter 1, then you know this means to designate the object as a “raw string,” or one that takes all characters of a string verbatim, meaning do not translate special character combinations. For example, \n usually means a newline character, but in a raw string, it means (literally) two characters: a backslash followed by an n. So the purpose of a raw string is specifically for DOS file paths, telling Python to not translate special characters (if there are any).
Creating the Tables
Now you tell Django to use the connection information you’ve given it to connect to the database and set up the tables your application needs. The command to do this is simply:
./manage.py syncdb # or ".\manage.py syncdb" on win32
You see some output that starts like this as Django sets up the database:
Creating table auth_message Creating table auth_group Creating table auth_user Creating table auth_permission Creating table django_content_type Creating table django_session Creating table django_site Creating table blog_blogpost
When you issue the syncdb command, Django looks for a models.py file in each of your INSTALLED_APPS. For each model it finds, it creates a database table. (There are exceptions to this later when we get into fancy stuff such as many-to-many relations, but it’s true for this example. If you are using SQLite, you also notice the django.db database file is created exactly where you specified.)
The other items in INSTALLED_APPS, the ones that were there by default, all have models too. The output from manage.py syncdb confirms this, as you can see Django is creating one or more tables for each of those apps.
That’s not all the output you got from the syncdb command, though. You also got some interactive queries related to the django.contrib.auth app.
You just installed Django's auth system, which means you don't have any superusers defined. Would you like to create one now? (yes/no): yes Username (Leave blank to use 'pbx'): E-mail address: firstname.lastname@example.org Password: Password (again): Superuser created successfully. Installing index for auth.Message model Installing index for auth.Permission model
Now you’ve got one superuser (hopefully yourself) in the auth system. This comes in handy in a moment, when we add in Django’s automatic admin application.
Finally, the process wraps up with a couple lines relating to a feature called fixtures, which we come back to in Chapter 4, “Defining and Using Models.” These enable you to preload data in a freshly created application. For now, we’re not using that feature, so Django moves on.
Loading 'initial_data' fixtures... No fixtures found.
Your initial database setup is now complete. The next time you run the syncdb command on this project (which you do any time you add an application or model), you see a bit less output because it doesn’t need to set up any of those tables a second time or prompt you to create a superuser.