Database Setup

Overview

IronClaw supports two database backends:

PostgreSQL - Production-grade, requires a running server
libSQL - Embedded SQLite, zero dependencies, optional Turso cloud sync

The onboarding wizard helps you choose and configure either option. This guide covers manual configuration and advanced settings.

PostgreSQL

Requirements

PostgreSQL 15 or later
pgvector extension (required for embeddings)

Installation

macOS
Ubuntu/Debian
Docker

# Install PostgreSQL and pgvector
brew install postgresql@15 pgvector

# Start PostgreSQL
brew services start postgresql@15

# Create database
createdb ironclaw

# Enable pgvector
psql ironclaw -c "CREATE EXTENSION IF NOT EXISTS vector;"

# Install PostgreSQL
sudo apt update
sudo apt install postgresql-15

# Install pgvector
sudo apt install postgresql-15-pgvector

# Start PostgreSQL
sudo systemctl start postgresql

# Create database (as postgres user)
sudo -u postgres createdb ironclaw
sudo -u postgres psql ironclaw -c "CREATE EXTENSION IF NOT EXISTS vector;"

# Use official pgvector image
docker run -d \
  --name ironclaw-db \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=ironclaw \
  -p 5432:5432 \
  pgvector/pgvector:pg15

# Enable pgvector (after container starts)
docker exec ironclaw-db psql -U postgres -d ironclaw \
  -c "CREATE EXTENSION IF NOT EXISTS vector;"

Configuration

Set the database URL in your environment or ~/.ironclaw/.env:

DATABASE_BACKEND=postgres
DATABASE_URL=postgres://user:password@localhost:5432/ironclaw
DATABASE_POOL_SIZE=10  # optional, default: 10

URL format:

postgres://username:password@host:port/database

Connection Pool

Configure the connection pool size:

DATABASE_POOL_SIZE=10  # Max concurrent connections

Recommendations:

Local development: 5-10 connections
Production: 20-50 connections (depends on workload)
Docker/VPS: Start with 10, adjust based on pg_stat_activity

SSL/TLS Configuration

Control SSL mode for PostgreSQL connections:

DATABASE_SSLMODE=prefer  # default

Options:

Mode	Behavior
`disable`	Never use TLS (plaintext only)
`prefer`	Try TLS first, fall back to plaintext
`require`	Require TLS; fail if unavailable

Recommendations:

Local PostgreSQL: disable (no TLS needed)
Managed databases (Neon, Supabase, RDS): prefer or require
VPS/self-hosted: prefer (default, works everywhere)

Migrations

Migrations run automatically on first connection. To run manually:

ironclaw onboard  # Prompts to run migrations

Or apply with refinery CLI:

cargo install refinery_cli
refinery migrate -e DATABASE_URL -p migrations/

Cloud Providers

Neon

Neon provides serverless Postgres with automatic scaling.

DATABASE_URL=postgres://user:password@ep-xxx.region.aws.neon.tech/ironclaw?sslmode=require

pgvector is pre-installed. Set DATABASE_SSLMODE=require.

Supabase

Supabase includes Postgres with pgvector.

DATABASE_URL=postgres://postgres:password@db.xxx.supabase.co:5432/postgres

Enable pgvector in SQL Editor:

CREATE EXTENSION IF NOT EXISTS vector;

Railway

Railway provides managed Postgres.

DATABASE_URL=${{Postgres.DATABASE_URL}}  # Railway variable

Install pgvector via Railway’s Postgres plugin settings.

AWS RDS

RDS for PostgreSQL with pgvector.

DATABASE_URL=postgres://user:password@instance.region.rds.amazonaws.com:5432/ironclaw
DATABASE_SSLMODE=require

Enable pgvector:

CREATE EXTENSION IF NOT EXISTS vector;

Troubleshooting

pgvector not found

Error: pgvector extension not foundSolution:

macOS: brew install pgvector
Ubuntu: apt install postgresql-15-pgvector
Docker: Use pgvector/pgvector:pg15 image
Source: github.com/pgvector/pgvector#installation

Then enable in your database:

CREATE EXTENSION IF NOT EXISTS vector;

PostgreSQL version too old

Error: PostgreSQL 14 detected. IronClaw requires PostgreSQL 15 or laterSolution: Upgrade PostgreSQL:

macOS: brew upgrade postgresql
Ubuntu: Follow postgresql.org/download/linux/ubuntu/
Docker: Use pgvector/pgvector:pg15 or later

Connection refused

Error: connection refused or could not connect to serverCheck PostgreSQL is running:

# macOS
brew services list | grep postgresql

# Linux
systemctl status postgresql

# Docker
docker ps | grep postgres

Check port:

lsof -i :5432  # Should show postgres

Check pg_hba.conf if connecting remotely.

Authentication failed

Error: password authentication failedCheck password:

psql -U username -d ironclaw  # Test connection

Reset password:

ALTER USER username WITH PASSWORD 'newpassword';

libSQL (Embedded)

Overview

libSQL is an embedded SQLite database with optional Turso cloud sync. No external database server required. Benefits:

Zero dependencies
Single file storage
Automatic migrations
Optional remote sync

Local Setup

DATABASE_BACKEND=libsql
LIBSQL_PATH=~/.ironclaw/ironclaw.db  # default

The database file is created automatically on first run.

Turso Cloud Sync

Turso provides remote replicas for libSQL databases. Setup:

Create a Turso database:
turso db create ironclaw
Get connection details:
turso db show ironclaw
Create an auth token:
turso db tokens create ironclaw

Configure IronClaw:

DATABASE_BACKEND=libsql
LIBSQL_PATH=~/.ironclaw/ironclaw.db
LIBSQL_URL=libsql://your-db.turso.io
LIBSQL_AUTH_TOKEN=your-token

How it works:

Local file (LIBSQL_PATH) is the primary database
Changes sync to the remote replica (LIBSQL_URL)
Other instances can read from the remote replica

Configuration Options

Variable	Description	Default
`DATABASE_BACKEND`	Backend type	`postgres`
`LIBSQL_PATH`	Local database file	`~/.ironclaw/ironclaw.db`
`LIBSQL_URL`	Turso remote URL (optional)	-
`LIBSQL_AUTH_TOKEN`	Turso auth token (required if URL is set)	-

Migrations

Migrations run automatically on first connection (idempotent CREATE IF NOT EXISTS).

Limitations

Concurrency: SQLite uses file-level locking (fine for single-user, not ideal for high-concurrency)
Vector search: Uses JSON instead of native vector types (slower than pgvector)
Backups: Copy the .db file (or use Turso cloud backups)

When to Use libSQL

Good for:

Personal use / single-user
Development / testing
Lightweight deployments
Portable installations

Use PostgreSQL if:

Multiple concurrent users
High-throughput workloads
Large-scale vector search
Production deployments

Switching Backends

To switch from PostgreSQL to libSQL (or vice versa):

Export data (if needed):

# PostgreSQL: pg_dump
pg_dump ironclaw > backup.sql

Change configuration:

# Edit ~/.ironclaw/.env
DATABASE_BACKEND=libsql
LIBSQL_PATH=~/.ironclaw/ironclaw.db

Re-run onboarding:
ironclaw onboard
Migrations run automatically on first connection.

Switching backends creates a fresh database. Export/import data manually if needed.

Environment Variables

PostgreSQL

Variable	Description	Default
`DATABASE_BACKEND`	Backend type (`postgres` or `libsql`)	`postgres`
`DATABASE_URL`	PostgreSQL connection URL	-
`DATABASE_POOL_SIZE`	Max connections in pool	`10`
`DATABASE_SSLMODE`	SSL mode (`disable`, `prefer`, `require`)	`prefer`

libSQL

Variable	Description	Default
`DATABASE_BACKEND`	Backend type	`postgres`
`LIBSQL_PATH`	Local database file	`~/.ironclaw/ironclaw.db`
`LIBSQL_URL`	Turso remote URL (optional)	-
`LIBSQL_AUTH_TOKEN`	Turso auth token	-

Backups

PostgreSQL

# Backup
pg_dump ironclaw > backup.sql

# Restore
psql ironclaw < backup.sql

libSQL

# Backup (copy file)
cp ~/.ironclaw/ironclaw.db ~/.ironclaw/ironclaw.db.backup

# Restore
cp ~/.ironclaw/ironclaw.db.backup ~/.ironclaw/ironclaw.db

Turso cloud: Automatic backups via Turso dashboard.

Get Started

Core Concepts

Configuration

Features

Security

Guides

Overview

PostgreSQL

Requirements

Installation

Configuration

Connection Pool

SSL/TLS Configuration

Migrations

Cloud Providers

Troubleshooting

libSQL (Embedded)

Overview

Local Setup

Turso Cloud Sync

Configuration Options

Migrations

Limitations

When to Use libSQL

Switching Backends

Environment Variables

PostgreSQL

libSQL

Backups

PostgreSQL

libSQL

​Overview

​PostgreSQL

​Requirements

​Installation

​Configuration

​Connection Pool

​SSL/TLS Configuration

​Migrations

​Cloud Providers

​Troubleshooting

​libSQL (Embedded)

​Overview

​Local Setup

​Turso Cloud Sync

​Configuration Options

​Migrations

​Limitations

​When to Use libSQL

​Switching Backends

​Environment Variables

​PostgreSQL

​libSQL

​Backups

​PostgreSQL

​libSQL

Overview

PostgreSQL

Requirements

Installation

Configuration

Connection Pool

SSL/TLS Configuration

Migrations

Cloud Providers

Troubleshooting

libSQL (Embedded)

Overview

Local Setup

Turso Cloud Sync

Configuration Options

Migrations

Limitations

When to Use libSQL

Switching Backends

Environment Variables

PostgreSQL

libSQL

Backups

PostgreSQL

libSQL