Upgrade Guide

How to upgrade SOAP-2-REST by Specaria between releases safely. v1.0 is the inaugural release, so there is no prior GA version to upgrade from; this guide…

How to upgrade SOAP-2-REST by Specaria between releases safely. v1.0 is the inaugural release, so there is no prior GA version to upgrade from; this guide describes the standard procedure for future upgrades and the principles the product is built around.

Principles

Forward-only, automatic schema migrations. Database schema changes ship as Flyway migrations applied on startup. You do not run migrations by hand. Migrations are immutable and forward-only.
Mapping versions are preserved. Upgrading the product does not change your active per-service mapping versions or your generated contracts. Your published APIs keep behaving the same across an upgrade.
Deploy provenance is observable. After an upgrade, each service logs its build (commit, branch, timestamp, image tag) at startup, and exposes it as deployment metadata, so you can confirm exactly what is running.
Re-apply configuration on every deploy. Operator-critical environment variables and secret bindings are not inherited from a prior revision on some platforms; the deployment tooling re-applies them on every deploy. Follow the platform-specific runbook.

Standard upgrade procedure

Read the target release notes. Check the Releases page for the version you're moving to, especially any license, schema, or breaking-change notes.
Confirm license compatibility. A product MAJOR upgrade may require a license that declares the corresponding license-format version. See License model.
Back up the database. Take a PostgreSQL backup before upgrading. See Backup & restore.
Pull the target images for the control plane, runtime, and worker at the target version tag.
Deploy the control plane (admin-api) first. It applies the schema migrations on startup. Confirm it reaches a healthy state and that the schema validated.
Deploy the runtime and worker. Confirm each reaches a healthy state.
If you run a traffic relay / ingest VM, refresh it to the matching image so its embedded logic matches the upgraded schema. (A stale relay can silently stop writing ingest rows after a schema change.)
Verify. Check the startup deploy-provenance log line on each service, confirm the dashboard loads, run a test call through a representative service, and confirm fresh ingest/discovery rows are landing.

Order of operations (why it matters)

1. admin-api  → applies Flyway migrations, advances schema version
2. runtime    → serves traffic against the new schema
3. worker     → aggregations, discovery derivation, learned examples
4. relay/ingest (if used) → refreshed to match the new schema

Deploying the schema-owning service (admin-api) first ensures the schema is at the expected version before the runtime and worker depend on it.

Rolling back

Application rollback: redeploy the previous image tags for admin-api, runtime, and worker. Because mapping versions and generated contracts are preserved across upgrades, a rollback restores prior behavior.
Schema rollback: schema migrations are forward-only. If a release introduces a schema change that a rollback cannot tolerate, the release notes will say so and provide guidance. In general, restore from the pre-upgrade database backup if a schema-level rollback is required.
Service-level rollback: independent of any product upgrade, you can roll a single service's mapping back to a previous version at any time from the UI — see Publish & version a service.

Zero-downtime considerations

The runtime autoscales with a warm minimum, and admin-api applies migrations before serving, so most upgrades are low-impact.
Large-table index builds (when a release needs one) are performed out-of-band so an upgrade does not stall on a long-running migration.
For HA deployments (Kubernetes), follow standard rolling-update practice; deploy admin-api first so the schema is ready before runtime pods cycle.

Always treat the target release notes as authoritative for that specific upgrade — this guide is the general procedure, and any release-specific steps override it.

All Specaria SOAP to REST docs

Loading…

Principles

Forward-only, automatic schema migrations. Database schema changes ship as Flyway migrations applied on startup. You do not run migrations by hand. Migrations are immutable and forward-only.

Mapping versions are preserved. Upgrading the product does not change your active per-service mapping versions or your generated contracts. Your published APIs keep behaving the same across an upgrade.

Deploy provenance is observable. After an upgrade, each service logs its build (commit, branch, timestamp, image tag) at startup, and exposes it as deployment metadata, so you can confirm exactly what is running.

Re-apply configuration on every deploy. Operator-critical environment variables and secret bindings are not inherited from a prior revision on some platforms; the deployment tooling re-applies them on every deploy. Follow the platform-specific runbook.

Standard upgrade procedure

Read the target release notes. Check the Releases page for the version you're moving to, especially any license, schema, or breaking-change notes.

Confirm license compatibility. A product MAJOR upgrade may require a license that declares the corresponding license-format version. See License model.

Back up the database. Take a PostgreSQL backup before upgrading. See Backup & restore.

Pull the target images for the control plane, runtime, and worker at the target version tag.

Deploy the control plane (admin-api) first. It applies the schema migrations on startup. Confirm it reaches a healthy state and that the schema validated.

Deploy the runtime and worker. Confirm each reaches a healthy state.

If you run a traffic relay / ingest VM, refresh it to the matching image so its embedded logic matches the upgraded schema. (A stale relay can silently stop writing ingest rows after a schema change.)

Verify. Check the startup deploy-provenance log line on each service, confirm the dashboard loads, run a test call through a representative service, and confirm fresh ingest/discovery rows are landing.

Order of operations (why it matters)

1. admin-api → applies Flyway migrations, advances schema version 2. runtime → serves traffic against the new schema 3. worker → aggregations, discovery derivation, learned examples 4. relay/ingest (if used) → refreshed to match the new schema

Deploying the schema-owning service (admin-api) first ensures the schema is at the expected version before the runtime and worker depend on it.

Rolling back

Application rollback: redeploy the previous image tags for admin-api, runtime, and worker. Because mapping versions and generated contracts are preserved across upgrades, a rollback restores prior behavior.

Schema rollback: schema migrations are forward-only. If a release introduces a schema change that a rollback cannot tolerate, the release notes will say so and provide guidance. In general, restore from the pre-upgrade database backup if a schema-level rollback is required.

Service-level rollback: independent of any product upgrade, you can roll a single service's mapping back to a previous version at any time from the UI — see Publish & version a service.

Zero-downtime considerations

The runtime autoscales with a warm minimum, and admin-api applies migrations before serving, so most upgrades are low-impact.

Large-table index builds (when a release needs one) are performed out-of-band so an upgrade does not stall on a long-running migration.

For HA deployments (Kubernetes), follow standard rolling-update practice; deploy admin-api first so the schema is ready before runtime pods cycle.

Always treat the target release notes as authoritative for that specific upgrade — this guide is the general procedure, and any release-specific steps override it.