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

# CockroachDB Serverless

> Distributed SQL database with automatic scaling and global consistency

CockroachDB provides a distributed, PostgreSQL-compatible database that automatically scales and handles multi-region deployments for resilient AI agents.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "CockroachDB Distributed Architecture"
        Agent[🤖 Agent] --> Request[📝 SQL Request]
        Request --> LoadBalancer[⚖️ Load Balancer]
        LoadBalancer --> Node1[🟦 Node 1]
        LoadBalancer --> Node2[🟦 Node 2]
        LoadBalancer --> Node3[🟦 Node 3]
        
        Node1 --> Consensus[🤝 Raft Consensus]
        Node2 --> Consensus
        Node3 --> Consensus
        
        Consensus --> Replicate[📑 Global Replication]
        Replicate --> Scale[📈 Auto-Scale]
    end
    
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef request fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef balancer fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef node fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef consensus fill:#10B981,stroke:#7C90A0,color:#fff
    
    class Agent agent
    class Request request
    class LoadBalancer balancer
    class Node1,Node2,Node3 node
    class Consensus,Replicate,Scale consensus
```

## Quick Start

<Steps>
  <Step title="Create CockroachDB Cluster">
    1. Sign up at [cockroachlabs.cloud](https://cockroachlabs.cloud)
    2. Create a new Serverless cluster
    3. Download the cluster certificate
    4. Copy the connection string

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    export COCKROACHDB_URL="postgresql://user:password@free-tier.gcp-us-central1.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full"
    ```
  </Step>

  <Step title="Create Distributed Agent">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="Distributed Agent",
        instructions="You are a globally distributed AI assistant.",
        db={"database_url": "postgresql://user:pass@xxx.cockroachlabs.cloud:26257/db?sslmode=verify-full"}
    )

    # Data automatically distributed across regions
    result = agent.start("I need high availability and consistency")
    print(result)
    ```
  </Step>

  <Step title="Test Global Consistency">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Write from one location
    agent.start("Remember: I'm testing global distribution")

    # Read from anywhere in the world - data is consistent
    result = agent.start("What was I testing?")
    print(result)  # "You were testing global distribution"
    # Same result worldwide due to strong consistency
    ```
  </Step>
</Steps>

***

## Installation

<Tabs>
  <Tab title="pip">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # CockroachDB uses standard PostgreSQL driver
    pip install "praisonai[cockroachdb]"
    ```
  </Tab>

  <Tab title="Environment Variables">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Required - includes SSL settings for security
    export COCKROACHDB_URL="postgresql://user:pass@cluster.cockroachlabs.cloud:26257/db?sslmode=verify-full"

    # Optional
    export OPENAI_API_KEY="sk-..."
    ```
  </Tab>
</Tabs>

***

## Configuration Options

| Option               | Type    | Default | Description                              |
| -------------------- | ------- | ------- | ---------------------------------------- |
| `database_url`       | `str`   | `None`  | Full PostgreSQL connection URL with SSL  |
| `max_retries`        | `int`   | `3`     | Retries for serialization errors (40001) |
| `retry_delay`        | `float` | `0.5`   | Base delay between retries               |
| `pool_size`          | `int`   | `5`     | Connection pool size                     |
| `auto_create_tables` | `bool`  | `True`  | Create tables automatically              |

***

## Usage Patterns

### Using Convenience Class

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

# Auto-reads from COCKROACHDB_URL environment variable
db = CockroachDB()
agent = Agent(name="CRDB Agent", db=db)
```

### Manual Configuration with Retry Settings

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

db = PraisonAIDB(
    database_url="postgresql://user:pass@cluster.cockroachlabs.cloud:26257/mydb?sslmode=verify-full",
    max_retries=5,  # Extra retries for serialization conflicts
    retry_delay=1.0,  # 1 second base delay
    pool_size=10  # Larger pool for distributed workload
)

agent = Agent(name="High-Availability Agent", db=db)
```

### Multi-Region Agent Setup

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import os
from praisonai import ManagedAgent, LocalManagedConfig
from praisonai.db.adapter import CockroachDB
from praisonaiagents import Agent

# Create globally distributed agent
db = CockroachDB(database_url=os.environ["COCKROACHDB_URL"])
managed = ManagedAgent(
    provider="local",
    db=db,
    config=LocalManagedConfig(
        model="gpt-4o-mini",
        name="Global Agent",
        system="You are a globally distributed AI assistant with strong consistency."
    )
)

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

# Agent data automatically distributed across regions
result1 = agent.run("Store this globally: I'm building a multi-region application")
print(f"Agent: {result1}")

result2 = agent.run("The app needs to handle users from different continents")
print(f"Agent: {result2}")

# Save session - data replicated globally
session_data = managed.save_ids()
print(f"Global session: {session_data['session_id']}")

# Resume from any region - same data everywhere
managed2 = ManagedAgent(provider="local", db=CockroachDB())
managed2.resume_session(session_data["session_id"])

agent2 = Agent(name="User", backend=managed2)
result3 = agent2.run("What application am I building?")
print(f"Resumed Agent: {result3}")
# Works from any region with strong consistency
```

***

## CockroachDB-Specific Features

### Automatic Serialization Retry

CockroachDB may return serialization errors (40001) under high contention. PraisonAI handles these automatically:

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

# Optimized for serialization conflict handling
db = CockroachDB(
    database_url="postgresql://...",
    max_retries=10,  # More retries for high-contention workloads
    retry_delay=0.1  # Shorter delays for faster retry
)

# Agent automatically retries on serialization conflicts
agent = Agent(name="High-Contention Agent", db=db)
```

### Global Data Distribution

Data is automatically distributed across regions:

```sql theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
-- View data distribution (run in CockroachDB SQL interface)
SHOW RANGES FROM TABLE praison_sessions;
SHOW RANGES FROM TABLE praison_messages;

-- See which nodes have your data
SELECT node_id, count(*) FROM [SHOW RANGES FROM TABLE praison_sessions] GROUP BY node_id;
```

### Follower Reads

Reduce latency by reading from local replicas:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Connection string with follower reads enabled
follower_url = "postgresql://user:pass@cluster.cockroachlabs.cloud:26257/db?sslmode=verify-full&options=--cluster=my-cluster"

# Some reads may be slightly stale but much faster
agent = Agent(
    name="Fast Read Agent",
    instructions="You prioritize read speed with slight staleness acceptable.",
    db={"database_url": follower_url}
)
```

### Backup and Point-in-Time Recovery

CockroachDB automatically backs up your data:

```sql theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
-- Restore to point in time (via CockroachDB Console)
RESTORE FROM LATEST IN 'gs://backup-bucket' AS OF SYSTEM TIME '2024-01-15 14:00:00';

-- Create scheduled backups
CREATE SCHEDULE FOR BACKUP INTO 'gs://my-backup-bucket' 
    RECURRING '@daily' 
    WITH SCHEDULE OPTIONS first_run = 'now';
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Handle Serialization Conflicts">
    CockroachDB uses optimistic concurrency control. Design for retries:

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

    # Tune retry settings for your workload
    db = CockroachDB(
        max_retries=10,  # High-contention: more retries
        retry_delay=0.05  # Fast retry for short transactions
    )

    # Keep agent operations short and idempotent
    agent = Agent(
        name="Optimized Agent",
        instructions="Keep responses concise for fast database transactions.",
        db=db
    )
    ```
  </Accordion>

  <Accordion title="Optimize Connection Pooling">
    Distributed systems benefit from larger connection pools:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    db = CockroachDB(
        database_url="postgresql://...",
        pool_size=20,  # Larger pool for distributed load
        max_retries=5
    )

    # Multiple agents can share the same pool efficiently
    agent1 = Agent(name="Agent 1", db=db)
    agent2 = Agent(name="Agent 2", db=db)
    ```
  </Accordion>

  <Accordion title="Monitor Performance">
    Track key CockroachDB metrics:

    * **Serialization conflicts**: High rate indicates need for retry tuning
    * **Node latency**: Shows geographic distribution performance
    * **Storage usage**: Plan for data growth

    Use the CockroachDB Console for monitoring and alerts.
  </Accordion>

  <Accordion title="Plan for Multi-Region">
    Design agent interactions for global distribution:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Store region information in session metadata
    agent = Agent(
        name="Regional Agent",
        instructions="You serve users globally with consistent data.",
        db=CockroachDB()
    )

    # Session metadata can track user region
    session_metadata = {"user_region": "us-east", "timezone": "America/New_York"}
    ```
  </Accordion>
</AccordionGroup>

***

## Environment Variables

| Variable          | Required | Format                                          | Example                                                                                                  |
| ----------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `COCKROACHDB_URL` | ✅        | `postgresql://...cockroachlabs.cloud:26257/...` | `postgresql://user:pass@cluster.gcp-us-central1.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full` |
| `OPENAI_API_KEY`  | ✅        | `sk-...`                                        | `sk-1234567890abcdef...`                                                                                 |

***

## Performance Characteristics

| Metric           | Serverless | Dedicated  | Use Case                 |
| ---------------- | ---------- | ---------- | ------------------------ |
| **Latency**      | 10-50ms    | 5-20ms     | Real-time chat           |
| **Throughput**   | 1000 QPS   | 10000+ QPS | High-volume agents       |
| **Consistency**  | Strong     | Strong     | Financial applications   |
| **Availability** | 99.9%      | 99.99%     | Mission-critical systems |

***

## Troubleshooting

### Serialization Conflict Errors

If you see "restart transaction: TransactionRetryWithProtoRefreshError":

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Increase retry settings
db = CockroachDB(max_retries=20, retry_delay=0.1)

# Or reduce transaction size by batching operations less
```

### SSL Certificate Issues

Ensure SSL is properly configured:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Download cluster certificate if needed
curl -k https://cluster.cockroachlabs.cloud:26257/ca.crt > ca.crt

# Add to connection string
export COCKROACHDB_URL="postgresql://user:pass@cluster.cockroachlabs.cloud:26257/db?sslmode=verify-full&sslrootcert=ca.crt"
```

### High Latency

For better performance across regions:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Use connection string with local region preference
regional_url = "postgresql://user:pass@us-east-1.cluster.cockroachlabs.cloud:26257/db?sslmode=verify-full"
```

### Connection Pool Exhaustion

If you hit connection limits:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
db = CockroachDB(
    pool_size=50,  # Increase pool size
    max_retries=3   # Reduce retries to fail faster
)
```

***

## Related

<CardGroup cols={2}>
  <Card title="Cloud Databases Overview" icon="cloud" href="/docs/features/cloud-databases">
    Compare all cloud database providers
  </Card>

  <Card title="Multi-Region Deployment" icon="globe" href="/docs/features/multi-region">
    Deploy agents across multiple regions
  </Card>
</CardGroup>