feat(snowflake)!: account objects as statements, and one table's storage facts

.claude/code_style.md

@@ -630,7 +630,7 @@ class DefaultCustomTimestampMixin(CustomTimestampMixin):
 
 1. **Proper Inheritance**:
    - All expression classes must inherit from `BaseExpression`
-   - Value expressions inherit from `SQLValueExpression`
+   - Value expressions inherit from `SQLValue`
    - Predicate expressions inherit from `SQLPredicate`
    - Use appropriate mixins for functionality (e.g., `ArithmeticMixin`, `ComparisonMixin`)
 
@@ -691,7 +691,7 @@ from . import bases, mixins
 if TYPE_CHECKING:  # pragma: no cover
     from ..dialect import SQLDialectBase
 
-class MyExpression(mixins.ArithmeticMixin, mixins.ComparisonMixin, bases.SQLValueExpression):
+class MyExpression(mixins.ArithmeticMixin, mixins.ComparisonMixin, bases.SQLValue):
     """Represents a custom SQL expression."""
     def __init__(self, dialect: "SQLDialectBase", value: str):
         super().__init__(dialect)

.github/workflows/test.yml

@@ -34,14 +34,21 @@ jobs:
           pip install -r requirements.txt
           pip install -r requirements-dev.txt
           pip install git+https://github.com/rhosocial/python-activerecord.git@release/v1.0.0.dev30#egg=rhosocial-activerecord
-          pip install git+https://github.com/rhosocial/python-activerecord-testsuite.git@release/v1.0.0.dev17#egg=rhosocial-activerecord-testsuite
+          pip install git+https://github.com/rhosocial/python-activerecord-testsuite.git@fix/column-constraint-gates#egg=rhosocial-activerecord-testsuite
 
       - name: Install package
         run: |
           pip install -e . --no-deps
 
       - name: Run tests with coverage (unit only, no Snowflake instance)
+        # PYTHONPATH=src:tests puts the repository-local plugin
+        # (``-p plugins.expression_xdist``, registered in pyproject.toml) and
+        # the scenario providers on the path. pytest resolves ``-p`` before the
+        # ``pythonpath`` ini option is applied on older 8.x releases, so the
+        # environment variable -- which is how the sibling backends do it --
+        # is the reliable spelling rather than a second path mechanism.
         run: |
+          export PYTHONPATH=src:tests
           pytest tests/ -k "not integration" --ignore=tests/snowflake_fakesnow --tb=short
           coverage run --source=src -m pytest tests/ -k "not integration" --ignore=tests/snowflake_fakesnow --tb=short
           coverage xml
@@ -78,14 +85,15 @@ jobs:
           pip install -r requirements.txt
           pip install -r requirements-dev.txt
           pip install git+https://github.com/rhosocial/python-activerecord.git@release/v1.0.0.dev30#egg=rhosocial-activerecord
-          pip install git+https://github.com/rhosocial/python-activerecord-testsuite.git@release/v1.0.0.dev17#egg=rhosocial-activerecord-testsuite
+          pip install git+https://github.com/rhosocial/python-activerecord-testsuite.git@fix/column-constraint-gates#egg=rhosocial-activerecord-testsuite
 
       - name: Install package
         run: |
           pip install -e . --no-deps
 
       - name: Run tests (unit only, no Snowflake instance)
         run: |
+          export PYTHONPATH=src:tests
           pytest tests/ -k "not integration" --ignore=tests/snowflake_fakesnow --tb=short
 
   test-free-threaded:
@@ -110,12 +118,13 @@ jobs:
           pip install -r requirements.txt
           pip install -r requirements-dev.txt
           pip install git+https://github.com/rhosocial/python-activerecord.git@release/v1.0.0.dev30#egg=rhosocial-activerecord
-          pip install git+https://github.com/rhosocial/python-activerecord-testsuite.git@release/v1.0.0.dev17#egg=rhosocial-activerecord-testsuite
+          pip install git+https://github.com/rhosocial/python-activerecord-testsuite.git@fix/column-constraint-gates#egg=rhosocial-activerecord-testsuite
 
       - name: Install package
         run: |
           pip install -e . --no-deps
 
       - name: Run tests (unit only, no Snowflake instance)
         run: |
+          export PYTHONPATH=src:tests
           pytest tests/ -k "not integration" --ignore=tests/snowflake_fakesnow --tb=short

.gitignore

@@ -157,3 +157,8 @@ tests/config/snowflake_scenarios.yml
 
 # Integration tests (contain local development paths and credentials)
 tests/rhosocial/activerecord_snowflake_test/feature/backend/test_backend_integration.py
+# Worktrees for feature/* and fix/* branches. Never tracked: a `git add -A`
+# from the repo root would commit each branch's whole toolchain -- the venv, the
+# build directory and the test artifacts -- and the directory disappears when the
+# branch merges, so the history would keep a second copy of the source tree.
+.worktree/

CLAUDE.md

@@ -41,6 +41,7 @@ This project is under active development. Key features implemented:
 - **pyformat placeholders**: `%s` style (snowflake-connector-python uses pyformat)
 - **PAT authentication**: Programmatic Access Tokens (JWT) for CI/automation
 - **Warehouse lifecycle**: Virtual warehouses auto-suspend; consider `client_session_keep_alive=True`
+- **No `status` subcommand**: this backend has no status introspector (no `AbstractStatusIntrospector` implementation under `introspection/`), so the CLI command list has no `status` — that is an accurate reflection of the library, not a missing wire-up. `info` covers the version and the protocol/capability matrix. If the backends are ever aligned on `status`, the library implementation comes first.
 
 ## Version Control and Changelog
 

README.md

@@ -52,12 +52,12 @@ from typing import ClassVar, Optional
 from rhosocial.activerecord.base import FieldProxy
 from rhosocial.activerecord.backend.impl.snowflake.backend import SnowflakeBackend
 from rhosocial.activerecord.backend.impl.snowflake.config import SnowflakeConnectionConfig
-from rhosocial.activerecord.backend.expression import CreateTableExpression
+from rhosocial.activerecord.backend.expression import CreateTableStatement
 from rhosocial.activerecord.backend.expression.objects import Table
 from rhosocial.activerecord.backend.expression.statements import (
     ColumnConstraint,
-    ColumnConstraintType,
     ColumnDefinition,
+    ColumnPrimaryKeyConstraint,
 )
 from rhosocial.activerecord.backend.expression.types import VarCharType
 from rhosocial.activerecord.model import ActiveRecord
@@ -87,13 +87,15 @@ User.configure(
 )
 
 dialect = User.__backend__.dialect
-User.__backend__.execute(*CreateTableExpression(
+User.__backend__.execute(*CreateTableStatement(
     dialect,
     Table(dialect, "users"),
     columns=[
         ColumnDefinition(
             dialect, "id", VarCharType(dialect, 36),
-            constraints=[ColumnConstraint(dialect, ColumnConstraintType.PRIMARY_KEY)],
+            constraints=[ColumnConstraint(
+                dialect, branch=ColumnPrimaryKeyConstraint(dialect),
+            )],
         ),
         ColumnDefinition(dialect, "name", VarCharType(dialect, 100)),
         ColumnDefinition(dialect, "email", VarCharType(dialect, 255)),

changelog.d/7.added.md

@@ -0,0 +1,3 @@
+`table-storage-metrics` on the introspect CLI, with `views NAME`; the type list derives from `_TYPE_CAPABILITIES`. Account objects (databases, schemas, warehouses) are declared as expression statements.
+
+Account-object introspection for the Snowflake backend: `list_databases()`, `list_schemas(database=None)`, `list_warehouses()` and `get_table_storage_metrics(table_name, schema=None)` on both the sync and async introspectors, with `databases` / `schemas` / `warehouses` added to the `introspect` CLI subcommand. Every statement is built as an expression tree (`SnowflakeDatabaseListQueryStatement`, `SnowflakeSchemaListQueryStatement`, `SnowflakeWarehouseListQueryStatement`, `SnowflakeTableStorageMetricsQueryStatement`) rendered by the dialect's `format_*_query_statement` methods, so no SQL text is assembled by concatenation. `SHOW WAREHOUSES` is used because no `INFORMATION_SCHEMA.WAREHOUSES` view exists. See `examples/introspection_account_objects.py` for a runnable walkthrough.

changelog.d/7.changed.md

@@ -0,0 +1 @@
+The table kind is the one the catalogue named, `include_views` no longer hides managed tables, and the catalogue's spelling is preserved rather than normalised.

changelog.d/7.fixed.md

@@ -0,0 +1 @@
+A managed table is no longer dropped from a `views` read, and the storage metrics distinguish "no row for this table" from "this role cannot see the view".

changelog.d/7.internal.md

@@ -0,0 +1 @@
+The CLI tests pin every declared type and serialise each output, and CI installs core from `release/v1.0.0.dev30` now that core #127 has merged.

pyproject.toml

@@ -78,7 +78,12 @@ namespaces = true
 
 [tool.pytest.ini_options]
 minversion = "7.0"
-addopts = "-ra -q"
+addopts = "-ra -q -p plugins.expression_xdist"
+# The plugin is addressed as ``plugins.expression_xdist`` because CI puts
+# ``tests`` itself on ``PYTHONPATH`` (``export PYTHONPATH=src:tests``), which is
+# also what makes the package layout under ``tests/`` importable. Adding
+# ``tests`` here as well would arrange a *different* root, and the plugin would
+# not resolve at all -- which is what Python 3.8's unit-only leg reported.
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"
 testpaths = [

src/rhosocial/activerecord/backend/impl/snowflake/backend/async_backend.py

@@ -240,7 +240,7 @@ async def _process_result_set(self, cursor, is_select, column_adapters=None, col
         ``cursor.description`` returns them as such.  Python model
         field names are lowercase by convention, so we normalise
         column names to lowercase before building row dicts so that
-        ``_map_columns_to_fields()`` and ``_remap_row_columns()`` can
+        ``_map_columns_to_fields()`` and ``remap_row_columns()`` can
         match them correctly.
         """
         if not is_select:
@@ -255,8 +255,8 @@ async def _process_result_set(self, cursor, is_select, column_adapters=None, col
             mapping = column_mapping or {}
             for row in rows:
                 row_dict = dict(zip(column_names, row))
-                adapted_row = self._adapt_row_types(row_dict, adapters)
-                final_row = self._remap_row_columns(adapted_row, mapping)
+                adapted_row = self.adapt_row_types(row_dict, adapters)
+                final_row = self.remap_row_columns(adapted_row, mapping)
                 final_results.append(final_row)
             return final_results
         except Exception as e:

src/rhosocial/activerecord/backend/impl/snowflake/backend/backend.py

@@ -276,7 +276,7 @@ def _process_result_set(self, cursor, is_select, column_adapters=None, column_ma
         ``cursor.description`` returns them as such.  Python model
         field names are lowercase by convention, so we normalise
         column names to lowercase before building row dicts so that
-        ``_map_columns_to_fields()`` and ``_remap_row_columns()`` can
+        ``_map_columns_to_fields()`` and ``remap_row_columns()`` can
         match them correctly.
         """
         if not is_select:
@@ -291,8 +291,8 @@ def _process_result_set(self, cursor, is_select, column_adapters=None, column_ma
             mapping = column_mapping or {}
             for row in rows:
                 row_dict = dict(zip(column_names, row))
-                adapted_row = self._adapt_row_types(row_dict, adapters)
-                final_row = self._remap_row_columns(adapted_row, mapping)
+                adapted_row = self.adapt_row_types(row_dict, adapters)
+                final_row = self.remap_row_columns(adapted_row, mapping)
                 final_results.append(final_row)
             return final_results
         except Exception as e:

src/rhosocial/activerecord/backend/impl/snowflake/cli/README.md

@@ -0,0 +1,105 @@
+# `introspect` — Snowflake metadata, from the command line
+
+The `introspect` subcommand asks a live Snowflake account what it holds, and
+prints the answer. Every question runs through the backend's introspector, so
+what the CLI reports is what the library sees — the same objects, the same
+types, the same parsing — rather than a second implementation that can drift
+from it.
+
+```bash
+python -m rhosocial.activerecord.backend.impl.snowflake introspect <TYPE> [NAME] [OPTIONS]
+```
+
+## What it can ask about
+
+| Type | `NAME` | Reads | Notes |
+| :--- | :--- | :--- | :--- |
+| `tables` | — | `information_schema.tables` | Tables, with the kind the catalogue reports and their comment. |
+| `views` | view, optional | `information_schema.views` | Views, with their definitions; one view when named. |
+| `columns` | table, required | `information_schema.columns` | One table's columns: name, type, nullability, ordinal position, default. |
+| `indexes` | table, required | `information_schema.table_constraints`, `key_column_usage` | Constraints and the columns each side names. |
+| `foreign-keys` | table, required | `information_schema.referential_constraints` | Referential constraints. |
+| `table-storage-metrics` | table, required | `information_schema.table_storage_metrics`, `information_schema.tables` | One table's billed storage: active, time travel, failsafe and clone-retained bytes, plus the row count, clustering key and kind `tables` reports. |
+| `databases` | — | `information_schema.databases` | The databases in the account, with owner and transient flag. |
+| `schemas` | — | `information_schema.schemata` | The schemas in a database — Snowflake's namespace level above a table. `--database` names the database to enumerate. |
+| `warehouses` | — | `SHOW WAREHOUSES` | Warehouses with size, state and auto-resume. This is `SHOW`, not an `information_schema` view, because no such view exists. |
+| `database` | — | `CURRENT_DATABASE()`, `CURRENT_VERSION()` | The database this session is in and the account's version. |
+
+`NAME` is required for `columns`, `indexes`, `foreign-keys` and
+`table-storage-metrics`. For `views` it is optional: a name asks for that one
+view, and a name the catalogue does not have exits 1. The list types —
+`tables`, `database`, `databases`, `schemas` and `warehouses` — take no name,
+and a stray one is refused (exit 2) rather than ignored: this backend has no
+`get_*_info` method that could answer for a single database, schema or
+warehouse. `schemas --database analytics` is unaffected — `--database` says
+which database's schemas to enumerate, not which schema to fetch.
+
+Exit codes follow that split: **1** is a runtime failure (connection, query,
+unexpected) and also "the named view or table is not there"; **2** is a request
+this backend cannot serve — a type whose capability switch is off, or a `NAME`
+on a list type.
+
+Two absences worth naming:
+
+*   **No `triggers` type.** Snowflake has no triggers, so there is no object to
+    ask about. That is an engine fact, not a gap in the CLI.
+*   **No `partition-metadata` type.** The dialect carries a formatter for it,
+    but no introspector method reads it, so there is no answer behind the type.
+
+`table-storage-metrics` is a type of its own rather than a column of `tables`
+for two reasons. Its statement joins two views, so folding it into the listing
+would charge every list for that join. And `TABLE_STORAGE_METRICS` returns no
+rows for roles other than `ACCOUNTADMIN`, so an empty answer means "no metrics
+for this role" — a `None` the command can state out loud, which a column on the
+listing could not. An exit of 1 on this type is therefore **not** "the table
+does not exist".
+
+## Options
+
+| Option | Default | Description |
+| :--- | :--- | :--- |
+| `-o, --output` | `table` | `table` (rich), `json`, `csv`, `tsv`. |
+| `--account` | `SNOWFLAKE_ACCOUNT` | Account identifier. |
+| `--host`, `--port` | _None_ | Connection endpoint, when not using the account locator. |
+| `--database` | `SNOWFLAKE_DATABASE` | Database to connect to. |
+| `--schema` | `SNOWFLAKE_SCHEMA` | Schema to connect to; introspection reads it. Defaults to `PUBLIC`. |
+| `--warehouse` | `SNOWFLAKE_WAREHOUSE` | Warehouse to run queries on. |
+| `--role` | `SNOWFLAKE_ROLE` | Role to assume. |
+| `--user`, `--password` | env | Credentials. |
+| `--authenticator` | _None_ | How the user is authenticated. |
+| `--use-async` | off | Drive the asynchronous backend. |
+
+## Notes
+
+*   **Read-only.** `introspect` never writes. It does not create, drop, or
+    alter anything, so it is safe to run against an account whose schema
+    matters.
+*   **The warehouse matters.** Snowflake needs one to run a query. If the role's
+    default warehouse is not set, pass `--warehouse`; a missing warehouse is a
+    connection failure, not an empty answer.
+*   **`SHOW WAREHOUSES` has no `information_schema` counterpart.** It also
+    caps its output, and its column names come back lower case — both are
+    recorded next to the query in the source rather than assumed here.
+*   **Nothing here was run against a live account.** The statements are written
+    from the official documentation (cited beside each one in the source).
+    Verify the first run against your account before relying on the shapes.
+*   **One question per invocation.** A CLI process is one connection that
+    opens, answers, and closes — there is no cache carried between runs.
+*   **No `status` subcommand.** This backend implements no status
+    introspector — there is no `AbstractStatusIntrospector` implementation
+    under `introspection/` — so the CLI has no `status` command to wire up.
+    That is a missing library capability, not a forgotten command: `info`
+    reports the version and the protocol/capability matrix instead. Aligning
+    the backends on `status` starts in the library, not here.
+
+## Examples
+
+```bash
+# Account-level objects, which Snowflake has and most engines do not
+python -m rhosocial.activerecord.backend.impl.snowflake introspect databases
+python -m rhosocial.activerecord.backend.impl.snowflake introspect schemas --database analytics
+python -m rhosocial.activerecord.backend.impl.snowflake introspect warehouses -o json
+
+# One table's storage facts
+python -m rhosocial.activerecord.backend.impl.snowflake introspect table-storage-metrics orders --schema public --database analytics
+```