linking-database.adoc

Linking Database

To configure the web application so it knows about the database, you can use an environment variable which passes the database connection string to the web application.

For the database details:

• Database Service Name: blog-db

• PostgreSQL Connection Username: username

• PostgreSQL Connection Password: password

• PostgreSQL Database Name: blog

the full database connection string you will need to use will be:

postgresql://username:password@blog-db:5432/blog

The web application used in this workshop expects the database connection string to be supplied in the environment variable DATABASE_URL. When supplied it will automatically re-configure itself to use the separate database server, rather than the SQLite database.

To set this environment variable for the web application, from the command line, run the command:

oc set env dc/blog DATABASE_URL=postgresql://username:password@blog-db:5432/blog

This should output:

deploymentconfig "blog" updated

Updating the configuration for the deployment configuratin will result in the web application being automatically re-deployed with the new environment variable being set.

You can verify what environment variables should be passed from the deployment configuration by running:

oc set env dc/blog --list

This should display:

# deploymentconfigs blog, container blog
DATABASE_URL=postgresql://username:password@blog-db:5432/blog

To verify that any environment variables are indeed being passed into the running web application, you can use the web console to create an interactive terminal against the pod and run the env command. Alternatively, you can use oc rsh from the command line to execute the env command inside of the pod for the web application.

To get a list of the pods running instances of the web application run the command:

oc get pods --selector app=blog -o name

Now run oc rsh substituting the name of the pod for that of the web application in the command:

oc rsh blog-X-XXXX env

Running the env command inside of the container will also show up any other environment variables which are automatically being passed into the web application, and not just the environment variable you added.

With the web application re-deployed, if you now visit the web application in your browser, you should see the blog site banner, but you will find there are no blog posts.

That there are no blog posts is because when using SQLite, the web application code was designed to automatically initialise the contents of the database, creating an initial user account and populating it with some blog posts. This was safe to do as the database was being discarded each time the web application was restarted. When using a separate persistent database server, it is safer to manually run any database initialisation, and do it only once. This ensures you don’t accidentally wipe the database.

To initialise the separate database server, a setup script is supplied as part of the web application. To run this setup script, run oc rsh against the pod again, but change the command executed to scripts/setup.

oc rsh blog-X-XXXX scripts/setup

This setup script is a simple wrapper which in turn calls the Django management commands for setting up the database and creating a super user account. It will also pre-load some blog posts. When creating the super user account, it will prompt you for a user name and password to use.

The output from running the command should be similar to the following:

 -----> Running Django database table migrations.
Operations to perform:
  Apply all migrations: admin, auth, blog, contenttypes, sessions
Running migrations:
  Applying contenttypes.0001_initial... OK
  Applying auth.0001_initial... OK
  Applying admin.0001_initial... OK
  Applying admin.0002_logentry_remove_auto_add... OK
  Applying contenttypes.0002_remove_content_type_name... OK
  Applying auth.0002_alter_permission_name_max_length... OK
  Applying auth.0003_alter_user_email_max_length... OK
  Applying auth.0004_alter_user_username_opts... OK
  Applying auth.0005_alter_user_last_login_null... OK
  Applying auth.0006_require_contenttypes_0002... OK
  Applying auth.0007_alter_validators_add_error_messages... OK
  Applying auth.0008_alter_user_username_max_length... OK
  Applying blog.0001_initial... OK
  Applying sessions.0001_initial... OK
 -----> Running Django super user creation
Username: developer
Email address: [email protected]
Password:
Password (again):
Superuser created successfully.
 -----> Pre-loading Django database with blog posts.
Installed 2 object(s) from 1 fixture(s)

Return to your browser and refresh the home page for the web application and you should again see the pre-populated blog posts. This time they are being stored in the separate PostgreSQL database server.

Login in to the blog site using the user name and password you supplied when the setup script was run above and add a new blog post. As before, only add the text for the content of the blog post, do not add any image to the post.

Now kill the running instance of the web application so it is restarted, by running:

oc delete pod --selector app=blog

Unlike before when the SQLite database was being used, the new post that you added should still be present.

This is obviously the case though as you only restarted the web application and the data is being stored in the separate PostrgreSQL instance.

To validate that the posts are actually persistent, you need to restart the PostgreSQL database.

Being a database and wanting to ensure that we don’t risk data corruption by brutely killing the container, you should perform a more orderly shutdown of the database. This can be done by running the command:

oc scale dc/blog-db --replicas=0

What this command will do is shutdown the running PostgreSQL database instance, but retain all the configuration related to it, as well as the persistent volume it is using.

Monitor the status of the database from the web console. Once it has shutdown, start it up again by running:

oc scale dc/blog-db --replicas=1

Do not run more than one replica, as this database configuration only supports a single reader/writer process. A more complex deployment configuration is required if you want to run a scalable database.

In your web browser, reload the page for the blog site. This may initially display an error as Django is setup to cache connections to the database, and the fact that we shutdown the database means that the connection was broken. Keep refreshing until you see the blog site being displayed once more.

When it is working again, take note how the blog post you added is still present.