Schemas and releases

Declarative schemas let you keep content models in your project as YAML, review changes as a plan, and apply them to each environment. nimbu release deploys schemas, cloud code, and the theme in one step and records the result.

Run these commands from a project that contains nimbu.yml. For the underlying endpoints, see Schema management.

Environments

Named environments select an API host and a site together. They are stored under environments in nimbu.yml:

nimbu env add staging --host=api.nimbu.io --site=acme-staging
nimbu env add production --host=api.nimbu.io --site=acme --protected
nimbu env list
nimbu env remove staging

environments:
  staging:
    host: api.nimbu.io
    site: acme-staging
  production:
    host: api.nimbu.io
    site: acme
    protected: true

Select one with the global --env flag. It takes precedence over --site and the API URL flags. The copy commands also accept environment names in --from and --to, for example nimbu sites copy --from=staging --to=production --dry-run.

--protected makes schema apply and release ask for confirmation on that environment. With --no-input, pass --yes instead. --force does not bypass this confirmation.

Schema files

nimbu schema pull writes the live schemas into schema/:

Each file is a single YAML document with an explicit fields array. For channels, blogs, and checkout profiles, slug must match the filename.

slug: events
name: Events
title_field: title
fields:
  - name: title
    label: Title
    type: string
    required: true
    localized: true
  - name: body
    label: Body
    type: text
    localized: true
  - name: category
    label: Category
    type: select
    options:
      - name: Concert
        slug: concert
      - name: Workshop
        slug: workshop
  - name: venue
    label: Venue
    type: belongs_to
    reference: venues
  - name: summary
    label: Summary
    type: text
    renamed_from: intro

reference names the target channel slug, or products, customers, orders, pages, or articles. To rename a field, change name and set renamed_from to the old name; without it, the plan reports a possible rename and blocks. Interactive schema apply offers to add renamed_from for you.

Pull a subset with --only:

nimbu schema pull --env=staging --only=channels/events,products

pull overwrites the pulled files but keeps local keys it does not manage, such as renamed_from.

Plan and apply

nimbu schema plan --env=production
nimbu schema apply --env=production

plan lists the operations per target with a risk of safe, destructive, or blocked, plus drift and warnings. Its exit code is 0 when nothing changes, 2 for changes (or unresolved references), 3 when a change is destructive, and 1 when the plan is blocked.

apply re-plans, shows the plan, and asks for confirmation. Pass --yes to confirm without a prompt, including destructive changes. Plans carry a fingerprint, so a schema that changed after planning is rejected instead of overwritten. Applies are serialized per site; a second apply that starts while one is running fails with 409. Avoid concurrent schema edits in the admin or through the API while deploying.

Type changes are only planned within compatible families (string, text, email, or integer, float). Other type changes are blocked: add a new field and migrate the data instead.

By default, fields and select options that are missing from a file are reported as drift and left alone. --prune removes them, which deletes the field data. Review plan --prune before running apply --prune.

When you create new channels that reference each other in a cycle, the CLI adds a temporary nimbu_schema_placeholder field to break the cycle. Remove it afterwards with a reviewed schema apply --prune.

Releases

nimbu release --env=production --dry-run
nimbu release --env=production
nimbu releases --env=production

A release runs three stages in order: apply schemas, push cloud code apps, and push the full theme. --only=schema,code,theme limits the stages. --dry-run plans each selected stage without deploying.

Releases deploy the checked-out git commit. A dirty working tree is refused; --allow-dirty deploys it anyway and marks the release as dirty. After all stages succeed, the CLI records the release (commit, ref, environment, and a summary per stage). nimbu releases lists recorded releases.

In CI, pass --no-input --yes to schema apply and release. Rename prompts are disabled during a release, so declare renamed_from in the schema files.

Failures and rollback

There is no automatic rollback. When schema apply or release fails, the error lists the completed, failed, and unattempted targets or stages. Earlier changes stay applied, and the failed target may be partly changed. Inspect the result and run plan again before retrying.

Deploying an older commit does not undo a field rename or bring back pruned data. If a release deployed but could not be recorded, do not redeploy just to record it.