Schema evolution across certified versions

Status

illustrative

Industry

Cross-industry

Language

Python

Framework

pytest

CI

any

Fulfilment

LEASE_CERTIFIED_VERSION

Profile

warehouse-migration

About this example

All data is synthetic. DataNivra provisions approved test data into a customer-controlled target; it does not run these tests. Credentials for the target are never returned by DataNivra — your runner holds its own.

Why test data matters

Readers must handle data written by the previous and the next schema version.

What is requested

A lease of the version the profile pins; a new profile version pins the next dataset version.

Policy gates

Each profile version is reviewed; old pins keep working until deprecated or revoked.

What is provisioned

The pinned certified version.

Expected output

AUTO_APPROVED (with dataset.provision).

Cleanup

Fixture releases.

Files

• request.yaml
• example.py
• test_with_datanivra.py

Run

1. A tenant administrator defines and a second person approves the profile (datanivra test-data define ../../profiles/warehouse-migration.yaml --submit, then datanivra policies approve).
2. datanivra test-data validate request.yaml && datanivra test-data plan request.yaml
3. Run the example with DATANIVRA_BASE_URL and a session or workload token.

# yaml-language-server: $schema=../../../../packages/contracts/schemas/v1/manifests/test-data-request.schema.json
# DataNivra test-data-request manifest (apiVersion datanivra.io/v1alpha1). Validate: datanivra test-data validate <file>
apiVersion: datanivra.io/v1alpha1
kind: TestDataRequest
metadata:
  name: schema-forward
spec:
  profile: { name: warehouse-migration, version: 1 }
  ttl_seconds: 1800

"""Schema evolution across certified versions — provision approved test data through the Python SDK.

``provision`` only asks DataNivra for data from the approved ``warehouse-migration`` profile; your own test
suite runs against the approved target with its own, separately managed database access.
"""

from __future__ import annotations

from pathlib import Path

from datanivra_contracts.testdata import TestDataRequest
from datanivra_sdk import DataNivraClient
from datanivra_sdk.testdata import TestDataClient

REQUEST = Path(__file__).with_name("request.yaml")


def provision(api: DataNivraClient, *, idempotency_key: str | None = None) -> TestDataRequest:
    """Create (or, for the same key, return) the request; DENIED raises ``DataNivraApiError``."""
    return TestDataClient(api).request(REQUEST, idempotency_key=idempotency_key)

"""Schema evolution across certified versions (pytest).

Run in your CI with ``DATANIVRA_BASE_URL`` and a token (``datanivra login --workload-identity ...``
or ``DATANIVRA_TOKEN``). The data is released after the session, even when tests fail.
"""

from __future__ import annotations

import os
from collections.abc import Iterator

import pytest
from datanivra_contracts.testdata import TestDataRequest
from datanivra_sdk import DataNivraClient
from datanivra_sdk.testdata import TestDataClient
from example import REQUEST


@pytest.fixture(scope="session")
def test_data() -> Iterator[TestDataRequest]:
    api = DataNivraClient(os.environ["DATANIVRA_BASE_URL"], token=os.environ["DATANIVRA_TOKEN"])
    with TestDataClient(api).acquire(REQUEST, idempotency_key=os.environ.get("CI_RUN_KEY")) as request:
        yield request


def test_reader_accepts_both_versions(test_data: TestDataRequest) -> None:
    # Your assertions run against your application and the approved target environment
    # ``test_data.environment_id``; DataNivra only returns metadata (ids, states, digests).
    assert test_data.state.value == "READY"

# yaml-language-server: $schema=../../../packages/contracts/schemas/v1/manifests/test-data-profile.schema.json
# DataNivra test-data-profile manifest (apiVersion datanivra.io/v1alpha1). Validate: datanivra test-data validate <file>
# Placeholder ids (00000000-0000-4000-8000-0000000000NN): replace with your ids.
# 01 = approved target environment, 11 = certified dataset, 21 = customer agent,
# 99 = workload identity trust (datanivra workload-identities list).
apiVersion: datanivra.io/v1alpha1
kind: TestDataProfile
metadata:
  name: warehouse-migration
  description: Certified, masked warehouse slice leased for schema-migration rehearsals
spec:
  fulfilment: LEASE_CERTIFIED_VERSION
  lease:
    dataset_id: 00000000-0000-4000-8000-000000000011
    agent_id: 00000000-0000-4000-8000-000000000021
    provider_kind: POSTGRESQL_CONTAINER
    default_ttl_seconds: 1800
    max_ttl_seconds: 7200
    target_pool:
      - vault://ci/warehouse-migration-db-1
      - vault://ci/warehouse-migration-db-2