Salesforce DX Developer Guide

How Salesforce Developer Experience Changes the Way You Work
Set Up Salesforce DX Tools for Developer Users
Project Setup
Authorization
Metadata Coverage
Scratch Orgs
Sandboxes
Track Changes Between Your Project and Org
Development
Build and Release Your App
Unlocked Packages
What’s an Unlocked Package?
Package-Based Development Model
Before You Create Unlocked Packages
Know Your Orgs
Create Org-Dependent Unlocked Packages
Workflow for Unlocked Packages
Configure Unlocked Packages
How We Handle Profile Settings in Unlocked Packages
Develop Unlocked Packages
Push a Package Upgrade for Unlocked Packages
Install an Unlocked Package
Install Packages with the CLI
Install Unlocked Packages from a URL
Upgrade a Version of an Unlocked Package
Sample Script for Installing Unlocked Packages with Dependencies
Migrate Deprecated Metadata from Unlocked Packages
Uninstall an Unlocked Package
Transfer an Unlocked Package to a Different Dev Hub
Continuous Integration
Troubleshoot Salesforce DX
Limitations for Salesforce DX
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Upgrade a Version of an Unlocked Package

Are you introducing metadata changes to an existing package? You can use the CLI to upgrade one package version to another.

When you perform a package upgrade, here’s what to expect for metadata changes.

When you upgrade to a new package version, you choose whether to require successful compilation of all Apex in the org and package (--apex-compile all), or only the Apex in the package (--apex-compile package).

  • Metadata introduced in the new version is installed as part of the upgrade.
  • If an upgraded component has the same API name as a component already in the target org, the component is overwritten with the changes.
  • If a component in the upgrade was deleted from the target org, the component is re-created during the upgrade.
  • Metadata that was removed in the new package version is also removed from the target org as part of the upgrade. Removed metadata is metadata not included in the current package version install, but present in the previous package version installed in the target org. If metadata is removed before the upgrade occurs, the upgrade proceeds normally. Some examples where metadata is deprecated and not deleted are:
    • User-entered data in custom objects and fields are deprecated and not deleted. Admins can export such data if necessary.
    • An object such as an Apex class is deprecated and not deleted if it’s referenced in a Lightning component that is part of the package.
  • In API version 45.0 and later (Salesforce CLI version 45.0.9 or later), you can specify what happens to removed metadata during package upgrade. Use the sf package install command’s -t | --upgrade-type parameter, specifying one of these values:
    • Delete specifies to delete all removed components, except for custom objects and custom fields, that don’t have dependencies.
    • DeprecateOnly specifies that all removed components must be marked deprecated. The removed metadata exists in the target org after package upgrade, but is shown in the UI as deprecated from the package. This option is useful when migrating metadata from one package to another.
    • Mixed (the default) specifies that some removed components are deleted, and other components are marked deprecated. For more information on hard-deleted components, see Hard-Deleted Components in Unlocked Packages.

Beta packages aren’t upgradeable. To install a new beta package or released version, first uninstall the beta package.

For package installs into production orgs, or any org that has Apex Compile on Deploy enabled, the platform compiles all Apex in the org after the package install or upgrade operation completes. This approach assures that package installs and upgrades don’t impact the performance of an org, and is done even if --apex-compile package is specified.

Note