feat(db): initialize only staging tables for processing

components/db/scripts/initialize_processing_tables.py

@@ -3,7 +3,7 @@
 # This file is part of the Pinta.
 # Licensed under the MIT License; see the repository LICENSE file.
 
-"""Materialize the canonical `processing` schema raster tables.
+"""Materialize the canonical `processing` schema staging raster tables.
 
 Meant to be run by CI for maintaining documentation.
 """
@@ -27,12 +27,8 @@
 _TABLE = "dem"
 
 
-def _exists(inspector: sa.Inspector, table_name: str) -> bool:
-    return inspector.has_table(table_name, schema=_SCHEMA)
-
-
 def main() -> None:
-    """Create the canonical processing-schema raster tables if missing."""
+    """Create canonical processing-schema raster staging tables if missing."""
     credentials = db_utils.get_primary_processing_worker_credentials(
         os.environ["DB_PRIMARY_NAME"]
     )
@@ -41,32 +37,35 @@ def main() -> None:
         with sqlmodel.Session(engine) as session:
             inspector = sa.inspect(engine)
 
-            if _exists(inspector, _TABLE):
-                logger.info("%s.%s already exists, skipping", _SCHEMA, _TABLE)
-            else:
-                raster.initialize_raster_table(session, _SCHEMA, _TABLE)
-                logger.info("created %s.%s", _SCHEMA, _TABLE)
+            if not inspector.has_table(_TABLE, schema=_SCHEMA):
+                msg = (
+                    f"{_SCHEMA}.{_TABLE} is missing; main raster tables must "
+                    "come from the template database"
+                )
+                raise SystemExit(msg)
 
-            inspector = sa.inspect(engine)
             overview_names = [
                 raster.OVERVIEW_TABLE_NAME.format(level=level, table_name=_TABLE)
                 for level in raster.DEFAULT_OVERVIEW_LEVELS
             ]
-            existing = [name for name in overview_names if _exists(inspector, name)]
-            if len(existing) == len(overview_names):
-                logger.info(
-                    "all overview tables in %s already exist, skipping", _SCHEMA
-                )
-            elif existing:
+            missing = [
+                name
+                for name in overview_names
+                if not inspector.has_table(name, schema=_SCHEMA)
+            ]
+            if missing:
                 msg = (
-                    f"partial overview tables present in {_SCHEMA} ({existing}); "
-                    "drop them manually before re-running"
+                    f"overview tables missing in {_SCHEMA} ({missing}); main "
+                    "overview tables must come from the template database"
                 )
                 raise SystemExit(msg)
-            else:
-                raster.initialize_overview_tables(session, _SCHEMA, _TABLE)
-                session.commit()
-                logger.info("created overview tables in %s", _SCHEMA)
+
+            raster.initialize_raster_table(session, _SCHEMA, _TABLE)
+            logger.info("initialized staging tables for %s.%s", _SCHEMA, _TABLE)
+
+            raster.initialize_overview_tables(session, _SCHEMA, _TABLE)
+            session.commit()
+            logger.info("initialized overview staging tables in %s", _SCHEMA)
     finally:
         engine.dispose()
 

components/db/src/pinta_db_utils/postgis/raster.py

@@ -44,9 +44,10 @@ def initialize_raster_table(
     staging_tables: int = 1,
     extra_columns: abc.Callable[[], list[sa.Column]] | None = None,
 ) -> None:
-    """Initialize a raster table with optional staging tables.
+    """Initialize staging tables for an existing raster table.
 
-    Creates a main table and staging tables (when specified) with:
+    The main raster table is expected to already exist in the database, usually
+    from the template database. Creates staging tables (when specified) with:
     - rid: serial primary key
     - rast: raster column
     - Additional custom columns (optional)
@@ -60,16 +61,7 @@ def initialize_raster_table(
     TOAST tuple target optimized TOAST chunk size. Staging tables are created as
     UNLOGGED with autovacuum disabled for better performance.
     """
-    table_created = _create_raster_table(
-        session,
-        schema,
-        table_name,
-        extra_columns=extra_columns() if extra_columns else None,
-    )
-    if table_created:
-        constraints.add_raster_constraints(
-            session, schema, table_name, pixel_size=env.DEM_PIXEL_SIZE
-        )
+    _ensure_raster_table_exists(session, schema, table_name)
 
     for i in range(staging_tables):
         staging_name = f"{table_name}_p{i}"
@@ -94,27 +86,20 @@ def initialize_overview_tables(
     table_name: str,
     staging_tables: int = 1,
 ) -> None:
-    """Initialize, register and index overview tables with optional staging tables.
+    """Initialize staging tables for existing overview tables.
 
-    Creates a main table and staging tables with:
+    The main overview tables are expected to already exist in the database,
+    usually from the template database. Creates staging tables with:
     - rid: serial primary key
     - rast: raster column
-
-    The main overview tables are also registered against the reference raster
-    table with PostGIS overview constraints and receive raster envelope indexes.
     """
+    _ensure_raster_table_exists(session, schema, table_name)
     for level in DEFAULT_OVERVIEW_LEVELS:
         overview_name = OVERVIEW_TABLE_NAME.format(level=level, table_name=table_name)
-        table_created = _create_raster_table(
-            session,
-            schema,
-            overview_name,
-        )
-        if table_created:
-            constraints.add_raster_constraints(
-                session, schema, overview_name, pixel_size=env.DEM_PIXEL_SIZE * level
-            )
+        _ensure_raster_table_exists(session, schema, overview_name)
 
+    for level in DEFAULT_OVERVIEW_LEVELS:
+        overview_name = OVERVIEW_TABLE_NAME.format(level=level, table_name=table_name)
         for i in range(staging_tables):
             staging_name = f"{overview_name}_p{i}"
             _create_raster_table(
@@ -127,8 +112,6 @@ def initialize_overview_tables(
                 session, schema, staging_name, pixel_size=env.DEM_PIXEL_SIZE * level
             )
 
-        _register_overview_table(session, schema, table_name, overview_name, level)
-        _create_raster_index(session, schema, overview_name)
         session.commit()
 
 
@@ -334,6 +317,24 @@ def _create_raster_table(
     return True
 
 
+def _ensure_raster_table_exists(
+    session: sqlmodel.Session,
+    schema: str,
+    table_name: str,
+) -> None:
+    """Raise if a raster table expected from the template database is missing."""
+    inspector = sa.inspect(session.connection())
+    if inspector.has_table(table_name, schema=schema):
+        return
+
+    msg = (
+        f"Expected raster table {schema}.{table_name} to exist in the database. "
+        "Main raster tables must be created by the template database; "
+        "initialization only creates staging tables."
+    )
+    raise ValueError(msg)
+
+
 def _create_raster_index(
     session: sqlmodel.Session,
     schema: str,