post-graph 0.1.0__py3-none-any.whl

post_graph/client_asyncpg.py

@@ -0,0 +1,1265 @@
+import json
+import logging
+import re
+from typing import Any, Dict, List, Optional, Tuple, Union
+import asyncpg
+
+from post_graph.errors import (
+    VertexNotFoundError,
+    EdgeNotFoundError,
+    TableExistsError,
+    TableNotFoundError,
+    PostGraphError,
+)
+from post_graph.models import Vertex, Edge, DataRecord
+
+logger = logging.getLogger("post_graph")
+
+
+class AsyncPostGraph:
+    def __init__(
+        self,
+        connection_or_pool: Union[asyncpg.Connection, asyncpg.Pool, None] = None,
+        dsn: Optional[str] = None,
+        schema_per_realm: bool = False,
+        **conn_kwargs
+    ):
+        self.connection = connection_or_pool
+        self.dsn = dsn
+        self.schema_per_realm = schema_per_realm
+        self.conn_kwargs = conn_kwargs
+        self._pool = None
+        self._schema_cache = {}  # Cache for edge metadata: key is edge_table (or (realm, edge_table) if schema_per_realm)
+
+    async def connect(self):
+        """Establish connection or connection pool to PostgreSQL."""
+        if self.connection is None:
+            if self.dsn:
+                self._pool = await asyncpg.create_pool(self.dsn, **self.conn_kwargs)
+            else:
+                self._pool = await asyncpg.create_pool(**self.conn_kwargs)
+            self.connection = self._pool
+
+    async def close(self):
+        """Close connection pool if it was managed by this client."""
+        if self._pool:
+            await self._pool.close()
+            self._pool = None
+            self.connection = None
+
+    def _validate_identifier(self, identifier: str):
+        """Ensure identifiers are safe and valid to prevent SQL injection."""
+        if not identifier or not isinstance(identifier, str):
+            raise ValueError("Identifier must be a non-empty string.")
+        if not re.match(r'^[a-zA-Z_][a-zA-Z0-9_]*$', identifier):
+            raise ValueError(
+                f"Invalid identifier: '{identifier}'. Must be alphanumeric and underscores only, "
+                f"starting with a letter or underscore."
+            )
+
+    def _get_table_ref(self, table_name: str, realm: Optional[str] = None) -> str:
+        """Get the table reference. Qualifies with schema (realm) if schema_per_realm is active."""
+        self._validate_identifier(table_name)
+        if self.schema_per_realm:
+            if not realm:
+                raise PostGraphError(f"Realm must be specified for table reference '{table_name}' under schema_per_realm mode.")
+            self._validate_identifier(realm)
+            return f'"{realm}"."{table_name}"'
+        return f'"{table_name}"'
+
+    async def _execute(self, query: str, *args) -> str:
+        if isinstance(self.connection, asyncpg.Pool):
+            async with self.connection.acquire() as conn:
+                return await conn.execute(query, *args)
+        else:
+            return await self.connection.execute(query, *args)
+
+    async def _fetch(self, query: str, *args) -> List[asyncpg.Record]:
+        if isinstance(self.connection, asyncpg.Pool):
+            async with self.connection.acquire() as conn:
+                return await conn.fetch(query, *args)
+        else:
+            return await self.connection.fetch(query, *args)
+
+    async def _fetchrow(self, query: str, *args) -> Optional[asyncpg.Record]:
+        if isinstance(self.connection, asyncpg.Pool):
+            async with self.connection.acquire() as conn:
+                return await conn.fetchrow(query, *args)
+        else:
+            return await self.connection.fetchrow(query, *args)
+
+    async def _run_in_tx(self, func, user_id: Optional[str] = None):
+        """Helper to run a block of operations inside a transaction, setting the user_id session context."""
+        async def _execute_block(conn):
+            if user_id:
+                # Set transaction-local session variable for auditing
+                await conn.execute("SELECT set_config('app.current_user_id', $1, true)", str(user_id))
+            else:
+                await conn.execute("SELECT set_config('app.current_user_id', '', true)")
+            return await func(conn)
+
+        if isinstance(self.connection, asyncpg.Pool):
+            async with self.connection.acquire() as conn:
+                async with conn.transaction():
+                    return await _execute_block(conn)
+        else:
+            async with self.connection.transaction():
+                return await _execute_block(self.connection)
+
+    async def _table_exists(self, table_name: str, realm: Optional[str] = None) -> bool:
+        """Check if a table exists in the database within the proper schema namespace."""
+        self._validate_identifier(table_name)
+        if self.schema_per_realm:
+            if not realm:
+                raise PostGraphError(f"Realm must be specified for _table_exists('{table_name}') in schema_per_realm mode.")
+            self._validate_identifier(realm)
+            query = """
+            SELECT 1 
+            FROM pg_class c
+            JOIN pg_namespace n ON c.relnamespace = n.oid
+            WHERE c.relname = $1 AND c.relkind = 'r' AND n.nspname = $2
+            """
+            row = await self._fetchrow(query, table_name, realm)
+        else:
+            query = """
+            SELECT 1 
+            FROM pg_class c
+            WHERE c.relname = $1 AND c.relkind = 'r' AND pg_table_is_visible(c.oid)
+            """
+            row = await self._fetchrow(query, table_name)
+        return row is not None
+
+    async def create_vertex_table(self, table_name: str, realm: Optional[str] = None):
+        """Create a new vertex table and its associated shadow audit table, indexes, and triggers."""
+        self._validate_identifier(table_name)
+        if self.schema_per_realm:
+            if not realm:
+                raise PostGraphError("realm must be specified in schema_per_realm mode when creating a table.")
+            self._validate_identifier(realm)
+
+        table_ref = self._get_table_ref(table_name, realm)
+        audit_table_ref = self._get_table_ref(f"{table_name}_audit", realm)
+        data_table_ref = self._get_table_ref(f"{table_name}_data", realm)
+
+        # Resolve schema prefix for triggers/functions
+        if self.schema_per_realm:
+            schema_prefix = f'"{realm}".'
+            await self._execute(f'CREATE SCHEMA IF NOT EXISTS "{realm}"')
+        else:
+            schema_prefix = ""
+
+        # Create trigger function for updated_at
+        await self._execute(f"""
+            CREATE OR REPLACE FUNCTION {schema_prefix}update_modified_column()
+            RETURNS TRIGGER AS $$
+            BEGIN
+                NEW.updated_at = now();
+                RETURN NEW;
+            END;
+            $$ language 'plpgsql';
+        """)
+
+        # Create shared trigger function for auditing
+        await self._execute(f"""
+            CREATE OR REPLACE FUNCTION {schema_prefix}audit_trigger_func()
+            RETURNS TRIGGER AS $$
+            DECLARE
+                v_user_id TEXT;
+                v_old_row JSONB := NULL;
+                v_new_row JSONB := NULL;
+                v_realm TEXT;
+            BEGIN
+                v_user_id := NULLIF(current_setting('app.current_user_id', true), '');
+                
+                IF (TG_OP = 'DELETE') THEN
+                    v_old_row := to_jsonb(OLD);
+                    v_realm := OLD.realm;
+                ELSIF (TG_OP = 'UPDATE') THEN
+                    v_old_row := to_jsonb(OLD);
+                    v_new_row := to_jsonb(NEW);
+                    v_realm := NEW.realm;
+                ELSIF (TG_OP = 'INSERT') THEN
+                    v_new_row := to_jsonb(NEW);
+                    v_realm := NEW.realm;
+                END IF;
+
+                EXECUTE format(
+                    'INSERT INTO %I.%I (realm, action, changed_by, old_row, new_row) VALUES ($1, $2, $3, $4, $5)',
+                    TG_TABLE_SCHEMA, TG_TABLE_NAME || '_audit'
+                ) USING v_realm, TG_OP, v_user_id, v_old_row, v_new_row;
+
+                IF (TG_OP = 'DELETE') THEN
+                    RETURN OLD;
+                ELSE
+                    RETURN NEW;
+                END IF;
+            END;
+            $$ LANGUAGE plpgsql;
+        """)
+
+        # 1. Create main table
+        query = f"""
+        CREATE TABLE IF NOT EXISTS {table_ref} (
+            realm TEXT NOT NULL,
+            id BIGSERIAL,
+            fqid TEXT GENERATED ALWAYS AS (realm || '/' || '{table_name}' || '/' || id::text) STORED NOT NULL,
+            payload JSONB NOT NULL DEFAULT '{{}}'::jsonb,
+            created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+            updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+            PRIMARY KEY (realm, id)
+        );
+        """
+        await self._execute(query)
+        await self._execute(f"ALTER TABLE {table_ref} ADD COLUMN IF NOT EXISTS fqid TEXT GENERATED ALWAYS AS (realm || '/' || '{table_name}' || '/' || id::text) STORED;")
+
+        # 2. Create shadow audit table
+        audit_query = f"""
+        CREATE TABLE IF NOT EXISTS {audit_table_ref} (
+            audit_id BIGSERIAL PRIMARY KEY,
+            realm TEXT NOT NULL,
+            action TEXT NOT NULL,
+            changed_by TEXT,
+            changed_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+            old_row JSONB,
+            new_row JSONB
+        );
+        """
+        await self._execute(audit_query)
+
+        # 3. Create append-only data table
+        data_query = f"""
+        CREATE TABLE IF NOT EXISTS {data_table_ref} (
+            data_id BIGSERIAL PRIMARY KEY,
+            realm TEXT NOT NULL,
+            id BIGINT NOT NULL,
+            payload JSONB NOT NULL DEFAULT '{{}}'::jsonb,
+            timestamp TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+            FOREIGN KEY (realm, id) REFERENCES {table_ref}(realm, id) ON DELETE CASCADE
+        );
+        """
+        await self._execute(data_query)
+        await self._execute(f'CREATE INDEX IF NOT EXISTS "idx_{table_name}_data_id" ON {data_table_ref} (realm, id);')
+        await self._execute(f'CREATE INDEX IF NOT EXISTS "idx_{table_name}_data_payload" ON {data_table_ref} USING gin (payload);')
+
+        # 4. Create GIN index on payload
+        await self._execute(
+            f'CREATE INDEX IF NOT EXISTS "idx_{table_name}_payload" ON {table_ref} USING gin (payload);'
+        )
+
+        # 5. Create trigger for updated_at
+        await self._execute(f'DROP TRIGGER IF EXISTS "update_{table_name}_modtime" ON {table_ref};')
+        await self._execute(f"""
+            CREATE TRIGGER "update_{table_name}_modtime"
+            BEFORE UPDATE ON {table_ref}
+            FOR EACH ROW
+            EXECUTE FUNCTION {schema_prefix}update_modified_column();
+        """)
+
+        # 6. Create trigger for auditing
+        await self._execute(f'DROP TRIGGER IF EXISTS "audit_{table_name}_trigger" ON {table_ref};')
+        await self._execute(f"""
+            CREATE TRIGGER "audit_{table_name}_trigger"
+            AFTER INSERT OR UPDATE OR DELETE ON {table_ref}
+            FOR EACH ROW
+            EXECUTE FUNCTION {schema_prefix}audit_trigger_func();
+        """)
+
+    async def create_edge_table(
+        self,
+        table_name: Optional[str] = None,
+        *,
+        from_vertex_table: str,
+        to_vertex_table: str,
+        cascade_delete_from: bool = False,
+        cascade_delete_to: bool = False,
+        realm: Optional[str] = None
+    ):
+        """Create a new edge table linking two vertex tables, plus shadow audit table and constraints."""
+        # Validate vertex table identifiers
+        self._validate_identifier(from_vertex_table)
+        self._validate_identifier(to_vertex_table)
+
+        # Determine effective edge table name: default is "{from}TO{to}" if not provided
+        if not table_name:
+            table_name = f"{from_vertex_table}TO{to_vertex_table}"
+        else:
+            self._validate_identifier(table_name)
+
+        if self.schema_per_realm:
+            if not realm:
+                raise PostGraphError("realm must be specified in schema_per_realm mode when creating an edge table.")
+            self._validate_identifier(realm)
+
+        table_ref = self._get_table_ref(table_name, realm)
+        audit_table_ref = self._get_table_ref(f"{table_name}_audit", realm)
+        data_table_ref = self._get_table_ref(f"{table_name}_data", realm)
+        from_vertex_ref = self._get_table_ref(from_vertex_table, realm)
+        to_vertex_ref = self._get_table_ref(to_vertex_table, realm)
+
+        # Check that from_vertex_table and to_vertex_table exist
+        if not await self._table_exists(from_vertex_table, realm=realm):
+            raise TableNotFoundError(f"Referenced from_vertex_table '{from_vertex_table}' does not exist.")
+        if not await self._table_exists(to_vertex_table, realm=realm):
+            raise TableNotFoundError(f"Referenced to_vertex_table '{to_vertex_table}' does not exist.")
+
+        # Resolve schema prefix for triggers/functions
+        if self.schema_per_realm:
+            schema_prefix = f'"{realm}".'
+        else:
+            schema_prefix = ""
+
+        # 1. Create main edge table
+        query = f"""
+        CREATE TABLE IF NOT EXISTS {table_ref} (
+            realm TEXT NOT NULL,
+            id BIGSERIAL,
+            fqid TEXT GENERATED ALWAYS AS (realm || '/' || '{from_vertex_table}-{to_vertex_table}' || '/' || id::text) STORED NOT NULL,
+            from_id BIGINT NOT NULL,
+            to_id BIGINT NOT NULL,
+            relation_type TEXT NOT NULL,
+            payload JSONB NOT NULL DEFAULT '{{}}'::jsonb,
+            created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+            updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+            PRIMARY KEY (realm, id),
+            FOREIGN KEY (realm, from_id) REFERENCES {from_vertex_ref}(realm, id) ON DELETE CASCADE,
+            FOREIGN KEY (realm, to_id) REFERENCES {to_vertex_ref}(realm, id) ON DELETE CASCADE
+        );
+        """
+        await self._execute(query)
+        await self._execute(f"ALTER TABLE {table_ref} ADD COLUMN IF NOT EXISTS fqid TEXT GENERATED ALWAYS AS (realm || '/' || '{from_vertex_table}-{to_vertex_table}' || '/' || id::text) STORED;")
+
+        # 2. Create shadow audit table
+        audit_query = f"""
+        CREATE TABLE IF NOT EXISTS {audit_table_ref} (
+            audit_id BIGSERIAL PRIMARY KEY,
+            realm TEXT NOT NULL,
+            action TEXT NOT NULL,
+            changed_by TEXT,
+            changed_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+            old_row JSONB,
+            new_row JSONB
+        );
+        """
+        await self._execute(audit_query)
+
+        # 3. Create append-only data table
+        data_query = f"""
+        CREATE TABLE IF NOT EXISTS {data_table_ref} (
+            data_id BIGSERIAL PRIMARY KEY,
+            realm TEXT NOT NULL,
+            id BIGINT NOT NULL,
+            payload JSONB NOT NULL DEFAULT '{{}}'::jsonb,
+            timestamp TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+            FOREIGN KEY (realm, id) REFERENCES {table_ref}(realm, id) ON DELETE CASCADE
+        );
+        """
+        await self._execute(data_query)
+        await self._execute(f'CREATE INDEX IF NOT EXISTS "idx_{table_name}_data_id" ON {data_table_ref} (realm, id);')
+        await self._execute(f'CREATE INDEX IF NOT EXISTS "idx_{table_name}_data_payload" ON {data_table_ref} USING gin (payload);')
+
+        # 3. Create indexes
+        await self._execute(
+            f'CREATE INDEX IF NOT EXISTS "idx_{table_name}_to" ON {table_ref} (realm, to_id);'
+        )
+        await self._execute(
+            f'CREATE INDEX IF NOT EXISTS "idx_{table_name}_payload" ON {table_ref} USING gin (payload);'
+        )
+
+        # 4. Create trigger for updated_at
+        await self._execute(f'DROP TRIGGER IF EXISTS "update_{table_name}_modtime" ON {table_ref};')
+        await self._execute(f"""
+            CREATE TRIGGER "update_{table_name}_modtime"
+            BEFORE UPDATE ON {table_ref}
+            FOR EACH ROW
+            EXECUTE FUNCTION {schema_prefix}update_modified_column();
+        """)
+
+        # 5. Create trigger for auditing
+        await self._execute(f'DROP TRIGGER IF EXISTS "audit_{table_name}_trigger" ON {table_ref};')
+        await self._execute(f"""
+            CREATE TRIGGER "audit_{table_name}_trigger"
+            AFTER INSERT OR UPDATE OR DELETE ON {table_ref}
+            FOR EACH ROW
+            EXECUTE FUNCTION {schema_prefix}audit_trigger_func();
+        """)
+
+        # 6. Create custom cascade delete trigger if either boolean is True
+        await self._execute(f'DROP TRIGGER IF EXISTS "cascade_delete_trigger_{table_name}" ON {table_ref};')
+        await self._execute(f'DROP FUNCTION IF EXISTS {schema_prefix}"cascade_delete_func_{table_name}"();')
+        if cascade_delete_from or cascade_delete_to:
+            from_clause = f'DELETE FROM {from_vertex_ref} WHERE realm = OLD.realm AND id = OLD.from_id;' if cascade_delete_from else ''
+            to_clause = f'DELETE FROM {to_vertex_ref} WHERE realm = OLD.realm AND id = OLD.to_id;' if cascade_delete_to else ''
+            
+            await self._execute(f"""
+                CREATE OR REPLACE FUNCTION {schema_prefix}"cascade_delete_func_{table_name}"()
+                RETURNS TRIGGER AS $$
+                BEGIN
+                    {from_clause}
+                    {to_clause}
+                    RETURN OLD;
+                END;
+                $$ LANGUAGE plpgsql;
+            """)
+            await self._execute(f"""
+                CREATE TRIGGER "cascade_delete_trigger_{table_name}"
+                AFTER DELETE ON {table_ref}
+                FOR EACH ROW
+                EXECUTE FUNCTION {schema_prefix}"cascade_delete_func_{table_name}"();
+            """)
+
+        # Clear cached schema as a new edge is declared
+        cache_key = (realm, table_name) if self.schema_per_realm else table_name
+        self._schema_cache.pop(cache_key, None)
+
+    async def add_vertex(
+        self,
+        table_name: str,
+        realm: str,
+        vertex_id: Optional[Union[str, int]] = None,
+        payload: Optional[Dict[str, Any]] = None,
+        user_id: Optional[str] = None
+    ) -> Vertex:
+        """Add a new vertex. Raises TableExistsError if it already exists."""
+        self._validate_identifier(table_name)
+        payload_json = json.dumps(payload or {})
+        table_ref = self._get_table_ref(table_name, realm)
+
+        async def _op(conn):
+            nonlocal vertex_id
+            table_ref_pg = f'"{realm}"."{table_name}"' if self.schema_per_realm else f'"{table_name}"'
+            if vertex_id is None:
+                seq_query = f"SELECT nextval(pg_get_serial_sequence('{table_ref_pg}', 'id'))"
+                v_id_int = await conn.fetchval(seq_query)
+            else:
+                v_id_int = int(str(vertex_id).split('/')[-1]) if '/' in str(vertex_id) else int(vertex_id)
+
+            v_id_str = str(v_id_int)
+
+            query = f"""
+            INSERT INTO {table_ref} (realm, id, payload)
+            VALUES ($1, $2, $3::jsonb)
+            RETURNING realm, id, fqid, payload, created_at, updated_at
+            """
+            try:
+                row = await conn.fetchrow(query, realm, v_id_int, payload_json)
+                if vertex_id is not None:
+                    await conn.execute(
+                        f"SELECT setval(pg_get_serial_sequence('{table_ref_pg}', 'id'), (SELECT COALESCE(MAX(id), 1) FROM {table_ref}))"
+                    )
+                return Vertex(
+                    realm=row['realm'],
+                    id=str(row['id']),
+                    fqid=row['fqid'],
+                    payload=row['payload'] if isinstance(row['payload'], dict) else json.loads(row['payload']),
+                    created_at=row['created_at'],
+                    updated_at=row['updated_at'],
+                    table_name=table_name,
+                    _client=self
+                )
+            except asyncpg.UniqueViolationError:
+                raise TableExistsError(
+                    f"Vertex with ID '{v_id_str}' already exists in table '{table_name}' under realm '{realm}'."
+                )
+            except asyncpg.UndefinedTableError:
+                raise TableNotFoundError(f"Vertex table '{table_name}' does not exist.")
+
+        return await self._run_in_tx(_op, user_id)
+
+    async def upsert_vertex(
+        self,
+        table_name: str,
+        realm: str,
+        vertex_id: Optional[Union[str, int]] = None,
+        payload: Optional[Dict[str, Any]] = None,
+        user_id: Optional[str] = None
+    ) -> Vertex:
+        """Upsert a vertex (merges payload JSONB on conflict)."""
+        self._validate_identifier(table_name)
+        payload_json = json.dumps(payload or {})
+        table_ref = self._get_table_ref(table_name, realm)
+
+        async def _op(conn):
+            nonlocal vertex_id
+            table_ref_pg = f'"{realm}"."{table_name}"' if self.schema_per_realm else f'"{table_name}"'
+            if vertex_id is None:
+                seq_query = f"SELECT nextval(pg_get_serial_sequence('{table_ref_pg}', 'id'))"
+                v_id_int = await conn.fetchval(seq_query)
+            else:
+                v_id_int = int(str(vertex_id).split('/')[-1]) if '/' in str(vertex_id) else int(vertex_id)
+
+            v_id_str = str(v_id_int)
+
+            query = f"""
+            INSERT INTO {table_ref} (realm, id, payload)
+            VALUES ($1, $2, $3::jsonb)
+            ON CONFLICT (realm, id) DO UPDATE
+            SET payload = {table_ref}.payload || EXCLUDED.payload,
+                updated_at = CURRENT_TIMESTAMP
+            RETURNING realm, id, fqid, payload, created_at, updated_at
+            """
+            try:
+                row = await conn.fetchrow(query, realm, v_id_int, payload_json)
+                return Vertex(
+                    realm=row['realm'],
+                    id=str(row['id']),
+                    fqid=row['fqid'],
+                    payload=row['payload'] if isinstance(row['payload'], dict) else json.loads(row['payload']),
+                    created_at=row['created_at'],
+                    updated_at=row['updated_at'],
+                    table_name=table_name,
+                    _client=self
+                )
+            except asyncpg.UndefinedTableError:
+                raise TableNotFoundError(f"Vertex table '{table_name}' does not exist.")
+
+        return await self._run_in_tx(_op, user_id)
+
+    async def get_vertex(self, table_name: str, realm: str, vertex_id: str) -> Optional[Vertex]:
+        """Fetch a vertex by realm and id."""
+        self._validate_identifier(table_name)
+        table_ref = self._get_table_ref(table_name, realm)
+        v_str = str(vertex_id)
+        query = f"""
+        SELECT realm, id, fqid, payload, created_at, updated_at 
+        FROM {table_ref} 
+        WHERE realm = $1 AND ((CASE WHEN $2 ~ '^[0-9]+$' THEN id = $2::bigint ELSE FALSE END) OR fqid = $2)
+        """
+        try:
+            row = await self._fetchrow(query, realm, v_str)
+            if not row:
+                return None
+            return Vertex(
+                realm=row['realm'],
+                id=str(row['id']),
+                fqid=row['fqid'] or f"{row['realm']}/{table_name}/{row['id']}",
+                payload=row['payload'] if isinstance(row['payload'], dict) else json.loads(row['payload']),
+                created_at=row['created_at'],
+                updated_at=row['updated_at'],
+                table_name=table_name,
+                _client=self
+            )
+        except asyncpg.UndefinedTableError:
+            raise TableNotFoundError(f"Vertex table '{table_name}' does not exist.")
+
+    async def delete_vertex(self, table_name: str, realm: str, vertex_id: str, user_id: Optional[str] = None) -> bool:
+        """Delete a vertex. Cascading foreign keys will automatically delete referencing edges."""
+        self._validate_identifier(table_name)
+        table_ref = self._get_table_ref(table_name, realm)
+        v_str = str(vertex_id)
+
+        async def _op(conn):
+            query = f"""
+            DELETE FROM {table_ref} 
+            WHERE realm = $1 AND ((CASE WHEN $2 ~ '^[0-9]+$' THEN id = $2::bigint ELSE FALSE END) OR fqid = $2)
+            """
+            try:
+                res = await conn.execute(query, realm, v_str)
+                return res == "DELETE 1"
+            except asyncpg.UndefinedTableError:
+                raise TableNotFoundError(f"Vertex table '{table_name}' does not exist.")
+
+        return await self._run_in_tx(_op, user_id)
+
+    async def add_edge(
+        self,
+        table_name: str,
+        realm: str,
+        from_id: str,
+        to_id: str,
+        relation_type: str,
+        edge_id: Optional[Union[str, int]] = None,
+        payload: Optional[Dict[str, Any]] = None,
+        user_id: Optional[str] = None,
+        check_cycle: Union[bool, List[str]] = False
+    ) -> Edge:
+        """Add a new edge. Raises TableExistsError if it already exists."""
+        self._validate_identifier(table_name)
+        payload_json = json.dumps(payload or {})
+        table_ref = self._get_table_ref(table_name, realm)
+
+        async def _op(conn):
+            nonlocal edge_id
+            schema = await self.get_edge_schema(table_name, realm=realm, conn=conn)
+            from_table = schema["from_id"]
+            to_table = schema["to_id"]
+
+            table_ref_pg = f'"{realm}"."{table_name}"' if self.schema_per_realm else f'"{table_name}"'
+            if edge_id is None:
+                seq_query = f"SELECT nextval(pg_get_serial_sequence('{table_ref_pg}', 'id'))"
+                e_id_int = await conn.fetchval(seq_query)
+            else:
+                e_id_int = int(str(edge_id).split('/')[-1]) if '/' in str(edge_id) else int(edge_id)
+
+            from_id_int = int(str(from_id).split('/')[-1]) if '/' in str(from_id) else int(from_id)
+            to_id_int = int(str(to_id).split('/')[-1]) if '/' in str(to_id) else int(to_id)
+
+            e_id_str = str(e_id_int)
+
+            if check_cycle:
+                cycle_tables = check_cycle if isinstance(check_cycle, list) else [table_name]
+                
+                path = await self.shortest_path(
+                    realm=realm,
+                    start_table=to_table,
+                    start_id=str(to_id_int),
+                    target_table=from_table,
+                    target_id=str(from_id_int),
+                    edge_tables=cycle_tables,
+                    conn=conn
+                )
+                if path:
+                    from post_graph.errors import CyclicReferenceError
+                    raise CyclicReferenceError(
+                        f"Adding edge '{e_id_str}' from '{from_id}' to '{to_id}' would create a cyclic reference. "
+                        f"Existing path: {' -> '.join(path['path'])}"
+                    )
+
+            query = f"""
+            INSERT INTO {table_ref} (realm, id, from_id, to_id, relation_type, payload)
+            VALUES ($1, $2, $3, $4, $5, $6::jsonb)
+            RETURNING realm, id, fqid, from_id, to_id, relation_type, payload, created_at, updated_at
+            """
+            try:
+                row = await conn.fetchrow(query, realm, e_id_int, from_id_int, to_id_int, relation_type, payload_json)
+                if edge_id is not None:
+                    await conn.execute(
+                        f"SELECT setval(pg_get_serial_sequence('{table_ref_pg}', 'id'), (SELECT COALESCE(MAX(id), 1) FROM {table_ref}))"
+                    )
+                return Edge(
+                    realm=row['realm'],
+                    id=str(row['id']),
+                    fqid=row['fqid'],
+                    from_id=str(row['from_id']),
+                    to_id=str(row['to_id']),
+                    relation_type=row['relation_type'],
+                    payload=row['payload'] if isinstance(row['payload'], dict) else json.loads(row['payload']),
+                    created_at=row['created_at'],
+                    updated_at=row['updated_at'],
+                    table_name=table_name,
+                    _client=self
+                )
+            except asyncpg.UniqueViolationError:
+                raise TableExistsError(
+                    f"Edge with ID '{e_id_str}' already exists in table '{table_name}' under realm '{realm}'."
+                )
+            except asyncpg.ForeignKeyViolationError as e:
+                raise VertexNotFoundError(f"Foreign key violation: referenced vertices do not exist. Details: {e}")
+            except asyncpg.UndefinedTableError:
+                raise TableNotFoundError(f"Edge table '{table_name}' does not exist.")
+
+        return await self._run_in_tx(_op, user_id)
+
+    async def upsert_edge(
+        self,
+        table_name: str,
+        realm: str,
+        from_id: str,
+        to_id: str,
+        relation_type: str,
+        edge_id: Optional[Union[str, int]] = None,
+        payload: Optional[Dict[str, Any]] = None,
+        user_id: Optional[str] = None,
+        check_cycle: Union[bool, List[str]] = False
+    ) -> Edge:
+        """Upsert an edge (merges payload JSONB on conflict)."""
+        self._validate_identifier(table_name)
+        payload_json = json.dumps(payload or {})
+        table_ref = self._get_table_ref(table_name, realm)
+
+        async def _op(conn):
+            nonlocal edge_id
+            schema = await self.get_edge_schema(table_name, realm=realm, conn=conn)
+            from_table = schema["from_id"]
+            to_table = schema["to_id"]
+
+            table_ref_pg = f'"{realm}"."{table_name}"' if self.schema_per_realm else f'"{table_name}"'
+            if edge_id is None:
+                seq_query = f"SELECT nextval(pg_get_serial_sequence('{table_ref_pg}', 'id'))"
+                e_id_int = await conn.fetchval(seq_query)
+            else:
+                e_id_int = int(str(edge_id).split('/')[-1]) if '/' in str(edge_id) else int(edge_id)
+
+            from_id_int = int(str(from_id).split('/')[-1]) if '/' in str(from_id) else int(from_id)
+            to_id_int = int(str(to_id).split('/')[-1]) if '/' in str(to_id) else int(to_id)
+
+            e_id_str = str(e_id_int)
+
+            if check_cycle:
+                cycle_tables = check_cycle if isinstance(check_cycle, list) else [table_name]
+                
+                path = await self.shortest_path(
+                    realm=realm,
+                    start_table=to_table,
+                    start_id=str(to_id_int),
+                    target_table=from_table,
+                    target_id=str(from_id_int),
+                    edge_tables=cycle_tables,
+                    conn=conn
+                )
+                if path:
+                    from post_graph.errors import CyclicReferenceError
+                    raise CyclicReferenceError(
+                        f"Upserting edge '{e_id_str}' from '{from_id}' to '{to_id}' would create a cyclic reference. "
+                        f"Existing path: {' -> '.join(path['path'])}"
+                    )
+
+            query = f"""
+            INSERT INTO {table_ref} (realm, id, from_id, to_id, relation_type, payload)
+            VALUES ($1, $2, $3, $4, $5, $6::jsonb)
+            ON CONFLICT (realm, id) DO UPDATE
+            SET from_id = EXCLUDED.from_id,
+                to_id = EXCLUDED.to_id,
+                relation_type = EXCLUDED.relation_type,
+                payload = {table_ref}.payload || EXCLUDED.payload,
+                updated_at = CURRENT_TIMESTAMP
+            RETURNING realm, id, fqid, from_id, to_id, relation_type, payload, created_at, updated_at
+            """
+            try:
+                row = await conn.fetchrow(query, realm, e_id_int, from_id_int, to_id_int, relation_type, payload_json)
+                return Edge(
+                    realm=row['realm'],
+                    id=str(row['id']),
+                    fqid=row['fqid'],
+                    from_id=str(row['from_id']),
+                    to_id=str(row['to_id']),
+                    relation_type=row['relation_type'],
+                    payload=row['payload'] if isinstance(row['payload'], dict) else json.loads(row['payload']),
+                    created_at=row['created_at'],
+                    updated_at=row['updated_at'],
+                    table_name=table_name,
+                    _client=self
+                )
+            except asyncpg.ForeignKeyViolationError as e:
+                raise VertexNotFoundError(f"Foreign key violation: referenced vertices do not exist. Details: {e}")
+            except asyncpg.UndefinedTableError:
+                raise TableNotFoundError(f"Edge table '{table_name}' does not exist.")
+
+        return await self._run_in_tx(_op, user_id)
+
+    async def get_edge(self, table_name: str, realm: str, edge_id: str) -> Optional[Edge]:
+        """Fetch an edge by realm and id."""
+        self._validate_identifier(table_name)
+        table_ref = self._get_table_ref(table_name, realm)
+        e_str = str(edge_id)
+        query = f"""
+        SELECT realm, id, fqid, from_id, to_id, relation_type, payload, created_at, updated_at 
+        FROM {table_ref} 
+        WHERE realm = $1 AND ((CASE WHEN $2 ~ '^[0-9]+$' THEN id = $2::bigint ELSE FALSE END) OR fqid = $2)
+        """
+        try:
+            row = await self._fetchrow(query, realm, e_str)
+            if not row:
+                return None
+            return Edge(
+                realm=row['realm'],
+                id=str(row['id']),
+                fqid=row['fqid'],
+                from_id=str(row['from_id']),
+                to_id=str(row['to_id']),
+                relation_type=row['relation_type'],
+                payload=row['payload'] if isinstance(row['payload'], dict) else json.loads(row['payload']),
+                created_at=row['created_at'],
+                updated_at=row['updated_at'],
+                table_name=table_name,
+                _client=self
+            )
+        except asyncpg.UndefinedTableError:
+            raise TableNotFoundError(f"Edge table '{table_name}' does not exist.")
+
+    async def delete_edge(self, table_name: str, realm: str, edge_id: str, user_id: Optional[str] = None) -> bool:
+        """Delete an edge."""
+        self._validate_identifier(table_name)
+        table_ref = self._get_table_ref(table_name, realm)
+        e_str = str(edge_id)
+
+        async def _op(conn):
+            query = f"""
+            DELETE FROM {table_ref} 
+            WHERE realm = $1 AND ((CASE WHEN $2 ~ '^[0-9]+$' THEN id = $2::bigint ELSE FALSE END) OR fqid = $2)
+            """
+            try:
+                res = await conn.execute(query, realm, e_str)
+                return res == "DELETE 1"
+            except asyncpg.UndefinedTableError:
+                raise TableNotFoundError(f"Edge table '{table_name}' does not exist.")
+
+        return await self._run_in_tx(_op, user_id)
+
+    async def delete_realm(self, realm: str, user_id: Optional[str] = None) -> int:
+        """Delete all rows belonging to a specific realm from all graph tables (vertices, edges, and audit tables)."""
+        async def _op(conn):
+            if self.schema_per_realm:
+                query = """
+                SELECT DISTINCT table_name 
+                FROM information_schema.columns 
+                WHERE column_name = 'realm' 
+                  AND table_schema = $1
+                """
+                rows = await conn.fetch(query, realm)
+            else:
+                query = """
+                SELECT DISTINCT table_name 
+                FROM information_schema.columns 
+                WHERE column_name = 'realm' 
+                  AND table_schema = CURRENT_SCHEMA()
+                """
+                rows = await conn.fetch(query)
+
+            tables = [row['table_name'] for row in rows]
+            
+            total_deleted = 0
+            for table in tables:
+                table_ref = self._get_table_ref(table, realm)
+                delete_query = f'DELETE FROM {table_ref} WHERE realm = $1'
+                res = await conn.execute(delete_query, realm)
+                if res.startswith("DELETE "):
+                    total_deleted += int(res.split(" ")[1])
+            return total_deleted
+
+        return await self._run_in_tx(_op, user_id)
+
+    async def get_edge_schema(self, edge_table: str, realm: Optional[str] = None, conn = None) -> Dict[str, str]:
+        """
+        Query system catalog pg_constraint to discover referenced vertex tables
+        for 'from_id' and 'to_id' keys of the edge table. Caches the schema.
+        """
+        cache_key = (realm, edge_table) if self.schema_per_realm else edge_table
+        if cache_key in self._schema_cache:
+            return self._schema_cache[cache_key]
+
+        self._validate_identifier(edge_table)
+        table_ref = self._get_table_ref(edge_table, realm)
+
+        query = """
+        SELECT 
+            a.attname AS column_name,
+            c.relname AS referenced_table
+        FROM pg_constraint con
+        JOIN pg_class c ON con.confrelid = c.oid
+        JOIN pg_attribute a ON a.attnum = ANY(con.conkey) AND a.attrelid = con.conrelid
+        WHERE con.conrelid = $1::regclass
+          AND con.contype = 'f'
+          AND a.attname IN ('from_id', 'to_id');
+        """
+
+        try:
+            if conn:
+                rows = await conn.fetch(query, table_ref)
+            else:
+                rows = await self._fetch(query, table_ref)
+        except asyncpg.UndefinedTableError:
+            raise TableNotFoundError(f"Edge table '{edge_table}' does not exist.")
+        except Exception as e:
+            raise PostGraphError(f"Error querying schema for '{edge_table}': {e}")
+
+        schema = {}
+        for row in rows:
+            schema[row['column_name']] = row['referenced_table']
+
+        if len(schema) < 2:
+            raise PostGraphError(
+                f"Edge table '{edge_table}' is missing proper foreign key constraints "
+                f"on 'from_id' and/or 'to_id' referencing vertex tables."
+            )
+
+        self._schema_cache[cache_key] = schema
+        return schema
+
+    async def get_neighbors(
+        self,
+        realm: str,
+        vertex_table: str,
+        vertex_id: str,
+        edge_tables: List[str],
+        direction: str = 'out'
+    ) -> List[Tuple[Vertex, Edge]]:
+        """
+        Get direct neighbor vertices and connecting edges.
+        Returns a list of tuples: (NeighborVertex, ConnectingEdge)
+        """
+        self._validate_identifier(vertex_table)
+        if direction not in ('out', 'in', 'both'):
+            raise ValueError("Direction must be 'out', 'in', or 'both'")
+
+        v_id_int = int(str(vertex_id).split('/')[-1]) if '/' in str(vertex_id) else int(vertex_id)
+
+        results = []
+        for edge_table in edge_tables:
+            self._validate_identifier(edge_table)
+            schema = await self.get_edge_schema(edge_table, realm=realm)
+
+            from_ref = schema['from_id']
+            to_ref = schema['to_id']
+
+            queries = []
+
+            # 1. Outgoing paths: from_id is the start, to_id is the neighbor
+            if direction in ('out', 'both') and from_ref == vertex_table:
+                edge_ref = self._get_table_ref(edge_table, realm)
+                to_ref_ref = self._get_table_ref(to_ref, realm)
+                queries.append((
+                    to_ref,
+                    f"""
+                    SELECT 
+                        v.id AS v_id, v.fqid AS v_fqid, v.payload AS v_payload, v.created_at AS v_created_at, v.updated_at AS v_updated_at,
+                        e.id AS e_id, e.fqid AS e_fqid, e.from_id AS e_from, e.to_id AS e_to, e.relation_type AS e_rel, e.payload AS e_payload, e.created_at AS e_created_at, e.updated_at AS e_updated_at
+                    FROM {edge_ref} e
+                    JOIN {to_ref_ref} v ON e.realm = v.realm AND e.to_id = v.id
+                    WHERE e.realm = $1 AND e.from_id = $2
+                    """
+                ))
+
+            # 2. Incoming paths: to_id is the start, from_id is the neighbor
+            if direction in ('in', 'both') and to_ref == vertex_table:
+                edge_ref = self._get_table_ref(edge_table, realm)
+                from_ref_ref = self._get_table_ref(from_ref, realm)
+                queries.append((
+                    from_ref,
+                    f"""
+                    SELECT 
+                        v.id AS v_id, v.fqid AS v_fqid, v.payload AS v_payload, v.created_at AS v_created_at, v.updated_at AS v_updated_at,
+                        e.id AS e_id, e.fqid AS e_fqid, e.from_id AS e_from, e.to_id AS e_to, e.relation_type AS e_rel, e.payload AS e_payload, e.created_at AS e_created_at, e.updated_at AS e_updated_at
+                    FROM {edge_ref} e
+                    JOIN {from_ref_ref} v ON e.realm = v.realm AND e.from_id = v.id
+                    WHERE e.realm = $1 AND e.to_id = $2
+                    """
+                ))
+
+            for neighbor_table, sql in queries:
+                rows = await self._fetch(sql, realm, v_id_int)
+                for r in rows:
+                    v = Vertex(
+                        realm=realm,
+                        id=str(r['v_id']),
+                        fqid=r['v_fqid'],
+                        payload=r['v_payload'] if isinstance(r['v_payload'], dict) else json.loads(r['v_payload']),
+                        created_at=r['v_created_at'],
+                        updated_at=r['v_updated_at'],
+                        table_name=neighbor_table,
+                        _client=self
+                    )
+                    e = Edge(
+                        realm=realm,
+                        id=str(r['e_id']),
+                        fqid=r['e_fqid'],
+                        from_id=str(r['e_from']),
+                        to_id=str(r['e_to']),
+                        relation_type=r['e_rel'],
+                        payload=r['e_payload'] if isinstance(r['e_payload'], dict) else json.loads(r['e_payload']),
+                        created_at=r['e_created_at'],
+                        updated_at=r['e_updated_at'],
+                        table_name=edge_table,
+                        _client=self
+                    )
+                    results.append((v, e))
+
+        return results
+
+    async def traverse(
+        self,
+        realm: str,
+        start_table: str,
+        start_id: str,
+        edge_tables: List[str],
+        max_depth: int = 3,
+        direction: str = 'out'
+    ) -> List[Dict[str, Any]]:
+        """
+        Perform a dynamic graph traversal starting from (start_table, start_id)
+        up to max_depth. scoped to a specific realm.
+        """
+        self._validate_identifier(start_table)
+        if direction not in ('out', 'in', 'both'):
+            raise ValueError("Direction must be 'out', 'in', or 'both'")
+
+        start_id_str = str(start_id).split('/')[-1] if '/' in str(start_id) else str(start_id)
+
+        subqueries = []
+        for edge_table in edge_tables:
+            schema = await self.get_edge_schema(edge_table, realm=realm)
+            from_ref = schema['from_id']
+            to_ref = schema['to_id']
+            edge_ref = self._get_table_ref(edge_table, realm)
+
+            if direction in ('out', 'both'):
+                subqueries.append(f"""
+                SELECT 
+                    to_id::text AS next_id, 
+                    '{to_ref}'::text AS next_table,
+                    id::text AS edge_id,
+                    relation_type,
+                    payload,
+                    '{edge_table}'::text AS edge_table
+                FROM {edge_ref}
+                WHERE realm = $1 AND from_id = (CASE WHEN t.current_id ~ '^[0-9]+$' THEN t.current_id::bigint ELSE NULL END) AND t.current_table = '{from_ref}'
+                """)
+
+            if direction in ('in', 'both'):
+                subqueries.append(f"""
+                SELECT 
+                    from_id::text AS next_id, 
+                    '{from_ref}'::text AS next_table,
+                    id::text AS edge_id,
+                    relation_type,
+                    payload,
+                    '{edge_table}'::text AS edge_table
+                FROM {edge_ref}
+                WHERE realm = $1 AND to_id = (CASE WHEN t.current_id ~ '^[0-9]+$' THEN t.current_id::bigint ELSE NULL END) AND t.current_table = '{to_ref}'
+                """)
+
+        if not subqueries:
+            return []
+
+        union_all_steps = "\nUNION ALL\n".join(subqueries)
+
+        cte_query = f"""
+        WITH RECURSIVE graph_traversal AS (
+            -- Anchor Member
+            SELECT 
+                $2::text AS current_id,
+                $3::text AS current_table,
+                0 AS depth,
+                ARRAY[$3::text || ':' || $2::text]::text[] AS path,
+                ARRAY[]::text[] AS edge_path,
+                ARRAY[]::text[] AS edge_ids
+            
+            UNION ALL
+            
+            -- Recursive Member
+            SELECT 
+                step.next_id,
+                step.next_table,
+                t.depth + 1,
+                t.path || (step.next_table || ':' || step.next_id),
+                t.edge_path || (step.edge_table || ':' || step.relation_type),
+                t.edge_ids || step.edge_id
+            FROM graph_traversal t
+            CROSS JOIN LATERAL (
+                {union_all_steps}
+            ) step
+            WHERE t.depth < $4
+              AND NOT ((step.next_table || ':' || step.next_id) = ANY(t.path))
+        )
+        SELECT current_id, current_table, depth, path, edge_path, edge_ids FROM graph_traversal;
+        """
+
+        rows = await self._fetch(cte_query, realm, start_id_str, start_table, max_depth)
+
+        return [
+            {
+                'id': row['current_id'],
+                'table_name': row['current_table'],
+                'depth': row['depth'],
+                'path': row['path'],
+                'edge_path': row['edge_path'],
+                'edge_ids': row['edge_ids']
+            }
+            for row in rows
+        ]
+
+    async def shortest_path(
+        self,
+        realm: str,
+        start_table: str,
+        start_id: str,
+        target_table: str,
+        target_id: str,
+        edge_tables: List[str],
+        max_depth: int = 5,
+        direction: str = 'out',
+        conn = None
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Find shortest path from (start_table, start_id) to (target_table, target_id)
+        in a specific realm. Returns None if no path exists.
+        """
+        self._validate_identifier(start_table)
+        self._validate_identifier(target_table)
+        if direction not in ('out', 'in', 'both'):
+            raise ValueError("Direction must be 'out', 'in', or 'both'")
+
+        start_id_str = str(start_id).split('/')[-1] if '/' in str(start_id) else str(start_id)
+        target_id_str = str(target_id).split('/')[-1] if '/' in str(target_id) else str(target_id)
+
+        subqueries = []
+        for edge_table in edge_tables:
+            schema = await self.get_edge_schema(edge_table, realm=realm)
+            from_ref = schema['from_id']
+            to_ref = schema['to_id']
+            edge_ref = self._get_table_ref(edge_table, realm)
+
+            if direction in ('out', 'both'):
+                subqueries.append(f"""
+                SELECT 
+                    to_id::text AS next_id, 
+                    '{to_ref}'::text AS next_table,
+                    id::text AS edge_id,
+                    relation_type,
+                    '{edge_table}'::text AS edge_table
+                FROM {edge_ref}
+                WHERE realm = $1 AND from_id = (CASE WHEN t.current_id ~ '^[0-9]+$' THEN t.current_id::bigint ELSE NULL END) AND t.current_table = '{from_ref}'
+                """)
+
+            if direction in ('in', 'both'):
+                subqueries.append(f"""
+                SELECT 
+                    from_id::text AS next_id, 
+                    '{from_ref}'::text AS next_table,
+                    id::text AS edge_id,
+                    relation_type,
+                    '{edge_table}'::text AS edge_table
+                FROM {edge_ref}
+                WHERE realm = $1 AND to_id = (CASE WHEN t.current_id ~ '^[0-9]+$' THEN t.current_id::bigint ELSE NULL END) AND t.current_table = '{to_ref}'
+                """)
+
+        if not subqueries:
+            return None
+
+        union_all_steps = "\nUNION ALL\n".join(subqueries)
+
+        cte_query = f"""
+        WITH RECURSIVE graph_traversal AS (
+            -- Anchor Member
+            SELECT 
+                $2::text AS current_id,
+                $3::text AS current_table,
+                0 AS depth,
+                ARRAY[$3::text || ':' || $2::text]::text[] AS path,
+                ARRAY[]::text[] AS edge_path,
+                ARRAY[]::text[] AS edge_ids
+            
+            UNION ALL
+            
+            -- Recursive Member
+            SELECT 
+                step.next_id,
+                step.next_table,
+                t.depth + 1,
+                t.path || (step.next_table || ':' || step.next_id),
+                t.edge_path || (step.edge_table || ':' || step.relation_type),
+                t.edge_ids || step.edge_id
+            FROM graph_traversal t
+            CROSS JOIN LATERAL (
+                {union_all_steps}
+            ) step
+            WHERE t.depth < $4
+              AND NOT ((step.next_table || ':' || step.next_id) = ANY(t.path))
+              AND NOT (t.current_id = $5 AND t.current_table = $6)
+        )
+        SELECT depth, path, edge_path, edge_ids
+        FROM graph_traversal 
+        WHERE current_id = $5 AND current_table = $6
+        ORDER BY depth ASC
+        LIMIT 1;
+        """
+
+        if conn:
+            row = await conn.fetchrow(cte_query, realm, start_id_str, start_table, max_depth, target_id_str, target_table)
+        else:
+            row = await self._fetchrow(cte_query, realm, start_id_str, start_table, max_depth, target_id_str, target_table)
+            
+        if not row:
+            return None
+
+        return {
+            'depth': row['depth'],
+            'path': row['path'],
+            'edge_path': row['edge_path'],
+            'edge_ids': row['edge_ids']
+        }
+
+    async def add_vertex_data(
+        self,
+        table_name: str,
+        realm: str,
+        vertex_id: Union[str, int],
+        payload: Dict[str, Any],
+        timestamp: Optional[Any] = None,
+        user_id: Optional[str] = None
+    ) -> DataRecord:
+        """Append a historical record to {table_name}_data table for a vertex."""
+        self._validate_identifier(table_name)
+        v_id_int = int(str(vertex_id).split('/')[-1]) if '/' in str(vertex_id) else int(vertex_id)
+        payload_json = json.dumps(payload or {})
+        data_table_ref = self._get_table_ref(f"{table_name}_data", realm)
+
+        async def _op(conn):
+            if timestamp:
+                query = f"""
+                INSERT INTO {data_table_ref} (realm, id, payload, timestamp)
+                VALUES ($1, $2, $3::jsonb, $4)
+                RETURNING data_id, realm, id, payload, timestamp
+                """
+                row = await conn.fetchrow(query, realm, v_id_int, payload_json, timestamp)
+            else:
+                query = f"""
+                INSERT INTO {data_table_ref} (realm, id, payload)
+                VALUES ($1, $2, $3::jsonb)
+                RETURNING data_id, realm, id, payload, timestamp
+                """
+                row = await conn.fetchrow(query, realm, v_id_int, payload_json)
+
+            return DataRecord(
+                data_id=str(row['data_id']),
+                realm=row['realm'],
+                id=str(row['id']),
+                payload=row['payload'] if isinstance(row['payload'], dict) else json.loads(row['payload']),
+                timestamp=row['timestamp']
+            )
+
+        return await self._run_in_tx(_op, user_id)
+
+    async def get_vertex_data(
+        self,
+        table_name: str,
+        realm: str,
+        vertex_id: Union[str, int],
+        limit: Optional[int] = None
+    ) -> List[DataRecord]:
+        """Fetch append-only data records for a vertex sorted by timestamp descending."""
+        self._validate_identifier(table_name)
+        v_id_int = int(str(vertex_id).split('/')[-1]) if '/' in str(vertex_id) else int(vertex_id)
+        data_table_ref = self._get_table_ref(f"{table_name}_data", realm)
+
+        limit_clause = f"LIMIT {limit}" if limit and limit > 0 else ""
+        query = f"""
+        SELECT data_id, realm, id, payload, timestamp
+        FROM {data_table_ref}
+        WHERE realm = $1 AND id = $2
+        ORDER BY timestamp DESC, data_id DESC
+        {limit_clause}
+        """
+        rows = await self._fetch(query, realm, v_id_int)
+        return [
+            DataRecord(
+                data_id=str(r['data_id']),
+                realm=r['realm'],
+                id=str(r['id']),
+                payload=r['payload'] if isinstance(r['payload'], dict) else json.loads(r['payload']),
+                timestamp=r['timestamp']
+            )
+            for r in rows
+        ]
+
+    async def add_edge_data(
+        self,
+        table_name: str,
+        realm: str,
+        edge_id: Union[str, int],
+        payload: Dict[str, Any],
+        timestamp: Optional[Any] = None,
+        user_id: Optional[str] = None
+    ) -> DataRecord:
+        """Append a historical record to {table_name}_data table for an edge."""
+        return await self.add_vertex_data(table_name, realm, edge_id, payload, timestamp=timestamp, user_id=user_id)
+
+    async def get_edge_data(
+        self,
+        table_name: str,
+        realm: str,
+        edge_id: Union[str, int],
+        limit: Optional[int] = None
+    ) -> List[DataRecord]:
+        """Fetch append-only data records for an edge sorted by timestamp descending."""
+        return await self.get_vertex_data(table_name, realm, edge_id, limit=limit)
+