Connecting to your Database

This guide will walk you through how to connect to your database in development and production.

How databases are configured

We follow the methods provided by the official docker images for each database. You'll notice in your docker-compose.*.yml files that we use environment variables to configure the database connection.

You can change the environment variables if you'd like, but regardless of the values in there, the container will automatically set up and configure the database for you.

Using a database GUI manager

The easiest way to connect to your database is through a GUI, like TablePlus.

Connecting in development

This method is pretty easy to refer to your .env file for the connection details. You can use the following connection details:

Connecting to a production database

Since exposing database ports is a security risk, we don't expose the database ports in production. Instead, you can use an SSH tunnel to connect to your database.

How it works

We use another one of our open source images called serversideup/docker-ssh to create an ssh service.

This container will create expose a secure SSH service that only allows users to connect with key-based authentication (a secure method compared to password-based authentication).

By default, the username of the SSH user is tunnel, but we can add many authorized keys to the container to allow multiple users to connect.

In your docker-compose.prod.yml file, you will notice a service called ssh:

  ssh:
    # We use an SSH image so we can securely tunnel into the Docker network with 
    # tools like Sequel Pro, TablePlus, Sequel Ace, etc.
    # Learn more how to secure your tunnel here: https://github.com/serversideup/docker-ssh
    image: serversideup/docker-ssh
    ports:
      - target: 2222
        published: 2222
        mode: host
    environment:
      # Change the keys below to your own keys 
      AUTHORIZED_KEYS: >
        "# Start Keys
         ssh-ed25519 1234567890abcdefghijklmnoqrstuvwxyz user-a
         ssh-ed25519 abcdefghijklmnoqrstuvwxyz1234567890 user-b
         # End Keys"
      # Be sure to configure the allowed IP addresses too
      ALLOWED_IPS: "AllowUsers tunnel"

Set your keys

For every user, you can set their public key in the AUTHORIZED_KEYS environment variable. You can add as many keys as you'd like.

Put one key per line:

  # Change the keys below to your own keys 
  AUTHORIZED_KEYS: >
    "# Start Keys
      ssh-ed25519 1234567890abcdefghijklmnoqrstuvwxyz user-a
      ssh-ed25519 abcdefghijklmnoqrstuvwxyz1234567890 user-b
      # End Keys"

You can get the value of your key by using the cat command as we show in our open source docs.

Locking down your SSH tunnel

You can also lock down the IP addresses that can connect to your SSH tunnel. This is done by setting the ALLOWED_IPS environment variable:

  ALLOWED_IPS: "AllowUsers [email protected]"

The above configuration will only allow the IP address 1.2.3.4 to connect to the SSH tunnel.

Connecting to your database

Once you have your SSH tunnel set up, you can use a GUI like TablePlus to connect to your database.

Create a new connection and click Over SSH.

You'll see the menus expand out where you can add more details.

Use the table below to help you configure your connection:

Once you've filled in the details, click Connect and you should be able to connect to your database.