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

# Natural Language Postgres CLI

> Query PostgreSQL from the command line

Query PostgreSQL databases using natural language from the command line.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    User([User]) --> CLI[CLI]
    CLI --> DB[(Postgres)]

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff

    class DB agent
    class User,CLI tool
    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff

```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    User([User]) --> CLI[CLI]
    CLI --> DB[(Postgres)]

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff

    class DB agent
    class User,CLI tool
```

## Quick Start

<Steps>
  <Step title="Simple Usage">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai-ts postgres query "Show all users" \
      --connection-url $DATABASE_URL
    ```
  </Step>

  <Step title="With Configuration">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai-ts postgres query "Top 10 products by sales" \
      --connection-url $DATABASE_URL \
      --max-rows 10 \
      --json
    ```
  </Step>
</Steps>

## Commands

### Query Database

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Simple query
praisonai-ts postgres query "Show all users" \
  --connection-url $DATABASE_URL

# With options
praisonai-ts postgres query "Top 10 products by sales" \
  --connection-url $DATABASE_URL \
  --max-rows 10 \
  --json
```

### Show Schema

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# List all tables
praisonai-ts postgres schema \
  --connection-url $DATABASE_URL

# Show specific table
praisonai-ts postgres schema users \
  --connection-url $DATABASE_URL
```

### Interactive Mode

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Start interactive SQL chat
praisonai-ts postgres chat \
  --connection-url $DATABASE_URL \
  --read-only
```

## Options

| Option             | Type    | Default | Description               |
| ------------------ | ------- | ------- | ------------------------- |
| `--connection-url` | string  | env     | Database URL              |
| `--read-only`      | boolean | `true`  | Read-only mode            |
| `--max-rows`       | number  | `100`   | Max rows returned         |
| `--allowed-tables` | string  | -       | Comma-separated whitelist |
| `--blocked-tables` | string  | -       | Comma-separated blacklist |
| `--json`           | boolean | `false` | JSON output               |
| `--show-sql`       | boolean | `false` | Show generated SQL        |

## Examples

### Basic Queries

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# List users
praisonai-ts postgres query "Show all active users"

# Aggregation
praisonai-ts postgres query "Average order value by month"

# With SQL output
praisonai-ts postgres query "Top customers" --show-sql
```

### Restricted Access

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Only allow specific tables
praisonai-ts postgres query "Show products" \
  --allowed-tables products,categories

# Block sensitive tables
praisonai-ts postgres query "Show data" \
  --blocked-tables users,payments
```

## Environment Variables

| Variable         | Required | Description               |
| ---------------- | -------- | ------------------------- |
| `DATABASE_URL`   | Yes      | PostgreSQL connection URL |
| `OPENAI_API_KEY` | Yes      | For NL to SQL             |

## Related

<CardGroup cols={2}>
  <Card title="Natural Language Postgres" icon="database" href="/docs/js/nl-postgres">
    SDK usage
  </Card>

  <Card title="PostgreSQL" icon="elephant" href="/docs/js/postgres">
    Agent persistence
  </Card>
</CardGroup>