PostgreSQL Syntax & PGWire

KalamDB is a Postgres-compatible backend with its own Rust engine. It supports PostgreSQL syntax and the PostgreSQL wire protocol, so SQL clients connect directly to KalamDB.

The same engine also serves HTTP queries, WebSocket live subscriptions, server functions, and durable topics. A write through a PostgreSQL driver can update a subscribed application and publish a topic event.

Connect directly to KalamDB

Enable the listener in your server’s server.toml. CLI projects use kalam/server/server.toml.

1[postgres_wire]2enabled = true3host = "127.0.0.1"4port = 5432

Restart the server after changing listener configuration. For a CLI-managed local server, stop the active development session, run kalam down, then start kalam dev again.

Connect with your KalamDB credentials:

1psql -h 127.0.0.1 -p 5432 -U root -d kalam -W

For DBeaver or another PostgreSQL client, select PostgreSQL and use the same host, port, database (kalam), username, and password. PGWire supports simple queries, prepared queries, and transactions.

The loopback configuration above is for local development. See the configuration guide and security guide for deployed services.

Use familiar SQL

Create a schema and a private table using familiar column syntax:

1CREATE SCHEMA IF NOT EXISTS app;2CREATE TABLE app.todos (3  id BIGSERIAL PRIMARY KEY,4  title TEXT NOT NULL,5  completed BOOLEAN NOT NULL DEFAULT FALSE6) WITH (TYPE = 'USER');7 8INSERT INTO app.todos (title) VALUES ('Connect with psql') RETURNING id, title;9SELECT * FROM app.todos WHERE completed = FALSE ORDER BY id DESC LIMIT 20;10EXPLAIN SELECT * FROM app.todos WHERE completed = FALSE;

BIGSERIAL avoids an application-specific ID expression. Treat the value as an opaque 64-bit key, not a consecutive PostgreSQL sequence; sequence-management and identity semantics are compatibility details to check for your application. WITH (TYPE = 'USER') enables KalamDB’s per-user isolation. For shared tables, use TYPE = 'SHARED' and CREATE POLICY.

SQL uses KalamDB’s authenticated session and permissions. PostgreSQL syntax is the foundation; KalamDB adds features such as USER, SHARED, and STREAM tables, durable topics, and live queries.

See the SQL reference for the supported statements, types, and KalamDB extensions.

Add live updates

With an authenticated SDK client, subscribe to the same table you wrote through PGWire:

1const stop = await client.live(2  'SELECT id, title, completed FROM app.todos WHERE completed = FALSE',3  (rows) => console.log(rows),4);5 6// Call await stop() when this subscription is no longer needed.

The SDK materializes the current row set and applies incoming changes. Live queries use the supported subscription subset of SQL; ordinary SQL query support does not imply every query shape is subscribable. See live-query options and React bindings.

PostgreSQL data types

Application schemas use PostgreSQL-oriented declarations such as INTEGER, BIGINT, REAL, DOUBLE PRECISION, NUMERIC(p,s), TEXT, BYTEA, UUID, JSONB, and TIMESTAMPTZ. SQL queries and live queries share the same logical column types across TypeScript, Dart, and Rust. FILE and EMBEDDING(n) remain KalamDB extensions.

Read PostgreSQL data types in KalamDB for aliases, SDK representations, decimal limits, and current PGWire result limitations. Supporting a SQL declaration does not imply every PostgreSQL driver encoding or precision rule is identical.

PostgreSQL tooling and compatibility

Use the PostgreSQL connection settings above with psql or your database IDE. Prepared queries and transactions use the same authenticated SQL engine. Inspect a slow query with EXPLAIN and EXPLAIN ANALYZE, and manage application schema changes through CLI migrations.

KalamDB runs its own DataFusion/Arrow engine with RocksDB and Parquet storage. It does not require a separate PostgreSQL server. Test your application’s SQL, types, extension dependencies, and administrative operations before migrating; wire compatibility does not imply every PostgreSQL feature has identical semantics.

Next steps

• SQL contracts, server functions, and typed SDKs
• Durable topics and consumers
• Multi-Raft clustering

Prepared statements and PostgreSQL catalogs

The wire listener supports simple queries and the extended Parse / Describe / Bind / Execute / Sync / Close flow. Parameter and row descriptions, text and binary binds, NULL parameters and per-connection statement limits are supported. Each connection has its own transaction and session settings. pg_catalog and information_schema expose schema, column, type, routine, constraint, index and sequence metadata.

Use psql, Node.js pg, Python psycopg, Rust tokio-postgres, or JDBC through this listener. Tool-specific workflows still need validation; protocol support is not a claim that every migration tool or PostgreSQL extension is compatible. Wire COPY and out-of-band CancelRequest are not supported. See 0.8 compatibility boundaries, schemas and session settings, and transactions and savepoints.

For SQL migration integrity, also review table constraint enforcement limits and serial-counter compatibility. Catalog metadata does not establish full PostgreSQL behavior.