Deploy and rollback

Two pointers matter. The environment points at one active deployment: the code and the graph a new run uses. An asset points at one latest materialization: the result readers treat as current. Deploying and rolling back are writes to those pointers.

Deploy

puppi deploy builds the project, asks the engine whether it already has this bundle, and uploads the bytes only when it does not. It then sends the manifest. On success it moves the environment’s active deployment to the new row. The previous deployment stays in the history. A run keeps the deployment it started on, so a deploy during a run leaves that run on the code it started with.

puppi deploy --env hello
puppi deploy --env hello --no-activate

--no-activate stores the deployment and leaves the pointer where it is.

A rejected manifest is still recorded as a failed deployment. The environment’s pointer stays put. The command prints the validation errors and exits 1. Typical refusals are a cycle, a connection the config does not declare, or a connection with no binding in the environment.

Allow a schema change

The engine compares each asset’s declared schema with the schema on the deployment that is active now. On a lenient environment a change is a warning and the deploy still activates. strict defaults to false, and puppi env create does not set it. On a strict environment the deploy is rejected until you name each changed asset:

puppi deploy --allow-contract-change core/customer

Repeat the flag for each key. The key has to be an asset whose declared schema actually changed, and the same key cannot be repeated. The acknowledgement is stored on that deployment and is not reused by the next one.

Activation also re-checks data that is already stored. For every asset with a schema, the engine compares the new contract with the columns recorded on the current latest materialization. No asset runs. A mismatch can mark that materialization quarantined. See Quarantine.

Roll back the code

Point the environment at an older deployment whose status is ready:

curl -X POST \
  -H "Authorization: Bearer $PUPPI_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "$PUPPI_ENGINE_URL/api/v1/deployments/<id>/activate"

PUPPI_ENGINE_URL defaults to http://127.0.0.1:4000 for the CLI. The CLI has no subcommand for this. GET /api/v1/environments/<name>/deployments lists the ids, newest first.

Activation re-checks stored data against the schemas in the deployment you pointed at. A quarantine that came from a schema change lifts when the previous contract matches the stored columns again.

Roll back the data

puppi rollback moves an asset’s latest pointer to an earlier materialization. It leaves the active deployment where it is.

puppi rollback core/customer
puppi rollback core/customer --to <materialization-id>

Without --to, the target is the newest materialization behind the current latest that is still retained and not quarantined.

The command succeeds for a full copy: a model in table mode (the default) or a source in full_refresh mode (the default). It refuses an append source, an incremental model, a view, and a destination. It also refuses a quarantined materialization, and one outside the newest two the engine keeps.

After the pointer moves, the engine walks downstream. An asset that already has a materialization built from the inputs that are now latest is repointed. An asset that does not is rebuilt in a new run. A destination in that run is delivered again, because moving a pointer leaves the system it already wrote to unchanged. puppi rollback waits for that run when there is one.

See Materializations for what latest points at.