Skip to Content
Overview

PostgreSQL Extension

In Development

pg_kalam is a remote-only PostgreSQL foreign data wrapper extension. PostgreSQL hosts the FDW callbacks, DDL hook, and local relation surface, while KalamDB executes scans, writes, and mirrored DDL over gRPC on the shared RPC listener.

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 codebase no longer contains an embedded-mode PostgreSQL runtime.

Keep these rules in mind from the start:

  • Point CREATE SERVER ... OPTIONS (host, port) at KalamDB’s RPC listener, not the HTTP API port.
  • Add shared_preload_libraries = 'pg_kalam' and restart PostgreSQL if you want CREATE TABLE ... USING kalamdb and the DDL mirroring hook to work.
  • CREATE TABLE ... USING kalamdb and kalam_exec(...) currently assume a default foreign server named kalam_server.
  • Use CREATE FOREIGN TABLE ... SERVER <name> when you need a non-default server or you want to mirror a relation explicitly.

What You Can Do Today

  • Install the extension into PostgreSQL 13 through 18, with pg16 as the default build target.
  • Create remote server definitions with host, port, optional auth header, timeout, and TLS material.
  • Define KalamDB tables from PostgreSQL with CREATE TABLE ... USING kalamdb.
  • Expose relations explicitly with CREATE FOREIGN TABLE ... SERVER ... when you need a non-default server name.
  • Run SELECT, INSERT, UPDATE, and DELETE through FDW callbacks.
  • Use top-level BEGIN, COMMIT, and ROLLBACK blocks for explicit transactions on shared and user tables.
  • Observe bridge sessions and explicit transactions with system.sessions and system.transactions.
  • Use kalam_exec(...) for direct remote SQL when you want to bypass the relation wrapper.
  • Work with FILE columns as JSONB FileRef payloads on the PostgreSQL side.

Current Capability Map

AreaStatusNotes
Remote bridgeAvailablekalam_compiled_mode() returns remote
CREATE TABLE ... USING kalamdbAvailable with limitsRequires shared_preload_libraries = 'pg_kalam' and the default server kalam_server
CREATE FOREIGN TABLE ... SERVER ...AvailableUse this path for non-default server names and explicit mirroring
Shared and user table DMLAvailableSELECT, INSERT, UPDATE, and DELETE run through FDW callbacks
Stream tablesAvailable with limitsStream-table DDL works; explicit transactions reject stream-table writes
Explicit transactionsAvailable with limitsTop-level BEGIN, COMMIT, and ROLLBACK; no DDL inside explicit transactions
PushdownPartialProjection plus simple equality filters; PostgreSQL still reapplies quals locally
Direct statement passthroughAvailable with limitskalam_exec(...) uses the default server and is revoked from PUBLIC
Helper SQL functionsAvailablekalam_version, kalam_compiled_mode, kalam_user_id, kalam_user_id_guc_name, snowflake_id, kalam_exec
IMPORT FOREIGN SCHEMANot availableRemote mode currently returns an unsupported error
Data type conversionsMixedSee Data Type Conversions for the exact current mapping and runtime caveats

Read This Section In Order

  1. Getting Started
  2. Architecture
  3. SQL Syntax
  4. Data Type Conversions
  5. Status & Limits

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:

  1. Download the matching pg_kalam release asset for your PostgreSQL major, or build it from source.
  2. Install the extension into the exact PostgreSQL instance you will use and add it to shared_preload_libraries.
  3. Give KalamDB a stable RPC address and point the default kalam_server foreign server at that endpoint.
  4. Define tables with CREATE TABLE ... USING kalamdb, or use CREATE FOREIGN TABLE ... SERVER ... for non-default servers.
  5. Set kalam.user_id in sessions that work with user-scoped tables.
  6. Use top-level BEGIN ... COMMIT when you need explicit transaction batching on shared or user tables.
  7. Use kalam_exec(...) only when you need direct remote SQL and can satisfy its privilege model.
Last updated on
Getting Started

Getting Started

Documentation

Resources

Community

© 2026 KalamDB. All rights reserved.
PrivacyTerms