Skip to main content
Neon provides serverless PostgreSQL with automatic scaling, branching, and point-in-time recovery for your AI agents.

​
Quick Start

1

Get Neon Credentials

  1. Create account at neon.tech
  2. Create a new project
  3. Copy connection string from dashboard
export NEON_DATABASE_URL="postgresql://user:password@ep-xxx.neon.tech/neondb?sslmode=require"
2

Create Agent with Neon

from praisonaiagents import Agent

agent = Agent(
    name="Neon Agent",
    instructions="You are a helpful assistant with persistent memory.",
    db={"database_url": "postgresql://user:pass@ep-xxx.neon.tech/db?sslmode=require"}
)

# Start conversation
result = agent.start("Remember that I work at TechCorp as a developer")
print(result)
3

Test Persistence

# Later session - agent remembers previous conversation
result = agent.start("What company do I work for?")
print(result)  # "You work at TechCorp as a developer"

​
Installation

# Install with Neon/PostgreSQL support
pip install "praisonai[neon]"

​
Configuration Options

OptionTypeDefaultDescription
database_urlstrNoneFull PostgreSQL connection URL
max_retriesint3Retries for cold-start recovery
retry_delayfloat0.5Base delay between retries (seconds)
pool_sizeint5Connection pool size
auto_create_tablesboolTrueCreate conversation tables automatically

​
Usage Patterns

​
Using Convenience Class

from praisonai.db.adapter import NeonDB
from praisonaiagents import Agent

# Auto-reads from NEON_DATABASE_URL environment variable
db = NeonDB()
agent = Agent(name="Neon Agent", db=db)

​
Manual Configuration

from praisonai.db.adapter import PraisonAIDB
from praisonaiagents import Agent

db = PraisonAIDB(
    database_url="postgresql://user:pass@ep-xxx.neon.tech/mydb?sslmode=require",
    max_retries=5,  # Extra retries for cold starts
    retry_delay=1.0  # 1 second base delay
)

agent = Agent(name="Custom Neon Agent", db=db)

​
Full Lifecycle Example

import os
from praisonai import ManagedAgent, LocalManagedConfig
from praisonai.db.adapter import NeonDB
from praisonaiagents import Agent

# Phase 1: Create persistent agent
db = NeonDB(database_url=os.environ["NEON_DATABASE_URL"])
managed = ManagedAgent(
    provider="local",
    db=db,
    config=LocalManagedConfig(
        model="gpt-4o-mini",
        name="Neon Demo Agent",
        system="You are a helpful assistant. Remember all user preferences."
    )
)

agent = Agent(name="User", backend=managed)

# Teach the agent some facts
result1 = agent.run("I prefer concise responses and work in AI/ML")
print(f"Agent: {result1}")

result2 = agent.run("Also, I use Python and prefer practical examples")
print(f"Agent: {result2}")

# Phase 2: Save session and simulate scale-to-zero
session_data = managed.save_ids()
print(f"Session saved: {session_data['session_id']}")
del agent, managed, db  # Simulate shutdown

# Phase 3: Resume from Neon after cold start
db2 = NeonDB(database_url=os.environ["NEON_DATABASE_URL"])
managed2 = ManagedAgent(provider="local", db=db2)
managed2.resume_session(session_data["session_id"])

agent2 = Agent(name="User", backend=managed2)
result3 = agent2.run("What do you know about my preferences?")
print(f"Resumed Agent: {result3}")
# Should recall: concise responses, AI/ML work, Python preference

​
Neon-Specific Features

​
Database Branching

Create development branches of your agent’s data: 
# Create a branch for testing
neon branches create --name agent-testing --parent main

# Get branch connection string
neon connection-string agent-testing

# Use branch for development
dev_db = NeonDB(database_url="postgresql://...@ep-xxx-branch.neon.tech/db")
dev_agent = Agent(name="Dev Agent", db=dev_db)

# Test new conversation flows without affecting production
result = dev_agent.start("Test new features here")

​
Point-in-Time Recovery

Restore agent conversations to any point in time: 
# Restore database to 2 hours ago
neon branches create --name agent-restore --parent main --point-in-time "2024-01-15 14:00:00"

​
Connection Pooling

Neon automatically pools connections, but you can tune for your workload: 
from praisonai.db.adapter import NeonDB

db = NeonDB(
    database_url="postgresql://...?sslmode=require",
    pool_size=10,  # Larger pool for high-concurrency agents
    max_retries=3,  # Standard retry for Neon cold starts
)

​
Best Practices

Neon databases auto-suspend after 5 minutes of inactivity. The first connection takes ~500ms-2s:
from praisonai.db.adapter import NeonDB

# Optimize retry settings for cold starts
db = NeonDB(
    database_url="postgresql://...",
    max_retries=5,  # Extra retries for wake-up
    retry_delay=1.0,  # 1 second between retries
)
Neon requires SSL for all connections. PraisonAI auto-adds sslmode=require:
# Both are equivalent - SSL is enforced automatically
db1 = NeonDB(database_url="postgresql://user:pass@ep-xxx.neon.tech/db")
db2 = NeonDB(database_url="postgresql://user:pass@ep-xxx.neon.tech/db?sslmode=require")
Track your database usage in the Neon dashboard:
  • Compute time: Billed per second of activity
  • Storage: Grows with conversation history
  • Data transfer: Minimal for typical agent workloads
Set up alerts before hitting free tier limits (0.5GB storage, 100 hours compute/month).
PraisonAI automatically handles transient connection failures:
# Connection failures are retried automatically
# No manual error handling needed
agent = Agent(
    name="Robust Agent",
    instructions="You handle network issues gracefully.",
    db={"database_url": os.environ["NEON_DATABASE_URL"]}
)

​
Environment Variables

VariableRequiredFormatExample
NEON_DATABASE_URL✅postgresql://user:pass@host/dbpostgresql://user:pass@ep-xxx.neon.tech/neondb?sslmode=require
OPENAI_API_KEY✅sk-...sk-1234567890abcdef...

​
Troubleshooting

​
Cold Start Timeouts

If you see connection timeouts on first request: 
# Increase retry settings
db = NeonDB(max_retries=5, retry_delay=2.0)

​
SSL Certificate Issues

Ensure your Neon URL includes SSL mode: 
# Add sslmode if missing
export NEON_DATABASE_URL="postgresql://user:pass@ep-xxx.neon.tech/db?sslmode=require"

​
Connection Pool Exhaustion

For high-concurrency agents, increase pool size: 
db = NeonDB(pool_size=20)  # Default is 5

Cloud Databases Overview

Compare all cloud database providers

Local PostgreSQL

Development setup with local PostgreSQL