Skip to content

ADR-0005 — DDL strategy — Core API over SQL, SQL as fallback

Update date : 2026-05-27 20:11

Status: accepted (stateless row refined by ADR-0006) Date: 2026-05-26

Context

Each Snowflake object type needs a deployment mechanism. Two options exist per object: - Core API (snowflake.core) — Python objects, typed, idempotent methods - Raw SQL — string DDL executed via connector

Decision

Decision tree applied per object type:

create_or_alter available in Core API    →  Core API
CREATE OR ALTER available in SQL         →  SQL
stateful (IF NOT EXISTS)                 →  Core API
stateless (OR REPLACE)                   →  Core API
Core API absent                          →  SQL  (temporary fallback)

Core API is always preferred. SQL fallback is temporary — migrated to Core API when support is added.

Consequences

  • Typed deployment: Pydantic validation before any API call.
  • Objects not yet in Core API (external_access_integration, storage_lifecycle_policy, semantic_view) use SQL fallback — tracked in explanation/design.md coverage table.
  • When Snowflake adds Core API support for a fallback object, migration is straightforward: replace the SQL string with a Core API call, no interface change for callers.