# Tuning

> Understand resource-based Postgres defaults and apply a named parameter group to an instance.

Source: https://oddk.dev/docs/tuning/
Project: https://github.com/AndrianBdn/oddk


oddk's default parameter group calculates memory and worker settings from the
RAM and CPU cores assigned to each instance. These are starting points; adjust
them for your workload and connection pool.

## Default parameters

For the default group `default:2025-08-27`, RAM below is the instance's assigned
memory in MB, and cores is its assigned CPU count. Memory calculations and
`max_connections` are rounded to whole numbers.

| Parameter | Default calculation |
|---|---|
| `shared_buffers` | RAM ÷ 4, in MB |
| `effective_cache_size` | RAM × 0.75, in MB |
| `max_connections` | RAM ÷ 16 |
| `maintenance_work_mem` | 5% of RAM, clamped to 64–2048 MB |
| `effective_io_concurrency` | cores × 8 |
| `max_worker_processes` | cores × 2, with a minimum of 8 |
| `work_mem` | 25% of RAM ÷ max_connections, clamped to 4–64 MB |

With the default connection calculation, `work_mem` resolves to 4 MB for the
8 GB instance in the [Quickstart](../quickstart/).

## Create a parameter group

Groups are named and cannot be edited in place. Export a group to use as your
starting point:

```bash
oddk parameters get --name default:2025-08-27 --json > app-params.json
```

Edit the `parameters` entries in `app-params.json`. For example, to use a
fixed connection limit, replace the existing `max_connections` entry with:

```json
{
  "name": "max_connections",
  "type": "postgres_cli_arg",
  "valueType": "numeric",
  "value": "200"
}
```

This is an example limit, not a workload recommendation. Keep the other entries
and choose a group name you have not used before:

```bash
oddk parameters put app-tuned --file app-params.json
```

The name passed to `put` names the new group. The exported object and a bare
parameter array are both accepted as input.

## Apply to an instance

Applying a group recreates the container while keeping its data volume. Plan
for a connection interruption, and take a snapshot first:

```bash
oddk snapshot make --comment "before tuning"
oddk instance apply app --parameter-group app-tuned
oddk checklist
```

Before removing the running container, oddk checks that the parameters resolve
and that the estimated shared memory fits the instance's RAM. If the new
container cannot become ready, it attempts to rebuild the previous configuration
and returns the error.

To deliberately return to the default group:

```bash
oddk instance apply app --parameter-group default:2025-08-27
```