# Database and Cache Monad keeps its configuration in Postgres and caches in a Redis-compatible store. By default the chart runs both in your cluster: Postgres through the CloudNativePG operator, and Dragonfly as the cache. Read this page to size the chart's Postgres, or to use a Postgres or cache you already run. Decide before the first install: the chart's Postgres volumes keep the StorageClass they are created with, and moving Monad to another database later is a migration you do yourself. :::note[Merge snippets into your values file] Each values snippet gives full paths from the top-level key. The chart's example files already have some of these keys, such as `global` in every example and `postgresql` in `private-cluster.yaml` and `local-auth-external-postgres.yaml`. Add a snippet's settings under the key you already have: a second copy of a top-level key silently replaces the first. See [Install](/docs/guides/self-managed/install#build-your-values-file). ::: ## Chart-managed Postgres With `postgresql.cnpg.enabled: true`, the default, the chart creates a CloudNativePG `Cluster`, which needs the CloudNativePG operator ([Operators and controllers](/docs/guides/self-managed/before-you-install#operators-and-controllers)). Postgres runs the image your operator defaults to. CloudNativePG creates an `app` database owned by an `app` user, and writes their connection to the Secret `monad-db-app`, which Monad's components read through `global.monad.dbSecret`. With [local authentication](/docs/guides/self-managed/authentication#local-authentication), the chart also creates a `kratos` database and role in it. | Key | Default | What it sets | | --- | --- | --- | | `postgresql.cnpg.instances` | `3` | Postgres instances: one primary, the rest standbys | | `postgresql.cnpg.minSyncReplicas` | `1` | Fewest standbys that must confirm each commit | | `postgresql.cnpg.maxSyncReplicas` | `1` | Most standbys that confirm each commit synchronously. Must be lower than `instances`. | | `postgresql.cnpg.storage.size` | `5Gi` | Each instance's data volume. It can grow later where the StorageClass allows expansion, and cannot shrink. | | `postgresql.cnpg.storage.storageClass` | Cluster default | StorageClass for the data volumes. Existing volumes keep the class they were created with. | | `postgresql.cnpg.resources` | Requests `10m` CPU, `512Mi` memory | Requests and limits for each instance | | `postgresql.cnpg.name` | `monad-db` | Name of the `Cluster`. CloudNativePG writes the connection to `-app`, so set `global.monad.dbSecret` to match when you change it. | | `postgresql.cnpg.monitoring.enabled` | `false` | Renders a PodMonitor for the Postgres pods. The render fails unless the Prometheus Operator CRDs are installed. | | `postgresql.cnpg.spec` | `{}` | Any other CloudNativePG `Cluster` field, copied in as written, such as `imageName` or `postgresql.parameters`. A field the chart also sets, such as `instances` or `storage`, takes the value here instead. | For example, to size the instances and put them on a particular StorageClass. In `private-cluster.yaml`, add these under its existing `postgresql.cnpg` key, which already sets the image and resources: ```yaml postgresql: cnpg: instances: 3 storage: size: 50Gi storageClass: resources: requests: cpu: 500m memory: 2Gi limits: memory: 2Gi ``` For a single instance, such as on a development cluster, also set `minSyncReplicas: 0` and `maxSyncReplicas: 0` in the same block. CloudNativePG rejects a `Cluster` whose `maxSyncReplicas` is not lower than `instances`. Every PVC the chart creates is listed in the [storage table](/docs/guides/self-managed/before-you-install#storage). Placement and priority for the Postgres pods are on [Scheduling and Resources](/docs/guides/self-managed/scheduling), and backups on [Backup and Restore](/docs/guides/self-managed/backup-and-restore#back-up-postgres). ## Your own Postgres To use a Postgres you run yourself, turn off the chart's, give Monad a database and a user, and put their connection in a Secret. The chart's `examples/local-auth-external-postgres.yaml` is a complete values file for your own Postgres with local authentication; see [Get the chart and its examples](/docs/guides/self-managed/install#get-the-chart-and-its-examples). ### Requirements - **Version.** Use PostgreSQL 16 or later. - **A database the Monad user owns.** Monad's migrations, which run before each api pod starts, create the `uuid-ossp` extension, tables, indexes and functions, and a daily `partition-manager` job creates and drops monthly partitions of the audit log. If your provider restricts extensions, allow `uuid-ossp` first. For example, as a user allowed to create roles and databases: ```sql CREATE USER monad WITH PASSWORD ''; GRANT monad TO CURRENT_USER; CREATE DATABASE monad OWNER monad; ``` The `GRANT` lets an administrator that is not a superuser, as on most managed services, give the database to `monad`. - **Network access** from the pods in the release namespace. - **TLS** as described below. How the components connect over TLS depends on the `useInsecure` key in the database Secret, or `global.monad.dbUseInsecure` when the Secret has none (default `"false"`): | Setting | Connection | | --- | --- | | `"true"` | Without TLS | | Anything else | With TLS when the server offers it, without verifying the server's certificate; without TLS when it does not | The migrations and `partition-manager` connect with the `uri` key as written instead, so set its `sslmode` to match, such as `sslmode=require` with TLS or `sslmode=disable` with `useInsecure: "true"`. ### Create the database Secret Create a Secret named `monad-db-app` in the release namespace. The components read it through the Kubernetes API when they start, so it must be in the same namespace as Monad. | Key | Read by | Value | | --- | --- | --- | | `host` | api, api-grpc, eventhandler, quota-service-cron | The server's host name. Monad does not read a `port` key, so for a port other than 5432 add it here, such as `db.example.com:6432`. | | `user` | The same | The Monad user | | `password` | The same | Its password | | `dbname` | The same | The Monad database | | `uri` | The api's migrations, `partition-manager` | The full connection URI, such as `postgresql://monad:@db.example.com:5432/monad?sslmode=require` | | `useInsecure` | Optional | `"true"` to connect without TLS | :::warning[Passwords go into a URI] Use a password of letters and digits, such as one from `openssl rand -hex 24`. Monad puts the password into a connection URI, and in some versions a character such as `@`, `/` or `%` makes it fail to connect or reach the wrong host. Put the password in `password` as it is, and percent-encode any character other than a letter or digit in `uri`. ::: For example, from a file named `db.env`. Keep each line exactly `key=value`, with no comments or trailing spaces, because kubectl copies everything after the `=` into the value: ```bash host=db.example.com dbname=monad user=monad password= uri=postgresql://monad:@db.example.com:5432/monad?sslmode=require ``` ```bash kubectl create secret generic monad-db-app \ --from-env-file=db.env \ -n monad ``` To use another name, set `global.monad.dbSecret` to it. Every component that connects to the database reads the Secret it names, including the migrations and `partition-manager`. ### Point the chart at your database Turn off the chart's Postgres in your values: ```yaml postgresql: cnpg: enabled: false ``` The CloudNativePG operator is then not needed. With local authentication, Kratos also needs a database of its own; see the next section. ### Kratos on your own Postgres With [local authentication](/docs/guides/self-managed/authentication#local-authentication), Kratos keeps its data in its own database. The chart creates it only in its own Postgres, so with yours: 1. Create a database for Kratos and a user that owns it. Kratos creates its tables when it starts, so the database can be empty: ```sql CREATE USER kratos WITH PASSWORD ''; GRANT kratos TO CURRENT_USER; CREATE DATABASE kratos OWNER kratos; ``` 2. Create the `monad-kratos-secrets` Secret with a `dsn` pointing at that database, such as `postgres://kratos:@db.example.com:5432/kratos?sslmode=require`, and set `kratos.secret.generate: false`. Both steps are in [Provide the Kratos Secret yourself](/docs/guides/self-managed/authentication#provide-the-kratos-secret-yourself). The chart fails to render if Kratos is on with your own Postgres and `generate` is still `true`. ## Your own Redis-compatible cache To use a Redis-compatible cache you already run instead of the chart's Dragonfly, turn Dragonfly off and set the cache's URL. If your values file already has a `global` block, as the chart's examples do, add `monad.redisUrl` under it rather than repeating `global`, because a repeated top-level key replaces the earlier one without an error: ```yaml dragonfly: enabled: false global: monad: redisUrl: redis://:6379 ``` The chart fails to render with `dragonfly.enabled: false` and no `redisUrl`. The URL takes the form `redis://[[user]:password@]host:port`, or `rediss://` for TLS; percent-encode reserved characters in the user and password. It reaches the api, api-grpc, http-input and the operator, and the operator passes it to the pipeline and alert pods it creates, as a plain environment variable that anyone who can read those pods can see. The operator still starts a separate Dragonfly for each pipeline that needs its own store. Its image is set apart from the chart's; see [Images and Registries](/docs/guides/self-managed/images).