> For the complete documentation index, see [llms.txt](https://docs.collibra.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.collibra.com/data-quality-self-hosted/installation/upgrade-data-quality-observability-self-hosted/roll-back-data-quality-observability-self-hosted/roll-back-a-data-quality-observability-self-hosted-deployment-on-azure-hdinsight.md).

# Roll back a Data Quality & Observability (self-hosted) deployment on Azure HDInsight

In an Azure HDInsight deployment, `dq-webapp` runs on a persistent Azure VM or App Service, `dq-agent` is installed on the HDInsight head node, and `dq-core` runs as a Spark YARN job. The Metastore is an Azure Database for PostgreSQL. Use this procedure to restore the previous version after an unsuccessful upgrade.

The preferred rollback method is an in-place JAR swap on the head node. Cluster deletion is not required and should be avoided.

{% hint style="info" %}
Before you start, confirm you completed the [Roll back Data Quality & Observability (self-hosted)](/data-quality-self-hosted/installation/upgrade-data-quality-observability-self-hosted/roll-back-data-quality-observability-self-hosted.md#pre-upgrade-checklist) before upgrading.
{% endhint %}

## Prerequisites

* SSH access to the HDInsight head node.
* The previous version JARs available in Azure Blob Storage.
* The Metastore snapshot from before the upgrade (required if schema migrations ran).

## In-place rollback (preferred)

{% stepper %}
{% step %}
SSH to the HDInsight head node.

```
ssh sshuser@<cluster-name>-ssh.azurehdinsight.net
```

{% endstep %}

{% step %}
Stop the agent.

```
$OWL_BASE/owl/bin/owlmanage.sh stop=owlagent
```

{% endstep %}

{% step %}
Restore the previous JARs from Blob Storage.

```
cd $OWL_BASE/owl/bin
 
mv dq-agent-<new-version>.jar                      dq-agent-<new-version>.jar.bad
mv dq-core-<new-version>-with-dependencies.jar     dq-core-<new-version>-with-dependencies.jar.bad
 
az storage blob download \
  --account-name <storage-account> \
  --container-name <container> \
  --name dq-agent-<old-version>.jar \
  --file dq-agent-<old-version>.jar
 
az storage blob download \
  --account-name <storage-account> \
  --container-name <container> \
  --name dq-core-<old-version>-with-dependencies.jar \
  --file dq-core-<old-version>-with-dependencies.jar
```

{% endstep %}

{% step %}
Restore the Metastore if schema migrations ran during the upgrade.

{% hint style="info" %}
Skip this step if the upgrade was a patch release with no schema migrations.
{% endhint %}

```
az postgres server restore \
  --resource-group <resource-group> \
  --name <restored-server-name> \
  --source-server <original-server-name> \
  --restore-point-in-time "<timestamp-before-upgrade>"
```

If the restored server has a different hostname, update `$OWL_BASE/owl/config/owl-env.sh` to point to it.
{% endstep %}

{% step %}
Restart the agent.

```
$OWL_BASE/owl/bin/owlmanage.sh start=owlagent
```

{% endstep %}

{% step %}
Roll back `dq-webapp` on the persistent Azure VM if it was upgraded separately.

Follow [Roll back a Spark standalone Data Quality & Observability (self-hosted) deployment](/data-quality-self-hosted/installation/upgrade-data-quality-observability-self-hosted/roll-back-data-quality-observability-self-hosted/roll-back-a-spark-standalone-data-quality-observability-self-hosted-deployment.md#steps) for the webapp VM.
{% endstep %}

{% step %}
Verify the rollback was successful.

```
tail -f $OWL_BASE/owl/log/owl-agent.log
 
psql -h <METASTORE_HOST> -U <METASTORE_USER> -d owldb \
  -c "SELECT agent_name, status, updt_ts FROM agent ORDER BY updt_ts DESC LIMIT 5;"
```

Confirm all items in the [Roll back a Data Quality & Observability (self-hosted) deployment on Azure HDInsight](#verification-checklist).
{% endstep %}
{% endstepper %}

## Cluster recreation (fallback only)

Use this path only if the head node is lost or the cluster must be rebuilt. Recreate the cluster with a Script Action referencing the old version package.

1. Delete the existing cluster.

   ```
   az hdinsight delete --name \<cluster-name\> --resource-group \<resource-group\>
   ```
2. Create a new cluster with a Script Action pointing to the previous version.

   ```
   az hdinsight create \
     --name \<cluster-name\> \
     --resource-group \<resource-group\> \
     --type Spark \
     --component-version Spark=\<version\> \
     --storage-account \<storage-account\> \
     --storage-account-key \<key\> \
     --storage-container \<container\> \
     --script-action name="InstallDQAgent" \
       uri="abfs://\<container\>@\<storage-account\>.dfs.core.windows.net/install-agent.sh" \
       node-types=headnode \
       parameters="\<old-version\> \<OWL_AGENT_ID\> \<METASTORE_HOST\> \<METASTORE_USER\> \<METASTORE_PASS\> \<PACKAGE_PATH\> \<LICENSE_KEY\>" \
     ...
   ```

## Rollback verification checklist

After the rollback, confirm the following before declaring success:

* `dq-webapp` health endpoint returns HTTP 200.
* `dq-webapp` logs show no Flyway version mismatch errors.
* `dq-agent` log shows a successful connection to the Metastore.
* The agent appears as `ACTIVE` in the `agent` table in the Metastore.
* A test job submits successfully and reaches `FINISHED` status in `agent_q`.
* The scheduler picks up and runs a scheduled job (check the `job_schedule_attempt` table).
* The UI loads and displays historical findings correctly.