2019-05-30 02:21:27 -04:00
---
2020-05-29 14:08:26 -04:00
stage: Verify
group: Runner
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
2019-05-30 02:21:27 -04:00
type: reference
---
2015-12-08 11:22:45 -05:00
# Using PostgreSQL
2015-11-25 08:41:14 -05:00
2020-11-23 16:09:19 -05:00
As many applications depend on PostgreSQL as their database, you
2015-12-08 11:22:45 -05:00
eventually need it in order for your tests to run. Below you are guided how to
do this with the Docker and Shell executors of GitLab Runner.
2015-11-25 08:41:14 -05:00
2015-12-08 11:22:45 -05:00
## Use PostgreSQL with the Docker executor
2015-11-25 08:41:14 -05:00
2020-10-05 20:09:01 -04:00
If you're using [GitLab Runner ](../runners/README.md ) with the Docker executor,
2015-12-08 14:11:27 -05:00
you basically have everything set up already.
2015-11-25 08:41:14 -05:00
2015-12-08 11:22:45 -05:00
First, in your `.gitlab-ci.yml` add:
2015-11-25 08:41:14 -05:00
2015-12-08 11:22:45 -05:00
```yaml
services:
2020-02-18 13:09:07 -05:00
- postgres:12.2-alpine
2015-11-25 08:41:14 -05:00
2015-12-08 11:22:45 -05:00
variables:
POSTGRES_DB: nice_marmot
2015-12-08 15:26:41 -05:00
POSTGRES_USER: runner
2020-02-27 22:09:04 -05:00
POSTGRES_PASSWORD: ""
POSTGRES_HOST_AUTH_METHOD: trust
2015-12-08 11:22:45 -05:00
```
2015-11-25 08:41:14 -05:00
2020-10-05 20:09:01 -04:00
To set values for the `POSTGRES_DB` , `POSTGRES_USER` ,
`POSTGRES_PASSWORD` and `POSTGRES_HOST_AUTH_METHOD` ,
[assign them to a variable in the user interface ](../variables/README.md#create-a-custom-variable-in-the-ui ),
then assign that variable to the corresponding variable in your
`.gitlab-ci.yml` file.
2019-07-24 02:11:14 -04:00
2015-12-08 14:11:27 -05:00
And then configure your application to use the database, for example:
2015-11-25 08:41:14 -05:00
2015-12-08 11:22:45 -05:00
```yaml
2015-12-08 16:49:05 -05:00
Host: postgres
2015-12-08 15:26:41 -05:00
User: runner
2020-02-27 22:09:04 -05:00
Password: ''
2015-12-08 11:22:45 -05:00
Database: nice_marmot
```
2015-11-25 08:41:14 -05:00
2020-10-05 20:09:01 -04:00
If you're wondering why we used `postgres` for the `Host` , read more at
2019-03-10 21:47:01 -04:00
[How services are linked to the job ](../docker/using_docker_images.md#how-services-are-linked-to-the-job ).
2015-12-08 16:49:05 -05:00
2020-05-27 05:08:30 -04:00
You can also use any other Docker image available on [Docker Hub ](https://hub.docker.com/_/postgres ).
2020-10-05 20:09:01 -04:00
For example, to use PostgreSQL 9.3, the service becomes `postgres:9.3` .
2015-11-25 08:41:14 -05:00
2020-10-05 20:09:01 -04:00
The `postgres` image can accept some environment variables. For more details,
see the documentation on [Docker Hub ](https://hub.docker.com/_/postgres ).
2015-11-25 08:41:14 -05:00
2015-12-08 11:22:45 -05:00
## Use PostgreSQL with the Shell executor
2015-11-25 08:41:14 -05:00
2015-12-08 11:22:45 -05:00
You can also use PostgreSQL on manually configured servers that are using
GitLab Runner with the Shell executor.
2015-11-25 08:41:14 -05:00
2015-12-08 11:22:45 -05:00
First install the PostgreSQL server:
2015-11-25 08:41:14 -05:00
2020-01-30 10:09:15 -05:00
```shell
2015-12-08 11:22:45 -05:00
sudo apt-get install -y postgresql postgresql-client libpq-dev
```
2015-11-25 08:41:14 -05:00
2020-10-05 20:09:01 -04:00
The next step is to create a user, so sign in to PostgreSQL:
2015-11-25 08:41:14 -05:00
2020-01-30 10:09:15 -05:00
```shell
2015-12-08 11:22:45 -05:00
sudo -u postgres psql -d template1
2015-12-08 15:26:41 -05:00
```
2015-11-25 08:41:14 -05:00
2020-11-23 16:09:19 -05:00
Then create a user (in our case `runner` ) which is used by your
2015-12-08 15:26:41 -05:00
application. Change `$password` in the command below to a real strong password.
2015-11-25 08:41:14 -05:00
2020-10-05 20:09:01 -04:00
NOTE: **Note:**
Be sure to not enter `template1=#` in the following commands, as that's part of
the PostgreSQL prompt.
2015-11-25 08:41:14 -05:00
2020-01-30 10:09:15 -05:00
```shell
2015-12-08 15:26:41 -05:00
template1=# CREATE USER runner WITH PASSWORD '$password' CREATEDB;
2015-12-08 11:22:45 -05:00
```
2015-11-25 08:41:14 -05:00
2020-10-05 20:09:01 -04:00
The created user has the privilege to create databases (`CREATEDB`). The
following steps describe how to create a database explicitly for that user, but
having that privilege can be useful if in your testing framework you have tools
that drop and create databases.
2015-12-08 15:26:41 -05:00
2020-10-05 20:09:01 -04:00
Create the database and grant all privileges to it for the user `runner` :
2015-11-25 08:41:14 -05:00
2020-01-30 10:09:15 -05:00
```shell
2015-12-08 15:26:41 -05:00
template1=# CREATE DATABASE nice_marmot OWNER runner;
```
2020-10-05 20:09:01 -04:00
If all went well, you can now quit the database session:
2015-11-25 08:41:14 -05:00
2020-01-30 10:09:15 -05:00
```shell
2015-12-08 15:26:41 -05:00
template1=# \q
2015-12-08 11:22:45 -05:00
```
2015-11-25 08:41:14 -05:00
2015-12-08 15:26:41 -05:00
Now, try to connect to the newly created database with the user `runner` to
check that everything is in place.
2015-11-25 08:41:14 -05:00
2020-01-30 10:09:15 -05:00
```shell
2015-12-08 15:26:41 -05:00
psql -U runner -h localhost -d nice_marmot -W
```
2020-10-05 20:09:01 -04:00
This command explicitly directs `psql` to connect to localhost to use the md5
2020-11-23 16:09:19 -05:00
authentication. If you omit this step, you are denied access.
2015-12-08 15:26:41 -05:00
Finally, configure your application to use the database, for example:
```yaml
2015-12-08 11:22:45 -05:00
Host: localhost
2015-12-08 15:26:41 -05:00
User: runner
Password: $password
2015-12-08 11:22:45 -05:00
Database: nice_marmot
```
2015-11-25 08:41:14 -05:00
2015-12-08 11:22:45 -05:00
## Example project
2020-03-30 02:07:59 -04:00
We have set up an [Example PostgreSQL Project ](https://gitlab.com/gitlab-examples/postgres ) for your
2015-12-08 11:22:45 -05:00
convenience that runs on [GitLab.com ](https://gitlab.com ) using our publicly
available [shared runners ](../runners/README.md ).
2020-10-05 20:09:01 -04:00
Want to hack on it? Fork it, commit, and push your changes. Within a few
2020-11-23 16:09:19 -05:00
moments the changes are picked by a public runner and the job begins.