rhosocial-activerecord-snowflake

Snowflake Backend for rhosocial-activerecord

Cloud Data Warehouse Support · VARIANT & ARRAY Types · Time Travel Queries

Note: This is a backend implementation for rhosocial-activerecord. It cannot be used standalone.

Why This Backend?

1. Snowflake-Specific Optimizations

2. True Sync-Async Parity

Same API surface for both sync and async operations:

# Sync
users = User.query().where(User.c.age >= 18).all()

# Async - just add await
users = await User.query().where(User.c.age >= 18).all()

3. Built for Cloud Data Warehouse

• Warehouse-aware connection configuration
• Schema and role support for multi-tenant environments
• Time travel for point-in-time data access
• VARIANT/ARRAY type adapters for semi-structured data

Quick Start

Installation

pip install rhosocial-activerecord-snowflake

Basic Usage

from rhosocial.activerecord.model import ActiveRecord
from rhosocial.activerecord.backend.impl.snowflake import SnowflakeBackend
from rhosocial.activerecord.backend.impl.snowflake.config import SnowflakeConnectionConfig
from typing import Optional

class User(ActiveRecord):
    __table_name__ = "users"
    id: Optional[int] = None
    name: str
    email: str

# Configure
config = SnowflakeConnectionConfig(
    account="your-account",
    warehouse="COMPUTE_WH",
    database="myapp",
    schema="public",
    username="user",
    password="password",
    role="SYSADMIN"
)
User.configure(config, SnowflakeBackend)

# Use
user = User(name="Alice", email="alice@example.com")
user.save()

Snowflake-Specific Features

VARIANT Type (Semi-Structured Data)

Native Snowflake VARIANT support for JSON-like data:

from rhosocial.activerecord.backend.impl.snowflake import SnowflakeVariantAdapter

# Store and query semi-structured data
settings = {"theme": "dark", "notifications": True}

Time Travel Queries

Access historical data using Snowflake's time travel capabilities:

# Query data as of a specific timestamp
results = User.query().where(User.c.age >= 18).all()

# Time travel with AT/BEFORE clauses (via raw SQL)

MERGE (Conditional Upsert)

Efficient conditional insert-or-update operations:

# Snowflake MERGE support for complex upsert scenarios

Requirements

• Python: 3.8+ (including 3.14t free-threaded builds; 3.13t is NOT supported due to cffi dependency incompatibility)
• Core: rhosocial-activerecord>=0.9.0
• Driver: snowflake-connector-python>=3.0.0

Comparison with Other Backends

Testing

⚠️ CRITICAL: Tests MUST run serially. Do NOT use pytest -n auto or parallel execution.

# Run all tests
PYTHONPATH=src pytest tests/

# Run specific feature tests
PYTHONPATH=src pytest tests/rhosocial/activerecord_snowflake_test/feature/backend/

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

Apache License 2.0 — Copyright © 2025 vistart