feat: switch managed databases to /databases API (hotdata>=0.2.3)

- Use DatabasesApi instead of ConnectionsApi for all managed database ops
- Rename create_managed_database first param from name to description (kw-only)
- Add expires_at param to create_managed_database
- ManagedDatabase: replace name/source_type with description/default_connection_id
- resolve_managed_database: ID lookup first, description scan as fallback
- list_managed_databases: fetch all databases, no source_type filter
- list_managed_tables, load_managed_table, delete_managed_table: use default_connection_id
- Remove MANAGED_SOURCE_TYPE, build_managed_config, create_connection_request from public API

Author: eddietejeda

CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-05-24
+
+### Changed
+
+- Switch managed database operations from the connections API to the dedicated `/databases` API (`hotdata>=0.2.3` required).
+- `create_managed_database` first parameter renamed from `name` to `description` (keyword-only).
+- `ManagedDatabase` dataclass: replace `name`/`source_type` fields with `description`/`default_connection_id`.
+- `resolve_managed_database` tries direct ID lookup first, then falls back to a description scan.
+- `list_managed_databases` now fetches all databases regardless of source type.
+- `list_managed_tables`, `load_managed_table`, and `delete_managed_table` use `default_connection_id` instead of database `id` for connection-scoped operations.
+
+### Added
+
+- `create_managed_database` accepts an optional `expires_at` parameter.
+
+### Removed
+
+- `MANAGED_SOURCE_TYPE`, `build_managed_config`, and `create_connection_request` removed from the public API.
+
 ## [0.1.1] - 2026-05-19
 
 ### Added

CONTRACT.md

@@ -33,10 +33,7 @@ The supported import surface is:
 - `ManagedDatabase`
 - `ManagedTable`
 - `LoadManagedTableResult`
-- `MANAGED_SOURCE_TYPE`
 - `DEFAULT_SCHEMA`
-- `build_managed_config`
-- `create_connection_request`
 - `is_parquet_path`
 
 Adapters should import from `hotdata_runtime` and treat this surface as the stable API.
@@ -58,10 +55,10 @@ Adapters should import from `hotdata_runtime` and treat this surface as the stab
 - `columns_for_qualified(qualified, connection_id=...)` resolves table columns, and
   adapters should pass `connection_id` when known.
 - `uploads()` returns the uploads API wrapper for parquet staging.
-- `list_managed_databases()` returns managed-catalog connections (`source_type: managed`).
-- `resolve_managed_database(name_or_id)` resolves a managed database by name or id.
-- `create_managed_database(name, schema=..., tables=...)` creates a managed database and optionally declares tables up front.
-- `delete_managed_database(name_or_id)` deletes a managed database connection.
+- `list_managed_databases()` returns all databases via the `/databases` API.
+- `resolve_managed_database(name_or_id)` resolves a database by id (direct lookup) or description (list scan).
+- `create_managed_database(description=..., schema=..., tables=..., expires_at=...)` creates a database via the `/databases` API and optionally declares tables up front.
+- `delete_managed_database(name_or_id)` deletes a database via the `/databases` API.
 - `list_managed_tables(database, schema=...)` lists tables in a managed database.
 - `upload_parquet(path)` uploads a local parquet file and returns an upload id.
 - `load_managed_table(database, table, schema=..., upload_id=..., file=...)` publishes parquet data into a declared managed table.

hotdata_runtime/__init__.py

@@ -13,9 +13,6 @@
     LoadManagedTableResult,
     ManagedDatabase,
     ManagedTable,
-    MANAGED_SOURCE_TYPE,
-    build_managed_config,
-    create_connection_request,
     is_parquet_path,
 )
 from hotdata_runtime.env import (
@@ -42,12 +39,9 @@
     "DEFAULT_SCHEMA",
     "HotdataClient",
     "LoadManagedTableResult",
-    "MANAGED_SOURCE_TYPE",
     "ManagedDatabase",
     "ManagedTable",
     "QueryResult",
-    "build_managed_config",
-    "create_connection_request",
     "is_parquet_path",
     "workspace_health_lines",
     "default_api_key",

hotdata_runtime/client.py

@@ -9,16 +9,20 @@
 
 from hotdata import ApiClient, Configuration
 from hotdata.api.connections_api import ConnectionsApi
+from hotdata.api.databases_api import DatabasesApi
 from hotdata.api.information_schema_api import InformationSchemaApi
 from hotdata.api.query_api import QueryApi
 from hotdata.api.query_runs_api import QueryRunsApi
 from hotdata.api.results_api import ResultsApi
 from hotdata.api.uploads_api import UploadsApi
 from hotdata.exceptions import ApiException
 from hotdata.models.async_query_response import AsyncQueryResponse
+from hotdata.models.create_database_request import CreateDatabaseRequest
+from hotdata.models.database_default_schema_decl import DatabaseDefaultSchemaDecl
+from hotdata.models.database_default_table_decl import DatabaseDefaultTableDecl
+from hotdata.models.load_managed_table_request import LoadManagedTableRequest
 from hotdata.models.query_request import QueryRequest
 from hotdata.models.query_response import QueryResponse
-from hotdata.models.load_managed_table_request import LoadManagedTableRequest
 from hotdata.models.table_info import TableInfo
 
 from hotdata_runtime.env import (
@@ -33,11 +37,9 @@
     LoadManagedTableResult,
     ManagedDatabase,
     ManagedTable,
-    MANAGED_SOURCE_TYPE,
     api_error_message,
-    create_connection_request,
     is_parquet_path,
-    managed_database_from_connection,
+    managed_database_from_detail,
 )
 from hotdata_runtime.http import default_http_retries
 from hotdata_runtime.result import QueryResult
@@ -130,6 +132,9 @@ def __exit__(self, *args: object) -> None:
     def connections(self) -> ConnectionsApi:
         return ConnectionsApi(self._api)
 
+    def _databases_api(self) -> DatabasesApi:
+        return DatabasesApi(self._api)
+
     def _information_schema(self) -> InformationSchemaApi:
         return InformationSchemaApi(self._api)
 
@@ -152,47 +157,71 @@ def uploads(self) -> UploadsApi:
         return UploadsApi(self._api)
 
     def list_managed_databases(self) -> list[ManagedDatabase]:
-        listing = self.connections().list_connections()
-        return [
-            managed_database_from_connection(c)
-            for c in listing.connections
-            if c.source_type == MANAGED_SOURCE_TYPE
-        ]
+        listing = self._databases_api().list_databases()
+        result: list[ManagedDatabase] = []
+        for summary in listing.databases:
+            try:
+                detail = self._databases_api().get_database(summary.id)
+                result.append(managed_database_from_detail(detail))
+            except ApiException:
+                pass
+        return result
 
     def resolve_managed_database(self, name_or_id: str) -> ManagedDatabase:
-        listing = self.connections().list_connections()
-        match = None
-        for c in listing.connections:
-            if c.id == name_or_id or c.name == name_or_id:
-                match = c
+        # Try direct ID lookup first
+        try:
+            detail = self._databases_api().get_database(name_or_id)
+            return managed_database_from_detail(detail)
+        except ApiException as e:
+            if e.status != 404:
+                raise RuntimeError(api_error_message(e)) from e
+
+        # Fall back to description-based lookup
+        listing = self._databases_api().list_databases()
+        match_id: str | None = None
+        for db in listing.databases:
+            if db.description == name_or_id:
+                match_id = db.id
                 break
-        if match is None:
+        if match_id is None:
             raise KeyError(f"No database named or with id {name_or_id!r}")
-        if match.source_type != MANAGED_SOURCE_TYPE:
-            raise ValueError(
-                f"{match.name!r} is not a managed database "
-                f"(source_type: {match.source_type})"
-            )
-        return managed_database_from_connection(match)
+        try:
+            detail = self._databases_api().get_database(match_id)
+        except ApiException as e:
+            raise RuntimeError(api_error_message(e)) from e
+        return managed_database_from_detail(detail)
 
     def create_managed_database(
         self,
-        name: str,
+        description: str | None = None,
         *,
         schema: str = DEFAULT_SCHEMA,
         tables: list[str] | None = None,
+        expires_at: str | None = None,
     ) -> ManagedDatabase:
-        request = create_connection_request(name, schema=schema, tables=tables)
+        schemas = None
+        if tables:
+            schemas = [
+                DatabaseDefaultSchemaDecl(
+                    name=schema,
+                    tables=[DatabaseDefaultTableDecl(name=t) for t in tables],
+                )
+            ]
+        request = CreateDatabaseRequest(
+            description=description,
+            schemas=schemas,
+            expires_at=expires_at,
+        )
         try:
-            created = self.connections().create_connection(request)
+            created = self._databases_api().create_database(request)
         except ApiException as e:
             raise RuntimeError(api_error_message(e)) from e
-        return managed_database_from_connection(created)
+        return managed_database_from_detail(created)
 
     def delete_managed_database(self, name_or_id: str) -> None:
         db = self.resolve_managed_database(name_or_id)
         try:
-            self.connections().delete_connection(db.id)
+            self._databases_api().delete_database(db.id)
         except ApiException as e:
             raise RuntimeError(api_error_message(e)) from e
 
@@ -204,12 +233,12 @@ def list_managed_tables(
     ) -> list[ManagedTable]:
         db = self.resolve_managed_database(database)
         rows: list[ManagedTable] = []
-        for t in self.iter_tables(connection_id=db.id):
+        for t in self.iter_tables(connection_id=db.default_connection_id):
             if schema is not None and t.var_schema != schema:
                 continue
             rows.append(
                 ManagedTable(
-                    full_name=f"{db.name}.{t.var_schema}.{t.table}",
+                    full_name=f"{db.id}.{t.var_schema}.{t.table}",
                     schema=t.var_schema,
                     table=t.table,
                     synced=t.synced,
@@ -258,7 +287,7 @@ def load_managed_table(
         )
         try:
             loaded = self.connections().load_managed_table(
-                db.id,
+                db.default_connection_id,
                 schema,
                 table,
                 request,
@@ -270,7 +299,7 @@ def load_managed_table(
             schema_name=loaded.schema_name,
             table_name=loaded.table_name,
             row_count=loaded.row_count,
-            full_name=f"{db.name}.{loaded.schema_name}.{loaded.table_name}",
+            full_name=f"{db.id}.{loaded.schema_name}.{loaded.table_name}",
         )
 
     def delete_managed_table(
@@ -282,7 +311,7 @@ def delete_managed_table(
     ) -> None:
         db = self.resolve_managed_database(database)
         try:
-            self.connections().delete_managed_table(db.id, schema, table)
+            self.connections().delete_managed_table(db.default_connection_id, schema, table)
         except ApiException as e:
             raise RuntimeError(api_error_message(e)) from e
 

hotdata_runtime/databases.py

@@ -7,17 +7,15 @@
 from typing import Any
 
 from hotdata.exceptions import ApiException
-from hotdata.models.create_connection_request import CreateConnectionRequest
 
-MANAGED_SOURCE_TYPE = "managed"
 DEFAULT_SCHEMA = "public"
 
 
 @dataclass(frozen=True)
 class ManagedDatabase:
     id: str
-    name: str
-    source_type: str
+    description: str | None
+    default_connection_id: str
 
     def to_dict(self) -> dict[str, Any]:
         return asdict(self)
@@ -51,39 +49,11 @@ def is_parquet_path(path: str) -> bool:
     return Path(path).suffix.lower() == ".parquet"
 
 
-def build_managed_config(schema: str, tables: list[str]) -> dict[str, Any]:
-    if not tables:
-        return {}
-    return {
-        "schemas": [
-            {
-                "name": schema,
-                "tables": [{"name": table} for table in tables],
-            }
-        ]
-    }
-
-
-def create_connection_request(
-    name: str,
-    *,
-    schema: str = DEFAULT_SCHEMA,
-    tables: list[str] | None = None,
-) -> CreateConnectionRequest:
-    table_list = tables or []
-    return CreateConnectionRequest(
-        name=name,
-        source_type=MANAGED_SOURCE_TYPE,
-        config=build_managed_config(schema, table_list),
-        skip_discovery=True,
-    )
-
-
-def managed_database_from_connection(conn: Any) -> ManagedDatabase:
+def managed_database_from_detail(detail: Any) -> ManagedDatabase:
     return ManagedDatabase(
-        id=str(conn.id),
-        name=str(conn.name),
-        source_type=str(conn.source_type),
+        id=str(detail.id),
+        description=detail.description,
+        default_connection_id=str(detail.default_connection_id),
     )
 
 

pyproject.toml

@@ -10,7 +10,7 @@ readme = "README.md"
 requires-python = ">=3.10"
 license = { text = "MIT" }
 dependencies = [
-  "hotdata>=0.2.0",
+  "hotdata>=0.2.3",
   "pandas>=2.0",
 ]
 

tests/test_contract.py

@@ -14,12 +14,9 @@ def test_public_exports_contract():
         "DEFAULT_SCHEMA",
         "HotdataClient",
         "LoadManagedTableResult",
-        "MANAGED_SOURCE_TYPE",
         "ManagedDatabase",
         "ManagedTable",
         "QueryResult",
-        "build_managed_config",
-        "create_connection_request",
         "is_parquet_path",
         "workspace_health_lines",
         "default_api_key",