Salesforce DX Developer Guide

How Salesforce Developer Experience Changes the Way You Work
Enable Dev Hub Features in Your Org
Project Setup
Authorization
Metadata Coverage
Scratch Orgs
Sandboxes
Track Changes Between Your Project and Org
Development
Build and Release Your App
First-Generation Managed Packages
Second-Generation Managed Packages
Partner Licensing Platform (Developer Preview)
Unlocked Packages
What’s a Package
Package-Based Development Model
Before You Create Unlocked Packages
Know Your Orgs
Create Org-Dependent Unlocked Packages
Workflow for Unlocked Packages
Configure Packages
How We Handle Profile Settings in Unlocked Packages
Create a Package
Push a Package Upgrade
Install a Package
Install Packages with the CLI
Install Packages from a URL
Upgrade a Package Version
Sample Script for Installing Packages with Dependencies
Migrate Deprecated Metadata from Unlocked Packages
Uninstall a Package
Transfer an Unlocked Package to a Different Dev Hub (Beta)
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 Package Version

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.
  • 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 is 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 force:package:install command’s -t | --upgradetype 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.

When you upgrade to a new package version, you choose whether to require successful compilation of all Apex in the org and package (--apexcompile all), or only the Apex in the package (--apexcompile 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 --apexcompile package is specified.

Note