Dependency resources

A dependency resource is Appaloft's record for a database or service dependency. Phase 7 supports provider-neutral Postgres, Redis, MySQL, ClickHouse, S3/MinIO object storage, and OpenSearch records, Appaloft-managed realization, imported external dependencies, safe read models, delete safety checks, and backup/restore.

appaloft dependency provision --kind postgres --project prj_prod --environment env_prod --name app-db
appaloft dependency import --kind redis --project prj_prod --environment env_prod --name cache --connection-url redis://cache.internal:6379/0

List/show output must mask connection secrets, provider tokens, passwords, and raw connection URLs.

A Resource dependency binding lets future deployment snapshots reference a dependency resource. The binding stores only provider-neutral safe metadata and secret references. It does not place database URLs or passwords on the Resource, and you do not pass database URLs to deployments.create.

appaloft resource dependency bind res_web --dependency dep_db --target DATABASE_URL

Unbind removes only the association. It does not delete the database, restart runtime, or rewrite historical deployment snapshots.

Repository config can declare an application dependency graph for config-driven CLI and GitHub Action deployments:

dependencies:
  db:
    kind: postgres
    source: managed
    bind:
      env: DATABASE_URL
    backup:
      enabled: true
      intervalHours: 24
      retentionDays: 7
  cache:
    kind: redis
    source: managed
    bind:
      env: REDIS_URL
    preview:
      lifecycle: ephemeral

During config deploy, Appaloft lists existing dependency resources and bindings, provisions a managed dependency when needed, binds the selected Resource to the requested environment variable, and then creates the deployment with ids only. Repository config accepts postgres, redis, mysql, clickhouse, object-storage, and opensearch for managed dependency declarations. The runtime receives the value through the same safe dependency runtime injection path described below.

Do not put provider accounts, tenants, credentials, database passwords, raw connection strings, or secret values in appaloft.yaml. controlPlane.install.database is only for the Appaloft control-plane installer database and is not an application dependency database.

For PR previews, preview.lifecycle: ephemeral lets preview cleanup unbind and delete only the dependency that has explicit repository-config provenance for that preview. Shared, manually bound, imported, or otherwise unproven dependencies are not deleted by preview cleanup.

Use backup when a managed dependency should have scheduled restore points:

dependencies:
  db:
    kind: postgres
    source: managed
    bind:
      env: DATABASE_URL
    backup:
      enabled: true
      intervalHours: 24
      retentionDays: 7
      retryOnFailure: true

Config deploy reconciles this through dependency backup policy operations. It does not run backup or restore work, and appaloft.yaml must not contain policy ids, provider keys, backup artifact handles, restore point ids, raw dump paths, provider accounts, credentials, or secret values.

When a Resource has active ready dependency bindings, Appaloft includes safe runtime injection readiness in deployment plan and deployment detail output. A binding can be delivered when the dependency is ready, the binding targets a runtime environment variable such as DATABASE_URL or REDIS_URL, and the selected runtime target supports dependency secret delivery.

appaloft deployments plan --project prj_prod --environment env_prod --resource res_web --server srv_prod
appaloft deployments show dep_123

deployments.create does not accept dependency connection strings. Appaloft captures the current safe binding reference in the deployment snapshot and asks the runtime target to provide the configured environment variable to the workload. Historical deployment snapshots keep their captured reference after later binding secret rotation.

Plan and show output report dependency runtime injection as ready, blocked, or not-applicable. blocked means at least one active binding cannot be delivered safely for the selected runtime target. Common safe reasons include a not-ready dependency, missing safe secret reference, an unresolved stored dependency secret, unsupported dependency kind, unsupported scope or injection mode, duplicate target name, an existing environment-variable conflict, or a runtime target that cannot deliver dependency secrets.

When deployments.create sees the same blocked state, it rejects the deployment before acceptance with dependency_runtime_injection_blocked. No deployment attempt is created, and the response does not expose raw connection strings, passwords, or provider payloads. Fix the dependency resource, binding, target name, or runtime target, then run plan again before deploying.

resources.rotate-dependency-binding-secret replaces only the safe secret reference or version on the binding. It affects future deployment snapshots. It does not rotate provider-native database passwords, update running container environment variables, or rewrite historical deployments.

After rotating, create a new deployment so the workload reads the new snapshot reference.

Backup creates a safe restore point. Restore performs an in-place restore to the same dependency resource after explicit acknowledgement that data may be overwritten and runtime will not restart automatically.

appaloft dependency backup create dep_db
appaloft dependency backup list dep_db
appaloft dependency backup restore bkp_123

For imported dependencies with an Appaloft-owned connection reference, the shell provider runs native Postgres dump/restore or Redis logical backup/restore. Provider-owned or unresolved references still produce safe metadata-only restore points until that provider supplies its own backup substrate. Raw connection values never appear in backup artifacts, read models, events, or errors.

Restore does not mutate ResourceBindings, deployment rollback/redeploy state, workload processes, or historical deployment snapshots. Dependency delete must be blocked while retained backups or in-flight restores remain.

Scheduled backup policies are opt-in records. They do not run unless the self-hosted shell enables the scheduled dependency backup runner. A due policy dispatches the same dependency-resources.create-backup operation as manual backup creation and records safe process attempt metadata for operator review.

appaloft dependency backup policy configure dep_db --retention-days 7 --interval-hours 24
appaloft dependency backup policy list dep_db
appaloft dependency backup policy show dbp_123

Before deleting a dependency resource, Appaloft checks active bindings, backup retention, deployment snapshot references, and provider-managed safety state. Imported external delete removes only the Appaloft control-plane record; it does not delete the external database.

When delete is blocked, inspect dependency detail, binding list, and backup list before explicitly removing the relevant references.