/ 
App-Netdisco-2.116000
⭐ Starred 676 / netdisco-db-deploy

NAME

netdisco-db-deploy - Database deployment for Netdisco

USAGE

This script upgrades or initializes a Netdisco database schema.

~/bin/netdisco-db-deploy [--redeploy-all | --force-step N | --check]

This script connects to the database and runs without user interaction. If there's no Netdisco schema, it is deployed. If there's an unversioned schema then versioning is added, and updates applied. Otherwise only necessary updates are applied to an already versioned schema.

Pre-existing requirements are that there's a working database connection and a user with rights to create tables in that database. These settings are defined in your environment YAML file (default ~/environments/deployment.yml).

From version 38 on, if a step fails, the script stops at that step and exits non-zero. Nothing from the failed step is applied. The message names the step file, the failing statement and the PostgreSQL error, and prints the commands to go on.

OPTIONS

--redeploy-all

Replays every upgrade step from version 2, tolerating the errors that come from steps already applied. It changes no data that Netdisco or an administrator maintains. It repeats one cleanup: step 39-40 deletes vlan-0 node rows that duplicate the same MAC address, switch and port on another VLAN.

--force-step N

Forces step N (from version N to N+1) when it keeps failing and you cannot fix the cause. N must be the next pending step. The failing statements in that step are skipped, the version is stamped, and a row is written to the schema_step_forced table so the skip is recorded. The upgrade then carries on with the following steps. Run netdisco-db-deploy --check afterwards to see what is missing. Once step N is applied, the option is no longer needed; if it is left in place, the script warns and carries on.

--check

Compares this database's schema with a fresh install of the same version and lists the differences, without changing anything. It exits 0 when they match and 1 when they differ. It builds the fresh install in a temporary schema and drops it afterwards, so the database user needs the CREATE privilege on the database, which an owner has; without it the check exits 2 and prints how to grant it. The database must already be at this version: on any other version the check exits 2 and asks for the upgrade first, because steps not yet applied would show as differences.

CONTAINERS

In the Netdisco Docker images and the Helm chart, this script runs in the db-init container. To pass it one of the options above, set NETDISCO_DB_DEPLOY_ARGS (for example NETDISCO_DB_DEPLOY_ARGS=--force-step 57 in .env for docker compose, or dbInit.deployArgs in the helm values), then rerun your docker compose up command or helm upgrade. Remove the setting again once the upgrade has finished.

For more database info see the netdisco wiki.

VERSIONS

  • Version 1 is a completely empty database schema with no tables

  • Version 2 is the "classic" Netdisco database schema as of Netdisco 1.1

  • Versions 5 to 16 add patches for Netdisco 1.2

  • Version 17 onwards deploys schema upgrades for Netdisco 2

  • Version 38 (2.023000) onwards applies each step completely or not at all (except under --redeploy-all or for a step named by --force-step)