Skip to main content

How to Configure Database Links within ACC?

In this section, we will learn how to configure database links within ACC.

Let's remember the akinon.json file we have created in the previous section:

{
"name": "Quickstart Project",
"description": "Quickstart Project",
"scripts": {
"release": "",
"build": "sh build.sh"
},
"env": {},
"formation": {
"web": {
"min": 1,
"max": "auto"
}
},
"runtime": "python:3.8-alpine",
"addons": []
}

Configuring Addons

You can fulfill the needs of your application by adding database, cache, cdn, etc. in the addons field. [See here] for detailed information about addons

Below is how we need to specify the addon our application needs within akinon.json:

{
"...": "...",
"addons": [
{
"plan": "postgresql",
// "options": {
// "instance_type": "db.r5.large",
// "instance_count": 1
// }
}
]
}

For specifying addons, it's enough to fill out the plan area. Additionally, as seen above, we can make optional configurations via options. For example, we can configure the type and amount of the database instance. Instance types are parallel with the database instance names on AWS.

Here is how our akinon.json file will look after configuration:

{
"name": "Quickstart Project",
"description": "Quickstart Project",
"scripts": {
"release": "",
"build": "sh build.sh"
},
"env": {},
"formation": {
"web": {
"min": 1,
"max": "auto"
}
},
"runtime": "python:3.8-alpine",
"addons": [
{
"plan": "postgresql"
}
]
}

Using Environment Variables in Configuration

For each added addon, a specific environment variable is embedded in your application. For database, the env values below are sent to your application:

  • DB_HOST: the hostname of the database
  • DB_PORT: the port to connect to the host
  • DB_NAME: the name of the database
  • DB_USER: the username to connect to the database
  • DB_PASSWORD: the password of the user

Let's configure our application to retrieve these envs:

settings.py

DATABASES = {
"default": {
"ENGINE": "django.db.backends.postgresql",
"HOST": env("DB_HOST"),
"USER": env("DB_USER"),
"PASSWORD": env("DB_PASSWORD"),
"NAME": env("DB_NAME"),
"PORT": env("DB_PORT", cast=int),
}
}

We also need to add the .env file to these envs in order to be able to test our application in a local environment.

.env

# postgres
DB_NAME=quickstart
DB_USER=postgres_user
DB_PASSWORD='postgres_password'
DB_HOST=127.0.0.1
DB_PORT=5432

In order for our application to communicate with PostgreSQL, we need to add the postgresql-dev library to the build.sh file.

Here is how our build.sh file will look like:

set -euo pipefail

apk add python3-dev postgresql-dev g++ jpeg-dev zlib-dev libffi-dev --no-cache
pip install -U --force-reinstall pip
pip install -r requirements.txt

apk del g++ python3-dev

Automatic Run of Database Migrations

Finally, we need to ensure the automatic run of our application's migration configurations. We need to enter the command to run database migrations in the release area within scripts in the akinon.json file:

{
//... ,
"scripts": {
"release": "python manage.py migrate --noinput",
"build": "sh build.sh"
},
// ...
}

Controlling the Database Connection with Health-Check

We can control our database connection by creating a healthcheck page. Healthcheck pages provide us with the information that our application is up and running and is properly configured. If everything is working as they should be, we need to return the HTTP 200 OK status code. If something is wrong, we need to handle the related issue and return with a proper error code.

Let's add a new view to the application that will respond in the /healthz path:

views.py

import django
from django.http import HttpResponse
from django.views import View

class HomeView(View):
def get(self, request):
return HttpResponse(content='Quickstart App Home Page', status=200)

class HealthCheckView(View):
def get(self, request):
try:
django.db.connection.ensure_connection()
except Exception as exc:
return HttpResponse(content='Database connection could not be established.', status=500)

return HttpResponse(content='OK', status=200)

urls.py

from django.contrib import admin
from django.urls import path

from quickstart.views import HealthCheckView, HomeView

urlpatterns = [
path('', HomeView.as_view(), name='home'),
path('admin/', admin.site.urls),
path('healthz/', HealthCheckView.as_view(), name='healthcheck')
]

Let's test our healthcheck page in the local environment:

Everything seems to be running smoothly! Let's retry by pausing our PostgreSQL service in the local:

When no database connection is made, the healthcheck page informs us about the situation.

Bu entering our healthcheck pattern within the akinon.json file, we can run an instant and automatic health check on our application at regular intervals, after our project runs on ACC.

All we need to do is to add our path with the healthcheck key under formation > web.

{
//...

"env": {},
"formation": {
"web": {
"min": 1,
"max": "auto",
"healthcheck": "/healthz/"
}
},

// ...
}

See here for detailed information.

In order to try the changes we have made in this section within the ACC environment, let's start a new version build by sending the changes we have made to our application repo within ACC, and deploy it:

We have deployed our application and, upon visiting the healthcheck page, we can see that the database connection is successfully made.