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:

# 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 - Detailed configuration options
• COMPATIBILITY.md - Feature compatibility matrix
• EXAMPLES.md - SQL examples and patterns
• Parent Directory - Protocol documentation overview
• PROTOCOL_COMPATIBILITY_MATRIX.md - 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 for migration patterns.