pixeltable 0.3.14__py3-none-any.whl → 0.4.0rc1__py3-none-any.whl

pixeltable/catalog/catalog.py

@@ -3,8 +3,10 @@ from __future__ import annotations
 import dataclasses
 import functools
 import logging
+import random
 import time
-from typing import TYPE_CHECKING, Any, Callable, Optional, TypeVar
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any, Callable, Iterator, Optional, TypeVar
 from uuid import UUID
 
 import psycopg
@@ -56,40 +58,60 @@ def _unpack_row(
     return result
 
 
-_MAX_RETRIES = 3
+# for now, we don't limit the number of retries, because we haven't seen situations where the actual number of retries
+# grows uncontrollably
+_MAX_RETRIES = 0
+
 T = TypeVar('T')
 
 
-def _retry_loop(op: Callable[..., T]) -> Callable[..., T]:
-    @functools.wraps(op)
-    def loop(*args: Any, **kwargs: Any) -> T:
-        num_remaining_retries = _MAX_RETRIES
-        while True:
-            try:
-                # in order for retry to work, we need to make sure that there aren't any prior db updates
-                # that are part of an ongoing transaction
-                assert not Env.get().in_xact()
-                with Env.get().begin_xact():
-                    return op(*args, **kwargs)
-            except sql.exc.DBAPIError as e:
-                if isinstance(e.orig, psycopg.errors.SerializationFailure):
-                    if num_remaining_retries > 0:
-                        num_remaining_retries -= 1
-                        # print(f'serialization failure:\n{e}')
-                        # print('retrying ************************************************************')
-                        time.sleep(1)
+def _retry_loop(*, for_write: bool) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    def decorator(op: Callable[..., T]) -> Callable[..., T]:
+        @functools.wraps(op)
+        def loop(*args: Any, **kwargs: Any) -> T:
+            num_remaining_retries = _MAX_RETRIES
+            while True:
+                try:
+                    # in order for retry to work, we need to make sure that there aren't any prior db updates
+                    # that are part of an ongoing transaction
+                    assert not Env.get().in_xact
+                    with Catalog.get().begin_xact(for_write=for_write):
+                        return op(*args, **kwargs)
+                except sql.exc.DBAPIError as e:
+                    # TODO: what other exceptions should we be looking for?
+                    if isinstance(e.orig, psycopg.errors.SerializationFailure):
+                        if num_remaining_retries > 0:
+                            num_remaining_retries -= 1
+                            _logger.debug(f'Serialization failure, retrying ({num_remaining_retries} retries left)')
+                            time.sleep(random.uniform(0.1, 0.5))
+                        else:
+                            raise excs.Error(f'Serialization retry limit ({_MAX_RETRIES}) exceeded') from e
                     else:
-                        raise excs.Error(f'Serialization retry limit ({_MAX_RETRIES}) exceeded') from e
-                else:
-                    raise
+                        raise
+
+        return loop
 
-    return loop
+    return decorator
 
 
 class Catalog:
     """The functional interface to getting access to catalog objects
 
-    All interface functions must be called in the context of a transaction, started with Env.begin().
+    All interface functions must be called in the context of a transaction, started with Catalog.begin_xact().
+
+    Caching and invalidation of metadata:
+    - Catalog caches TableVersion instances in order to avoid excessive metadata loading
+    - for any specific table version (ie, combination of id and effective version) there can be only a single
+      Tableversion instance in circulation; the reason is that each TV instance has its own store_tbl.sa_tbl, and
+      mixing multiple instances of sqlalchemy Table objects in the same query (for the same underlying table) leads to
+      duplicate references to that table in the From clause (ie, incorrect Cartesian products)
+    - in order to allow multiple concurrent Python processes to perform updates (data and/or schema) against a shared
+      Pixeltable instance, Catalog needs to reload metadata from the store when there are changes
+    - concurrent changes are detected by comparing TableVersion.version with the stored current version
+      (TableMd.current_version)
+    - cached live TableVersion instances (those with effective_version == None) are validated against the stored
+      metadata on transaction boundaries; this is recorded in TableVersion.is_validated
+    - metadata validation is only needed for live TableVersion instances (snapshot instances are immutable)
     """
 
     _instance: Optional[Catalog] = None
@@ -99,6 +121,8 @@ class Catalog:
     # - snapshot versions: records the version of the snapshot
     _tbl_versions: dict[tuple[UUID, Optional[int]], TableVersion]
     _tbls: dict[UUID, Table]
+    _in_write_xact: bool  # True if we're in a write transaction
+    _x_locked_tbl_id: Optional[UUID]  # set if begin_xact() was asked to write-lock a table
 
     @classmethod
     def get(cls) -> Catalog:
@@ -109,22 +133,127 @@ class Catalog:
     @classmethod
     def clear(cls) -> None:
         """Remove the instance. Used for testing."""
+        # invalidate all existing instances to force reloading of metadata
+        for tbl_version in cls._instance._tbl_versions.values():
+            # _logger.debug(
+            #     f'Invalidating table version {tbl_version.id}:{tbl_version.effective_version} ({id(tbl_version):x})'
+            # )
+            tbl_version.is_validated = False
         cls._instance = None
 
     def __init__(self) -> None:
         self._tbl_versions = {}
         self._tbls = {}  # don't use a defaultdict here, it doesn't cooperate with the debugger
+        self._in_write_xact = False
+        self._x_locked_tbl_id = None
         self._init_store()
 
-    @classmethod
-    def _lock_dir(cls, parent_id: Optional[UUID], dir_id: Optional[UUID], dir_name: Optional[str]) -> None:
-        """Update directory record(s) to sequentialize thread access. Lock is released when transaction commits.
+    def validate(self) -> None:
+        """Validate structural consistency of cached metadata"""
+        for (tbl_id, effective_version), tbl_version in self._tbl_versions.items():
+            assert tbl_id == tbl_version.id, f'{tbl_id} != {tbl_version.id}'
+            assert tbl_version.effective_version == tbl_version.version or tbl_version.effective_version is None, (
+                f'{tbl_version.effective_version} != {tbl_version.version} for id {tbl_id}'
+            )
+            assert effective_version == tbl_version.effective_version, (
+                f'{effective_version} != {tbl_version.effective_version} for id {tbl_id}'
+            )
+            assert len(tbl_version.mutable_views) == 0 or tbl_version.is_mutable, (
+                f'snapshot_id={tbl_version.id} mutable_views={tbl_version.mutable_views}'
+            )
+
+            if tbl_version.is_view and tbl_version.is_mutable:
+                # make sure this mutable view is recorded in a mutable base
+                base = tbl_version.base
+                assert base is not None
+                if base.effective_version is None:
+                    assert (base.id, None) in self._tbl_versions
+                    assert TableVersionHandle.create(tbl_version) in self._tbl_versions[base.id, None].mutable_views
+
+            if len(tbl_version.mutable_views) > 0:
+                # make sure we also loaded mutable view metadata, which is needed to detect column dependencies
+                for v in tbl_version.mutable_views:
+                    assert v.effective_version is None, f'{v.id}:{v.effective_version}'
+
+    @contextmanager
+    def begin_xact(self, *, tbl_id: Optional[UUID] = None, for_write: bool = False) -> Iterator[sql.Connection]:
+        """
+        Return a context manager that yields a connection to the database. Idempotent.
+
+        It is mandatory to call this method, not Env.begin_xact(), if the transaction accesses any table data
+        or metadata.
+
+        Lock acquisition:
+        - x-locks Table records by updating Table.lock_dummy
+        - this needs to be done in a retry loop, because Postgres can decide to abort the transaction
+          (SerializationFailure, LockNotAvailable)
+        - for that reason, we do all lock acquisition prior to doing any real work (eg, compute column values),
+          to minimize (maybe avoid altogether) loosing that work
+        """
+        if Env.get().in_xact:
+            if tbl_id is not None and for_write:
+                # make sure that we requested the required table lock at the beginning of the transaction
+                assert tbl_id == self._x_locked_tbl_id, f'{tbl_id} != {self._x_locked_tbl_id}'
+            yield Env.get().conn
+            return
+
+        # tv_msg = '\n'.join(
+        #     [
+        #         f'{tv.id}:{tv.effective_version} : tv={id(tv):x} sa_tbl={id(tv.store_tbl.sa_tbl):x}'
+        #         for tv in self._tbl_versions.values()
+        #     ]
+        # )
+        # _logger.debug(f'begin_xact(): {tv_msg}')
+        num_retries = 0
+        while True:
+            try:
+                with Env.get().begin_xact() as conn:
+                    if tbl_id is not None and for_write:
+                        # X-lock Table record
+                        conn.execute(
+                            sql.select(schema.Table).where(schema.Table.id == tbl_id).with_for_update(nowait=True)
+                        )
+                        conn.execute(sql.update(schema.Table).values(lock_dummy=1).where(schema.Table.id == tbl_id))
+                        self._x_locked_tbl_id = tbl_id
+
+                    self._in_write_xact = for_write
+                    yield conn
+                    return
+            except sql.exc.DBAPIError as e:
+                if isinstance(e.orig, (psycopg.errors.SerializationFailure, psycopg.errors.LockNotAvailable)) and (
+                    num_retries < _MAX_RETRIES or _MAX_RETRIES == 0
+                ):
+                    num_retries += 1
+                    _logger.debug(f'Retrying ({num_retries}) after {type(e.orig)}')
+                    time.sleep(random.uniform(0.1, 0.5))
+                else:
+                    raise
+            finally:
+                self._in_write_xact = False
+                self._x_locked_tbl_id = None
+
+                # invalidate cached current TableVersion instances
+                for tv in self._tbl_versions.values():
+                    if tv.effective_version is None:
+                        _logger.debug(f'invalidating table version {tv.id}:None (tv={id(tv):x})')
+                        tv.is_validated = False
+
+                if _logger.isEnabledFor(logging.DEBUG):
+                    self.validate()
+
+    @property
+    def in_write_xact(self) -> bool:
+        return self._in_write_xact
+
+    def _acquire_dir_xlock(self, parent_id: Optional[UUID], dir_id: Optional[UUID], dir_name: Optional[str]) -> None:
+        """Force acquisition of an X-lock on a Dir record via a blind update.
+
         If dir_id is present, then all other conditions are ignored.
         Note that (parent_id==None) is a valid where condition.
         If dir_id is not specified, the user from the environment is added to the directory filters.
         """
         user = Env.get().user
-        conn = Env.get().conn
+        assert self._in_write_xact
         q = sql.update(schema.Dir).values(lock_dummy=1)
         if dir_id is not None:
             q = q.where(schema.Dir.id == dir_id)
@@ -134,7 +263,7 @@ class Catalog:
                 q = q.where(schema.Dir.md['name'].astext == dir_name)
             if user is not None:
                 q = q.where(schema.Dir.md['user'].astext == user)
-        conn.execute(q)
+        Env.get().conn.execute(q)
 
     def get_dir_path(self, dir_id: UUID) -> Path:
         """Return path for directory with given id"""
@@ -156,7 +285,7 @@ class Catalog:
         dir_entries: dict[str, Catalog.DirEntry]
         table: Optional[schema.Table]
 
-    @_retry_loop
+    @_retry_loop(for_write=False)
     def get_dir_contents(self, dir_path: Path, recursive: bool = False) -> dict[str, DirEntry]:
         dir = self._get_schema_object(dir_path, expected=Dir, raise_if_not_exists=True)
         return self._get_dir_contents(dir._id, recursive=recursive)
@@ -183,7 +312,7 @@ class Catalog:
 
         return result
 
-    @_retry_loop
+    @_retry_loop(for_write=True)
     def move(self, path: Path, new_path: Path) -> None:
         self._move(path, new_path)
 
@@ -272,7 +401,7 @@ class Catalog:
 
         # check for subdirectory
         if for_update:
-            self._lock_dir(dir_id, None, name)
+            self._acquire_dir_xlock(dir_id, None, name)
         q = sql.select(schema.Dir).where(
             schema.Dir.parent_id == dir_id, schema.Dir.md['name'].astext == name, schema.Dir.md['user'].astext == user
         )
@@ -296,7 +425,7 @@ class Catalog:
         tbl_id = conn.execute(q).scalar_one_or_none()
         if tbl_id is not None:
             if tbl_id not in self._tbls:
-                self._tbls[tbl_id] = self._load_tbl(tbl_id)
+                _ = self._load_tbl(tbl_id)
             return self._tbls[tbl_id]
 
         return None
@@ -349,10 +478,15 @@ class Catalog:
             tbl = self._load_tbl(tbl_id)
             if tbl is None:
                 return None
-            self._tbls[tbl_id] = tbl
+            # if this is a mutable table, we also need to have its mutable views loaded, in order to track column
+            # dependencies
+            tbl_version = tbl._tbl_version.get()
+            if tbl_version.is_mutable:
+                for v in tbl_version.mutable_views:
+                    _ = self.get_table_by_id(v.id)
         return self._tbls[tbl_id]
 
-    @_retry_loop
+    @_retry_loop(for_write=True)
     def create_table(
         self,
         path: Path,
@@ -385,7 +519,7 @@ class Catalog:
         self._tbls[tbl._id] = tbl
         return tbl
 
-    @_retry_loop
+    @_retry_loop(for_write=True)
     def create_view(
         self,
         path: Path,
@@ -431,14 +565,17 @@ class Catalog:
         self._tbls[view._id] = view
         return view
 
-    @_retry_loop
+    @_retry_loop(for_write=True)
     def create_replica(
         self, path: Path, md: list[schema.FullTableMd], if_exists: IfExistsParam = IfExistsParam.ERROR
-    ) -> Table:
+    ) -> None:
         """
         Creates table, table_version, and table_schema_version records for a replica with the given metadata.
         The metadata should be presented in standard "ancestor order", with the table being replicated at
         list position 0 and the (root) base table at list position -1.
+
+        TODO: create_replica() also needs to create the store tables and populate them in order to make
+        replica creation atomic.
         """
         tbl_id = UUID(md[0].tbl_md.tbl_id)
 
@@ -451,20 +588,19 @@ class Catalog:
                     'but a different table already exists at that location.'
                 )
             assert isinstance(existing, View)
-            return existing
+            return
 
         # Ensure that the system directory exists.
         self._create_dir(Path('_system', allow_system_paths=True), if_exists=IfExistsParam.IGNORE, parents=False)
 
         # Now check to see if this table already exists in the catalog.
-        # TODO: Handle concurrency in create_replica()
         existing = Catalog.get().get_table_by_id(tbl_id)
         if existing is not None:
-            existing_path = Path(existing._path, allow_system_paths=True)
+            existing_path = Path(existing._path(), allow_system_paths=True)
             # It does exist. If it's a non-system table, that's an error: it's already been replicated.
             if not existing_path.is_system_path:
                 raise excs.Error(
-                    f'That table has already been replicated as {existing._path!r}. \n'
+                    f'That table has already been replicated as {existing._path()!r}. \n'
                     f'Drop the existing replica if you wish to re-create it.'
                 )
             # If it's a system table, then this means it was created at some point as the ancestor of some other
@@ -489,22 +625,20 @@ class Catalog:
                 # The table already exists in the catalog. The existing path might be a system path (if the table
                 # was created as an anonymous base table of some other table), or it might not (if it's a snapshot
                 # that was directly replicated by the user at some point). In either case, use the existing path.
-                replica_path = Path(replica._path, allow_system_paths=True)
+                replica_path = Path(replica._path(), allow_system_paths=True)
 
             # Store the metadata; it could be a new version (in which case a new record will be created) or a
             # known version (in which case the newly received metadata will be validated as identical).
             self.__store_replica_md(replica_path, ancestor_md)
 
-        # Update the catalog (as a final step, after all DB operations completed successfully).
-        # Only the table being replicated is actually made visible in the catalog.
-        self._tbls[tbl_id] = self._load_tbl(tbl_id)
-        return self._tbls[tbl_id]
+        # don't create TableVersion instances at this point, they would be superseded by calls to TV.create_replica()
+        # in TableRestorer.restore()
 
     def __store_replica_md(self, path: Path, md: schema.FullTableMd) -> None:
         _logger.info(f'Creating replica table at {path!r} with ID: {md.tbl_md.tbl_id}')
-        # TODO: Handle concurrency
         dir = self._get_schema_object(path.parent, expected=Dir, raise_if_not_exists=True)
         assert dir is not None
+        assert self._in_write_xact
 
         conn = Env.get().conn
         tbl_id = md.tbl_md.tbl_id
@@ -582,14 +716,24 @@ class Catalog:
 
         self.store_tbl_md(UUID(tbl_id), new_tbl_md, new_version_md, new_schema_version_md)
 
-    @_retry_loop
+    @_retry_loop(for_write=False)
     def get_table(self, path: Path) -> Table:
+        obj = self._get_table(path)
+        return obj
+
+    def _get_table(self, path: Path) -> Table:
         obj = Catalog.get()._get_schema_object(path, expected=Table, raise_if_not_exists=True)
         assert isinstance(obj, Table)
-        obj._tbl_version.get().ensure_md_loaded()
+        tbl_version = obj._tbl_version.get()
+        # TODO: instead of calling this here, move the logic into TableVersion.init(), which is called after
+        # registering the instance in _tbl_versions
+        tbl_version.ensure_md_loaded()
+        # if this table has mutable views, we need to load those as well, in order to record column dependencies
+        for v in tbl_version.mutable_views:
+            self.get_table_by_id(v.id)
         return obj
 
-    @_retry_loop
+    @_retry_loop(for_write=True)
     def drop_table(self, path: Path, if_not_exists: IfNotExistsParam, force: bool) -> None:
         _, _, src_obj = self._prepare_dir_op(
             drop_dir_path=path.parent,
@@ -621,11 +765,11 @@ class Catalog:
                 msg: str
                 if is_replace:
                     msg = (
-                        f'{obj_type_str} {tbl._path} already exists and has dependents. '
+                        f'{obj_type_str} {tbl._path()} already exists and has dependents. '
                         "Use `if_exists='replace_force'` to replace it."
                     )
                 else:
-                    msg = f'{obj_type_str} {tbl._path} has dependents.'
+                    msg = f'{obj_type_str} {tbl._path()} has dependents.'
                 raise excs.Error(msg)
 
             for view_id in view_ids:
@@ -636,9 +780,9 @@ class Catalog:
         tbl._drop()
         assert tbl._id in self._tbls
         del self._tbls[tbl._id]
-        _logger.info(f'Dropped table `{tbl._path}`.')
+        _logger.info(f'Dropped table `{tbl._path()}`.')
 
-    @_retry_loop
+    @_retry_loop(for_write=True)
     def create_dir(self, path: Path, if_exists: IfExistsParam, parents: bool) -> Dir:
         return self._create_dir(path, if_exists, parents)
 
@@ -673,7 +817,7 @@ class Catalog:
         Env.get().console_logger.info(f'Created directory {str(path)!r}.')
         return dir
 
-    @_retry_loop
+    @_retry_loop(for_write=True)
     def drop_dir(self, path: Path, if_not_exists: IfNotExistsParam, force: bool) -> None:
         _, _, schema_obj = self._prepare_dir_op(
             drop_dir_path=path.parent,
@@ -698,7 +842,7 @@ class Catalog:
                 raise excs.Error(f'Directory {str(dir_path)!r} is not empty.')
 
         # drop existing subdirs
-        self._lock_dir(dir_id, None, None)
+        self._acquire_dir_xlock(dir_id, None, None)
         dir_q = sql.select(schema.Dir).where(schema.Dir.parent_id == dir_id)
         for row in conn.execute(dir_q).all():
             self._drop_dir(row.id, dir_path.append(row.md['name']), force=True)
@@ -725,17 +869,37 @@ class Catalog:
         return result
 
     def get_tbl_version(self, tbl_id: UUID, effective_version: Optional[int]) -> Optional[TableVersion]:
-        if (tbl_id, effective_version) not in self._tbl_versions:
-            self._tbl_versions[tbl_id, effective_version] = self._load_tbl_version(tbl_id, effective_version)
-        return self._tbl_versions[tbl_id, effective_version]
-
-    def add_tbl_version(self, tbl_version: TableVersion) -> None:
-        """Explicitly add a TableVersion"""
-        self._tbl_versions[tbl_version.id, tbl_version.effective_version] = tbl_version
-        # if this is a mutable view, also record it in the base
-        if tbl_version.is_view and tbl_version.effective_version is None:
-            base = tbl_version.base.get()
-            base.mutable_views.append(TableVersionHandle(tbl_version.id, tbl_version.effective_version))
+        # we need a transaction here, if we're not already in one; if this starts a new transaction,
+        # the returned TableVersion instance will not be validated
+        with self.begin_xact(tbl_id=tbl_id, for_write=False) as conn:
+            tv = self._tbl_versions.get((tbl_id, effective_version))
+            if tv is None:
+                tv = self._load_tbl_version(tbl_id, effective_version)
+            elif not tv.is_validated:
+                # only live instances are invalidated
+                assert effective_version is None
+                # we validate live instances by comparing our cached version number to the stored current version
+                # _logger.debug(f'validating metadata for table {tbl_id}:{tv.version} ({id(tv):x})')
+                q = sql.select(schema.Table.md).where(schema.Table.id == tbl_id)
+                row = conn.execute(q).one()
+                current_version = row.md['current_version']
+
+                # the stored version can be behind TableVersion.version, because we don't roll back the in-memory
+                # metadata changes after a failed update operation
+                if current_version != tv.version:
+                    # the cached metadata is invalid
+                    _logger.debug(
+                        f'reloading metadata for table {tbl_id} '
+                        f'(cached version: {tv.version}, current version: {current_version}'
+                        # f', id: {id(tv):x})'
+                    )
+                    tv = self._load_tbl_version(tbl_id, None)
+                else:
+                    # the cached metadata is valid
+                    tv.is_validated = True
+
+            assert tv.is_validated
+            return tv
 
     def remove_tbl_version(self, tbl_version: TableVersion) -> None:
         assert (tbl_version.id, tbl_version.effective_version) in self._tbl_versions
@@ -745,7 +909,7 @@ class Catalog:
         """Return the Dir with the given id, or None if it doesn't exist"""
         conn = Env.get().conn
         if for_update:
-            self._lock_dir(None, dir_id, None)
+            self._acquire_dir_xlock(None, dir_id, None)
         q = sql.select(schema.Dir).where(schema.Dir.id == dir_id)
         row = conn.execute(q).one_or_none()
         if row is None:
@@ -761,7 +925,7 @@ class Catalog:
         conn = Env.get().conn
         if path.is_root:
             if for_update:
-                self._lock_dir(parent_id=None, dir_id=None, dir_name='')
+                self._acquire_dir_xlock(parent_id=None, dir_id=None, dir_name='')
             q = sql.select(schema.Dir).where(schema.Dir.parent_id.is_(None), schema.Dir.md['user'].astext == user)
             row = conn.execute(q).one_or_none()
             return schema.Dir(**row._mapping) if row is not None else None
@@ -770,7 +934,7 @@ class Catalog:
             if parent_dir is None:
                 return None
             if for_update:
-                self._lock_dir(parent_id=parent_dir.id, dir_id=None, dir_name=path.name)
+                self._acquire_dir_xlock(parent_id=parent_dir.id, dir_id=None, dir_name=path.name)
             q = sql.select(schema.Dir).where(
                 schema.Dir.parent_id == parent_dir.id,
                 schema.Dir.md['name'].astext == path.name,
@@ -780,6 +944,7 @@ class Catalog:
             return schema.Dir(**row._mapping) if row is not None else None
 
     def _load_tbl(self, tbl_id: UUID) -> Optional[Table]:
+        """Loads metadata for the table with the given id and caches it."""
         _logger.info(f'Loading table {tbl_id}')
         from .insertable_table import InsertableTable
         from .view import View
@@ -808,8 +973,9 @@ class Catalog:
         if view_md is None:
             # this is a base table
             if (tbl_id, None) not in self._tbl_versions:
-                self._tbl_versions[tbl_id, None] = self._load_tbl_version(tbl_id, None)
+                _ = self._load_tbl_version(tbl_id, None)
             tbl = InsertableTable(tbl_record.dir_id, TableVersionHandle(tbl_id, None))
+            self._tbls[tbl_id] = tbl
             return tbl
 
         # this is a view; determine the sequence of TableVersions to load
@@ -829,18 +995,18 @@ class Catalog:
         view_path: Optional[TableVersionPath] = None
         for id, effective_version in tbl_version_path[::-1]:
             if (id, effective_version) not in self._tbl_versions:
-                self._tbl_versions[id, effective_version] = self._load_tbl_version(id, effective_version)
+                _ = self._load_tbl_version(id, effective_version)
             view_path = TableVersionPath(TableVersionHandle(id, effective_version), base=base_path)
             base_path = view_path
         view = View(tbl_id, tbl_record.dir_id, tbl_md.name, view_path, snapshot_only=pure_snapshot)
-        # TODO: also load mutable views
+        self._tbls[tbl_id] = view
         return view
 
     def load_tbl_md(self, tbl_id: UUID, effective_version: Optional[int]) -> schema.FullTableMd:
         """
         Loads metadata from the store for a given table UUID and version.
         """
-        _logger.info(f'Loading metadata for table version: {tbl_id}:{effective_version}')
+        # _logger.info(f'Loading metadata for table version: {tbl_id}:{effective_version}')
         conn = Env.get().conn
 
         q = (
@@ -915,8 +1081,15 @@ class Catalog:
         If inserting `version_md` or `schema_version_md` would be a primary key violation, an exception will be raised.
         """
         conn = Env.get().conn
+        assert self._in_write_xact
 
         if tbl_md is not None:
+            assert tbl_md.tbl_id == str(tbl_id)
+            if version_md is not None:
+                assert tbl_md.current_version == version_md.version
+                assert tbl_md.current_schema_version == version_md.schema_version
+            if schema_version_md is not None:
+                assert tbl_md.current_schema_version == schema_version_md.schema_version
             result = conn.execute(
                 sql.update(schema.Table.__table__)
                 .values({schema.Table.md: dataclasses.asdict(tbl_md)})
@@ -925,6 +1098,9 @@ class Catalog:
             assert result.rowcount == 1, result.rowcount
 
         if version_md is not None:
+            assert version_md.tbl_id == str(tbl_id)
+            if schema_version_md is not None:
+                assert version_md.schema_version == schema_version_md.schema_version
             conn.execute(
                 sql.insert(schema.TableVersion.__table__).values(
                     tbl_id=tbl_id, version=version_md.version, md=dataclasses.asdict(version_md)
@@ -932,6 +1108,7 @@ class Catalog:
             )
 
         if schema_version_md is not None:
+            assert schema_version_md.tbl_id == str(tbl_id)
             conn.execute(
                 sql.insert(schema.TableSchemaVersion.__table__).values(
                     tbl_id=tbl_id,
@@ -978,50 +1155,60 @@ class Catalog:
         return md
 
     def _load_tbl_version(self, tbl_id: UUID, effective_version: Optional[int]) -> Optional[TableVersion]:
+        """Creates TableVersion instance from stored metadata and registers it in _tbl_versions."""
         tbl_md, _, schema_version_md = self.load_tbl_md(tbl_id, effective_version)
         view_md = tbl_md.view_md
 
-        _logger.info(f'Loading table version: {tbl_id}:{effective_version}')
         conn = Env.get().conn
 
-        # load mutable view ids
-        q = sql.select(schema.Table.id).where(
-            sql.text(
-                f"md->'view_md'->'base_versions'->0->>0 = {tbl_id.hex!r} "
-                "AND md->'view_md'->'base_versions'->0->1 IS NULL"
+        # load mutable view ids for mutable TableVersions
+        mutable_view_ids: list[UUID] = []
+        # If this is a replica, effective_version should not be None. We see this today, because
+        # the replica's TV instance's Column instances contain value_expr_dicts that reference the live version.
+        # This is presumably a source of bugs, because it ignores schema version changes (eg, column renames).
+        # TODO: retarget the value_expr_dict when instantiating Columns for a particular TV instance.
+        if effective_version is None and not tbl_md.is_replica:
+            q = sql.select(schema.Table.id).where(
+                sql.text(
+                    f"md->'view_md'->'base_versions'->0->>0 = {tbl_id.hex!r} "
+                    "AND md->'view_md'->'base_versions'->0->>1 IS NULL"
+                )
             )
-        )
-        mutable_view_ids = [r[0] for r in conn.execute(q).all()]
+            mutable_view_ids = [r[0] for r in conn.execute(q).all()]
         mutable_views = [TableVersionHandle(id, None) for id in mutable_view_ids]
 
+        tbl_version: TableVersion
         if view_md is None:
             # this is a base table
             tbl_version = TableVersion(
                 tbl_id, tbl_md, effective_version, schema_version_md, mutable_views=mutable_views
             )
-            return tbl_version
+        else:
+            assert len(view_md.base_versions) > 0  # a view needs to have a base
+            pure_snapshot = view_md.is_snapshot and view_md.predicate is None and len(schema_version_md.columns) == 0
+            assert not pure_snapshot  # a pure snapshot doesn't have a physical table backing it, no point in loading it
+
+            base: TableVersionHandle
+            base_path: Optional[TableVersionPath] = None  # needed for live view
+            if view_md.is_snapshot:
+                base = TableVersionHandle(UUID(view_md.base_versions[0][0]), view_md.base_versions[0][1])
+            else:
+                base_path = TableVersionPath.from_md(tbl_md.view_md.base_versions)
+                base = base_path.tbl_version
 
-        assert len(view_md.base_versions) > 0  # a view needs to have a base
-        pure_snapshot = view_md.is_snapshot and view_md.predicate is None and len(schema_version_md.columns) == 0
-        assert not pure_snapshot  # a pure snapshot doesn't have a physical table backing it, no point in loading it
+            tbl_version = TableVersion(
+                tbl_id,
+                tbl_md,
+                effective_version,
+                schema_version_md,
+                base_path=base_path,
+                base=base,
+                mutable_views=mutable_views,
+            )
+
+        self._tbl_versions[tbl_id, effective_version] = tbl_version
+        tbl_version.init()
 
-        base: TableVersionHandle
-        base_path: Optional[TableVersionPath] = None  # needed for live view
-        if view_md.is_snapshot:
-            base = TableVersionHandle(UUID(view_md.base_versions[0][0]), view_md.base_versions[0][1])
-        else:
-            base_path = TableVersionPath.from_md(tbl_md.view_md.base_versions)
-            base = base_path.tbl_version
-
-        tbl_version = TableVersion(
-            tbl_id,
-            tbl_md,
-            effective_version,
-            schema_version_md,
-            base_path=base_path,
-            base=base,
-            mutable_views=mutable_views,
-        )
         return tbl_version
 
     def _init_store(self) -> None: