In my previous articles, I covered the basics of Django installation for development environment, as well as configuring Django to work with MySQL database. Today, we will look at configuring Django to use PostgreSQL database.
Same as before, I will be covering the entire process of getting Django + MySQL installed and configured, but for more detailed steps and additional information, you may refer to my previous posts on installation of AMP stack (covers MySQL and Workbench) and Django. If you have read my previous articles, then it should be pretty clear to you that installing required packages per se is not really a big task, and the complex part here is to wrap your head around how Django components interact with each other and how to configure them to work together.
What is PostgreSQL? Well, PostgreSQL, a.k.a. Postgres, is a popular RDBMS and, along with MySQL, those two are by far the most widely used RDBMS (at least when it comes to web applications back ends). PostgreSQL has more focus on SQL standards compliance, which becomes important when you build apps using heterogeneous databases. It also often goes as a default ingredient of production Django deployments, where SQLite database (a no go for concurrent multiuser workloads) is replaced by PostgreSQL database, and Django development server (the one that you start with manage.py runserver) gets replaced with Gunicorn acting as Python WSGI HTTP Server, often combined with Nginx reverse-proxy.
In this article, we will look at how to get your development Django server configured to work with PostgreSQL database.
If you don’t have Ubuntu 18.04 server readily available to you, then one of the easiest options to get it is to use Hyper-V Quick Create feature:
Using Hyper-V Quick Create feature to provision Ubuntu 18.04.3 LTS VM
Once you are logged on to your Ubuntu server, a good thing to do before moving on with the installation of packages is to run sudo apt update to have your APT package index updated with the latest changes made in the repositories, or in plain words, made server aware about the latest package versions available. To install available updates for already installed packages, you will need to run sudo apt upgrade after running sudo apt update.
Now, let’s install the packages that we need for the Django development server with PostgreSQL. As the first step, let’s install Python 3.7 along with the required dependencies as shown below. We just need to execute the following command:
Installing required Python and dependencies
Our second step is PostgreSQL installation by means of executing sudo apt install -y postgresql postgresql-contrib command as shown below:
Installing PostgreSQL
Once PostgreSQL is installed, you may try to connect to it using the sudo -u postgres psql command:
Connecting to PostgreSQL via psql
In my case, using clean Ubuntu 18.04.2 LTS server, I run into an issue while connecting to PostgreSQL immediately after the installation – immediately after issuing sudo -u postgres psql command I was getting the “psql: could not connect to server: No such file or directory” error:
Unable to connect to PostgreSQL – “psql: could not connect to server: No such file or directory”
This error may confuse you a bit as it occurs while your postgresql service itself is up and running (as can be checked with the sudo service postgresql status command). If you see the above-mentioned error, it likely means that you need to start pg_ctlcluster as shown below:
The command you need to run is sudo pg_ctlcluster 10 main start, where 10 should match the PostgreSQL version installed in your environment (you can check it using ls /etc/postgresql/ command – in my case, I have version 10 installed).
Once you are connected to the PostgreSQL server, you need to create database and database user, using the following commands:
|
1 2 3 |
CREATE DATABASE django_project_db; CREATE USER django_project_user WITH ENCRYPTED PASSWORD ‘P@ssw0rd’; |
Here is a screenshot illustrating the successful execution of those commands:
Creating PostgreSQL database and user
Once database is created, we also need to configure the number of database settings (encoding, transaction isolation and timezone) and grant our newly created user all privileges on database, using the following commands:
|
1 2 3 4 5 6 7 |
ALTER ROLE django_project_user SET client_encoding TO 'utf8'; ALTER ROLE django_project_user SET default_transaction_isolation TO 'read committed'; ALTER ROLE django_project_user SET timezone TO 'UTC'; GRANT ALL PRIVILEGES ON DATABASE django_project_db TO django_project_user; |
Let’s execute them (reconnecting to Postgres using the sudo -u postgres psql command if necessary):
Configuring PostgreSQL database settings
Once all the Postgres database settings are configured, you can quit from Postgres command prompt using \q command.
Optionally, and especially if you are working on a local development server vs production box, you may want to install pgAdmin III if you prefer to have an administrative GUI for your PostgreSQL installation. To install pgAdmin run the sudo apt-get -y install pgadmin3 command:
Installing pgAdmin III
Now, with both Python and PostgreSQL installed, let’s create a virtual environment and activate it as shown below:
Creating and activating Python virtual environment
Now, having our Python virtual environment activated, we just need to install Django into it and create a new project as show below:
Installing Django in virtual environment
As you can see from the screenshot above, we just issued the pip install django command inside of our virtual environment using python -V and django-admin –version commands to check on the installed versions of Python and Django respectively.
As a next step, we need to create a new Django project using the django-admin startproject django_project command (django_project is my utterly original project name, which you can replace with something more relevant/original for you). This command creates a Django project folder, which includes, amongst other things, settings.py file, located inside of the project’s folder subfolder:
Django project folder contents
Having created the project, let’s open the settings.py file to configure our database connection settings. We can do that using the nano django_project/django_project/settings.py command and locating database connection settings section inside of this file:
settings.py – Default DATABASES configuration
As you can see, by default, Django project configuration specifies use of SQLite3 engine. Let’s edit these settings to use Postgres by changing the content of the ‘default’ section to the following:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
'default': { 'ENGINE': 'django.db.backends.postgresql', 'NAME': 'django_project_db', 'USER': 'django_project_user', 'PASSWORD': 'P@ssw0rd', 'HOST': 'localhost', 'PORT': '5432', } |
Here is a sample screenshot of the file with these settings added:
settings.py – Database configuration adjusted for use of PostgreSQL database
Once we adjusted the Django project’s settings.py file, we also need to install the psycopg2 module using the pip install psycopg2-binary command as shown below:
Installing psycopg2-binary package
Next, we need to perform initial migration. After the Django project’s creation, we already have the number of unapplied migrations, which we can list using the python3 manage.py showmigrations command executed from the project’s root folder (note that your manage.py file located in the root of your Django project folder, so be sure to switch to that directory):
Listing migrations using showmigrations command
In case you need a refresher on Django terminology, Django uses models which define structure of database tables, and migrations are scripts responsible for creating and changing these tables. Although we have not defined any custom models in our project, Django comes with default applications (e.g. admin, auth) which require creation of database tables associated with them, and this set of tables is known as initial migration.
Let’s migrate the Django project changes using the python manage.py migrate command as shown below (again, remember that you have to run this from the virtual environment context running the manage.py file in the root of Django project’s folder):
Applying initial migration changes using migrate command
Once migrations are applied, you can rerun the python manage.py showmigrations command and confirm that all migrations were applied (all of them marked with “X” now):
Migrations applied
Now, we can open our Django PostgreSQL database and see that corresponding tables appeared there after we did the initial migration. To do that, we use the psql command and, once connected to PostgreSQL, we can switch to the desired database with \c %database_name% and list tables with the \dt command:
Default Django project tables in PostgreSQL database
Once you finished reviewing the tables in the project database, you can quit from psql using the \q command. The fact of successful initial migration and presence of the tables in the database already demonstrates that our Django project is set up correctly to work with Postgres database, yet it does never hurt to do extra steps and run Django server to make sure that it works 😊.
As a final test, lets get back to our Python virtual environment (change directory and activate it if necessary) and use the python3.7 manage.py runserver command, executing it as shown below:
Starting Django server
Once the server is started, you can navigate to http://127.0.0.1:8000 in your browser and see the default Django page confirming that the installation was successful:
Django – Installation Successful page
This concludes the process of configuring Django project for working with PostgreSQL database. By now, I think I said enough about database settings configuration and, in my next article, I’ll move on to web server configuration. Thanks for reading and stay tuned for new posts.
