Document PG wire format

Author: mamcx

docs/docs/nav.js

@@ -68,6 +68,7 @@ const nav = {
     page('Unreal Reference', 'unreal/reference', 'unreal/reference.md'),
     section('SQL'),
     page('SQL Reference', 'sql', 'sql/index.md'),
+    page('PostgreSQL wire protocol (PGWire) ', 'sql/pg-wire', 'sql/pg-wire.md'),
     section('Subscriptions'),
     page('Subscription Reference', 'subscriptions', 'subscriptions/index.md'),
     page(

docs/docs/sql/pg-wire.md

@@ -0,0 +1,229 @@
+# PostgreSQL Wire Protocol (PGWire) Compatibility
+
+*SpacetimeDB* supports the [PostgreSQL wire protocol (](https://www.postgresql.org/docs/current/protocol.html)[
+*PGWire*](https://www.postgresql.org/docs/current/protocol.html)[)](https://www.postgresql.org/docs/current/protocol.html),
+enabling compatibility with PostgreSQL clients and tools.
+
+The PostgreSQL wire protocol is a network protocol used by PostgreSQL clients to communicate with compatible servers. It
+defines how messages are formatted and exchanged between client and server. The protocol is agnostic to the query
+dialect,
+meaning it can be used with different SQL engines and feature sets, in concrete, *SpacetimeDB*.
+
+This allows users to leverage the existing PostgreSQL ecosystem, including drivers, ORMs, IDEs, CLI tools, and GUI
+clients that support PostgreSQL.
+
+When using *PGWire* with *SpacetimeDB*, consider the following:
+
+## Feature Support
+
+SpacetimeDB is progressively adding PostgreSQL client compatibility. Some features are unsupported, partially
+implemented, or behave differently:
+
+- **Protocol Version**: Only *PGWire* protocol *version 3.0* is supported, and only the *Simple Query Protocol*, and
+  without parameterized queries.
+- **SQL Features**: Only the subset of SQL features documented in the [SQL documentation](index.md) are
+  supported. Subscription queries do not update in real time.
+- **Authentication**: SpacetimeDB does not implement database users or roles. The connection string
+  `user_name@database_name` ignores `user_name`; only `database_name` is used. Authentication is based on the *auth
+  token*
+  provided via the `password` field.
+- **SSL/TLS**: SSL is supported only for `maincloud` deployments (without mutual TLS). Other deployments (such as
+  `standalone`) do not support SSL/TLS connections.
+- **System Tables and Views**: SpacetimeDB provides its own system tables (e.g., `SELECT * FROM st_table`) for
+  introspection. These are not PostgreSQL-compatible, so tools relying on PostgreSQL system catalogs will not work.
+- **Port and Host**:
+    - In `standalone` deployments, specify the port with `spacetime start --pg-port <port>`. Without this flag,
+      connections using the PostgreSQL protocol are not enabled.
+    - In `maincloud` deployments, the port is always `5432`.
+- **Transactions**: User-defined transactions (`BEGIN TRANSACTION`, `COMMIT`, etc.) are not supported. Each SQL
+  statement executes in its own transaction context. Client libraries should disable automatic transaction handling.
+
+## Connection Parameters
+
+To connect to SpacetimeDB using a PostgreSQL client, use the following parameters:
+
+- **Host**:
+    - `localhost` for `standalone` or `local` deployments
+    - `maincloud.spacetimedb.com` for `maincloud` deployments
+- **Port**:
+    - `5432` for `maincloud`
+    - The value passed with `--pg-port` for `standalone`
+- **Database**: The target SpacetimeDB database
+- **User**: Any string (ignored by SpacetimeDB)
+- **Password**: The `auth token`
+- **SSL Mode**: `require` (only for `maincloud`)
+
+### Auth Token
+
+> **Warning**: The `auth token` is sensitive. Do not expose it in logs, version control, or insecure locations.
+
+SpacetimeDB uses the `password` field to pass the `auth token`. Obtain the token with:
+
+```bash
+spacetime login show --token
+```
+
+To export the token to `PGPASSWORD`:
+
+```python
+# token.py
+import sys, re
+
+text = sys.stdin.read()
+match = re.search(r"Your auth token \(don't share this!\) is\s+(\S+)", text)
+if not match:
+    sys.exit("No token found")
+
+print(f"export PGPASSWORD={match.group(1)}")
+```
+
+```bash
+eval "$(spacetime login show --token | python3 ~/token.py)"
+```
+
+## Examples
+
+Assume you are using the `quickstart-chat` database created in
+the [Rust Module Quickstart](/docs/modules/rust/quickstart) or [C# Module Quickstart](/docs/modules/c-sharp/quickstart),
+and have set the `auth token` as shown above.
+
+### Using `psql`
+
+Standalone or local deployment:
+
+```bash
+psql "host=localhost port=5432 user=any dbname=quickstart-chat"
+```
+
+Maincloud deployment:
+
+```bash
+psql "host=maincloud.spacetimedb.com port=5432 user=any dbname=quickstart-chat sslmode=require"
+```
+
+> **Note**: Introspection commands such as `\dt` will not work, as SpacetimeDB does not support PostgreSQL schemas.
+
+### Using Python (`psycopg2`)
+
+```python
+import psycopg2
+import os
+
+conn = psycopg2.connect(
+    host="localhost",  # or "maincloud.spacetimedb.com" for maincloud
+    port=5432,
+    dbname="quickstart-chat",
+    user="any",
+    password=os.getenv("PGPASSWORD"),
+    sslmode="disable"  # use "require" for maincloud
+)
+conn.set_session(autocommit=True)  # disable transactions
+
+print("Running query:")
+with conn.cursor() as cur:
+    cur.execute("SELECT * FROM message;")
+    for row in cur.fetchall():
+        print(row)
+
+conn.close()
+print("Done.")
+```
+
+### Using Rust (`tokio-postgres` + `rustls`)
+
+We use the `tokio-postgres-rustls` because is stricter, so we can show how disables certificate verification.
+
+```toml
+# Cargo.toml
+[dependencies]
+anyhow = "1.0.71"
+tokio-postgres = "0.7.14"
+tokio-postgres-rustls = "0.13.0"
+tokio = { version = "1.47.1", features = ["full"] }
+rustls = "0.23.32"
+```
+
+```rust
+// main.rs
+use std::env;
+use std::sync::Arc;
+use rustls::client::danger::{ServerCertVerified, ServerCertVerifier};
+use rustls::pki_types::{CertificateDer, ServerName, UnixTime};
+use rustls::{ClientConfig, Error, RootCertStore, SignatureScheme};
+use tokio_postgres_rustls::MakeRustlsConnect;
+
+#[derive(Debug)]
+struct NoVerifier;
+
+impl ServerCertVerifier for NoVerifier {
+    fn verify_server_cert(
+        &self,
+        _: &CertificateDer<'_>,
+        _: &[CertificateDer<'_>],
+        _: &ServerName<'_>,
+        _: &[u8],
+        _: UnixTime,
+    ) -> Result<ServerCertVerified, Error> {
+        Ok(ServerCertVerified::assertion())
+    }
+
+    fn verify_tls12_signature(
+        &self,
+        _: &[u8],
+        _: &CertificateDer<'_>,
+        _: &rustls::DigitallySignedStruct,
+    ) -> Result<rustls::client::danger::HandshakeSignatureValid, Error> {
+        Ok(rustls::client::danger::HandshakeSignatureValid::assertion())
+    }
+
+    fn verify_tls13_signature(
+        &self,
+        _: &[u8],
+        _: &CertificateDer<'_>,
+        _: &rustls::DigitallySignedStruct,
+    ) -> Result<rustls::client::danger::HandshakeSignatureValid, Error> {
+        Ok(rustls::client::danger::HandshakeSignatureValid::assertion())
+    }
+
+    fn supported_verify_schemes(&self) -> Vec<SignatureScheme> {
+        vec![
+            SignatureScheme::ECDSA_NISTP384_SHA384,
+            SignatureScheme::ECDSA_NISTP256_SHA256,
+            SignatureScheme::RSA_PSS_SHA512,
+            SignatureScheme::RSA_PSS_SHA384,
+            SignatureScheme::RSA_PSS_SHA256,
+            SignatureScheme::ED25519,
+        ]
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<(), anyhow::Error> {
+    let password = env::var("PGPASSWORD").expect("PGPASSWORD not set");
+
+    let mut config = ClientConfig::builder()
+        .with_root_certificates(RootCertStore::empty())
+        .with_no_client_auth();
+
+    config.dangerous().set_certificate_verifier(Arc::new(NoVerifier));
+    let connector = MakeRustlsConnect::new(config);
+
+    let (client, connection) = tokio_postgres::connect(
+        &format!(
+            "host=localhost port=5432 user=any sslmode=require dbname=quickstart-chat password={password}"
+        ),
+        connector,
+    ).await?;
+
+    tokio::spawn(async move { connection.await.expect("connection error") });
+
+    println!("Running query:");
+    let rows = client.simple_query("SELECT * FROM message;").await?;
+    for row in rows {
+        println!("Row: {:?}", row);
+    }
+    println!("Done.");
+    Ok(())
+}
+```
+

docs/nav.ts

@@ -98,6 +98,7 @@ const nav: Nav = {
 
     section('SQL'),
     page('SQL Reference', 'sql', 'sql/index.md'),
+    page('PostgreSQL wire protocol (PGWire) ', 'sql/pg-wire', 'sql/pg-wire.md'),
 
     section('Subscriptions'),
     page('Subscription Reference', 'subscriptions', 'subscriptions/index.md'),