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

# PostgreSQL Persistence

> Production SQL persistence with JSONB, connection pooling, and serverless support

PostgreSQL persists agent conversations with JSONB metadata, connection pooling, and automatic serverless retry.

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

agent = Agent(
    name="ProductionBot",
    instructions="You are a helpful assistant.",
    db=db(database_url="postgresql://user:pass@localhost:5432/praisonai"),
    session_id="prod-session",
)
agent.start("Hello — save this to PostgreSQL")
```

The user talks to production agents; PostgreSQL stores conversations with JSONB metadata.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Agent[🤖 Agent] --> Store[🗃️ Postgres Store]
    Store --> Pool[🔗 Connection Pool]
    Pool --> DB[(🐘 PostgreSQL)]

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef store fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef database fill:#10B981,stroke:#7C90A0,color:#fff

    class Agent agent
    class Store,Pool store
    class DB database
```

## Quick Start

<Steps>
  <Step title="Simple Usage">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install psycopg2-binary praisonai
    ```

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

    agent = Agent(
        name="ProductionBot",
        db=db(database_url="postgresql://user:pass@localhost:5432/praisonai"),
        session_id="session-1",
    )
    agent.start("Hello!")
    ```
  </Step>

  <Step title="With Configuration">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonai.persistence.conversation.postgres import PostgresConversationStore

    store = PostgresConversationStore(
        url="postgresql://user:pass@localhost:5432/praisonai",
        schema="public",
        table_prefix="praison_",
        auto_create_tables=True,
        pool_size=10,
        max_retries=3,
        retry_delay=0.5,
    )
    ```
  </Step>
</Steps>

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant Agent
    participant Store as PostgresConversationStore
    participant PostgreSQL

    Agent->>Store: save message
    Store->>PostgreSQL: CREATE TABLE IF NOT EXISTS
    Store->>PostgreSQL: INSERT (JSONB metadata)
    PostgreSQL-->>Agent: persisted
```

| Feature              | Description                                    |
| -------------------- | ---------------------------------------------- |
| **JSONB columns**    | Rich metadata queries on session data          |
| **Serverless retry** | Auto SSL and retry for Neon, CockroachDB, Xata |
| **Schema support**   | Isolate tables with a PostgreSQL schema        |

***

## Configuration Options

| Option               | Type    | Default       | Description                                          |
| -------------------- | ------- | ------------- | ---------------------------------------------------- |
| `url`                | `str`   | `None`        | Full connection URL (overrides individual options)   |
| `host`               | `str`   | `"localhost"` | Database host                                        |
| `port`               | `int`   | `5432`        | Database port                                        |
| `database`           | `str`   | `"praisonai"` | Database name                                        |
| `user`               | `str`   | `"postgres"`  | Database user                                        |
| `password`           | `str`   | `""`          | Database password                                    |
| `schema`             | `str`   | `"public"`    | PostgreSQL schema                                    |
| `table_prefix`       | `str`   | `"praison_"`  | Prefix for table names                               |
| `auto_create_tables` | `bool`  | `True`        | Create tables automatically                          |
| `pool_size`          | `int`   | `5`           | Connection pool size                                 |
| `max_retries`        | `int`   | `3`           | Retries on connection errors (serverless cold-start) |
| `retry_delay`        | `float` | `0.5`         | Base delay between retries in seconds                |

### URL formats

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
db(database_url="postgresql://user:pass@localhost:5432/praisonai")
db(database_url="postgresql://user:pass@host:5432/db?sslmode=require")
```

Aliases: `neon`, `cockroachdb`, `crdb`, `xata` resolve to the postgres backend. For async, use `create_conversation_store("async_postgres", ...)`.

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use db() for most agents">
    `Agent(db=db(database_url="postgresql://..."))` is the simplest path — store wiring is automatic.
  </Accordion>

  <Accordion title="Enable SSL in production">
    Set `sslmode=require` in the URL for encrypted connections.
  </Accordion>

  <Accordion title="Use serverless aliases for Neon/Xata">
    Point at Neon or Xata URLs — SSL and retry are applied automatically.
  </Accordion>

  <Accordion title="Resume sessions after restart">
    Reuse the same `session_id` — conversation history loads on the next `agent.start()`.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="SQLite Persistence" icon="database" href="/docs/features/persistence-sqlite">
    Local file database for development
  </Card>

  <Card title="Database Persistence" icon="database" href="/docs/features/persistence">
    Compare all persistence backends
  </Card>
</CardGroup>