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
2015-12-08 11:22:45 -05:00
As many applications depend on PostgreSQL as their database, you will
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
2015-12-08 14:11:27 -05:00
If you are using [GitLab Runner ](../runners/README.md ) with the Docker executor
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
2019-07-24 02:11:14 -04:00
NOTE: **Note:**
2020-02-27 22:09:04 -05:00
The `POSTGRES_DB` , `POSTGRES_USER` , `POSTGRES_PASSWORD` and `POSTGRES_HOST_AUTH_METHOD`
variables can't be set in the GitLab UI. To set them, assign them to a variable
2020-05-05 14:09:43 -04:00
[in the UI ](../variables/README.md#create-a-custom-variable-in-the-ui ), and then assign that
2020-02-27 22:09:04 -05:00
variable to the `POSTGRES_DB` , `POSTGRES_USER` , `POSTGRES_PASSWORD` and `POSTGRES_HOST_AUTH_METHOD`
variables in your `.gitlab-ci.yml` .
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
2015-12-08 16:49:05 -05:00
If you are 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 ).
2015-12-08 11:22:45 -05:00
For example, to use PostgreSQL 9.3 the service becomes `postgres:9.3` .
2015-11-25 08:41:14 -05:00
2015-12-08 11:22:45 -05:00
The `postgres` image can accept some environment variables. For more details
2020-03-30 02:07:59 -04:00
check 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
2015-12-08 15:26:41 -05:00
The next step is to create a user, so login 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
2015-12-08 15:26:41 -05:00
Then create a user (in our case `runner` ) which will be used by your
application. Change `$password` in the command below to a real strong password.
2015-11-25 08:41:14 -05:00
2015-12-08 15:26:41 -05:00
*__Note:__ Do not type `template1=#` , this is 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
2015-12-08 15:26:41 -05:00
*__Note:__ Notice that we created the user with the privilege to be able to
2019-07-12 04:15:38 -04:00
create databases (`CREATEDB`). In the following steps we will create a database
2015-12-08 15:26:41 -05:00
explicitly for that user but having that privilege can be useful if in your
testing framework you have tools that drop and create databases.*
Create the database and grant all privileges on 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;
```
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
```
*__Note:__ We are explicitly telling `psql` to connect to localhost in order
to use the md5 authentication. If you omit this step you will be denied access.*
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-03-13 05:09:23 -04:00
Want to hack on it? Simply fork it, commit and push your changes. Within a few
2017-02-13 11:59:57 -05:00
moments the changes will be picked by a public runner and the job will begin.