Database Setup

Configure PostgreSQL or libSQL for IronClaw persistence

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

# 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;"

Ubuntu/Debian

# 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;"

Docker

# 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:[e-mail]/ironclaw?sslmode=require

pgvector is pre-installed. Set DATABASE_SSLMODE=require.

Supabase

Supabase includes Postgres with pgvector.

DATABASE_URL=postgres://postgres:[e-mail]: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:[e-mail]:5432/ironclaw
DATABASE_SSLMODE=require

Enable pgvector:

CREATE EXTENSION IF NOT EXISTS vector;

Troubleshooting

pgvector not found

Error: pgvector extension not found

Solution:

• 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 later

Solution: 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 server

Check 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 failed

Check 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:

1. Create a Turso database:

   turso db create ironclaw
   

2. Get connection details:

   turso db show ironclaw
   

3. Create an auth token:

   turso db tokens create ironclaw
   

4. 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):

1. Export data (if needed):

   # PostgreSQL: pg_dump
   pg_dump ironclaw > backup.sql
   

2. Change configuration:

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

3. Re-run onboarding:

   ironclaw onboard
   

4. 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.