# Postgres Adapter

| Hostname                 | Port          |
| ------------------------ | ------------- |
| `postgres.altertable.ai` | 443 (TLS/SSL) |

The Postgres adapter lets you connect to Altertable through the PostgreSQL wire protocol. It works with BI tools and SQL clients that already speak Postgres.

This adapter is ideal for:

- **BI tools** like Hex, Looker, Tableau, Power BI, and Metabase
- **SQL clients** such as DBeaver and pgAdmin

## Authentication

Use your lakehouse username and lakehouse password with TLS enabled.

## SQL Dialect

While the connection uses the Postgres protocol, queries are executed using **DuckDB SQL dialect**. This means that Postgres-specific functions (e.g., `string_agg`, `generate_series`) may not work.

## Quick Start

### Postgres

```sql
-- Altertable speaks the Postgres wire protocol natively.
-- No SDK needed — any Postgres client works out of the box.

-- psql
psql "postgresql://{{LAKEHOUSE_USERNAME}}:{{LAKEHOUSE_PASSWORD}}@postgres.altertable.ai:443/my_db"
```

## Connection examples

**psql**

```bash
PGSSLMODE=require psql -h postgres.altertable.ai -p 443 -U {{LAKEHOUSE_USERNAME}} your_database
```

**Python (psycopg2)**

```python
import psycopg2

conn = psycopg2.connect(
host="postgres.altertable.ai",
port=443,
database="your_database",
user="{{LAKEHOUSE_USERNAME}}",
password="{{LAKEHOUSE_PASSWORD}}",
sslmode="require"
)
```

## TLS negotiation

The Postgres adapter supports standard PostgreSQL SSL negotiation on port 443.

If a connection times out before authentication, check whether your network performs TLS inspection on port 443. Some configurations, including Cloudflare Gateway TLS inspection, may reject PostgreSQL's plaintext SSLRequest preamble.

- Preferred: bypass TLS inspection for `postgres.altertable.ai`.
- For clients using libpq 17 or newer, add `sslnegotiation=direct` alongside `sslmode=require`.
- Clients without TLS-direct support, including Node `pg`, require the network bypass.