v0.3.0

v0.3.0 (02.01.2026)

Streamlined release that consolidates engine configuration into fully-resolved, self-contained schema files. Eliminates the need for separate base and engine-specific config files in the output.

Fully-Resolved Engine Configuration

Single Config File Per Engine

• Before: Output contained config/base.json + config/engines/{engine}.json requiring reference resolution at runtime
• After: Output contains only config/{engine}.json with all references fully inlined

Benefits

• Self-contained schemas - no external $ref dependencies to resolve
• Simpler consumption by downstream tools and validators
• Reduced complexity for CLI and web application integration
• Each engine config includes all base definitions (envVarString, envFilePath, schemaDefinition, etc.)

JSON Reference Resolution Enhancements

JSON Pointer Support (RFC 6901)

• Added support for JSON pointers in $ref values
• Local references: #/$defs/foo
• External file references with pointers: engines/postgresql.json#/$defs/envs

Performance Improvements

• File caching during resolution to avoid redundant reads
• Proper circular reference detection for all reference types

Output Structure Changes

New Output Structure

output/
├── smap.json
├── manifest.json
├── config/
│   └── postgresql.json      # Fully resolved, self-contained
└── postgresql/
    └── v15.0/
        ├── tables.json
        └── snapshot/
            ├── stored.json
            └── working.json

Removed

• output/config/base.json - No longer generated
• output/config/engines/ directory - No longer needed

Schema Map (smap.json) Structure Change

Before

{
  "project": {
    "manifest": "https://example.com/manifest.json",
    "config": {
      "base": "https://example.com/config/base.json",
      "engines": {
        "postgresql": "https://example.com/config/engines/postgresql.json"
      }
    }
  }
}

After

{
  "project": {
    "manifest": "https://example.com/manifest.json",
    "config": {
      "postgresql": "https://example.com/config/postgresql.json"
    }
  }
}

The config section now maps engine names directly to their fully-resolved schema URLs.

Internal Changes

JSONRefResolver (resolution/resolver.py)

• New _resolve_json_pointer() method for RFC 6901 pointer resolution
• New _resolve_external_ref_with_pointer() for handling file.json#/path/to/def syntax
• Added _file_cache for caching loaded JSON files during resolution
• Enhanced circular reference detection covering all reference types

OutputManager (io/output_manager.py)

• New write_resolved_engine_config() method for generating fully-resolved config files
• Updated write_schema_map() to output flat config: {engine: url} structure
• Removed _write_base_config() method (no longer needed)

SchemaGenerator (cli/generator.py)

• Updated to use write_resolved_engine_config() for per-engine config generation
• Removed base.json generation logic

Test Coverage

• 81 tests passing
• 89% code coverage
• New tests for JSON pointer resolution (24 tests in test_resolver.py)
• Updated integration tests for new output structure

Breaking Changes

• smap.json structure: project.config.base and project.config.engines replaced with flat project.config.{engine} mapping
• Output paths: Config files now at config/{engine}.json instead of config/engines/{engine}.json
• Downstream tools consuming smap.json or config files will need updates

Supported

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

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

v0.1.0

v0.1.0 (2.9.2025)

Initial version of the Database Schema Specifications that are supported by Bfloo Application.

Schema Structure

• Schema metadata: UUID identifier, name (max 64 chars), description
• Snapshot tracking: UUID-based snapshots with labels (max 64 chars), parent relationships, timestamps
• Tables: Array of table definitions

PostgreSQL 15.0 Support

Tables

• Numeric identifiers
• Names: lowercase, snake_case, max 63 chars
• Descriptions
• Columns and constraints arrays

Columns

• Numeric identifiers
• Names: lowercase, snake_case, max 63 chars
• Data types: text, integer, serial, boolean, date, timestamp
• Optional descriptions and default values
• Inline constraints: nullable, unique, primary_key

Text Columns

• min_length constraint (named constraint + value)
• max_length constraint (named constraint + value)

Integer Columns

• min_value constraint (named constraint + value)
• max_value constraint (named constraint + value)

Table Constraints

• Foreign keys: reference table/column, on_delete actions (cascade, set_null, set_default, restrict, no_action), on_update actions
• Unique constraints: multi-column unique indexes
• Numeric identifiers, names (lowercase, snake_case, max 63 chars), descriptions, column arrays

Validation Rules

• Default value type matching (text→string, integer/serial→number, boolean→boolean, date/timestamp→current_date/current_timestamp)
• serial columns cannot have defaults, cannot be nullable, cannot be unique
• primary_key=true forces nullable=false, prevents unique=true
• nullable=false prevents default=null
• default=null forces nullable=true
• Naming patterns enforced on all identifiers

---

Supported: PostgreSQL 15.0
Format: JSON Schema Draft-07