PostgreSQL Extension
In Development
The pg_kalam PostgreSQL extension lets PostgreSQL define and use KalamDB tables with PostgreSQL-shaped SQL while forwarding the real table definition and execution to a running KalamDB server.
Prebuilt release assets are published on the KalamDB GitHub Releases page for the current Linux x86_64 PostgreSQL extension target. Other platforms or PostgreSQL majors can still be built from source with pgrx.
KalamDB also publishes a ready-to-run Docker image with PostgreSQL and pg_kalam preinstalled at jamals86/pg-kalam on Docker Hub .
This chapter documents the current supported remote-mode surface. The extension is usable today, but it is still in development and some PostgreSQL FDW features remain intentionally unavailable.
What You Can Do Today
- Download the prebuilt
pg_kalamrelease package or build it from source, then install it into PostgreSQL. - Point a foreign server at KalamDB after the extension binaries are installed.
- Define KalamDB tables with
CREATE TABLE ... USING kalamdb. - Use
SELECT,INSERT,UPDATE, andDELETEfrom PostgreSQL against Kalam-backed tables. - Use explicit
BEGIN,COMMIT, andROLLBACKblocks for atomic multi-statement work. - Reuse the same KalamDB table options through PostgreSQL
WITH (...)clauses. - Forward arbitrary statements directly to KalamDB with
SELECT kalam_exec('<sql>'). - Set
kalam.user_idper session for user-scoped tables. - Read
_seqon all exposed PostgreSQL tables and_useridon user tables. - Observe active bridge sessions and explicit transactions with
system.sessionsandsystem.transactions.
Current Capability Map
| Area | Status | Notes |
|---|---|---|
| Remote bridge | Available | Current compiled mode is remote |
| Shared table DML | Available | SELECT, INSERT, UPDATE, DELETE work through FDW callbacks |
| User table DML | Available | Set kalam.user_id before tenant-scoped work |
| Explicit transactions | Available | BEGIN, COMMIT, and ROLLBACK stage KalamDB writes until final commit |
CREATE TABLE ... USING kalamdb | Available | Public authoring syntax for PostgreSQL-managed KalamDB tables |
| System columns | Available | _seq is auto-injected on all tables, read-only, and _userid is auto-injected on user tables |
| KalamDB table options | Available | PostgreSQL WITH (...) options are forwarded to the server as-is |
| Direct statement passthrough | Available | kalam_exec(...) sends SQL directly to KalamDB |
| Extension helper functions | Available | Includes kalam_* metadata helpers and SNOWFLAKE_ID() |
| Transaction observability | Available | system.sessions is pg-only; system.transactions covers all active explicit transactions |
IMPORT FOREIGN SCHEMA | Not yet available | Remote mode currently rejects it |
Start Here
Recommended Workflow
Use the PostgreSQL extension when you want PostgreSQL tooling, SQL clients, or migrations to operate against KalamDB tables without switching your operators to the HTTP API or an SDK.
In most cases the flow is:
- Download the matching
pg_kalamrelease asset for your PostgreSQL major, or build it from source. - Install the extension into the exact PostgreSQL instance you will use.
- Create a
kalam_serverforeign server that points at KalamDB’s gRPC endpoint. - Define tables with
CREATE TABLE ... USING kalamdb. - Set
kalam.user_idin sessions that work with user-scoped tables. - Use
BEGIN ... COMMITwhen you need atomic multi-statement writes. - Use
kalam_exec(...)when you want to send a KalamDB statement directly without a PostgreSQL wrapper.