@cli4ai/postgres

@cli4ai/postgres

Official @cli4ai package • https://cli4ai.com • Install cli4ai: npm i -g cli4ai

PostgreSQL explorer with read-only queries (blocks writes by default).

Setup

npm i -g cli4ai
cli4ai add -g postgres

Configure a default connection using POSTGRES_URL (or DATABASE_URL):

POSTGRES_URL="postgres://user:pass@host:5432/db" cli4ai run postgres databases

Alternatively, configure `POSTGRES_URL` using `cli4ai secrets`:

```bash
cli4ai secrets set POSTGRES_URL "postgres://user:pass@host:5432/db"
cli4ai run postgres databases

Named connections are supported via env vars like `POSTGRES_PROD_URL`. Pass the name as `[conn]`:

```bash
POSTGRES_PROD_URL="postgres://..." cli4ai run postgres tables prod public

Commands

cli4ai run postgres databases [conn]
cli4ai run postgres schemas [conn]
cli4ai run postgres tables [conn] [schema]
cli4ai run postgres views [conn] [schema]
cli4ai run postgres columns [conn] <table>
cli4ai run postgres indexes [conn] <table>
cli4ai run postgres constraints [conn] <table>
cli4ai run postgres fkeys [conn] <table>
cli4ai run postgres sample [conn] <table> [limit]
cli4ai run postgres count [conn] <table>
cli4ai run postgres query [conn] <sql>
cli4ai run postgres stats [conn] <table>
cli4ai run postgres sizes [conn] [schema]
cli4ai run postgres search [conn] <pattern>
cli4ai run postgres version [conn]

Examples

POSTGRES_URL="postgres://user:pass@host:5432/db" cli4ai run postgres tables
POSTGRES_URL="postgres://user:pass@host:5432/db" cli4ai run postgres query "select now() as now"

Security

Read-Only Enforcement

This tool blocks destructive SQL commands (INSERT, UPDATE, DELETE, DROP, etc.) at the application layer. However, this is defense-in-depth only.

Best practice: Use a read-only database user for maximum protection. PostgreSQL allows creating users with restricted privileges:

CREATE USER readonly_user WITH PASSWORD 'secure_password';
GRANT CONNECT ON DATABASE mydb TO readonly_user;
GRANT USAGE ON SCHEMA public TO readonly_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO readonly_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO readonly_user;

The application-layer filtering may have edge cases (e.g., stored procedures, unusual syntax). Database-level permissions are the authoritative security boundary.