# Running and verifying the deploy

Pipeline: `db-deploy-pipeline` (definition: `execute_db_deploy_jenkinsfile` at
the root of `theorchard/database`). One run per environment — triggered in
parallel when there's more than one (see "Running it" below).

**The job name and parameters are already known — don't spend time rediscovering
them.** `jobFullName` for the Jenkins MCP tools is `db-deploy-pipeline`, and its
parameters are exactly the ones listed under "Running it" below. There's no
need to call `getJobs`/`getJob` to search for or confirm the job first; go
straight to `triggerBuild` once the ordering gate and user confirmation are
satisfied.

## Before running it — the ordering gate

Two things must both already be true, or the run will fail:

1. **The `terraform-infra` PR is merged AND applied** — not just merged. The
   apply is what actually creates the service user/role in Snowflake; the
   Jenkins run will fail on authentication/authorization if it's only merged.
   Confirm this explicitly with the user (they may need to check with whoever
   runs applies, or check the apply job themselves) — don't assume merged
   implies applied.
2. **The `db.properties`/`rsa_key.p8` for that environment are uploaded to
   S3** (see `references/database-repo.md` step 2) — the deploy job pulls
   these fresh from `s3://nickelback/db-deploy/<ENV>/snowflake/<DB_FOLDER>/`
   at run time.

## Running it

Trigger `db-deploy-pipeline` (`triggerBuild` with `jobFullName: "db-deploy-pipeline"`)
with parameters:
- `ENV` — the environment being deployed (`qa`, `prod`, etc.)
- `PR_NUMBER` — the database-repo PR number from
  `references/database-repo.md` step 5
- `type` — `update` (not `rollback`, for an initial onboarding)

The pipeline's first stage checks the PR has been approved
(`pr_approval_check.py --pr-number <PR_NUMBER> --raise-exception`) and fails
immediately if not — the database-repo PR needs at least one approval before
this will proceed. It then runs directly off the PR branch
(`refs/remotes/origin/pr/<PR_NUMBER>/head`) via the downstream `db-deploy` job
— no need to merge the database-repo PR first.

Mechanically, `db_deploy.sh` diffs the PR branch against `master` to find
changed `.xml`/`.sql`/`.cypher` files (excluding `pom.xml`) and runs Liquibase
against each one found — which is why only the *new* connection-check
changeset gets executed, not the whole changelog history.

Get explicit user confirmation before triggering the run(s) — this executes a
real deploy against Snowflake, even though this particular changeset is a
harmless `SELECT`. For a multi-environment database, confirm once for all
environments together (the plan from `SKILL.md` step 2 already lists them),
then **trigger every environment's `triggerBuild` call in parallel** — they're
independent runs (different `ENV` parameter, different Snowflake database),
so there's no reason to wait for qa's build to finish before starting prod's.

## Verifying success

Use the Jenkins MCP tools (`getBuild`, `getBuildLog`, `getTestResults`, etc.)
rather than asking the user to check the Jenkins UI themselves. When multiple
environments were triggered in parallel, check them in parallel too — don't
wait on qa's result before checking prod's.

1. Check `db-deploy-pipeline`'s build result for each run you
   triggered.
2. Each triggers a downstream `db-deploy` build — check that build's result
   too; a green outer build with a failed inner build is still a failure.
3. On failure, pull the build log and summarize the actual error rather than
   just reporting "it failed" — most failures at this stage are either the
   ordering gate above (role/service user not applied yet, or S3 upload
   missing/wrong path) or a typo in `db.properties`/the tfvars blocks.

Report per-environment pass/fail clearly; if any environment failed, don't
proceed to declare the database "onboarded" — surface the failure and likely
cause, and stop there for the user to decide next steps.