---
title: "PostgreSQL Protocol Documentation"
---

# PostgreSQL Protocol Documentation

This directory contains consolidated documentation for HeliosDB's PostgreSQL 17 protocol support and compatibility.

## Quick Start

Connect to HeliosDB using any PostgreSQL client:

```bash
# Using psql
psql -h localhost -p 5432 -U helios -d heliosdb

# Using connection string
psql "postgresql://helios:password@localhost:5432/heliosdb"
```

## Contents

| File | Description |
|------|-------------|
| **README.md** | Overview and quick start (this file) |
| **CONFIGURATION.md** | Connection and protocol configuration |
| **COMPATIBILITY.md** | PostgreSQL 17 feature compatibility matrix |
| **EXAMPLES.md** | SQL examples and usage patterns |

## Feature Overview

### Wire Protocol Support

HeliosDB implements PostgreSQL wire protocol v3.0 with full feature support:

- **Authentication**: Password, MD5, SCRAM-SHA-256
- **Extended Query Protocol**: Prepare, Bind, Execute, Describe
- **COPY Protocol**: Binary and text formats, streaming
- **Replication Protocol**: Logical and physical replication
- **Notification**: LISTEN/NOTIFY support

### PostgreSQL 17 Features

| Feature | Availability | Description |
|---------|--------|-------------|
| JSON_TABLE | Supported | SQL/JSON table conversion |
| MERGE with RETURNING | Supported | Upsert with result capture |
| COPY with ON_ERROR | Supported | Error handling during bulk load |
| Incremental Backup | Planned | Block-level incremental backups |
| Slot Failover | Planned (with replication) | Logical replication HA |
| Vacuum Optimization | Planned (`VACUUM` is accepted and returns immediately today) | 20x memory reduction |

### SQL Compatibility

- **DDL**: CREATE, ALTER, DROP (tables, indexes, views, functions)
- **DML**: INSERT, UPDATE, DELETE, MERGE, COPY
- **Queries**: SELECT, CTEs, window functions, subqueries
- **Transactions**: MVCC, isolation levels, savepoints
- **Extensions**: Common extensions compatibility

## Connection Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `host` | localhost | Server hostname |
| `port` | 5432 | PostgreSQL wire protocol port |
| `database` | postgres | Default database |
| `user` | - | Username for authentication |
| `password` | - | Password for authentication |
| `sslmode` | prefer | SSL connection mode |

## Performance Characteristics

| Metric | Value |
|--------|-------|
| Connection handshake | 1 RTT |
| Auth overhead | 1-2 RTT |
| Query latency | Comparable to PostgreSQL |
| Bulk load (COPY) | 100K+ rows/sec |

## Client Compatibility

Tested with:

- **CLI**: psql, pgcli
- **GUI**: pgAdmin, DBeaver, DataGrip
- **Languages**: psycopg2/3 (Python), node-postgres (JS), lib/pq (Go), JDBC (Java)
- **ORMs**: SQLAlchemy, Prisma, ActiveRecord, GORM

## Related Documentation

- **[CONFIGURATION.md](https://www.heliosdb.com/docs/full/reference/protocols/postgresql/configuration/)** - Detailed configuration options
- **[COMPATIBILITY.md](https://www.heliosdb.com/docs/full/reference/protocols/postgresql/compatibility/)** - Feature compatibility matrix
- **[EXAMPLES.md](https://www.heliosdb.com/docs/full/reference/protocols/postgresql/examples/)** - SQL examples and patterns
- **[Parent Directory](https://www.heliosdb.com/docs/full/reference/protocols/readme/)** - Protocol documentation overview
- **[PROTOCOL_COMPATIBILITY_MATRIX.md](https://www.heliosdb.com/docs/full/reference/protocols/protocol_compatibility_matrix/)** - Cross-protocol comparison

## Migration from PostgreSQL

HeliosDB is designed as a drop-in replacement for PostgreSQL:

1. No schema changes required
2. Standard `pg_dump` import supported
3. Connection string compatible
4. Client libraries work without modification

See **[EXAMPLES.md](https://www.heliosdb.com/docs/full/reference/protocols/postgresql/examples/)** for migration patterns.