refactor: PostgresCatalogSettings, simpler pg_get_collection_index and backend-specific geometry literal hooks

CHANGES.md

@@ -11,17 +11,21 @@ Note: Minor version `0.X.0` update might break the API, It's recommended to pin
 * change: move PostgreSQL-specific code into a new `tipg.pg` submodule **breaking change**
     * `tipg.collections.PgCollection` and `tipg.collections.pg_get_collection_index` → `tipg.pg.collections`
     * `tipg.database` → `tipg.pg.database` (`connect_to_db`, `close_db_connection`)
-    * `tipg.settings.PostgresSettings`, `DatabaseSettings` and `CustomSQLSettings` → `tipg.pg.settings`
+    * `tipg.settings.PostgresSettings` and `CustomSQLSettings` → `tipg.pg.settings`
+    * `tipg.settings.DatabaseSettings` → `tipg.pg.settings.PostgresCatalogSettings` (renamed, still using the `TIPG_DB_` env prefix)
     * `tipg/sql/dbcatalog.sql` → `tipg/pg/sql/dbcatalog.sql`
-    * `connect_to_db`, `close_db_connection`, `pg_get_collection_index`, `PostgresSettings`, `DatabaseSettings` and `CustomSQLSettings` are re-exported from `tipg.pg`
+    * `connect_to_db`, `close_db_connection`, `pg_get_collection_index`, `PostgresSettings`, `PostgresCatalogSettings` and `CustomSQLSettings` are re-exported from `tipg.pg`
 * change: add required `connection_pool: asyncpg.Pool` attribute to `PgCollection` (reference to the shared pool, excluded from serialization) **breaking change**
 * change: remove the `conn` positional argument from `PgCollection.features()` and `PgCollection.get_tile()`: collections now acquire their own connection **breaking change**
-* change: add required `connection_pool` keyword argument to `tipg.pg.collections.pg_get_collection_index` **breaking change**
-* change: move `register_collection_catalog` from `tipg.pg.collections` to `tipg.main` (the catalog is no longer PG-specific) **breaking change**
+* change: update `tipg.pg.collections.pg_get_collection_index` signature to `pg_get_collection_index(*, connection_pool: asyncpg.Pool, settings: PostgresCatalogSettings | None = None)`: it acquires a connection from the pool instead of taking an `asyncpg.Connection` **breaking change**
+* change: move `register_collection_catalog` from `tipg.pg.collections` to `tipg.main` (the catalog is no longer PG-specific) and replace its `db_settings` option with a required `catalog_settings: PostgresCatalogSettings` argument **breaking change**
 * perf: compute datetime extents with `min(col)::timestamptz` / `max(col)::timestamptz` instead of casting each value before aggregating, so btree indexes on `timestamp` / `date` columns are used instead of a full table scan on every catalog refresh
 * perf: use `ST_EstimatedExtent` for spatial extents whenever table statistics exist.
 * perf: cache `Collection.extent`, `bounds`, `dt_bounds`, `geometry_columns` and `datetime_columns` (`functools.cached_property`) instead of recomputing them on every access
 * perf: skip SQL statement formatting in `tipg.pg.collections.debug_query` when `DEBUG` logging is disabled
+* change: add `Collection._tag_geometry_literal` and `Collection._reproject_geometry_literal` abstract methods, defining how CQL2/bbox geometry literals are tagged with, or reprojected to, the geometry column CRS for each backend **breaking change** (custom `Collection` subclasses must implement them)
+* change: move `_quote_ident` from `tipg.pg.collections` to `tipg.collections`
+* docs: update the `examples/non_app_usage.ipynb` notebook for the new `tipg.pg` API
 
 ## [1.6.1] - 2026-09-03
 

docs/src/advanced/customization.md

@@ -14,7 +14,7 @@ from tipg.collections import Catalog
 from tipg.errors import DEFAULT_STATUS_CODES, add_exception_handlers
 from tipg.factory import OGCFeaturesFactory
 from tipg.pg import (
-    DatabaseSettings,
+    PostgresCatalogSettings,
     PostgresSettings,
     close_db_connection,
     connect_to_db,
@@ -26,15 +26,13 @@ from fastapi import FastAPI
 
 async def register_collection_catalog(
     app: FastAPI,
-    db_settings: DatabaseSettings | None = None,
+    catalog_settings: PostgresCatalogSettings | None = None,
 ) -> None:
     """Register Collection catalog."""
-    async with app.state.pool.acquire() as conn:
-        collections = await pg_get_collection_index(
-            conn,
-            settings=db_settings,
-            connection_pool=app.state.pool,
-        )
+    collections = await pg_get_collection_index(
+        connection_pool=app.state.pool,
+        settings=catalog_settings,
+    )
 
     app.state.collection_catalog = Catalog(
         collections={col.id: col for col in collections},
@@ -59,7 +57,10 @@ async def lifespan(app: FastAPI):
     )
     await register_collection_catalog(
         app,
-        db_settings=DatabaseSettings(schemas=["public"], application_schema="pg_temp"),
+        catalog_settings=PostgresCatalogSettings(
+            schemas=["public"],
+            application_schema="pg_temp",
+        ),
     )
 
     yield
@@ -116,10 +117,10 @@ In [`eoAPI`](https://github.com/developmentseed/eoAPI), we use a custom logo by
 
 `Functions` will be either found by `tipg` at startup within the specified schemas or by registering them dynamically to the [`pg_temp`](https://www.postgresql.org/docs/current/runtime-config-client.html) schema when creating the [Database connection](https://github.com/developmentseed/tipg/blob/2543707238a97a0527effff710a83f9bea66440f/tipg/db.py#L63-L65).
 
-To `register` custom SQL functions, user can set `TIPG_CUSTOM_SQL_DIRECTORY` environment variable when using `tipg` demo application or set `user_sql_files` option in [tipg.db.connect_to_db](https://github.com/developmentseed/tipg/blob/2543707238a97a0527effff710a83f9bea66440f/tipg/main.py#L90-L109).
+To `register` custom SQL functions, user can set `TIPG_CUSTOM_SQL_DIRECTORY` environment variable when using `tipg` demo application or set `user_sql_files` option in `tipg.pg.connect_to_db`.
 
 ```python
-from tipg.pg import DatabaseSettings, PostgresSettings, connect_to_db
+from tipg.pg import PostgresCatalogSettings, PostgresSettings, connect_to_db
 
 # `register_collection_catalog` defined as in the "Application" example above
 
@@ -139,7 +140,7 @@ async def startup_event() -> None:
     )
     await register_collection_catalog(
         app,
-        db_settings=DatabaseSettings(
+        catalog_settings=PostgresCatalogSettings(
             schemas=["public"],
             exclude_function_schemas=["public"],
         ),

docs/src/advanced/ogc_features_server.md

@@ -17,7 +17,7 @@ from tipg.factory import OGCFeaturesFactory
 from tipg.middleware import CacheControlMiddleware, CatalogUpdateMiddleware
 from tipg.pg import (
     CustomSQLSettings,
-    DatabaseSettings,
+    PostgresCatalogSettings,
     PostgresSettings,
     close_db_connection,
     connect_to_db,
@@ -31,21 +31,19 @@ from starlette.templating import Jinja2Templates
 from starlette_cramjam.middleware import CompressionMiddleware
 
 postgres_settings = PostgresSettings()
-db_settings = DatabaseSettings()
+postgres_catalog_settings = PostgresCatalogSettings()
 custom_sql_settings = CustomSQLSettings()
 
 
 async def register_collection_catalog(
     app: FastAPI,
-    db_settings: DatabaseSettings | None = None,
+    catalog_settings: PostgresCatalogSettings | None = None,
 ) -> None:
     """Register Collection catalog."""
-    async with app.state.pool.acquire() as conn:
-        collections = await pg_get_collection_index(
-            conn,
-            settings=db_settings,
-            connection_pool=app.state.pool,
-        )
+    collections = await pg_get_collection_index(
+        connection_pool=app.state.pool,
+        settings=catalog_settings,
+    )
 
     app.state.collection_catalog = Catalog(
         collections={col.id: col for col in collections},
@@ -60,12 +58,12 @@ async def lifespan(app: FastAPI):
     await connect_to_db(
         app,
         settings=postgres_settings,
-        schemas=db_settings.schemas,
+        schemas=postgres_catalog_settings.schemas,
         user_sql_files=custom_sql_settings.sql_files,
     )
 
     # Register Collection Catalog
-    await register_collection_catalog(app, db_settings=db_settings)
+    await register_collection_catalog(app, catalog_settings=postgres_catalog_settings)
 
     yield
 
@@ -106,7 +104,7 @@ app.add_middleware(
     CatalogUpdateMiddleware,
     func=register_collection_catalog,
     ttl=300,
-    db_settings=db_settings,
+    catalog_settings=postgres_catalog_settings,
 )
 
 add_exception_handlers(app, DEFAULT_STATUS_CODES)

docs/src/advanced/ogc_tiles_server.md

@@ -17,7 +17,7 @@ from tipg.factory import OGCTilesFactory
 from tipg.middleware import CacheControlMiddleware, CatalogUpdateMiddleware
 from tipg.pg import (
     CustomSQLSettings,
-    DatabaseSettings,
+    PostgresCatalogSettings,
     PostgresSettings,
     close_db_connection,
     connect_to_db,
@@ -31,21 +31,19 @@ from starlette.templating import Jinja2Templates
 from starlette_cramjam.middleware import CompressionMiddleware
 
 postgres_settings = PostgresSettings()
-db_settings = DatabaseSettings()
+postgres_catalog_settings = PostgresCatalogSettings()
 custom_sql_settings = CustomSQLSettings()
 
 
 async def register_collection_catalog(
     app: FastAPI,
-    db_settings: DatabaseSettings | None = None,
+    catalog_settings: PostgresCatalogSettings | None = None,
 ) -> None:
     """Register Collection catalog."""
-    async with app.state.pool.acquire() as conn:
-        collections = await pg_get_collection_index(
-            conn,
-            settings=db_settings,
-            connection_pool=app.state.pool,
-        )
+    collections = await pg_get_collection_index(
+        connection_pool=app.state.pool,
+        settings=catalog_settings,
+    )
 
     app.state.collection_catalog = Catalog(
         collections={col.id: col for col in collections},
@@ -60,14 +58,14 @@ async def lifespan(app: FastAPI):
     await connect_to_db(
         app,
         settings=postgres_settings,
-        schemas=db_settings.schemas,
+        schemas=postgres_catalog_settings.schemas,
         user_sql_files=custom_sql_settings.sql_files,
     )
 
     # Register Collection Catalog
     await register_collection_catalog(
         app,
-        db_settings=db_settings,
+        catalog_settings=postgres_catalog_settings,
     )
 
     yield
@@ -110,7 +108,7 @@ app.add_middleware(
     CatalogUpdateMiddleware,
     func=register_collection_catalog,
     ttl=300,
-    db_settings=db_settings,
+    catalog_settings=postgres_catalog_settings,
 )
 
 add_exception_handlers(app, DEFAULT_STATUS_CODES)

docs/src/api/tipg/pg/collections.md

@@ -1 +1 @@
-::: tipg.collections
+::: tipg.pg.collections

docs/src/api/tipg/pg/database.md

@@ -1 +1 @@
-::: tipg.collections
+::: tipg.pg.database

docs/src/api/tipg/pg/settings.md

@@ -1 +1 @@
-::: tipg.collections
+::: tipg.pg.settings

docs/src/user_guide/configuration.md

@@ -5,7 +5,7 @@ Example of `.env` file can be found in [.env.example](https://github.com/develop
 
 ## DB connection settings
 
-class: `tipg.settings.PostgresSettings`
+class: `tipg.pg.settings.PostgresSettings`
 
 #### Database address
 
@@ -45,7 +45,7 @@ ref: https://magicstack.github.io/asyncpg/current/api/index.html#connection-pool
 
 ## DB visibility settings
 
-class: `tipg.settings.DatabaseSettings`
+class: `tipg.pg.settings.PostgresCatalogSettings`
 
 prefix: **`TIPG_DB_`**
 
@@ -94,7 +94,7 @@ TIPG_TABLE_CONFIG__pgstac_items__PK=id
 
 `TiPG` allows for exposing custom `SQL Functions` as collections (see https://developmentseed.org/tipg/advanced/functions/)
 
-class: `tipg.settings.CustomSQLSettings`
+class: `tipg.pg.settings.CustomSQLSettings`
 
 prefix: **`TIPG_`**