1.11 Migrating Property Graph Applications from Before Release 21c

If you are migrating from a previous version of Oracle Spatial and Graph to Release 21c, you may need to make some changes to existing property graph-related applications.

Also note that Oracle Graph Server and Client is required for property graph applications. This can be downloaded from Oracle Software Delivery Cloud or from Oracle Downloads page.

Security-Related Changes

The Property Graph feature contains a series of enhancements to further strengthen the security of the property graph component of product. The following enhancements may require manual changes to existing graph applications so that they continue to work properly.

• Graph configuration files now require sensitive information such as passwords to be stored in Java Keystore files

  If you use graph configuration files you are required to use Java Keystore files to store sensitive information such as passwords. (See Store the Database Password in a Keystore for how to create and reference such a keystore.)

  All existing graph configuration files with secrets in them must be migrated to the keystore-based approach.

• In a three-tier deployment, access to the PGX server file system requires a directories allowlist

  By default, the PGX server does not allow remote access to the local file system. This can be explicitly allowed, though, in /etc/oracle/graph/pgx.conf by setting allow_local_filesystem to true. If you set allow_local_filesystem to true, you must also specify a list of directories that are allowed to be accessed, by setting datasource_dir_whitelist. For example:

  "allow_local_filesystem": true,
  "datasource_dir_whitelist": ["/scratch/data1", "/scratch/data2"]

  This will allow remote users to read and write data on the server's file-system from and into /scratch/data1 and /scratch/data2.

• In a three-tier deployment, reading from remote locations into PGX is no longer allowed by default

  Previously, PGX allowed graph data to be read from remote locations over FTP or HTTP. This is no longer allowed by default and requires explicit opt-in by the server administrator. To opt-in, specify the allowed_remote_loading_locations configuration option in /etc/oracle/graph/pgx.conf. For example:

  allowed_remote_loading_locations: ["*"]

  In addition:

  • The ftp and http protocols are no longer supported for loading or storing data because they are unencrypted and thus insecure.
  • Configuration files can no longer be loaded from remote locations, but must be loaded from the local file system.
• Removed shell command line options

  The following command line options of the Groovy-based opg shell have been removed and will no longer work:

  • --attach - the shell no longer supports attaching to existing sessions via command line
  • --password - the shell will prompt now for the password

  Also note that the Groovy-based shell has been deprecated, and you are encourage to use the new JShell-based shell instead (see Interactive Graph Shell).

• Changes to PGX APIs

  The following APIs no longer return graph configuration information:

  • ServerInstance#getGraphInfo()
  • ServerInstance#getGraphInfos()
  • ServerInstance#getServerState()

  The REST API now identifies collections, graphs, and properties by UUID instead of a name.

  The namespaces for graphs and properties are session private by default now. This implies that some operations that would previously throw an exception due to a naming conflict could succeed now.

  PgxGraph#publish() throws an exception now if a graph with the given name has been published before.

Migrating Data to a New Database Version

Oracle Graph Server and Client works with older database versions. (See Database Compatibility and Restrictions for information.) If as part of your upgrade you also upgraded your Oracle Database, you can migrate your existing graph data that was stored using the Oracle Property Graph format by invoking the following helper script in your database after the upgrade:

sqlplus> EXECUTE mdsys.opg.migrate_pg_to_current(graph_name=>'mygraph');

The preceding example migrates the property graph mygraph to the current database version.

Uninstalling Previous Versions of Property Graph Libraries

This is only necessary if you are using Oracle Database versions 12.2, 18c, or 19c.

Use of the Property Graph feature of Oracle Database now requires Oracle Graph Server and Client that is installed separately. After you have completed the Graph Server and Client installation, complete the preceding migration steps (if needed), and confirmed that everything is working well, it is recommended that you remove the binaries of older graph installations from your Oracle Database installation by performing the following un-install steps:

1. Make sure the Property Graph mid-tier components are not in use on the target database host. For example, ensure that there is no application running which uses any files under $ORACLE_HOME/md/property_graph. Examples of such an application are a running PGX server on the same host as the database or a client application that references the JAR files under $ORACLE_HOME/md/property_graph/lib.

   It is not necessary to shut down the database to perform the uninstall. The Oracle database itself does not reference or use any files under $ORACLE_HOME/md/property_graph.

2. Remove the files under $ORACLE_HOME/md/property_graph on your database host. On Linux, you can copy the following helper script to your database host and run it with as the DBA operating system user: /opt/oracle/graph/scripts/patch-opg-oracle-home.sh