Manage geodatabase upgrades in a service-based architecture

After reviewing the What’s new pages for ArcGIS Pro and ArcGIS Enterprise to learn about new functionality and changes in the software, you may have discovered a new feature you want to use. Your organization may also apply a patch to your ArcGIS applications that targets quality and performance improvements in the software. While you can use many new features just by having the latest ArcGIS client, there are instances where a corresponding geodatabase upgrade is required to use new functionality and patches that introduce quality and performance fixes.

The following will help you better understand what a geodatabase upgrade is, how to know when to upgrade, and which ArcGIS client to use to perform the upgrade.

The ArcGIS clients and DBMS upgrade considerations blog article discussed the importance of ensuring that the database version is supported with all your ArcGIS clients (ArcGIS Enterprise, ArcGIS Pro) to maintain workflow functionality after the upgrade process.

Now you’ll learn about the importance of upgrading your geodatabase to use new features and apply bug fixes. You’ll also learn about maintaining the same release version for the geodatabase and the ArcGIS clients that connect directly to it—particularly in a service-based architecture. Having a clear understanding of this practice is crucial for organizations that use web services referencing enterprise geodatabase data in their workflows.

What is a geodatabase upgrade?

A geodatabase is more than just your user data. It’s built on top of the relational database structure and contains the following components:

• User data
• System repository tables, which are a collection of tables managed by ArcGIS
• Software elements managed by ArcGIS, including packages, stored procedures, triggers, functions, and more

During a geodatabase upgrade, additions and modifications can occur to any of these components.

An enterprise geodatabase is upgraded by the geodatabase administrator using the Upgrade Geodatabase geoprocessing tool, or via the Database Properties dialog.

Check if the geodatabase can be upgraded from the ArcGIS client software

After installing a new ArcGIS product version, review the Database Properties settings as the geodatabase administrator by clicking Database Properties > Geodatabase Version > Upgrade Status. This displays the current geodatabase version and whether an upgrade can be performed.

Note: Starting with ArcGIS Pro 3.1 and ArcGIS Server 11.1, the geodatabase administrator can review the prior versions of the geodatabase along with the upgrade date by accessing the Geodatabase Version History section on the Database Properties dialog box.

When to upgrade a geodatabase

How do you know when you need to upgrade your enterprise geodatabase?
Review the following examples to help you determine if an enterprise geodatabase upgrade is necessary and how it is performed:

• Installing a new client version—It is recommended that you keep the enterprise geodatabase up to date by performing upgrades as you are updating your client applications. This allows you to apply fixes for software defects and other minor enhancements that impact the geodatabase system, even if these changes are not explicitly documented with each software release.
• Installing a new client version for a new feature—Some new features only require you to upgrade your ArcGIS Pro client. If you have upgraded to take advantage of a new feature, review the documentation to learn whether the new feature includes a minimum geodatabase version or lists that a geodatabase upgrade is required.
  Examples:
  • To use new data types—such as big integer, date only, time only, and timestamp with offset—both a client and geodatabase upgrade are required. To be able to create these new field types with ArcGIS Pro 3.2, you must upgrade your enterprise geodatabase to a minimum of 11.2.
  • With the ArcGIS Pro 3.2 release, you can use the Generate Schema Report geoprocessing tool to export your geodatabase schema to an output format like XLSX for use in Microsoft Excel. Using this tool does not require an upgraded geodatabase.
• Applying a patch—Patches are targeted fixes applied to an existing ArcGIS client version. These small software updates typically address specific issues or security vulnerabilities, without introducing any major new features. Review the documentation for the patch you are applying to learn whether a geodatabase upgrade is required. These could be ArcGIS Server or ArcGIS Pro patches. Use the ArcGIS client you applied the patch to when upgrading your geodatabase. For more information and to see available patches, check Featured patches and updates.

Which ArcGIS client to use for the geodatabase upgrade

As previously mentioned, you must maintain the version of your enterprise geodatabase at the same release as your ArcGIS clients. But how do you know which ArcGIS client matches your geodatabase version?  The answer depends on your workflow.

The above diagram shows the possible client environments for accessing enterprise geodatabase data sources:

• Client/server, also known as direct connect, refers to an environment in which the ArcGIS Pro software is the main client interacting directly with the enterprise geodatabase through a database connection. This is commonly referred to as direct connect.
• Services refers to an environment in which the enterprise geodatabase data is accessed from a service. These services can be accessed from ArcGIS Pro, web maps, or apps with an ArcGIS Enterprise portal.

After identifying the type of environment you are working in, you can understand where the geodatabase upgrade must be performed. The following example can help you identify the correct ArcGIS client to perform a geodatabase upgrade.

Upgrade a geodatabase from a client/server environment

If your organization uses editing workflows in which you are connecting directly to the database through a database connection (for example, workflows with traditional versioned data), the geodatabase upgrade can be performed by any client. Typically, in this example, the most common client to perform an upgrade from is ArcGIS Pro.

After updating your ArcGIS Pro client to the desired version, use the Upgrade Geodatabase tool or a Python script. This will upgrade your geodatabase to match the release of ArcGIS Pro.

For instance, an organization that has recently upgraded its ArcGIS Pro client from 2.9 to 3.1 will use the Upgrade Geodatabase tool as the geodatabase administrator. When the geodatabase is upgraded in ArcGIS Pro, the resulting geodatabase version is 11.1.0.41833. You can see that the geodatabase version number uses a combination of the corresponding ArcGIS Enterprise release number (for example, 10.x or 11.x) and a unique build number, typically composed of five digits (for example, 41833).

The following table shows the equivalent ArcGIS Enterprise and ArcGIS Pro releases and their resulting geodatabase release.

A Python script can also be used to check the current version of the geodatabase and perform an upgrade if the geodatabase version is not at the same release as your client.

import arcpy

sde_file = r'<path to SDE file>’

if not arcpy.Describe(sde_file).currentRelease:
print(“Upgrading Geodatabase…”)
arcpy.management.UpgradeGDB(sde_file, “PREREQUISITE_CHECK”, “UPGRADE”)
print(arcpy.GetMessages())
else:
print(“Geodatabase already latest release”)

Upgrade a geodatabase from a service-based environment

If you are working in a services-based editing environment (for example, workflows with branch versioned data) you can perform the geodatabase upgrade in ArcGIS Enterprise. This is particularly beneficial when the geodatabase version is older or at the same release as the ArcGIS Enterprise version.

Perform a geodatabase upgrade in ArcGIS Enterprise

When installing an ArcGIS Server Utility Network and Data Management Patch, for example, you must perform the geodatabase upgrade in ArcGIS Enterprise.

In service-based architectures, the ArcGIS Enterprise software components are considered the client that connects directly to the geodatabase. In this type of environment, it is recommended that you keep the ArcGIS Enterprise client at an identical release to the geodatabase version.
Examples using services based workflows:

• You are using branch versioned data when the data editing and administration is done through the services
• You use clients that connect to a web service, such as ArcGIS Field Maps or ArcGIS Survey123

ArcGIS Server includes the ArcPy site package, which allows you to run most of the same geoprocessing tools from your ArcGIS Server machine using Python that you can run from ArcGIS Pro.

It is important to understand the python.exe path used will determine whether ArcGIS Pro or ArcGIS Enterprise is used to perform the upgrade.

ArcGIS Enterprise path: arcgis_server_installation_directory>\framework\runtime\ArcGIS\bin\Python\envs\arcgispro-py3
eg: C:\Program Files\ArcGIS\Server\framework\runtime\ArcGIS\bin\Python\envs\arcgispro-py3

ArcGIS Pro path: arcgis_pro_installation_directory>\bin\Python\envs\arcgispro-py3
eg: C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3

The next example uses a Windows machine.

The following is a Python script using the arcpy.UpgradeGDB_management operation to upgrade an enterprise geodatabase.

#Update .sde file to a valid connection established as the geodatabase administrator
import arcpy

arcpy.UpgradeGDB_management(

input_workspace=r”c:\junk\SQLServer-mjarman-marketing(sde).sde”,

input_prerequisite_check=”PREREQUISITE_CHECK”,

input_upgradegdb_check=”UPGRADE”)

warnings = arcpy.GetMessages(1)

errors = arcpy.GetMessages(2)

print(warnings)

print(errors)

When you create or upgrade a geodatabase from a server client, the geodatabase version is the ArcGIS Enterprise 10.x release number only.

Note: See the following topics for more information:
ArcGIS Server and ArcPy – Windows
ArcGIS Server and ArcPy – Linux

Mixed clients and geodatabase incompatibility

The practices outlined above are particularly effective when both the ArcGIS Pro and ArcGIS Enterprise clients are up to date. For instance, if you upgrade ArcGIS Pro to version 3.4, it is recommended that you upgrade ArcGIS Enterprise to version 11.4. Keeping all ArcGIS products updated is important as the software is designed to work together, allowing you to use the latest features and performance enhancements. This is even more important when working with data through published services, especially for complex data like utility networks, parcel fabrics, and other branch versioned data.

However, in some situations, the geodatabase version does not match the ArcGIS Server release. It is common to encounter a variety of ArcGIS client versions at a single site where one client, for example ArcGIS Pro is updated frequently, and ArcGIS Enterprise remains a few versions behind.

It’s important to explore strategies for planning a geodatabase upgrade to prevent compatibility issues between older and newer clients. A significant disparity in client versions can result in the geodatabase entering an incompatible state.

For example, a more recent client may introduce new dataset types or functionalities in the geodatabase that are inaccessible to older clients. After you create a new geodatabase or upgrade an existing geodatabase to version 3.0 to use catalog datasets in your workflows, you will find that access is restricted from any version of ArcGIS Pro earlier than 3.0 or ArcGIS Enterprise earlier than 11.0.

Attempting to access a newer dataset type from an older ArcGIS client will trigger an error message indicating the incompatibility:

The version of the Geodatabase client is incompatible with the dataset and cannot open it. Failed to add data, unsupported data type.

Note: For more information on types of datasets that are not supported with a specific ArcGIS client release, access the Client and geodatabase compatibility documentation.

Although rare, another example of incompatible state is when the geodatabase version is newer than the ArcGIS Enterprise client version. If you have upgraded your enterprise geodatabase using an ArcGIS Pro client that is more up to date than the ArcGIS Enterprise release, and a critical patch is released for your ArcGIS Server version that requires a geodatabase upgrade, then you cannot upgrade your geodatabase using the patched ArcGIS Enterprise.

Instead, you would need to wait and install a comparable patch for your ArcGIS Pro client that was last used to upgrade the enterprise geodatabase. Alternatively, you could upgrade your ArcGIS Server client to an equivalent version of ArcGIS Pro (for example, ArcGIS Server 11.1 and ArcGIS Pro 3.1 or ArcGIS Server 11.2 and ArcGIS Pro 3.2) and then apply the critical patch to ArcGIS Enterprise and upgrade from there.

Keeping your geodatabase aligned with your ArcGIS clients allows you to avoid problems down the road. Whether you’re working in a direct connect or service-based environment, understanding when and how to upgrade your geodatabase prevents workflow disruptions caused by version mismatches while allowing you to use the latest features.

The key takeaway: Don’t treat geodatabase upgrades as an afterthought. Make them part of your regular upgrade planning process. Review the documentation, check compatibility, and choose the right client—ArcGIS Pro or ArcGIS Enterprise—based on how your organization accesses data. And if you’re unsure, reach out to Esri Support Services or to Esri Professional Services for a more detailed approach, including architecture review and upgrade path. A little planning now can save a lot of troubleshooting later.

For additional resources on spatial data management check out the Geodatabase Resources Hub.