Complete Walkthrough: Running ElizaOS with PostgreSQL and Exporting the Schema

This step-by-step guide will walk you through the process of configuring ElizaOS to use PostgreSQL instead of its default embedded database, and then exporting the database schema for analysis or documentation purposes.

Prerequisites

Before starting, ensure you have the following:

ElizaOS installed (repo cloned)
PostgreSQL installed on your system
sudo access or PostgreSQL superuser credentials
Basic knowledge of terminal commands

Step 1: Create a PostgreSQL Database for ElizaOS

First, let's create a dedicated database for ElizaOS:

# Connect as the postgres superuser
sudo -u postgres psql

# In the PostgreSQL shell, create a database
CREATE DATABASE elizaos;

# Create a user for ElizaOS (replace 'secure_password' with a strong password)
CREATE USER elizauser WITH PASSWORD 'secure_password';

# Grant privileges on the database to the user
GRANT ALL PRIVILEGES ON DATABASE elizaos TO elizauser;

# Exit PostgreSQL shell
\q

Step 2: Install Required PostgreSQL Extensions

ElizaOS requires the vector extension (pgvector) for embedding storage and similarity search. This must be installed by a superuser:

# First, make sure the extension package is installed (for Ubuntu/Debian)
sudo apt-get install postgresql-14-pgvector

# If you're using a different PostgreSQL version, adjust accordingly:
# sudo apt-get install postgresql-XX-pgvector

# Now add the extension to your database
sudo -u postgres psql -d elizaos -c "CREATE EXTENSION IF NOT EXISTS vector;"
sudo -u postgres psql -d elizaos -c "CREATE EXTENSION IF NOT EXISTS fuzzystrmatch;"

Step 3: Configure ElizaOS to Use PostgreSQL

Next, create or modify the .env file in your ElizaOS project directory:

# Navigate to your ElizaOS directory
cd ~/path/to/eliza

# Create or edit the .env file
nano .env

Add the following line to your .env file, replacing 'secure_password' with the password you set earlier:

POSTGRES_URL=postgresql://elizauser:secure_password@localhost:5432/elizaos

Save and exit the editor (Ctrl+O, Enter, Ctrl+X in nano).

Step 4: Run Migrations Manually (Optional but Recommended)

Before starting ElizaOS, you can run the database migrations manually to ensure they complete successfully:

# From your ElizaOS directory
POSTGRES_URL=postgresql://elizauser:secure_password@localhost:5432/elizaos bun packages/plugin-sql/dist/migrate.js

You should see output indicating the migrations were successful. If you encounter errors, verify your PostgreSQL configuration and credentials.

Step 5: Start ElizaOS

Now start ElizaOS with your PostgreSQL configuration:

bun start

ElizaOS should start up and connect to your PostgreSQL database. If the migrations weren't run manually in the previous step, ElizaOS will attempt to run them now.

Step 6: Verify the Database Is Working

After ElizaOS has started successfully, you can verify the database is working by accessing the web interface:

http://localhost:3000

Try creating a conversation with an agent. If everything is working correctly, the conversation should persist in the database.

Step 7: Export the Database Schema

Now that ElizaOS is using PostgreSQL and the schema has been created, you can export it for documentation or analysis:

# Export only the schema (-s flag) without data
pg_dump -s -d elizaos -U elizauser > elizaos_schema.sql

# You'll be prompted for the password you set earlier

To view the exported schema:

# Using less for basic viewing
less elizaos_schema.sql

# Or if you have bat/batcat installed (prettier output)
batcat elizaos_schema.sql

Step 8: Exploring the Schema

The exported schema file contains the complete database structure including:

Table definitions
Indexes
Constraints
Foreign keys
Extensions

Pay special attention to these key tables:

agents: Stores agent configurations
memories: Stores conversation history and knowledge
embeddings: Stores vector representations for semantic search
entities: Represents users and other objects
rooms: Represents chat channels or conversation spaces

Troubleshooting

Permission Denied to Create Extension

If you see "permission denied to create extension 'vector'", make sure you're running the CREATE EXTENSION command as the postgres superuser:

sudo -u postgres psql -d elizaos -c "CREATE EXTENSION IF NOT EXISTS vector;"

Password Authentication Failed

If you're getting authentication errors, verify your PostgreSQL user and password. You can test the connection with:

PGPASSWORD=secure_password psql -U elizauser -d elizaos -c "SELECT 'Connection successful';"

Relation Does Not Exist

If you see "relation does not exist" errors, it means the migrations haven't run successfully. Try running them manually as described in Step 4.

Empty Schema Export

If your schema export is empty, it means either:

The database exists but no tables have been created (migrations failed)
You're connecting to the wrong database
You don't have permissions to view the schema

Verify your connection details and permissions.

Advanced: Running Queries on the Database

Once ElizaOS is using PostgreSQL, you can directly query the database for advanced analysis:

# Connect to the database
psql -U elizauser -d elizaos

# Example queries:
SELECT COUNT(*) FROM memories;
SELECT COUNT(*) FROM agents;
SELECT room_id, COUNT(*) FROM memories GROUP BY room_id;

# Exit the psql client
\q

Conclusion

You've successfully configured ElizaOS to use PostgreSQL instead of the embedded PGlite database and exported the schema for documentation or analysis. This setup provides better performance, scalability, and access to PostgreSQL's rich ecosystem of tools for backup, monitoring, and management.

For production deployments, consider additional steps such as:

Setting up regular database backups
Configuring connection pooling
Implementing database monitoring
Tuning PostgreSQL for performance

By leveraging PostgreSQL, you're unlocking the full potential of ElizaOS for robust, scalable agent deployments.

LinuxIsCool/eliza-postgres.md