PostgreSQL Extension Status and Limits
In Development
The PostgreSQL extension is usable, but it is still an active development surface. Plan for incremental feature growth rather than assuming complete PostgreSQL FDW parity.
Supported Today
- Remote-mode PostgreSQL bridge to a running KalamDB server
- Shared and user table reads and writes through FDW callbacks
- Stream-table authoring and normal FDW access outside explicit transactions
- Explicit
BEGIN,COMMIT, andROLLBACKtransaction blocks for Kalam-backed tables CREATE TABLE ... USING kalamdbas the public PostgreSQL-side authoring syntax- Auto-injected system columns:
_seqon all tables and_useridon user tables - Forwarding KalamDB table options from PostgreSQL
WITH (...) - Direct pass-through execution with
kalam_exec(...) - Session-scoped tenant routing with
kalam.user_id - Extension helper functions including
kalam_version()andSNOWFLAKE_ID()
Hard Limits and Current Constraints
| Area | Current behavior |
|---|---|
| Compile mode | kalam_compiled_mode() currently reports remote; this chapter documents that mode only |
| DDL hook | CREATE TABLE ... USING kalamdb requires shared_preload_libraries = 'pg_kalam' and a PostgreSQL restart |
| Default server binding | CREATE TABLE ... USING kalamdb and kalam_exec(...) currently assume the default foreign server name kalam_server |
| Schema import | IMPORT FOREIGN SCHEMA is not available in remote mode |
| Runtime mapping source | Relation schema and relation name are the runtime namespace and table; OPTIONS (namespace, table) are not the canonical scan/write mapping |
| Filter pushdown | Only simple equality filters are pushed down; PostgreSQL still reapplies quals locally |
| Order and limit pushdown | ORDER BY and LIMIT are not pushed down today |
| User scoping | User-table operations should set kalam.user_id; _userid is only an explicit INSERT override |
kalam.user_id privileges | kalam.user_id is registered as a PostgreSQL SUSET parameter |
Row identity for UPDATE/DELETE | The current FDW path uses the first non-system column as its row-identity heuristic |
| Explicit transactions | The documented surface is top-level BEGIN, COMMIT, and ROLLBACK blocks |
| DDL in transactions | DDL is rejected inside explicit transactions |
| Stream tables in transactions | Stream-table writes are rejected inside explicit transactions |
| Direct SQL helper | kalam_exec(text) is revoked from PUBLIC and does not automatically mirror PostgreSQL search_path or current schema |
| Type conversions | The logical mapping is broader than the extension’s dedicated PostgreSQL runtime branches; see Data Type Conversions |
| Reserved columns | _seq, _userid, and _deleted are reserved names; only _seq and _userid are auto-injected into the current PostgreSQL relation surface |
Additional practical limits:
_seqis read-only metadata projected from KalamDB. Values supplied inINSERTorUPDATEare not forwarded.- Multi-row user-table
INSERTstatements must use one_useridvalue consistently. UPDATEandDELETEon user tables use the sessionkalam.user_idscope. Reassigning ownership through_useridupdates is not supported.- The server and table validators are permissive. Some bad option combinations fail on first use rather than at
CREATE SERVERorCREATE FOREIGN TABLEtime.
Prototype Syntax vs Supported Syntax
This docs section focuses on the current remote-mode flow.
If you see older prototype scripts that mention experimental helpers such as schema opt-in functions, treat those as development artifacts unless they are covered in this chapter. The supported documentation surface today is:
CREATE EXTENSIONCREATE SERVER/ALTER SERVER/DROP SERVERCREATE TABLE ... USING kalamdbBEGIN/COMMIT/ROLLBACKkalam_exec(...)SELECT,INSERT,UPDATE,DELETE- extension helper functions and
kalam.user_id
Troubleshooting
| Symptom | Likely cause | What to check |
|---|---|---|
extension "pg_kalam" is not available | Extension files are not installed into the active PostgreSQL instance | Reinstall the extension into that PostgreSQL 16 installation |
could not access file "$libdir/pg_kalam" | PostgreSQL cannot find the shared library | Verify the extension was installed into the correct PostgreSQL library directory |
CREATE TABLE ... USING kalamdb does not mirror DDL | The preload hook is not active | Check SHOW shared_preload_libraries and confirm it includes pg_kalam, then restart PostgreSQL |
| Remote connection failure | The foreign-server host or port is wrong, the HTTP API port was used, or KalamDB is down | Verify the foreign server options and point them at the KalamDB RPC endpoint |
| Auth failures | auth_header is missing or stale | Update the foreign server definition with the right bearer token or shared secret |
| User-table reads or writes fail | kalam.user_id was not set, or the role cannot set it | Set kalam.user_id in the PostgreSQL session and verify the PostgreSQL role can change SUSET parameters |
permission denied for function kalam_exec | kalam_exec(text) is revoked from PUBLIC | Use a superuser or GRANT EXECUTE ON FUNCTION kalam_exec(text) to the desired role |
UPDATE or DELETE targets the wrong row | The table’s primary key is not the first user column | Recreate the table with the primary key first or use a carefully controlled direct SQL path |
IMPORT FOREIGN SCHEMA fails | Feature gap in current remote mode | Use CREATE TABLE ... USING kalamdb or kalam_exec(...) instead |
Related
Last updated on