snowflake-code-unit-registry 0.8.1

SCAI state management library for database migrations

scai-state

SCAI state management library for database migrations.

Installation

pip install scai-state

Usage

from scai_state import CodeUnitRegistry
from scai_state.types import CodeUnit, SourceMetadata, TargetMetadata, ObjectType, Kind

# Initialize a new registry
registry = CodeUnitRegistry.init("/path/to/repo")

# Or open an existing registry
registry = CodeUnitRegistry.open("/path/to/existing/repo")

# Create a code unit
code_unit = CodeUnit(
    kind=Kind.databaseObject,
    source=SourceMetadata(
        objectType=ObjectType.table,
        database="RETAIL_DB",
        schema="dbo",
        name="Customer",
    ),
    target=TargetMetadata(
        objectType=ObjectType.table,
        database="RETAIL",
        schema="DBO",
        name="CUSTOMER",
    ),
)

# Returns the ID (auto-generated if not provided)
id = registry.create(code_unit)

# Load a code unit
cu = registry.load(id)

# List all code units (with optional filter)
results = registry.list("source.objectType = 'table'")

# Update specific fields
registry.update(id, {"planning.wave": 2})

# Delete a code unit
registry.delete(id)

Testing

Integration tests live in tests/ and cover the full Python -> Rust -> disk -> Rust -> Python round-trip:

Test file	What it verifies
test_serialization.py	FFI round-trip fidelity for all fields, Pydantic alias handling, extensions empty-map preservation
test_errors.py	ScaiError.error_code contract across FFI (1001, 1003)
test_batch.py	BatchResult wire format with partial failures (1004)
test_crud.py	Full CRUD lifecycle, upsert deep-merge semantics
test_query.py	find_by_object partial matching with exclude_unset

Run them from the repo root:

./scripts/run-tests.sh python

Or directly:

cd crates/scai-state-python
maturin develop
pytest tests/ -v

Building from Source

This package requires Rust and maturin to build:

# Install maturin
pip install maturin

# Build and install in development mode
cd crates/scai-state-python
maturin develop

License

Apache-2.0