> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Infrastructure

> Toggle between interaction store backends and plan migrations as your platform scales.

## Overview

KaireonAI's interaction store is the highest-volume component in the platform — every `recommend` and `respond` call reads or writes interaction data. The platform ships **four backend implementations**. The active backend is selected process-wide by the `INTERACTION_STORE` environment variable, read once at startup (default `pg`). An admin API records the intended backend as a tenant setting for visibility and audit, but changing the live adapter requires setting `INTERACTION_STORE` (plus the per-backend env vars) and restarting.

***

## Interaction Store Backend Setting

The intended backend is recorded as a tenant-level setting (admin-only) and can be read or updated via the API. This records your preference and writes an audit-log entry — it does **not** repoint live traffic or migrate data. The runtime adapter is chosen by the `INTERACTION_STORE` env var.

```bash theme={null}
# Read the recorded backend for the tenant (admin only)
curl /api/v1/settings/interaction-store \
  -H 'X-API-Key: <admin-key>' -H 'X-Tenant-Id: <tenant-id>'

# Record the intended backend (admin only)
curl -X PUT /api/v1/settings/interaction-store \
  -H 'X-API-Key: <admin-key>' -H 'X-Tenant-Id: <tenant-id>' \
  -H 'Content-Type: application/json' \
  -d '{ "backend": "dynamodb" }'
```

Accepted `backend` values for the setting: `postgresql`, `keyspaces`, `scylla`, `dynamodb`. Note the `INTERACTION_STORE` env var uses `pg` (not `postgresql`) for the PostgreSQL backend.

### Available Backends

| Backend           | Value        | Best For                                          |
| ----------------- | ------------ | ------------------------------------------------- |
| **PostgreSQL**    | `postgresql` | Development, small deployments (\<500K customers) |
| **AWS Keyspaces** | `keyspaces`  | Managed Cassandra-compatible, moderate scale      |
| **ScyllaDB**      | `scylla`     | High throughput, low latency, self-managed        |
| **DynamoDB**      | `dynamodb`   | Serverless, auto-scaling, multi-region            |

`postgresql` is the default and requires no additional infrastructure beyond your existing database.

<Note>
  All four implementations exist and are fully functional. The runtime adapter is chosen by the `INTERACTION_STORE` env var at process start (default `pg`) — changing the tenant setting alone does not repoint reads and writes. Set the env var and restart to switch the live backend.
</Note>

***

## When to Switch

Consider moving off PostgreSQL when any of the following apply:

| Signal                   | Threshold                                      |
| ------------------------ | ---------------------------------------------- |
| Customer base            | >500K active customers                         |
| Write throughput         | >1,000 writes/sec sustained                    |
| Multi-region requirement | Need cross-region replication                  |
| Query latency            | Interaction queries degrading OLTP performance |

For most deployments under these thresholds, PostgreSQL is the simplest and most cost-effective option.

***

## Migration Path

Switching backends does not automatically migrate existing data, and there is **no built-in dual-write mode**. Plan an operational cutover:

### Step 1 — Provision and Point the New Backend

Provision the target store (DynamoDB table, ScyllaDB cluster, or Keyspaces keyspace), then set `INTERACTION_STORE` and the matching per-backend environment variables (see [Infrastructure Backends](/self-host/deploy/infrastructure-backends)) and roll the deployment.

### Step 2 — Backfill from Exported Files

Use the [exported interaction files](/governance-security/retention) (Hive-partitioned NDJSON) to backfill historical data into the new backend. This avoids reading from the production PostgreSQL database during migration.

### Step 3 — Cut Over

Once the backfill is complete and you have verified data consistency, roll the fleet onto the new `INTERACTION_STORE` value. All reads and writes then flow through the new backend. The old PostgreSQL interaction tables can be archived or dropped after a safety period.

<Warning>
  Test the new backend with production-like load before cutting over. Use the decision trace debug mode to verify that interaction lookups return consistent results after the backfill.
</Warning>

***

## Related

<CardGroup cols={3}>
  <Card title="Infrastructure Backends" icon="server" href="/self-host/deploy/infrastructure-backends">
    Full details on all pluggable backends (cache, events, search, and more).
  </Card>

  <Card title="Retention & Archival" icon="archive" href="/governance-security/retention">
    Export interaction history before migration or cleanup.
  </Card>

  <Card title="Capacity Planning" icon="chart-line" href="/self-host/operate/capacity-planning">
    Size your infrastructure for production workloads.
  </Card>
</CardGroup>