Package maintainer pre-inst script `install` vs `upgrade`

According to the Debian package maintainer script documentation, the pre-install script can be called with either the install or the upgrade first argument:

The preinst script may be called in the following ways:

new-preinst install

new-preinst install old-version new-version

new-preinst upgrade old-version new-version

What is the difference between install old-version new-version and upgrade old-version new-version? The first form (just install) seems clear, but I don’t understand the difference between install and upgrade where the old and new version numbers are also specified.

Asked By: Jason C

Source

This is explained in the “details” section:

if the package is already fully installed, preinst is called with upgrade and the old and new versions;
if the package was previously installed, and still has its configuration files (it is in “Config-Files” state, i.e. it shows up as rc in dpkg -l’s output), preinst is called with install and the old and new versions;
if the package is being newly installed, or was previously purged, preinst is called with install and no version information.

Since preinst runs before the unpack phase, upgrade indicates that a previous version of the package’s contents is available, whereas install indicates that no version of the package’s contents is present (other than configuration files). Separately, if version information is provided, that indicates that there might be configuration files needing to be handled.

There aren’t many scenarios where the difference between upgrade and install is significant, but one that does spring to mind is upgrades that involve exporting data. For example, in upgrade mode, slapd’s preinst exports its databases; it can’t do that in install mode because the appropriate tools aren’t present.

Answered By: Stephen Kitt

Consider:

You install package A, version x.
You remove package A, but withuot purging, so conffiles, users, groups etc. remain.
You install package A, version y.

Now the maintainer scripts need to handle these conffiles, users, groups, etc., even though strictly speaking, you’re not upgrading, but just installing. You can see this in the second flowchart here: "Installing a package that was previously removed, but not purged"

Answered By: muru