dataflow.db.supabase

Supabase database integration for the Haive registry system.

This module provides functionality for connecting to and interacting with a Supabase database instance for storing registry data. It handles connection management, schema mapping, and query execution.

The module uses environment variables for configuration: - SUPABASE_URL: The URL of your Supabase instance - SUPABASE_SERVICE_KEY: Service role API key (preferred for admin operations) - SUPABASE_ANON_KEY: Anonymous API key (fallback)

Typical usage example:

>>> from haive.dataflow.db.supabase import get_supabase_client
>>>
>>> # Get a Supabase client
>>> supabase = get_supabase_client()
>>>
>>> # Query a table
>>> result = supabase.table('registry_items').select('*').execute()
>>> items = result.data
>>> print(f"Found {len(items)} registry items")

Functions

fetch_all_schemas_and_tables(client)	Return all non-system tables grouped by schema using raw SQL.
fetch_foreign_key_relations(client)	Return foreign key relationships between tables using raw SQL.
fetch_primary_keys(client)	Get all primary keys per table.
fetch_table_columns(client)	Get all columns, types, and constraints from.
get_supabase_client([schema])	Get a configured Supabase client instance.
parse_table_reference(table_ref)	Parse a table reference to extract table name and schema.
sanitize_sql(sql)	Remove trailing semicolons and whitespace for safe RPC use.
table(client, table_ref[, schema_override])	Get a table reference with appropriate schema handling.

Module Contents

dataflow.db.supabase.fetch_all_schemas_and_tables(client)

Return all non-system tables grouped by schema using raw SQL.

Parameters:

client (supabase.Client)

Return type:

list[dict]

dataflow.db.supabase.fetch_foreign_key_relations(client)

Return foreign key relationships between tables using raw SQL.

Parameters:

client (supabase.Client)

Return type:

list[dict]

dataflow.db.supabase.fetch_primary_keys(client)

Get all primary keys per table.

Parameters:

client (supabase.Client)

Return type:

list[dict]

dataflow.db.supabase.fetch_table_columns(client)

Get all columns, types, and constraints from. information_schema.columns.

Parameters:

client (supabase.Client)

Return type:

list[dict]

dataflow.db.supabase.get_supabase_client(schema=None)

Get a configured Supabase client instance.

Creates and returns a Supabase client configured with the specified schema. The client uses environment variables for connection parameters.

Parameters:

schema (str | None) – Optional database schema to use. If not specified, defaults to “public” schema.

Returns:

A configured Supabase client instance.

Return type:

Client

Raises:

EnvironmentError – If required environment variables are not set.

Examples

>>> # Get client with default schema
>>> client = get_supabase_client()
>>>
>>> # Get client with specific schema
>>> registry_client = get_supabase_client("registry")

dataflow.db.supabase.parse_table_reference(table_ref)

Parse a table reference to extract table name and schema.

This function parses table references in various formats and extracts the table name and schema. It handles: - Simple table names: “items” (uses default schema mapping) - Schema-qualified names: “registry.items” (explicit schema)

Parameters:

table_ref (str) – Table reference string in one of the supported formats. Examples: “items”, “registry.items”, “models.providers”

Returns:

A tuple containing (table_name, schema_name),

where schema_name may be None if not specified and not in DEFAULT_SCHEMA_MAP.

Return type:

Tuple[str, Optional[str]]

Examples

>>> parse_table_reference("items")
('items', 'registry')  # Uses default schema mapping
>>> parse_table_reference("registry.items")
('items', 'registry')  # Explicit schema
>>> parse_table_reference("custom_table")
('custom_table', None)  # No mapping found

dataflow.db.supabase.sanitize_sql(sql)

Remove trailing semicolons and whitespace for safe RPC use.

Parameters:

sql (str)

Return type:

str

dataflow.db.supabase.table(client, table_ref, schema_override=None)

Get a table reference with appropriate schema handling.

Parameters:

• client (supabase.Client) – Supabase client

• table_ref (str) – Table reference (can include schema)

• schema_override (str | None) – Optional schema to override detected schema

Returns:

Table reference for queries

Return type:

Any