import { TabsGroup, TabsItem } from "@/components/DocsTabs";
import Alert from "@/components/DocsAlert";

# Custom External Database

Firezone uses [Postgresql DB](https://postgresql.org) as its primary data store.

## Compatibility

Firezone should work fine on Postgres versions 12 and above, but we recommend
using the latest stable version whenever possible. If you find an issue with
your particular version of Postgres,
[please open a GitHub issue ](https://github.com/firezone/firezone/issues).

In general, Firezone should also work fine using external Postgres-based
database services like Amazon RDS. See the
[configuration ](#configure-firezone-to-connect) section below for more
information configuring Firezone with an external DB.

<Alert
  color="warning"
  html={`
Configuring Firezone to use an external database can be complicated and
error-prone. We recommend using the bundled Postgres for Omnibus-based
deployments or the official Postgres Docker image for Docker-based deployments
if possible.
`}
/>

## Configure Firezone to Connect

<TabsGroup>
<TabsItem title="Docker" active>

The Firezone Docker image uses the following environment variables to connect to
the DB (fields in bold required):

| Name                          | Description                                                                                                                                                                                                           | Format                | Default                              |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ------------------------------------ |
| **`DATABASE_ENCRYPTION_KEY`** | The base64-encoded symmetric encryption key used to encrypt and decrypt sensitive fields.                                                                                                                             | base64-encoded String | None -- must be generated on install |
| `DATABASE_HOST`               | Database host                                                                                                                                                                                                         | IP or hostname        | `postgres`                           |
| `DATABASE_PORT`               | Database port                                                                                                                                                                                                         | Integer               | `5432`                               |
| `DATABASE_NAME`               | Name of database                                                                                                                                                                                                      | String                | `firezone`                           |
| `DATABASE_USER`               | User                                                                                                                                                                                                                  | String                | `postgres`                           |
| `DATABASE_PASSWORD`           | Password                                                                                                                                                                                                              | String                | `postgres`                           |
| `DATABASE_POOL`               | Size of the Firezone connection pool                                                                                                                                                                                  | Integer               | `10`                                 |
| `DATABASE_SSL`                | Whether to connect to the database over SSL                                                                                                                                                                           | Boolean               | `false`                              |
| `DATABASE_SSL_OPTS`           | Map of options to send to the `:ssl_opts` option when connecting over SSL. See [Ecto.Adapters.Postgres documentation](https://hexdocs.pm/ecto_sql/Ecto.Adapters.Postgres.html#module-connection-options)              | JSON-encoded String   | `{}`                                 |
| `DATABASE_PARAMETERS`         | Map of parameters to send to the `:parameters` option when connecting to the database. See [Ecto.Adapters.Postgres documentation](https://hexdocs.pm/ecto_sql/Ecto.Adapters.Postgres.html#module-connection-options). | JSON-encoded String   | `{}`                                 |

For more information, see the
[environment variable reference ](/docs/reference/env-vars).

<Alert
  color="info"
  html={`
The official <code>postgres</code> docker image can be configured by setting environment
variables for the container. See the Postgres image
<a href="https://hub.docker.com/_/postgres">documentation</a> for more details.
`}
/>

</TabsItem>
<TabsItem title="Omnibus">

The following configuration options are used to configure the bundled Postgres
for Omnibus-based deployments:

| Config Key                                      | Description                                                                                                                                                                                                            | Default                                            |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `default['firezone']['database']['user']`       | Specifies the username Firezone will use to connect to the DB.                                                                                                                                                         | `node['firezone']['postgresql']['username']`       |
| `default['firezone']['database']['password']`   | If using an external DB, specifies the password Firezone will use to connect to the DB.                                                                                                                                | `'change_me'`                                      |
| `default['firezone']['database']['name']`       | Database that Firezone will use. Will be created if it doesn't exist.                                                                                                                                                  | `'firezone'`                                       |
| `default['firezone']['database']['host']`       | Database host that Firezone will connect to.                                                                                                                                                                           | `node['firezone']['postgresql']['listen_address']` |
| `default['firezone']['database']['port']`       | Database port that Firezone will connect to.                                                                                                                                                                           | `node['firezone']['postgresql']['port']`           |
| `default['firezone']['database']['pool']`       | Database pool size Firezone will use.                                                                                                                                                                                  | `[10, Etc.nprocessors].max`                        |
| `default['firezone']['database']['ssl']`        | Whether to connect to the database over SSL.                                                                                                                                                                           | `false`                                            |
| `default['firezone']['database']['ssl_opts']`   | Hash of options to send to the `:ssl_opts` option when connecting over SSL. See [Ecto.Adapters.Postgres documentation](https://hexdocs.pm/ecto_sql/Ecto.Adapters.Postgres.html#module-connection-options).             | `{}`                                               |
| `default['firezone']['database']['parameters']` | Hash of parameters to send to the `:parameters` option when connecting to the database. See [Ecto.Adapters.Postgres documentation](https://hexdocs.pm/ecto_sql/Ecto.Adapters.Postgres.html#module-connection-options). | `{}`                                               |
| `default['firezone']['database']['extensions']` | Database extensions to enable.                                                                                                                                                                                         | `{ 'plpgsql' => true, 'pg_trgm' => true }`         |

For more details, see the
[configuration file reference ](/docs/reference/configuration-file).

</TabsItem>
</TabsGroup>
