Upgrade a geodatabase in Db2

Available with Standard or Advanced license.

The goal of upgrading an enterprise geodatabase is to update the geodatabase system tables, stored procedures, types, and functions to take advantage of new functionality and bug fixes. You may also need to upgrade the database if the version you use is no longer supported for the ArcGIS clients you use.

Install a new version of ArcGIS Pro or ArcGIS Server or apply a service pack, patch, or hot fix to an existing installation and upgrade the geodatabase.

Note:

Even if you do not upgrade the geodatabase, the database version you use may no longer be supported with the current release of ArcGIS software. Always check the system requirements to ensure you're still using a supported database release. If the database version is no longer supported, you may need to upgrade the geodatabase. The longer you go between upgrades, the more involved the upgrade process becomes.

When you upgrade the geodatabase using ArcGIS Pro 3.3, the upgraded geodatabase version is 11.3.0.

Complete the required steps prior to upgrading, and upgrade the geodatabase using the Upgrade Geodatabase geoprocessing tool or a Python script.

Before you upgrade

Plan ahead before you upgrade any enterprise system, including a geodatabase. Test the new version on a development or test server to ensure that it works with all your client applications.

When you determine that the new system works the way you expect, schedule the upgrade; be sure the necessary staff are available to perform the upgrade and that they have the permissions necessary to complete their assigned tasks.

Be aware of the following:

  • Upgrades from beta or prerelease versions of the software are not supported.
  • You can upgrade directly from a 10.7.x, 10.8.x, 10.9.x, or 11.x geodatabase if your database release is supported for the ArcGIS versions to which you upgrade.

    If the IBM Db2 database is not at a release that is supported for the current geodatabase release, you may have to upgrade the database and the geodatabase more than once before you can upgrade the geodatabase to the current release. The longer you go between geodatabase upgrades, the more upgrades you will have to do to get to the latest geodatabase release.

    For each intermediate geodatabase upgrade, follow the upgrade instructions for that geodatabase version, and test the geodatabase as you move from version to version. Similarly, follow the upgrade instructions from the database vendor for each database version, and test as you move from version to version.

  • There is no formal mechanism to downgrade a geodatabase to a previous version. If, after upgrading to a newer version, you want to downgrade the geodatabase, you can restore the database from a backup file that contains the older geodatabase version.

The following is a checklist of steps to complete before you upgrade the geodatabase:

  1. Ensure that the Db2 and ArcGIS version combination you want to use is supported. See IBM Db2 database requirements for ArcGIS for information.

    The database must be at a supported release and your hardware must meet the minimum system requirements before you upgrade the geodatabase.

  2. Confirm that the geodatabase can be upgraded. To do this, install the ArcGIS client version you want to move to onto one machine. If you install ArcGIS Desktop, you can connect to the geodatabase and open the Database Properties dialog box to determine whether a geodatabase upgrade is possible. If you install ArcGIS Server (Enterprise edition) or the ArcGIS Engine Geodatabase Update extension, you can use the ArcPy Describe function to determine whether the geodatabase can be upgraded. The following example creates a connection to the geodatabase and checks whether the geodatabase can be upgraded:
    # Open Python.
    cd /arcgis/server/tools
    ./python
    
    # Create a connection to the geodatabase.
    arcpy.CreateDatabaseConnection_management("/tmp/",
                                              "egdb_connection.sde",
                                              "DB2",
                                              "mydbgdb",
                                              "DATABASE_AUTH",
                                              "sde",
                                              "mysdepassword",
                                              "SAVE_USERNAME")
    
    # Import ArcPy and check the geodatabase release.
    import arcpy
    
    isCurrent = arcpy.Describe('/tmp/egdb_connection.sde').currentRelease
    
    print isCurrent

    If false is returned, you can upgrade the geodatabase. If true is returned, you do not need to upgrade the geodatabase. Do not proceed with the subsequent steps.

  3. Create a backup of the database.
  4. The sde user must run the MON_GET_CONNECTION function to remove unneeded connections from the PROCESS_INFORMATION system table. Therefore, grant the EXECUTE privilege on the MON_GET_CONNECTION function to the sde user.

    GRANT EXECUTE 
     ON MON_GET_CONNECTION 
     TO SDE;

  5. If your database administrator has revoked the SELECT privilege on the SYSIBM.SYSDUMMY1 catalog view, the administrator must grant the privilege to all users who connect to the geodatabase in Db2.

    This privilege is necessary for SQL queries to the database.

    If users do not have the SELECT privilege on this catalog view, they see an error similar to the following when they try to connect:

    SQL0551N  "SASHA" does not have the privilege to perform operation "SELECT" on object "SYSIBM.SYSDUMMY1".  SQLSTATE=42501

    To grant the SELECT privilege on this view to PUBLIC, issue the following command while signed in as a user with DBADM authority in the database:

    GRANT SELECT 
     ON SYSIBM.SYSDUMMY1 
     TO PUBLIC;
  6. Grant the sde user DBADM authority in the database.

    This is required to upgrade a geodatabase and can be revoked after upgrading.

  7. Remove any custom functionality you have added to the geodatabase system tables outside ArcGIS, such as triggers or additional indexes.

    The upgrade procedure cannot accommodate customizations you make to the system tables. If such customizations prevent the alteration of a system table's schema, the upgrade will fail.

  8. At this point, consider creating a second backup of the database to preserve the changes you made in the preceding steps.
  9. Install the current release of an ArcGIS client—ArcGIS Pro Desktop Standard or Desktop Advanced or ArcGIS Server (enterprise edition)—on a computer that can connect to the geodatabase to perform the upgrade.
  10. Ensure that there are no connections to the geodatabase you are upgrading.

    To see a list of who is currently connected to the geodatabase, go to the Geodatabase Administration dialog box in ArcGIS Pro.

You can now upgrade the geodatabase.

Upgrade the geodatabase

You can use the Upgrade Geodatabase tool in ArcGIS Pro or a Python script run on an ArcGIS Pro or ArcGIS Server machine to upgrade your geodatabase.

Note:

If the geodatabase contains branch versioned data, additional postupgrade steps may be required. See How Upgrade Geodatabase works for instructions.

Use the Upgrade Geodatabase tool

Open the Upgrade Geodatabase geoprocessing tool from one of the following:

  • The Geodatabase Administration toolset in the Data Management toolbox
  • The Run Upgrade button on the General tab of the Database Properties dialog box in ArcGIS Pro

If you open the tool from Database Properties, the Input geodatabase text box is prepopulated with the geodatabase connection information.

Esri recommends that you leave the Pre-requisites check and Upgrade geodatabase options checked. That way, the tool confirms that the prerequisites to upgrade have been met before continuing with the geodatabase upgrade.

The prerequisite check detects other active connections to the geodatabase, determines whether the connecting user has sufficient privileges to upgrade the geodatabase, ensures that the database can support XML columns, ensures that all datasets can be opened, and confirms that the database and libraries are at the same release. If any prerequisites are not met, the tool terminates. You must correct any problems before you run the upgrade procedure again.

The results of this check are reported on the geoprocessing tool dialog box. If the check fails, results are also written to the GDBUpgrade.log file in the c:\Users\<user name>\AppData\Local\ESRI\<ArcGIS product> folder.

If all checks pass, the tool proceeds with the upgrade. The status for the prerequisites check and the upgrade are shown on the geoprocessing tool progress dialog box. If the upgrade fails, information is written to the GDBUpgrade.log file. Additional information is written to the sde_setup.log file in your user TEMP directory. If your user does not have a temp directory configured, the system TEMP directory is used.

Run a script

To upgrade the geodatabase using a Python script, copy one of these example scripts into a text editor. Alter any variable values to match the information at your site.

  • If you have an existing database connection file that connects as the sde user, copy the script that applies to your operating system, paste it into a text editor, alter it to use information specific to your site, save and close the file, and run it:
    # Name: upgradesdegdb_example.py
    # Description: Connect from a Windows computer 
    # with an existing database connection file 
    # and upgrade an enterprise geodatabase
    
    # Import arcpy module
    import arcpy
     
    # Local variables:
    Output_Workspace = "C:\\ArcGIS\connection_files\<Connection file>"
    Default_gdb = "C:\\ArcGIS\connection_files\<Connection file>"
    
    # Process: Upgrade Geodatabase
    arcpy.UpgradeGDB_management(Default_gdb, "PREREQUISITE_CHECK", "UPGRADE")
    # Name: upgradesdegdb_example.py
    # Description: Connect from a Linux or UNIX computer 
    # with an existing database connection file 
    # and upgrade an enterprise geodatabase
    
    # Import arcpy module
    import arcpy
     
    # Local variables:
    Output_Workspace = "<user>/connections/<Connection_file>"
    Default_gdb = "<user>/connections/<Connection_file>"
    
    # Process: Upgrade Geodatabase
    arcpy.UpgradeGDB_management(Default_gdb, "PREREQUISITE_CHECK", "UPGRADE")
  • If you do not have a database connection file on the computer from which you are scripting the upgrade, you can copy the following script and provide your site-specific information at the command line:
    """
    Name: upgrade_gdb.py
    Description: Provide connection information to an Enterprise geodatabase 
    and upgrade the geodatabase
    Type upgrade_gdb.py -h or upgrade_gdb.py --help for usage
    """
    
    # Import system modules
    import arcpy
    import os
    import optparse
    import sys
    
    
    # Define usage and version
    parser = optparse.OptionParser(usage = "usage: %prog [Options]", version="%prog 2.0; valid for 10.1 only")
    
    #Define help and options
    parser.add_option ("--DBMS", dest="Database_type", type="choice", choices=['SQLSERVER', 'ORACLE', 'POSTGRESQL', 'DB2','INFORMIX','DB2ZOS',''], default="", help="Type of enterprise DBMS:  SQLSERVER, ORACLE, or POSTGRESQL.")
    parser.add_option ("-i", dest="Instance", type="string", default="", help="DBMS instance name")
    parser.add_option ("--auth", dest="account_authentication", type ="choice", choices=['DATABASE_AUTH', 'OPERATING_SYSTEM_AUTH'], default='DATABASE_AUTH', help="Authentication type options (case-sensitive):  DATABASE_AUTH, OPERATING_SYSTEM_AUTH.  Default=DATABASE_AUTH")
    parser.add_option ("-u", dest="User", type="string", default="", help="Geodatabase administrator user name")
    parser.add_option ("-p", dest="Password", type="string", default="", help="Geodatabase administrator password")
    parser.add_option ("--upgrade", dest="Upgrade", type="choice", choices=['TRUE', 'FALSE'], default="FALSE", help="Upgrade Options (case-sensitive):  TRUE=Perform Pre-requisite check and upgrade geodatabase, FALSE=Perform Pre-requisite check only.  Default=FALSE")                   
    parser.add_option ("-D", dest="Database", type="string", default="none", help="Database name:  Not required for Oracle")
    
    
    # Check if value entered for option
    try:
    	(options, args) = parser.parse_args()
    
    	
    #Check if no system arguments (options) entered
    	if len(sys.argv) == 1:
    		print("%s: error: %s\n" % (sys.argv[0], "No command options given"))
    		parser.print_help()
    		sys.exit(3)
    
    	#Usage parameters for spatial database connection to upgrade
    	account_authentication = options.account_authentication.upper()
    	username = options.User.lower() 
    	password = options.Password	
    	do_upgrade = options.Upgrade
    	database = options.Database.lower()
    	database_type = options.Database_type.upper()
    	instance = options.Instance
    	
    	if (database_type == ""):
    		print("\nDatabase type must be specified!\n")
    		parser.print_help()
    		sys.exit(3)
    	
    	if (database_type == "SQLSERVER"):
    		database_type = "SQL_SERVER"
    	
    	# Get the current product license
    	product_license=arcpy.ProductInfo()
    	
    	# Checks required license level to upgrade
    	if product_license.upper() == "ARCVIEW" or product_license.upper() == 'ENGINE':
    		print("\n" + product_license + " license found!" + "  Enterprise geodatabase upgrade requires an ArcGIS Desktop Standard or Advanced, ArcGIS Engine with the Geodatabase Update extension, or ArcGIS Server license.")
    		sys.exit("Re-authorize ArcGIS before upgrading.")
    	else:
    		print("\n" + product_license + " license available!  Continuing to upgrade...")
    		arcpy.AddMessage("+++++++++")
    	
    	# Local variables
    	instance_temp = instance.replace("\\","_")
    	instance_temp = instance_temp.replace("/","_")
    	instance_temp = instance_temp.replace(":","_")
    	Conn_File_NameT = instance_temp + "_" + database + "_" + username     
    	
    	if os.environ.get("TEMP") == None:
    		temp = "c:\\temp"	
    	else:
    		temp = os.environ.get("TEMP")
    	
    	if os.environ.get("TMP") == None:
    		temp = "/usr/tmp"		
    	else:
    		temp = os.environ.get("TMP")  
    	
    	Connection_File_Name = Conn_File_NameT + ".sde"
    	Connection_File_Name_full_path = temp + os.sep + Conn_File_NameT + ".sde"
    	
    	# Check for the .sde file and delete it if present
    	arcpy.env.overwriteOutput=True
    	if os.path.exists(Connection_File_Name_full_path):
    		os.remove(Connection_File_Name_full_path)
    	
    	print("\nCreating Database Connection File...\n")
    	# Process: Create Database Connection File...
    	# Usage:  out_file_location, out_file_name, DBMS_TYPE, instnace, database, account_authentication, username, password, save_username_password(must be true)
    	arcpy.CreateDatabaseConnection_management(out_folder_path=temp, out_name=Connection_File_Name, database_platform=database_type, instance=instance, database=database, account_authentication=account_authentication, username=username, password=password, save_user_pass="TRUE")
            for i in range(arcpy.GetMessageCount()):
    		if "000565" in arcpy.GetMessage(i):   #Check if database connection was successful
    			arcpy.AddReturnMessage(i)
    			arcpy.AddMessage("\n+++++++++")
    			arcpy.AddMessage("Exiting!!")
    			arcpy.AddMessage("+++++++++\n")
    			sys.exit(3)            
    		else:
    			arcpy.AddReturnMessage(i)
    			arcpy.AddMessage("+++++++++\n")
    			
    	# Check whether geodatabase needs upgrade
    	isCurrent = arcpy.Describe(Connection_File_Name_full_path).currentRelease
    	
    	if isCurrent == True:
    		print("The geodatabase is already at the current release and cannot be upgraded!")
    		sys.exit("Upgrade did not run.")
    	
    	
    	# Process: Upgrade geodatabase...
    	try:
    		if do_upgrade.lower() == "true":
    			print("Upgrading Geodatabase...\n")
    			arcpy.UpgradeGDB_management(input_workspace=Connection_File_Name_full_path, input_prerequisite_check="PREREQUISITE_CHECK", input_upgradegdb_check="UPGRADE")
    			for i in range(arcpy.GetMessageCount()):
    				arcpy.AddReturnMessage(i)
    			arcpy.AddMessage("+++++++++\n")
    	
    		else:
    			print("Running Pre-Requisite Check...\n")
    			arcpy.UpgradeGDB_management(input_workspace=Connection_File_Name_full_path, input_prerequisite_check="PREREQUISITE_CHECK", input_upgradegdb_check="NO_UPGRADE")
    			for i in range(arcpy.GetMessageCount()):
    				arcpy.AddReturnMessage(i)
    			arcpy.AddMessage("+++++++++\n")
    		
    	        
    	except:
    		for i in range(arcpy.GetMessageCount()):
    			arcpy.AddReturnMessage(i)
    		
    	if os.path.exists(Connection_File_Name_full_path):
    		os.remove(Connection_File_Name_full_path)
    	
    #Check if no value entered for option	
    except SystemExit as e:
    	if e.code == 2:
    		parser.usage = ""
    		print("\n")
    		parser.print_help()
    		parser.exit(2)
    For example, if you saved the text file as gdbupgrade and your cataloged database is mydbgdb, type the following at a command prompt:

    gdbupgrade --DBMS DB2 -i mydbgdb --auth DATABASE_AUTH -u sde -p mysdepassword --upgrade TRUE