> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud-Native Serverless Databases

> Scale-to-zero database persistence with Neon, Supabase, Turso, CockroachDB, and Xata

PraisonAI supports cloud-native serverless databases that automatically scale to zero when idle, reducing costs for bursty AI agent workloads.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Cloud-Native Database Flow"
        Agent[🤖 Agent] --> Detect{🔍 Detect Provider}
        Detect -->|neon.tech| Neon[💚 Neon]
        Detect -->|supabase.co| Supa[🟢 Supabase]
        Detect -->|turso.io| Turso[🟦 Turso]
        Detect -->|cockroachlabs.cloud| Roach[🟤 CockroachDB]
        Detect -->|xata.sh| Xata[🟣 Xata]
        
        Neon --> Features[⚡ Serverless Features]
        Supa --> Features
        Turso --> Features
        Roach --> Features
        Xata --> Features
        
        Features --> Scale[🎯 Auto Scale]
    end
    
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef detect fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef provider fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef features fill:#10B981,stroke:#7C90A0,color:#fff
    classDef scale fill:#6366F1,stroke:#7C90A0,color:#fff
    
    class Agent agent
    class Detect detect
    class Neon,Supa,Turso,Roach,Xata provider
    class Features features
    class Scale scale
```

## Quick Start

<Steps>
  <Step title="Choose Provider">
    Pick your preferred cloud database provider and get credentials:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

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

    # Using Turso (libSQL)
    agent = Agent(
        name="Edge Agent", 
        instructions="You are a helpful assistant with edge persistence.",
        db={
            "database_url": "libsql://mydb-user.turso.io",
            "auth_token": "eyJ..."
        }
    )
    ```
  </Step>

  <Step title="Start Conversation">
    Your agent automatically gets persistent memory across sessions:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # First conversation
    result = agent.start("Remember: My favorite color is blue")
    print(result)  # Agent confirms and stores this fact

    # Later (different session)
    result = agent.start("What's my favorite color?")
    print(result)  # "Your favorite color is blue"
    ```
  </Step>
</Steps>

***

## Supported Providers

| Provider                       | Backend           | Protocol                      | Auto-Scale | Edge Replicas | Free Tier |
| ------------------------------ | ----------------- | ----------------------------- | ---------- | ------------- | --------- |
| **[Neon](neon)**               | PostgreSQL        | `postgresql://`               | ✅          | ❌             | 0.5GB     |
| **[Supabase](supabase)**       | PostgreSQL + REST | `postgresql://` or `https://` | ✅          | ❌             | 500MB     |
| **[Turso](turso)**             | libSQL/SQLite     | `libsql://`                   | ✅          | ✅             | 9GB       |
| **[CockroachDB](cockroachdb)** | PostgreSQL        | `postgresql://`               | ✅          | ❌             | 5GB       |
| **[Xata](xata)**               | PostgreSQL        | `postgresql://`               | ✅          | ❌             | 15GB      |

<CardGroup cols={2}>
  <Card title="PostgreSQL Compatible" icon="database" href="#postgresql-providers">
    Neon, Supabase, CockroachDB, Xata use standard PostgreSQL drivers
  </Card>

  <Card title="Edge-First" icon="bolt" href="#edge-databases">
    Turso provides SQLite replicas at the edge for microsecond reads
  </Card>
</CardGroup>

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant Agent
    participant PraisonDB
    participant Cloud as Cloud Provider
    participant Store as Conversation Store
    
    Agent->>PraisonDB: Start session
    PraisonDB->>Cloud: Cold start connection
    Cloud-->>PraisonDB: Database wakes up
    PraisonDB->>Store: Load conversation history
    Store-->>Agent: Previous messages
    
    Agent->>PraisonDB: Save new message
    PraisonDB->>Store: Store with retry logic
    Store->>Cloud: Persist to serverless DB
    Cloud-->>Store: Confirmed
    
    Note over Cloud: Auto-suspend after 5 mins idle
```

### Serverless-Resilient Features

All cloud providers get these features automatically:

| Feature                 | Description                               | Benefit                     |
| ----------------------- | ----------------------------------------- | --------------------------- |
| **SSL Enforcement**     | `sslmode=require` added automatically     | Security compliance         |
| **Cold-Start Retry**    | 3 retries with exponential backoff        | Handles database wake-up    |
| **Extended Timeout**    | 30s connect timeout (vs 5s default)       | Accommodates scale-up delay |
| **Connection Recovery** | Broken connections discarded and replaced | Resilient to network issues |

***

## Installation

<Tabs>
  <Tab title="All Providers">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Install PraisonAI with all database support
    pip install "praisonai[databases]"
    ```
  </Tab>

  <Tab title="Individual Providers">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # PostgreSQL-based (Neon, CockroachDB, Xata, Supabase Direct)
    pip install "praisonai[neon]"

    # Turso/libSQL
    pip install "praisonai[turso]"

    # Supabase REST API
    pip install supabase
    ```
  </Tab>
</Tabs>

***

## Common Patterns

### Environment-Based Configuration

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import os
from praisonaiagents import Agent

# Set environment variables for your provider
os.environ["NEON_DATABASE_URL"] = "postgresql://user:pass@ep-xxx.neon.tech/db"

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
    db=True  # Auto-detects from environment variables
)
```

### Multi-Provider Setup

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.db.adapter import PraisonAIDB

# Different stores for different purposes
db = PraisonAIDB(
    database_url="postgresql://user:pass@ep-xxx.neon.tech/conversations",  # Chat history
    state_url="redis://upstash-redis.com:6379",  # Session state
    knowledge_url="https://vector-db.qdrant.io",  # RAG knowledge
)

agent = Agent(name="Multi-Store Agent", db=db)
```

### Session Resume Pattern

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai import ManagedAgent, LocalManagedConfig

# Create agent with cloud persistence
managed = ManagedAgent(
    provider="local",
    db={"database_url": "libsql://mydb-user.turso.io"},
    config=LocalManagedConfig(name="Persistent Agent")
)

# Save session for later resume
session_ids = managed.save_ids()

# Resume from any device/deployment
managed2 = ManagedAgent(provider="local", db=db)
managed2.resume_session(session_ids["session_id"])
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Choose the Right Provider">
    * **Neon**: Best for traditional PostgreSQL workloads with auto-scaling
    * **Supabase**: Great for rapid prototyping with built-in auth and REST API
    * **Turso**: Perfect for edge deployment and global distribution
    * **CockroachDB**: Ideal for distributed, multi-region applications
    * **Xata**: Excellent for full-text search and analytics use cases
  </Accordion>

  <Accordion title="Handle Cold Starts">
    Set appropriate retry and timeout settings for serverless databases:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonai.db.adapter import NeonDB

    db = NeonDB(
        database_url="postgresql://...",
        max_retries=5,  # More retries for cold starts
        retry_delay=1.0,  # Base delay between retries
    )
    ```
  </Accordion>

  <Accordion title="Optimize for Scale-to-Zero">
    Design your agent interactions to be stateless between sessions:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    agent = Agent(
        name="Stateless Agent",
        instructions="Always greet returning users and recap our last conversation.",
        db=True  # Persistence handles state across scale-to-zero cycles
    )
    ```
  </Accordion>

  <Accordion title="Monitor Database Usage">
    Most providers offer usage dashboards. Set up alerts for:

    * Connection timeout increases (indicates cold starts)
    * Query latency spikes
    * Storage or bandwidth limits approaching
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Local Databases" icon="hard-drive" href="/docs/features/local-databases">
    SQLite, PostgreSQL, MySQL for local development
  </Card>

  <Card title="Vector Databases" icon="vector-square" href="/docs/features/vector-databases">
    Qdrant, Pinecone, Weaviate for RAG and knowledge storage
  </Card>
</CardGroup>