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

# Database Setup

> Configure RDS PostgreSQL for agent memory and knowledge

## Overview

AgentOS uses PostgreSQL for:

* Agent memory and sessions
* Knowledge embeddings (pgvector)
* Custom application data

RDS is created automatically by `ag infra up prd:aws`.

## Prerequisites

Complete [Secrets Setup](/deploy/templates/aws/configure/secrets) first. The database credentials must exist before deployment.

## Database Credentials

Edit `infra/secrets/prd_db_secrets.yml`:

```yaml theme={null}
DB_USER: "ai"
DB_PASS: "YourSecurePassword123"
```

Generate a secure password:

```bash theme={null}
openssl rand -base64 24
```

<Warning>
  Avoid `@`, `#`, `%`, `&` in passwords. These require URL encoding and cause silent connection failures.

  Safe characters: alphanumeric, `!`, `-`, `_`
</Warning>

## RDS Configuration

Default configuration in `prd_resources.py`:

| Setting             | Default        | Description     |
| ------------------- | -------------- | --------------- |
| `engine`            | `postgres`     | PostgreSQL      |
| `engine_version`    | `17.2`         | PostgreSQL 17   |
| `allocated_storage` | `64`           | 64 GB storage   |
| `db_instance_class` | `db.t4g.small` | \~\$25/month    |
| `db_name`           | `ai`           | Database name   |
| `port`              | `5432`         | PostgreSQL port |

### Customize RDS

Edit `prd_resources.py`:

```python prd_resources.py theme={null}
prd_db = DbInstance(
    ...
    db_instance_class="db.t4g.medium",  # Larger instance
    allocated_storage=128,               # More storage
    engine_version="17.2",               # PostgreSQL version
)
```

After changes:

<CodeGroup>
  ```bash Full Options theme={null}
  ag infra patch --env prd --infra aws --type dbinstance
  ```

  ```bash Shorthand theme={null}
  ag infra patch prd:aws:::dbinstance
  ```
</CodeGroup>

<Note>
  Some changes (like instance class) require a reboot. Check AWS Console for
  status.
</Note>

## Connection Settings

The app connects via environment variables set automatically in `prd_resources.py`:

| Variable      | Source                        |
| ------------- | ----------------------------- |
| `DB_HOST`     | RDS endpoint (auto-populated) |
| `DB_PORT`     | RDS port (auto-populated)     |
| `DB_USER`     | From `prd_db_secrets.yml`     |
| `DB_PASS`     | From `prd_db_secrets.yml`     |
| `DB_DATABASE` | RDS database name             |

## Migrations

### Option 1: Run on Deployment

Add `MIGRATE_DB` to `prd_resources.py`:

```python prd_resources.py theme={null}
container_env = {
    ...
    "MIGRATE_DB": True,
}
```

Then update and redeploy:

<CodeGroup>
  ```bash Full Options theme={null}
  ag infra patch --env prd --infra aws --name td && ag infra patch --env prd --infra aws --name service
  ```

  ```bash Shorthand theme={null}
  ag infra patch prd:aws::td && ag infra patch prd:aws::service
  ```
</CodeGroup>

### Option 2: Run Manually via ECS Exec

```bash theme={null}
ECS_CLUSTER={infra_name}-prd
TASK_ARN=$(aws ecs list-tasks --cluster $ECS_CLUSTER --query "taskArns[0]" --output text)

aws ecs execute-command \
    --cluster $ECS_CLUSTER \
    --task $TASK_ARN \
    --container {infra_name}-prd-api \
    --interactive \
    --command "alembic -c db/alembic.ini upgrade head"
```

## Verify Connection

After deployment, verify the database is accessible:

```bash theme={null}
# Get RDS endpoint
aws rds describe-db-instances \
  --db-instance-identifier {infra_name}-prd-db \
  --query 'DBInstances[0].Endpoint.Address' \
  --output text
```

Test connection (requires `psql`):

```bash theme={null}
psql -h [RDS_ENDPOINT] -U ai -d ai
```

## Troubleshooting

| Issue                     | Solution                                           |
| ------------------------- | -------------------------------------------------- |
| Cannot connect to RDS     | Check security group allows port 5432 from your IP |
| Connection fails silently | Remove special characters from password            |
| RDS not ready             | Wait \~5 minutes, check AWS Console                |
| ECS can't connect         | Verify security group allows ECS security group    |