Connection Configuration
Database URL Format
Set thePOSTGRES_URL environment variable with your PostgreSQL connection string:
username: PostgreSQL userpassword: User passwordhost: Database server hostname (e.g.,localhost,db.example.com)port: PostgreSQL port (default:5432)database: Database name
Example Configurations
Async Driver Setup
Junkie automatically converts standard PostgreSQL URLs to use theasyncpg driver for better performance:
agent/agent_factory.py:60-81 and provides better throughput for async operations.
If your
POSTGRES_URL already includes +asyncpg or +psycopg_async, the URL will be used as-is.Database Schema
Junkie creates and manages three types of tables:1. Messages Table
Stores Discord message history for context retrieval.message_id: Unique Discord message IDchannel_id: Discord channel where message was sentauthor_id: Discord user ID of authorauthor_name: Display name of authorcontent: Message text contentcreated_at: Timestamp with timezonetimestamp_str: Human-readable timestamp string
2. Channel Status Table
Tracks backfill completion status for channels.channel_id: Discord channel IDis_fully_backfilled: Whether all historical messages have been loadedlast_updated: Last update timestamp
3. Agent Tables (Managed by Agno)
Additional tables are created automatically by the Agno framework:agent_sessions: Stores conversation history and session stateuser_memories: Stores user-specific memories for personalization
agent/agent_factory.py:89-93:
Database Operations
Initialization
The database connection pool is initialized on bot startup:core/database.py:11-20
Connection Pool
Junkie usesasyncpg connection pooling for efficient database access:
- Pool is created once at startup
- Connections are acquired from pool for each operation
- Automatic connection management and cleanup
Message Storage
Messages are stored with upsert logic (insert or update if exists):core/database.py:66-90
Performance Optimizations
Indexes
- Descending index on
(channel_id, created_at DESC)for fast retrieval of recent messages - Primary key index on
message_idfor fast upserts
Query Patterns
Messages are fetched in reverse chronological order, then reversed for display:core/database.py:106-126
No Database Mode
IfPOSTGRES_URL is not configured:
- Message history will not be stored
- Agent sessions will not persist between restarts
- User memories will be lost
- The bot will still function but without persistence
Cleanup
Close the connection pool gracefully on shutdown:core/database.py:22-28