# Storage block

Cerbos supports multiple backends for storing policies. Which storage driver to use is defined by the `driver` setting.

## Blob driver

Cerbos policies can be stored in AWS S3, Google Cloud Storage, or any other S3-compatible storage systems such as [Minio](https://www.minio.io/).

### Configuration keys

- `bucket`: Required. A URL specifying the service (e.g. S3, GCS), the storage bucket and any other configuration parameters required by the provider.

- AWS S3: `s3://my-bucket?region=us-west-1`. Must specify region in the URL.
  - Google Cloud Storage: `gs://my-bucket`
  - S3-compatible (e.g. Minio): `s3://my-bucket?endpoint=my.minio.local:8080&disableSSL=true&s3ForcePathStyle=true&region=local`. Must specify region in the URL.

- `prefix`: Optional. Look for policies only under this key prefix.
- `workDir`: Optional. Path to the local directory to download the policies to. Defaults to the system cache directory if not specified.
- `updatePollInterval`: Optional. How frequently the blob store should be checked to discover new or updated policies. Defaults to 0 — which disables polling.
- `requestTimeout`: Optional. HTTP request timeout. It takes an HTTP request to download a policy file. Defaults to 5s.
- `downloadTimeout`: Optional. Timeout to download all policies from the storage provider. Must be greater than the `requestTimeout`. Defaults to 60s.

### Blob driver example configurations

AWS S3

```yaml
storage:
  driver: "blob"
  blob:
    bucket: "s3://my-bucket-name?region=us-east-2"
    prefix: policies
    workDir: ${HOME}/tmp/cerbos/work
    updatePollInterval: 15s
    downloadTimeout: 30s
    requestTimeout: 10s
```

Google Cloud Storage

```yaml
storage:
  driver: "blob"
  blob:
    bucket: "gs://my-bucket-name"
    workDir: ${HOME}/tmp/cerbos/work
    updatePollInterval: 10s
```

Minio local container

```yaml
storage:
  driver: "blob"
  blob:
    bucket: "s3://my-bucket-name?endpoint=localhost:9000&disableSSL=true&s3ForcePathStyle=true&region=local"
    workDir: ${HOME}/tmp/cerbos/work
    updatePollInterval: 10s
```

## Disk driver

The disk driver is a way to serve the policies from a directory on the filesystem. Any `.yaml`, `.yml` or `.json` files in the directory tree rooted at the given path will be read and parsed as policies.

### Static fileset with no change detection

```yaml
storage:
  driver: disk
  disk:
    directory: /etc/cerbos/policies
```

### Dynamic fileset with change detection

```yaml
storage:
  driver: disk
  disk:
    directory: /etc/cerbos/policies
    watchForChanges: true
```

### Archive files

You can opt to archive and/or compress your policies directory into a Zip (`.zip`), Tar (`.tar`) or Gzip file (`.tgz` or `.tar.gz`). The archive is assumed to be laid out like a standard policy directory.

```yaml
storage:
  driver: disk
  disk:
    directory: /etc/cerbos/policies.zip
```

## Git driver

Git is the preferred method of storing Cerbos policies. The server detects when new commits are made to the git repository and refreshes its state based on the changes.

### Local git repository

```yaml
storage:
  driver: "git"
  git:
    protocol: file
    url: file://${HOME}/tmp/cerbos/policies
    checkoutDir: ${HOME}/tmp/cerbos/work
    updatePollInterval: 10s
```

### Remote git repository accessed over HTTPS

```yaml
storage:
  driver: "git"
  git:
    protocol: https
    url: https://github.com/cerbos/policy-test.git
    branch: main
    subDir: policies
    checkoutDir: ${HOME}/tmp/work/policies
    updatePollInterval: 60s
    operationTimeout: 30s
    https:
      username: cerbos
      password: ${GITHUB_TOKEN}
```

### Remote git repository accessed over SSH

```yaml
storage:
  driver: "git"
  git:
    protocol: ssh
    url: github.com:cerbos/policy-test.git
    branch: main
    subDir: policies
    checkoutDir: ${HOME}/tmp/cerbos/work
    updatePollInterval: 60s
    ssh:
      user: git
      privateKeyFile: ${HOME}/.ssh/id_rsa
```

## MySQL driver

The MySQL storage backend supports adding or updating policies at runtime through the [Admin API](https://docs.cerbos.dev/cerbos/0.36.0/configuration/server#admin-api).

### Use MySQL as a storage backend for Cerbos

```yaml
storage:
  driver: "mysql"
  mysql:
    dsn: "${MYSQL_USER}:${MYSQL_PASSWORD}@tcp(localhost:3306)/cerbos"
```

### Secure connections

If your MySQL server requires TLS or if you want to use RSA key pair-based password exchange:

```yaml
storage:
  driver: "mysql"
  mysql:
    dsn: "${MYSQL_USER}:${MYSQL_PASSWORD}@tcp(localhost:3306)/cerbos?tls=mysecuretls"
    tls:
      mysecuretls:
        caCert: /path/to/ca_certificate.crt
        cert: /path/to/certificate.crt
        key: /path/to/private.key
```

### Connection pool

```yaml
storage:
  driver: "mysql"
  mysql:
    dsn: "${MYSQL_USER}:${MYSQL_PASSWORD}@tcp(localhost:3306)/cerbos"
    connPool:
      maxLifeTime: 5m
      maxIdleTime: 3m
      maxOpen: 10
      maxIdle: 5
```

## Postgres driver

The Postgres storage backend supports adding or updating policies at runtime through the [Admin API](https://docs.cerbos.dev/cerbos/0.36.0/configuration/server#admin-api).

### Use Postgres as a storage backend for Cerbos

```yaml
storage:
  driver: "postgres"
  postgres:
    url: "postgres://${PG_USER}:${PG_PASSWORD}@localhost:5432/postgres?sslmode=disable&search_path=cerbos"
```

### Connection pool

```yaml
storage:
  driver: "postgres"
  postgres:
    url: "postgres://${PG_USER}:${PG_PASSWORD}@localhost:5432/postgres?sslmode=disable&search_path=cerbos"
    connPool:
      maxLifeTime: 5m
      maxIdleTime: 3m
      maxOpen: 10
      maxIdle: 5
```

## SQLite3 driver

The SQLite3 storage backend supports adding or updating policies at runtime through the [Admin API](https://docs.cerbos.dev/cerbos/0.36.0/configuration/server#admin-api).

### In-memory ephemeral database

```yaml
storage:
  driver: "sqlite3"
  sqlite3:
    dsn: ":memory:"
```

### On-disk persistent database

```yaml
storage:
  driver: "sqlite3"
  sqlite3:
    dsn: "file:/tmp/cerbos.sqlite?mode=rwc&cache=shared&_fk=true"
```

## Microsoft SQL Server driver

The SQL Server storage backend supports adding or updating policies at runtime through the [Admin API](https://docs.cerbos.dev/cerbos/0.36.0/configuration/server#admin-api).

### Use SQL Server as a storage backend for Cerbos

```yaml
storage:
  driver: "sqlserver"
  sqlserver:
    url: "sqlserver://${SQL_SERVER_USERNAME}:${SQL_SERVER_PASSWORD}@host/instance?database=cerbos&param1=value&param2=value"
```

### Connection pool

```yaml
storage:
  driver: "sqlserver"
  sqlserver:
    url: "sqlserver://${SQL_SERVER_USERNAME}:${SQL_SERVER_PASSWORD}@host/instance?database=cerbos&param1=value&param2=value"
    connPool:
      maxLifeTime: 5m
      maxIdleTime: 3m
      maxOpen: 10
      maxIdle: 5
```

### Database object definitions

```sql
CREATE DATABASE IF NOT EXISTS cerbos CHARACTER SET utf8mb4;
USE cerbos;
CREATE TABLE IF NOT EXISTS policy (...);
...;
```