v0.2.0

v0.2.0 (10.12.2025)

Major refactoring release introducing modular project configuration, snapshot-based version tracking, and a complete CLI architecture for schema management and web application synchronization.

Project Configuration

Modular Config Structure

• Split configuration into base + engine-specific schemas
• config/base.json - Common settings: schema_id, database.engine, API configuration
• config/engines/{engine}.json - Engine-specific connection parameters

Environment Variable Support

• ${VAR_NAME} syntax for sensitive values (API keys, passwords, hosts)
• Resolution order: system environment → .env file (config dir → project root → cwd)
• --env-file CLI flag for custom .env location

PostgreSQL Connection Parameters

• Full libpq specification support (40+ parameters)
• Multi-environment configuration (development, staging, production)
• SSL/TLS options: sslmode, sslcert, sslkey, sslrootcert, protocol versions
• Connection tuning: timeouts, keepalives, TCP settings
• Authentication: password, SCRAM-SHA-256, GSS/Kerberos, channel binding
• High availability: target_session_attrs, load_balance_hosts, multi-host support

Snapshot Manifest System

manifest.json Schema

• Tracks all schema snapshots with metadata
• current - Active snapshot label
• Snapshot entries: label, id (UUID), parent_id, database_version, created_at, file, synced

Snapshot Tree Structure

• Parent-child relationships via parent_id
• Supports branching (multiple snapshots can share same parent)
• Database version tracked per-snapshot (enables version upgrades between snapshots)

File Naming Convention

• Pattern: YYYY-MM-DD_<label>.yaml
• Examples: 2024-01-15_v1.0.0.yaml, 2024-03-20_v2.0.0.yaml

Schema Specification Updates

Unique Identifiers

• Added id (integer) to tables, columns, and constraints
• Enables rename tracking and web application synchronization
• IDs are local to each schema file

Schema Structure

• name - Schema name (required, max 64 chars)
• description - Schema description (optional, max 256 chars)
• tables - Array of table definitions with IDs

CLI Architecture (Documented)

Project Commands

• db init - Initialize new database project
• db validate - Validate schema against specification

Snapshot Commands

• db snapshot create --label "v1.0.0" --database-version "15.0"
• db snapshot list - Tree view of all snapshots
• db snapshot show <label> - Snapshot details
• db snapshot checkout <label> - Switch active snapshot
• db snapshot rename <old> <new> - Rename snapshot

Synchronization Commands

• db sync push - Push local snapshots to web application
• db sync pull --to <label> - Pull snapshots from web application

Migration Commands

• db migrate --to <label> --env <environment> - Run migrations
• db migrate --preview / --plan - Preview SQL without executing
• Sequential generation, atomic execution (single transaction)
• Automatic rollback on failure

Diff Commands

• db diff <from> <to> - Compare two snapshots
• db diff <label> - Compare current schema to snapshot
• db diff - Compare current schema to active snapshot

Output Structure

Schema Map (smap.json)

• Renamed from vmap.json
• Nested structure: project.config.engines mapping
• Engine/version discovery for downstream tools

Project Schemas

• $id injection for config and manifest schemas
• Automatic schema generation for project configuration files

Internal Changes

Registry System

• _registry_.json for engine/version discovery
• oneOf format listing supported engine/version combinations
• Used by generator for variant extraction

Code Cleanup

• Removed conditional_merger.py (no longer needed)
• Simplified resolver with direct spec loading
• Updated variant_extractor.py to use oneOf format

CI/CD

• Consolidated workflows with service version image creation
• Automated schema generation and validation in CI pipeline

---

Supported: PostgreSQL 15.0
Format: JSON Schema Draft-07
Config Format: YAML