From 0ca1e58b0f5155e5ec5439bde009c7150058616d Mon Sep 17 00:00:00 2001
From: Eddie A Tejeda <669988+eddietejeda@users.noreply.github.com>
Date: Wed, 9 Sep 2026 19:55:40 -0700
Subject: [PATCH 1/2] docs: fix three stale README claims

- Requirements named hotdata >=0.7,<0.9; pyproject pins >=0.9.0,<0.10
- "Table names must be declared when the database is created" is no
  longer true: the loads endpoint creates an undeclared table
  automatically ("declaring tables up front is optional" per the API
  spec), and create_table calls it with no client-side check
- The existing-sources example passed "my_postgres" where a connection
  id belongs: list_catalogs() returns connection ids (c["id"]), and
  list_databases/list_tables filter by that id, so a display name
  matches nothing
---
 README.md | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 33b616d..33815ba 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 Use [Ibis](https://ibis-project.org/) to create on-demand databases, upload data, and query with Python expressions — get pandas or Arrow results back without writing SQL.
 
-**Requirements:** Python 3.10+, **ibis-framework** ≥12,<13, **hotdata** ≥0.7,<0.9.
+**Requirements:** Python 3.10+, **ibis-framework** ≥12,<13, **hotdata** ≥0.9,<0.10.
 
 ## Install
 
@@ -112,7 +112,7 @@ con.create_table(
 )
 ```
 
-Table names must be declared when the database is created — you cannot upload to a table name that was not listed in `tables=`.
+Declaring table names in `tables=` is optional — loading into a table that was not declared creates it automatically as part of the load.
 
 ### Query
 
@@ -241,19 +241,21 @@ con = ibis.hotdata.connect(
     api_url="https://api.hotdata.dev",
     token="YOUR_API_KEY",
     workspace_id="ws_...",
-    default_connection="my_postgres",
+    default_connection="<connection_id>",  # a connection id, from con.list_catalogs()
     default_schema="public",
 )
 
-t = con.table("orders")  # resolves to my_postgres.public.orders
+t = con.table("orders")  # resolves to <connection_id>.public.orders
 ```
 
-Discover what's available:
+Discover what's available. Catalogs are connection **ids** — the `id` field of the
+workspace's connections, as returned by `list_catalogs()` — not display names:
 
 ```python
-con.list_catalogs()                                    # connection IDs
-con.list_databases(catalog="my_postgres")              # schemas
-con.list_tables(database=("my_postgres", "public"))    # tables
+con.list_catalogs()                                # connection ids
+conn_id = con.list_catalogs()[0]
+con.list_databases(catalog=conn_id)                # schemas
+con.list_tables(database=(conn_id, "public"))      # tables
 ```
 
 ## What's supported

From fa6cd132c5a9007b2b4a219823cd97f4b4ff6319 Mon Sep 17 00:00:00 2001
From: Eddie A Tejeda <669988+eddietejeda@users.noreply.github.com>
Date: Wed, 9 Sep 2026 19:59:03 -0700
Subject: [PATCH 2/2] docs: create_table docstring no longer implies the table
 must be declared

Same staleness the README fix corrects: the loads endpoint creates an
undeclared table automatically, so 'declared managed table' overstates
the precondition.
---
 src/ibis_hotdata/backend.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/ibis_hotdata/backend.py b/src/ibis_hotdata/backend.py
index 24e7725..83ab5f8 100644
--- a/src/ibis_hotdata/backend.py
+++ b/src/ibis_hotdata/backend.py
@@ -663,7 +663,10 @@ def create_table(
         temp: bool = False,
         overwrite: bool = False,
     ) -> ir.Table:
-        """Upload local data into a declared managed table.
+        """Upload local data into a managed table.
+
+        The table does not have to be declared in advance: loading into an
+        undeclared table creates it automatically as part of the load.
 
         ``database``'s first element must be the instant database id returned
         by ``create_database``, not its display name — Hotdata database names