14 Oracle Graph Server and Client Installation
This chapter describes the steps for installing the graph server and the graph clients.
- Before You Begin
Before you begin to work with Oracle Property Graphs, you must understand the workflow for installing Oracle Graph Server and Client. - Oracle Graph Server Installation
You must install the Oracle Graph Server to run graph queries and analytics in the graph server (PGX). - Oracle Graph Client Installation
You can interact with the various graph features using the client CLIs and the graph visualization web client. - Setting Up Transport Layer Security
The graph server (PGX), by default, allows only encrypted connections using Transport Layer Security (TLS). TLS requires the server to present a server certificate to the client and the client must be configured to trust the issuer of that certificate.
Parent topic: Installing Oracle Graph Server (PGX) and Client
14.1 Before You Begin
Before you begin to work with Oracle Property Graphs, you must understand the workflow for installing Oracle Graph Server and Client.
Table 14-1 Workflow for Installing Oracle Graph Server and Client
Sequence | Task | Description | More Information |
---|---|---|---|
1 | Verify Oracle Database Requirements | Ensure that your Oracle Database version is 12.2 and higher. | Verifying Database Compatibility |
2 | Download Oracle Graph Server and Client | Download Oracle Graph Server and Client from Oracle Software Delivery Cloud or from Oracle Technology Network. | Downloading Oracle Graph Server and Client |
3 | Install the PL/SQL patch in your Oracle Database | Upgrade the PL/SQL Graph packages in your Oracle Database. | Installing PL/SQL Packages in Oracle Database |
4 | Install Oracle Graph Server | Install Oracle Graph server, which is available as a separate downloadable package. | Installing Oracle Graph Server |
5 | Install Oracle Graph Clients | Install the graph clients (such as the graph shell CLIs and graph visualization application) to work with property graphs. | Oracle Graph Client Installation |
6 | Set up transport layer security | Configure the graph server and client to trust the self-signed keystore. | Setting Up Transport Layer Security |
7 | Add permissions to publish the graph | Grant permissions to publish graphs. | Adding Permissions to Publish the Graph |
- Verifying Database Compatibility
- Downloading Oracle Graph Server and Client
- Installing PL/SQL Packages in Oracle Database
Oracle Graph Server and Client will work with Oracle Database 12.2 onward. However, you must install the updated PL/SQL packages that are part of the Oracle Graph Server and Client download.
Parent topic: Oracle Graph Server and Client Installation
14.1.1 Verifying Database Compatibility
Oracle Graph Server and Client works with Oracle Database 12.2 onwards on both on-premises and cloud environments. The cloud environment includes working with all versions of Oracle Autonomous Database Serverless and Oracle Autonomous Database Dedicated.
However, modifying a property graph using a PGQL INSERT
,
UPDATE
, or DELETE
query is not supported for
Oracle Database 12.2.
Parent topic: Before You Begin
14.1.2 Downloading Oracle Graph Server and Client
You can download Oracle Graph Server and Client from Oracle Software Delivery Cloud or from Oracle Technology Network.
Table 14-2 summarizes all the files contained in the Oracle Graph Server and Client deployment.
<ver>
denoted in the file name in the Table 14-2 reflects the downloaded Oracle Graph Server and Client version.
Table 14-2 Components in the Oracle Graph Server and Client Deployment
File | Component | Description |
---|---|---|
oracle-graph-<ver>.rpm |
Oracle Graph Server | An rpm file to deploy Oracle Graph Server. |
oracle-graph-client-<ver>.zip |
Oracle Graph Client | A zip file containing Oracle Graph Client. |
oracle-graph-hdfs-connector-<ver>.zip |
Oracle Graph HDFS Connector | A zip file containing libraries to connect Oracle Graph Server with the Apache Hadoop Distributed Filesystem (HDFS). |
oracle-graph-sqlcl-plugin-<ver>.zip |
Oracle Graph PGQL Plugin for SQLcl | A plugin for SQLcl to run PGQL queries in SQLcl. |
oracle-graph-webapps-<ver>.zip |
Oracle Graph Web Applications | A zip file containing .war files for deploying graph servers in an application server.
|
oracle-graph-plsql-<ver>.zip |
Oracle Graph PL/SQL Patch | A zip file containing PL/SQL packages. It is recommended to update the PL/SQL Graph packages in your database with these packages. Instructions are in the README file.
|
oracle-graph-visualization-library-<ver>.zip |
Oracle Graph Visualization Library | A zip file containing a Java Script library for the Graph Visualization application. |
Parent topic: Before You Begin
14.1.3 Installing PL/SQL Packages in Oracle Database
Oracle Graph Server and Client will work with Oracle Database 12.2 onward. However, you must install the updated PL/SQL packages that are part of the Oracle Graph Server and Client download.
Note:
You can skip this section if you are using Graph Server and Client with Oracle Autonomous Database. You only need to create roles and assign permissions by executing step-5 and step-6 in Basic Steps for Using an Oracle Database for Authentication. You can run these steps using Database Actions in Oracle Cloud Infrastructure Console.
Parent topic: Before You Begin
14.2 Oracle Graph Server Installation
You must install the Oracle Graph Server to run graph queries and analytics in the graph server (PGX).
You also require the graph server to visualize graphs loaded into the graph server (PGX) and the graphs in the database.
The following sections explain the steps to install the Oracle Graph Server in a standalone mode or deploy the server as a web application using Oracle WebLogic Server or Apache Tomcat.
- Using the RPM Installation
You can run the downloaded RPM file to install the Oracle Graph Server. - Deploying Oracle Graph Server to a Web Server
You can deploy Oracle Graph Server to Apache Tomcat or Oracle WebLogic Server. - User Authentication and Authorization
The Oracle Graph server (PGX) uses an Oracle Database as identity manager. Both username and password based as well as Kerberos based authentication is supported.
Related Topics
Parent topic: Oracle Graph Server and Client Installation
14.2.1 Using the RPM Installation
You can run the downloaded RPM file to install the Oracle Graph Server.
- Prerequisites for Installing Oracle Graph Server
- Installing Oracle Graph Server
- Uninstalling Oracle Graph Server
- Upgrading Oracle Graph Server
Parent topic: Oracle Graph Server Installation
14.2.1.1 Prerequisites for Installing Oracle Graph Server
Your system must adhere to certain prerequisite requirements in order to install the Oracle Graph Server.
- Verify that you meet the following system requirements:
- Oracle Linux 7 or 8 x64 or a similar Linux distribution such as RedHat
- Oracle JDK 8, JDK 11, or JDK 17
Note:
- Due to a bug in Open JDK, it is recommended to
avoid the following Oracle JDK versions:
- JDK 11.0.9
- JDK 11.0.10
- JDK 11.0.11
- JDK 11.0.12
See this note for more details.
- Compiling custom graph algorithms using the PGX Algorithm API is not supported on Oracle JDK 17.
- Due to a bug in Open JDK, it is recommended to
avoid the following Oracle JDK versions:
- Verify if you already have an installed version of the graph
server, by running the following
command:
sudo rpm -q oracle-graph [sudo] password for oracle: oracle-graph-23.3.0-0.x86_64
Graph server installation may throw an error if an installation already exists. In that case, see Upgrading Oracle Graph Server to upgrade to a newer version.
Parent topic: Using the RPM Installation
14.2.1.2 Installing Oracle Graph Server
systemctl status pgx
- If the graph server has successfully started, the response may
appear
as:
● pgx.service - Oracle Graph In-Memory Server Loaded: loaded (/etc/systemd/system/pgx.service; disabled; vendor preset: disabled) Active: active (running) since Wed 2021-01-27 10:06:06 EST; 33s ago Main PID: 32127 (bash) CGroup: /system.slice/pgx.service ├─32127 /bin/bash start-server └─32176 java -Dlogback.configurationFile=/etc/oracle/graph/logback-server.xml -Doracle.jdbc.fanEnabled=false -cp /opt/oracle/graph/pgx/bin/../../pgx/server/lib/jackson-databind...
The graph server is now ready to accept requests.
- If the graph server has not started, then you must check the log
files in
/var/log/oracle/graph
for errors. Additionally, you can also run the following command to view anysystemd
errors:sudo journalctl -u pgx.service
For instructions to deploy the graph server in Oracle WebLogic Server or Apache Tomcat, see:
You can also deploy the graph server behind a load balancer. See Deploying Oracle Graph Server Behind a Load Balancer for more information.
Parent topic: Using the RPM Installation
14.2.1.3 Uninstalling Oracle Graph Server
Parent topic: Using the RPM Installation
14.2.1.4 Upgrading Oracle Graph Server
Parent topic: Using the RPM Installation
14.2.2 Deploying Oracle Graph Server to a Web Server
You can deploy Oracle Graph Server to Apache Tomcat or Oracle WebLogic Server.
The following explains the deployment instructions to a web server:
- Deploying to Apache Tomcat
The example in this topic shows how to deploy the graph server as a web application with Apache Tomcat. - Deploying to Oracle WebLogic Server
The example in this topic shows how to deploy the graph server as a web application with Oracle WebLogic Server.
Parent topic: Oracle Graph Server Installation
14.2.2.1 Deploying to Apache Tomcat
The example in this topic shows how to deploy the graph server as a web application with Apache Tomcat.
The graph server will work with Apache Tomcat 9.0.x.
- Download the Oracle Graph Webapps zip file from Oracle Software Delivery Cloud. This file contains ready-to-deploy Java web application archives (
.war
files). The file name will be similar to this:oracle-graph-webapps-<version>.zip
. - Unzip the file into a directory of your choice.
- Locate the
.war
file that follows the naming pattern:graph-server-webapp-<version>.war
. - Configure the graph server.
- Modify authentication and other server settings by modifying the
WEB-INF/classes/pgx.conf
file inside the web application archive. See User Authentication and Authorization section for more information. - Optionally, change logging settings by modifying the
WEB-INF/classes/logback.xml
file inside the web application archive. - Optionally, change other servlet specific deployment descriptors by modifying the
WEB-INF/web.xml
file inside the web application archive.
- Modify authentication and other server settings by modifying the
- Copy the
.war
file into the Tomcatwebapps
directory. For example:cp graph-server-webapp-<version>.war $CATALINA_HOME/webapps/pgx.war
Note:
The name you give the war file in the Tomcatwebapps
directory determines the context path of the graph server application. It is recommended naming the war file aspgx.war
. - Configure Tomcat specific settings, like the correct use of TLS/encryption.
- Ensure that port 8080 is not already in use.
- Start Tomcat:
cd $CATALINA_HOME ./bin/startup.sh
The graph server will now listen on
localhost:8080/pgx
.You can connect to the server from JShell by running the following command:
$ <client_install_dir>/bin/opg4j --base_url https://localhost:8080/pgx -u <graphuser>
Related Topics
Parent topic: Deploying Oracle Graph Server to a Web Server
14.2.2.2 Deploying to Oracle WebLogic Server
The example in this topic shows how to deploy the graph server as a web application with Oracle WebLogic Server.
This example shows how to deploy the graph server with Oracle WebLogic Server. Graph server supports WebLogic Server version 12.1.x and 12.2.x.
- Download the Oracle Graph Webapps zip file from Oracle Software Delivery Cloud. This file contains ready-to-deploy Java web application archives (
.war
files). The file name will be similar to this:oracle-graph-webapps-<version>.zip
. - Unzip the file into a directory of your choice.
- Locate the
.war
file that follows the naming pattern:graph-server-webapp-<version>.war
. - Configure the graph server.
- Modify authentication and other server settings by modifying the
WEB-INF/classes/pgx.conf
file inside the web application archive. - Optionally, change logging settings by modifying the
WEB-INF/classes/logback.xml
file inside the web application archive. - Optionally, change other servlet specific deployment descriptors by modifying the
WEB-INF/web.xml
file inside the web application archive. - Optionally, change WebLogic Server-specific deployment descriptors by modifying the
WEB-INF/weblogic.xml
file inside the web application archive.
- Modify authentication and other server settings by modifying the
- Configure WebLogic specific settings, like the correct use of TLS/encryption.
- Deploy the
.war
file to WebLogic Server. The following example shows how to do this from the command line:. $MW_HOME/user_projects/domains/mydomain/bin/setDomainEnv.sh . $MW_HOME/wlserver/server/bin/setWLSEnv.sh java weblogic.Deployer -adminurl http://localhost:7001 -username <username> -password <password> -deploy -source <path-to-war-file>
14.2.2.2.1 Installing Oracle WebLogic Server
To download and install the latest version of Oracle WebLogic Server, see
http://www.oracle.com/technetwork/middleware/weblogic/documentation/index.html
Parent topic: Deploying to Oracle WebLogic Server
14.2.3 User Authentication and Authorization
The Oracle Graph server (PGX) uses an Oracle Database as identity manager. Both username and password based as well as Kerberos based authentication is supported.
The actions that you are allowed to do on the graph server are determined by the privileges enabled by roles that have been granted to you in the Oracle Database.
- Privileges and Roles in Oracle Database
All database users that work with graphs require theCREATE SESSION
privilege in the database. - Basic Steps for Using an Oracle Database for Authentication
You can follow the steps explained in this section to authenticate users to the graph server (PGX). - Prepare the Graph Server for Database Authentication
Locate thepgx.conf
file of your installation. - Store the Database Password in a Keystore
- Adding Permissions to Publish the Graph
There are two ways by which you can view any graph in your graph server (PGX) session in the graph visualization application. - Token Expiration
By default, tokens are valid for 1 hour. - Customizing Roles and Permissions
You can fully customize the permissions to roles mapping by adding and removing roles and specifying permissions for a role. You can also authorize individual users instead of roles. - Revoking Access to the Graph Server
To revoke a user's ability to access the graph server, either drop the user from the database or revoke the corresponding roles from the user, depending on how you defined the access rules in your pgx.conf file. - Examples of Custom Authorization Rules
You can define custom authorization rules for developers. - Kerberos Enabled Authentication for the Graph Server (PGX)
The graph server (PGX) can authenticate users using an Oracle Database with Kerberos enabled as identity provider.
Parent topic: Oracle Graph Server Installation
14.2.3.1 Privileges and Roles in Oracle Database
All database users that work with graphs require the CREATE SESSION
privilege in the database.
Roles that are created for working with graphs are in Table 14-3. These roles are created when you install the PL/SQL package of the Oracle Graph Server and Client distribution on the target database.
Table 14-3 Privileges and Roles in Oracle Database
Role | Operations enabled by this role | Used By |
---|---|---|
PGX_SESSION_CREATE |
Create a new PGX session using the ServerInstance.createSession API. | Graph developers and graph users |
PGX_SERVER_GET_INFO |
Get status information on the PGX instance using the Admin API. | Users who administer PGX |
PGX_SERVER_MANAGE (includes PGX_SERVER_GET_INFO) |
Manage the PGX instance using the Admin API to stop or restart PGX. | Users who administer PGX |
PGX_SESSION_NEW_GRAPH |
Create a new graph in PGX by loading from the database using a config file, using the CREATE PROPERTY GRAPH statement in PGQL, creating a sub-graph from another graph, or using the GraphBuilder. | Graph developers and graph users |
PGX_SESSION_GET_PUBLISHED_GRAPH |
Query and view graphs published by another user to the public namespace. | Graph developers and graph users |
PGX_SESSION_ADD_PUBLISHED_GRAPH (includes PGX_SESSION_GET_PUBLISHED_GRAPH) |
Publish a graph to the public namespace. | Graph developers |
PGX_SESSION_COMPILE_ALGORITHM |
Compile an algorithm using the PGX Algorithm API. | Graph developers |
PGX_SESSION_READ_MODEL |
Load and use an ML model using PgxML. | Graph developers |
PGX_SESSION_MODIFY_MODEL |
Create, train, and store an ML model using PgxML. | Graph developers |
Few additional roles are also created to group multiple roles together. They provide a convenient way to grant multiple roles to database users. See Mapping Graph Server Roles to Default Privileges for more information on these additional roles.
You can create additional groups that are useful for your application, as described in Adding and Removing Roles and Defining Permissions for Individual Users.
Parent topic: User Authentication and Authorization
14.2.3.2 Basic Steps for Using an Oracle Database for Authentication
You can follow the steps explained in this section to authenticate users to the graph server (PGX).
Parent topic: User Authentication and Authorization
14.2.3.3 Prepare the Graph Server for Database Authentication
Locate the pgx.conf
file of your installation.
If you installed the graph server via RPM, the file is located at: /etc/oracle/graph/pgx.conf
If you use the webapps
package to deploy into Tomcat or WebLogic Server, the pgx.conf
file is located inside the web application archive file (WAR file) at: WEB-INF/classes/pgx.conf
vim graph-server-webapp-<version>.war
Inside the pgx.conf
file, locate the jdbc_url
line of the realm options:
...
"pgx_realm": {
"implementation": "oracle.pg.identity.DatabaseRealm",
"options": {
"jdbc_url": "<REPLACE-WITH-DATABASE-URL-TO-USE-FOR-AUTHENTICATION>",
"token_expiration_seconds": 3600,
...
Replace the text with the JDBC URL pointing to your database that you configured in the previous step. For example:
...
"pgx_realm": {
"implementation": "oracle.pg.identity.DatabaseRealm",
"options": {
"jdbc_url": "jdbc:oracle:thin:@myhost:1521/myservice",
"token_expiration_seconds": 3600,
...
Then, start the graph server by running the following command as a
root
user or with sudo
:
sudo systemctl start pgx
Preparing the Graph Server (PGX) to Connect to Autonomous Database
You can configure your graph server(PGX) to connect to an Autonomous Database instance.
Irrespective of whether your graph server (PGX) instance is running on premises
or on Oracle Cloud Infrastructure (OCI), you can perform the following steps to determine
the service name to connect to your Autonomous Database instance and update the JDBC URL in
/etc/oracle/graph/pgx.conf
file.
- Download and save the wallet for your Autonomous Database instance from the Oracle Cloud Infrastructure (OCI) Console. See Download Client Credentials (Wallets) for more information.
- Unzip the wallet to a new subdirectory in
/etc/oracle/graph/wallets/<dbname>
, and change the group permission as shown:sudo unzip Wallet_<dbname>.zip -d /etc/oracle/graph/wallets/<dbname> sudo chgrp -R oraclegraph /etc/oracle/graph/wallets/<dbname>
- Determine the connect identifier from the
tnsnames.ora
file in/etc/oracle/graph/wallets/<dbname>
directory. For example, the entry must be similar to:graphdb_low = description= (retry_count=20)(retry_delay=3) (address= (protocol=tcps)(port=1522) (host=adwc.example.oraclecloud.com) ) (connect_data=(service_name=graphdb_low.adwc.oraclecloud.com)) (security=(ssl_server_cert_dn="CN=adwc.example.oraclecloud.com, OU=Oracle BMCS US, O=Oracle Corporation, L=Redwood City, ST=California, C=US")) )
In the preceding example,
graphdb_low
is the connect identifier. - Update the JDBC URL in
/etc/oracle/graph/pgx.conf
file with the connect identifier determined in the preceding step along with the directory path to the unzipped wallet file. For example:... "pgx_realm": { "implementation": "oracle.pg.identity.DatabaseRealm", "options": { "jdbc_url": "jdbc:oracle:thin:@graphdb_low?TNS_ADMIN=/etc/oracle/graph/wallets/<dbname>", "token_expiration_seconds": 3600, ...
- Finally, restart the graph server as
shown:
sudo systemctl restart pgx
Parent topic: User Authentication and Authorization
14.2.3.4 Store the Database Password in a Keystore
PGX requires a database account to read data from the database into memory. The account should be a low-privilege account (see Security Best Practices with Graph Data).
As described in Reading Graphs from Oracle Database into the Graph Server (PGX), you can read data from the database into the graph server without specifying additional authentication as long as the token is valid for that database user. But if you want to access a graph from a different user, you can do so, as long as that user's password is stored in a Java Keystore file for protection.
You can use the keytool
command that is bundled together with the JDK to generate such a keystore file on the command line. See the following script as an example:
# Add a password for the 'database1' connection
keytool -importpass -alias database1 -keystore keystore.p12
# 1. Enter the password for the keystore
# 2. Enter the password for the database
# Add another password (for the 'database2' connection)
keytool -importpass -alias database2 -keystore keystore.p12
# List what's in the keystore using the keytool
keytool -list -keystore keystore.p12
If you are using Java version 8 or lower, you should pass the additional parameter -storetype pkcs12
to the keytool commands in the preceding example.
You can store more than one password into a single keystore file. Each password can be referenced using the alias name provided.
- Write the PGX graph configuration file to load a graph directly from relational tables
- Read the data
- Secure coding tips for graph client applications
Write the PGX graph configuration file to load a graph directly from relational tables
The following example loads a subset of the HR sample data from relational tables directly into PGX as a graph. The configuration file specifies a mapping from relational to graph format by using the concept of vertex and edge providers.
Note:
Specifying the vertex_providers
and edge_providers
properties loads the data into an optimized representation of the graph.
{
"name":"hr",
"jdbc_url":"jdbc:oracle:thin:@myhost:1521/orcl",
"username":"hr",
"keystore_alias":"database1",
"vertex_id_strategy": "no_ids",
"vertex_providers":[
{
"name":"Employees",
"format":"rdbms",
"database_table_name":"EMPLOYEES",
"key_column":"EMPLOYEE_ID",
"key_type": "string",
"props":[
{
"name":"FIRST_NAME",
"type":"string"
},
{
"name":"LAST_NAME",
"type":"string"
},
{
"name":"EMAIL",
"type":"string"
},
{
"name":"SALARY",
"type":"long"
}
]
},
{
"name":"Jobs",
"format":"rdbms",
"database_table_name":"JOBS",
"key_column":"JOB_ID",
"key_type": "string",
"props":[
{
"name":"JOB_TITLE",
"type":"string"
}
]
},
{
"name":"Departments",
"format":"rdbms",
"database_table_name":"DEPARTMENTS",
"key_column":"DEPARTMENT_ID",
"key_type": "string",
"props":[
{
"name":"DEPARTMENT_NAME",
"type":"string"
}
]
}
],
"edge_providers":[
{
"name":"WorksFor",
"format":"rdbms",
"database_table_name":"EMPLOYEES",
"key_column":"EMPLOYEE_ID",
"source_column":"EMPLOYEE_ID",
"destination_column":"EMPLOYEE_ID",
"source_vertex_provider":"Employees",
"destination_vertex_provider":"Employees"
},
{
"name":"WorksAs",
"format":"rdbms",
"database_table_name":"EMPLOYEES",
"key_column":"EMPLOYEE_ID",
"source_column":"EMPLOYEE_ID",
"destination_column":"JOB_ID",
"source_vertex_provider":"Employees",
"destination_vertex_provider":"Jobs"
},
{
"name":"WorkedAt",
"format":"rdbms",
"database_table_name":"JOB_HISTORY",
"key_column":"EMPLOYEE_ID",
"source_column":"EMPLOYEE_ID",
"destination_column":"DEPARTMENT_ID",
"source_vertex_provider":"Employees",
"destination_vertex_provider":"Departments",
"props":[
{
"name":"START_DATE",
"type":"local_date"
},
{
"name":"END_DATE",
"type":"local_date"
}
]
}
]
}
Read the data
Now you can instruct PGX to connect to the database and read the data by passing in both the keystore and the configuration file to PGX, using one of the following approaches:
- Interactively in the graph shell
If you are using the graph shell, start it with the
--secret_store
option. It will prompt you for the keystore password and then attach the keystore to your current session. For example:cd /opt/oracle/graph ./bin/opg4j --secret_store /etc/my-secrets/keystore.p12 enter password for keystore /etc/my-secrets/keystore.p12:
Inside the shell, you can then use normal PGX APIs to read the graph into memory by passing the JSON file you just wrote into the
readGraphWithProperties
API:opg4j> var graph = session.readGraphWithProperties("config.json") graph ==> PgxGraph[name=hr,N=215,E=415,created=1576882388130]
- As a PGX preloaded graphAs a server administrator, you can instruct PGX to load graphs into memory upon server startup. To do so, modify the PGX configuration file at
/etc/oracle/graph/pgx.conf
and add the path the graph configuration file to thepreload_graphs
section. For example:{ ... "preload_graphs": [{ "name": "hr", "path": "/path/to/config.json" }], "authorization": [{ "pgx_role": "GRAPH_DEVELOPER", "pgx_permissions": [{ "preloaded_graph": "hr", "grant": "read" }] }, .... ] }
As root user, edit the service file at/etc/systemd/system/pgx.service
and change theExecStart
command to specify the location of the keystore containing the password:ExecStart=/bin/bash start-server --secret-store /etc/keystore.p12
Note:
Please note that/etc/keystore.p12
must not be password protected for this to work. Instead protect the file via file system permission that is only readable byoraclegraph
user.After the file is edited, reload the changes using:sudo systemctl daemon-reload
Finally start the server:sudo systemctl start pgx
- In a Java application
To register a keystore in a Java application, use the
registerKeystore()
API on thePgxSession
object. For example:import oracle.pgx.api.*; class Main { public static void main(String[] args) throws Exception { String baseUrl = args[0]; String keystorePath = "/etc/my-secrets/keystore.p12"; char[] keystorePassword = args[1].toCharArray(); String graphConfigPath = args[2]; ServerInstance instance = Pgx.getInstance(baseUrl); try (PgxSession session = instance.createSession("my-session")) { session.registerKeystore(keystorePath, keystorePassword); PgxGraph graph = session.readGraphWithProperties(graphConfigPath); System.out.println("N = " + graph.getNumVertices() + " E = " + graph.getNumEdges()); } } }
You can compile and run the preceding sample program using the Oracle Graph Client package. For example:cd $GRAPH_CLIENT // create Main.java with above contents javac -cp 'lib/*' Main.java java -cp '.:conf:lib/*' Main http://myhost:7007 MyKeystorePassword path/to/config.json
Secure coding tips for graph client applications
When writing graph client applications, make sure to never store any passwords or other secrets in clear text in any files or in any of your code.
Do not accept passwords or other secrets through command line arguments either. Instead, use Console.html#readPassword()
from the JDK.
Parent topic: User Authentication and Authorization
14.2.3.5 Adding Permissions to Publish the Graph
There are two ways by which you can view any graph in your graph server (PGX) session in the graph visualization application.
When you log into the graph visualization tool in your browser, that will be a different session from your JShell session or application session. To visualize the graph you are working on in your JShell session or application session in your graph visualization session, you can perform one of the following two steps:
Parent topic: User Authentication and Authorization
14.2.3.6 Token Expiration
By default, tokens are valid for 1 hour.
Internally, the graph client automatically renews tokens which are about to expire in less than 30 minutes. This is also configurable by re-authenticating your credentials with the database. By default, tokens can only be automatically renewed for up to 24 times, then you need to login again.
GraphServer#reauthenticate (instance,
"<user>", "<password>")
API.
Note:
If a session time out occurs before you re-authenticate, then you may lose your session data.For example:
opg4j> var graph = session.readGraphByName("BANK_GRAPH_VIEW",GraphSource.PG_VIEW) // fails because token cannot be renewed anymore
opg4j> GraphServer.reauthenticate(instance, "<user>", "<password>".toCharArray()) // log in again
opg4j> var graph = session.readGraphByName("BANK_GRAPH_VIEW",GraphSource.PG_VIEW) // works now
Parent topic: User Authentication and Authorization
14.2.3.7 Customizing Roles and Permissions
You can fully customize the permissions to roles mapping by adding and removing roles and specifying permissions for a role. You can also authorize individual users instead of roles.
This topic includes examples of how to customize the permission mapping.
- Checking Graph Permissions Using API
- Adding and Removing Roles
You can add new role permission mappings or remove existing mappings by modifying the authorization list. - Defining Permissions for Individual Users
In addition to defining permissions for roles, you can define permissions for individual users. - Defining Permissions to Use Custom Graph Algorithms
You can define permissions to allow developers to compile custom graph algorithms.
Parent topic: User Authentication and Authorization
14.2.3.7.1 Checking Graph Permissions Using API
You can view your roles and graph permissions using the following PGX API methods:
Table 14-4 API for Checking Graph Permissions
Class | Method | Description |
---|---|---|
ServerInstance |
getPgxUsername() |
Name of the current user |
ServerInstance |
getPgxUserRoles() |
Role names of the current user |
ServerInstance |
getPgxGenericPermissions() |
Non-graph (system) permissions of the current user:
|
PgxGraph |
getPermission() |
Permission on the graph instance for a current user |
You can get all permission-related information using the API in JShell as shown:
/bin/opg4j -b "https://<host>:<port>" -u "<graphuser>"
opg4j> instance
instance ==> ServerInstance[embedded=false,baseUrl=https://<host>:<port>,serverVersion=null]
opg4j> instance.getPgxUsername()
$2 ==> "ORACLE"
opg4j> instance.getPgxUserRoles()
$3 ==> [GRAPH_DEVELOPER]
opg4j> instance.getPgxGenericPermissions()
$4 ==> [PGX_SESSION_CREATE, PGX_SESSION_READ_MODEL, PGX_SESSION_ADD_PUBLISHED_GRAPH, PGX_SESSION_NEW_GRAPH, PGX_SESSION_GET_PUBLISHED_GRAPH, PGX_SESSION_MODIFY_MODEL]
opg4j> var g = session.readGraphByName("BANK_GRAPH_VIEW", GraphSource.PG_VIEW)
g ==> PgxGraph[name=BANK_GRAPH_VIEW,N=999,E=4993,created=1688558374973]
opg4j> g.getPermission() // To get graph permissions
$9 ==> MANAGE
import oracle.pg.rdbms.*;
import java.sql.Connection;
import java.sql.Statement;
import oracle.pg.rdbms.pgql.PgqlConnection;
import oracle.pg.rdbms.pgql.PgqlStatement;
import oracle.pgx.api.*;
import oracle.ucp.jdbc.PoolDataSourceFactory;
import oracle.ucp.jdbc.PoolDataSource;
import java.nio.file.Files;
import java.nio.file.Path;
/**
* This example shows how to get all permissions.
*/
public class GetPermissions
{
public static void main(String[] args) throws Exception
{
int idx=0;
String host = args[idx++];
String port = args[idx++];
String sid = args[idx++];
String user = args[idx++];
String password = args[idx++];
String graph = args[idx++];
Connection conn = null;
PgxPreparedStatement stmt = null;
try {
// Get a jdbc connection
PoolDataSource pds = PoolDataSourceFactory.getPoolDataSource();
pds.setConnectionFactoryClassName("oracle.jdbc.pool.OracleDataSource");
pds.setURL("jdbc:oracle:thin:@"+host+":"+port +"/"+sid);
pds.setUser(user);
pds.setPassword(password);
conn = pds.getConnection();
conn.setAutoCommit(false);
ServerInstance instance = GraphServer.getInstance("http://localhost:7007", user, password.toCharArray());
PgxSession session = instance.createSession("my-session");
var statement = Files.readString(Path.of("/media/sf_Linux/Java/create-pg.pgql"));
stmt = session.preparePgql(statement);
stmt.execute();
PgxGraph g = session.getGraph(graph);
System.out.println("Graph: "+ g);
String userName = instance.getPgxUsername();
var userRoles = instance.getPgxUserRoles();
var genericPermissions = instance.getPgxGenericPermissions();
String graphPermission = g.getPermission().toString();
System.out.println("Username is " + userName);
System.out.println("User Roles are " + userRoles);
System.out.println("Generic permissions are " + genericPermissions);
System.out.println("Graph permission is " + graphPermission);
}
finally {
// close the sql statment
if (stmt != null) {
stmt.close();
}
// close the connection
if (conn != null) {
conn.close();
}
}
}
}
On execution, the code gives the following output:
Graph: PgxGraph[name=BANK_GRAPH_PG,N=1000,E=5001,created=1625731370402]
Username is ORACLE
User Roles are [GRAPH_DEVELOPER]
Generic permissions are [PGX_SESSION_MODIFY_MODEL, PGX_SESSION_CREATE, PGX_SESSION_NEW_GRAPH, PGX_SESSION_READ_MODEL, PGX_SESSION_ADD_PUBLISHED_GRAPH, PGX_SESSION_GET_PUBLISHED_GRAPH]
Graph permission is MANAGE
Parent topic: Customizing Roles and Permissions
14.2.3.7.2 Adding and Removing Roles
You can add new role permission mappings or remove existing mappings by modifying the authorization list.
For example:
CREATE ROLE MY_CUSTOM_ROLE_1
GRANT PGX_SESSION_CREATE TO MY_CUSTOM_ROLE1
GRANT PGX_SERVER_GET_INFO TO MY_CUSTOM_ROLE1
GRANT MY_CUSTOM_ROLE1 TO SCOTT
Parent topic: Customizing Roles and Permissions
14.2.3.7.3 Defining Permissions for Individual Users
In addition to defining permissions for roles, you can define permissions for individual users.
For example:
GRANT PGX_SESSION_CREATE TO SCOTT GRANT PGX_SERVER_GET_INFO TO SCOTT
Parent topic: Customizing Roles and Permissions
14.2.3.7.4 Defining Permissions to Use Custom Graph Algorithms
You can define permissions to allow developers to compile custom graph algorithms.
Parent topic: Customizing Roles and Permissions
14.2.3.8 Revoking Access to the Graph Server
To revoke a user's ability to access the graph server, either drop the user from the database or revoke the corresponding roles from the user, depending on how you defined the access rules in your pgx.conf file.
For example:
REVOKE graph_developer FROM scott
Revoking Graph Permissions
If you have the MANAGE permission on a graph, you can revoke graph access from users or roles using the PgxGraph#revokePermission
API. For example:
PgxGraph g = ...
g.revokePermission(new PgxRole("GRAPH_DEVELOPER")) // revokes previously granted role access
g.revokePermission(new PgxUser("SCOTT")) // revokes previously granted user access
Parent topic: User Authentication and Authorization
14.2.3.9 Examples of Custom Authorization Rules
You can define custom authorization rules for developers.
Example 14-1 Allowing Developers to Publish Graphs
Sharing of graphs with other users should be done in Oracle Database where possible. Use GRANT statements on the database tables so that other users can create graphs from the tables.
In the graph server (PGX) you can use the following permissions to share a graph that is already in memory, with other users connected to the graph server.
Table 14-5 Allowed Permissions
Permission | Actions Enabled by this Permission |
---|---|
READ |
|
MANAGE |
|
EXPORT |
|
The creator of the graph automatically gets the MANAGE permission granted on the
graph. If you have the MANAGE permission, you can grant other roles or users READ or EXPORT
permission on the graph. You cannot grant MANAGE on a graph. The following describes
an example of granting READ
permission on a graph to the
GRAPH_DEVELOPER
role by userA:
import oracle.pgx.api.*;
import oracle.pgx.common.auth.*;
...
PgxSession session = GraphServer.getInstance("<base-url>", "<userA>", "<password-of-userA").createSession("userA");
PgxGraph g = session.readGraphByName("SAMPLE_GRAPH", GraphSource.PG_VIEW);
g.grantPermission(new PgxRole("GRAPH_DEVELOPER"), PgxResourcePermission.READ);
g.publish();
GRAPH_DEVELOPER
role can access this graph
and have READ
access on it, as shown in the following example of
userB:PgxSession session = GraphServer.getInstance("<base-url>", "<userB>", "<password-of-userB").createSession("userB")
PgxGraph g = session.getGraph("sample_graph")
g.queryPgql("select count(*) from match (v)").print().close()
Similarly, graphs can be shared with individual users instead of roles, as shown in the following example:
g.grantPermission(new PgxUser("OTHER_USER"), PgxResourcePermission.EXPORT)
where OTHER_USER is the user name of the user that will receive the EXPORT permission on graph g
.
Example 14-2 Allowing Developers to Access Preloaded Graphs
To allow developers to access preloaded graphs (graphs loaded during graph server startup), grant the read permission on the preloaded graph in the pgx.conf file. For example:
"preload_graphs": [{
"path": "/data/my-graph.json",
"name": "global_graph"
}],
"authorization": [{
"pgx_role": "GRAPH_DEVELOPER",
"pgx_permissions": [{
"preloaded_graph": "global_graph"
"grant": "read"
},
...
You can grant READ, EXPORT, or MANAGE permission.
Example 14-3 Allowing Developers Access to the Hadoop Distributed Filesystem (HDFS) or the Local File System
To allow developers to read files from HDFS, you must first declare the HDFS directory and then map it to a read or write permission. For example:
CREATE OR REPLACE DIRECTORY pgx_file_location AS 'hdfs:/data/graphs'
GRANT READ ON DIRECTORY pgx_file_location TO GRAPH_DEVELOPER
Similarly, you can add another permission with GRANT WRITE
to allow write access. Such a write access is required in order to export graphs.
Access to the local file system (where the graph server runs) can be granted the same way. The only difference is that location would be an absolute file path without the hdfs:
prefix. For example:
CREATE OR REPLACE DIRECTORY pgx_file_location AS '/opt/oracle/graph/data'
Note that in addition to the preceding configuration, the operating system user that runs the graph server process must have the corresponding directory privileges to actually read or write into those directories.
Example 14-4 Allowing Access to Directories on Autonomous Database
To allow developers to read and write from files in Oracle Autonomous Database, you must perform the following steps:
- Connect to your Autonomous Database instance as an ADMIN user using any of the SQL based Oracle Database tools or using Database Actions, the built-in web-based interface.
- Create the directory by specifying the path to the directory using the
graph:
prefix as shown:CREATE OR REPLACE DIRECTORY pgx_file_location AS 'graph:/opt/oracle/graph/data'
- Grant read or write permissions to the directory for the desired role. For
example:
GRANT READ ON DIRECTORY pgx_file_location TO GRAPH_DEVELOPER
Parent topic: User Authentication and Authorization
14.2.3.10 Kerberos Enabled Authentication for the Graph Server (PGX)
The graph server (PGX) can authenticate users using an Oracle Database with Kerberos enabled as identity provider.
You can log into the graph server using a Kerberos ticket and the actions which you are allowed to do on the graph server are determined by the roles that have been granted to you in the Oracle Database.
- Prerequisite Requirements
- Prepare the Graph Server for Kerberos Authentication
- Login to the Graph Server Using Kerberos Ticket
Parent topic: User Authentication and Authorization
14.2.3.10.1 Prerequisite Requirements
In order to enable Kerberos authentication on the graph server (PGX), the following system requirements must be met:
- The database needs to have Kerberos authentication enabled. See Configuring Kerberos Authentication for more information.
- Both the database and the Kerberos Authentication Server need to be reachable from the host where the graph server runs.
- The database is prepared for graph server authentication. That is, relevant graph roles have been granted to users who will log into the graph server.
14.2.3.10.2 Prepare the Graph Server for Kerberos Authentication
14.3 Oracle Graph Client Installation
You can interact with the various graph features using the client CLIs and the graph visualization web client.
The following sections explain the steps to install the various clients:
- Graph Clients
The Oracle Graph client installation supports a Java and a Python client. - Running the Graph Visualization Web Client
You require a running graph server (PGX) to use the Graph Visualization web application.
Related Topics
Parent topic: Oracle Graph Server and Client Installation
14.3.1 Graph Clients
The Oracle Graph client installation supports a Java and a Python client.
The following sections explain the steps to install the clients:
- Oracle Graph Java Client
You can install the Java client from theoracle-graph-client-23.3.0.zip
file that is shipped with Oracle Graph Server and Client or you can use the Java client on Maven Central. - Oracle Graph Python Client
You can install the Python client by downloading theoracle-graph-client-23.3.0.zip
file that is shipped with Oracle Graph Server and Client or from PyPI.
Parent topic: Oracle Graph Client Installation
14.3.1.1 Oracle Graph Java Client
You can install the Java client from the
oracle-graph-client-23.3.0.zip
file
that is shipped with Oracle Graph Server and Client or you can use
the Java client on Maven Central.
- Installing the Java Client From the Graph Server and Client Downloads
You can download the zip file for Oracle Graph Client 23.3.0 and install the Java client. - Using Oracle Graph Java Client on Maven Central
You can obtain the property graph Java client from Maven Central.
Parent topic: Graph Clients
14.3.1.1.1 Installing the Java Client From the Graph Server and Client Downloads
You can download the zip file for Oracle Graph Client 23.3.0 and install the Java client.
- A Unix-based operation system (such as Linux) or macOS or Microsoft Windows
- Oracle JDK 11 or JDK 17
Note:
- JDK 11.0.9
- JDK 11.0.10
- JDK 11.0.11
- JDK 11.0.12
Parent topic: Oracle Graph Java Client
14.3.1.1.2 Using Oracle Graph Java Client on Maven Central
You can obtain the property graph Java client from Maven Central.
- Group Name: com.oracle.database.graph
- Artifact Name: opg-client
- Version: 23.3.0
You can perform the following steps to use the graph Java client from Maven Central:
Parent topic: Oracle Graph Java Client
14.3.1.2 Oracle Graph Python Client
You can install the Python client by downloading the
oracle-graph-client-23.3.0.zip
file
that is shipped with Oracle Graph Server and Client or from
PyPI.
Alternatively, you can also install the python client in embedded mode.
- Installing the Python Client From the Graph Server and Client Downloads
You can download the zip file fororacle-graph-client-23.3.0
from the Graph Server and Client downloads and install the Python client. - Installing the Python Client from PyPI
You can obtain the property graph Python client from PyPI. - Installing the Python Client in Embedded Mode
You can install and work with the Python client in embedded mode. - Uninstalling the Python Client
This section describes how to uninstall the Python client.
Parent topic: Graph Clients
14.3.1.2.1 Installing the Python Client From the Graph Server and Client Downloads
You can download the zip file for oracle-graph-client-23.3.0
from the Graph Server and Client downloads
and install the Python client.
Before installing the Python client, ensure that your system meets all the required prerequisites which are listed in Prerequisites for Installing the Python Client.
Note:
See Python API Reference for more information on the Python APIs.You can perform the following steps to install and connect using the Python client:
14.3.1.2.2 Installing the Python Client from PyPI
You can obtain the property graph Python client from PyPI.
- Operating system: Linux, Windows, or macOS (M1 or M2 processor)
- Oracle JDK 8 or later
- Python 3.8 or later
- Ensure that you set the
JAVA_HOME
environment variable. - If you are behind a proxy, then set the
https_proxy
environment variable to the proxy server.
You can install and verify the Python client installation as shown:
Parent topic: Oracle Graph Python Client
14.3.1.2.3 Installing the Python Client in Embedded Mode
You can install and work with the Python client in embedded mode.
To install the embedded Python client:
Parent topic: Oracle Graph Python Client
14.3.1.2.4 Uninstalling the Python Client
This section describes how to uninstall the Python client.
To uninstall the Python client, run the following command:
pip uninstall oracle-graph-client
Parent topic: Oracle Graph Python Client
14.3.2 Running the Graph Visualization Web Client
You require a running graph server (PGX) to use the Graph Visualization web application.
In addition, ensure that you have provided the JDBC URL for your database in the
jdbc_url
parameter in the /etc/oracle/graph/pgx.conf
file.
To launch the graph visualization application:
- Start the graph server on your installation.
- See Installing Oracle Graph Server for more information on using the rpm installation.
- See Deploying Oracle Graph Server to a Web Server for more information on graph server deployment to a web server.
- Connect to your browser for running the Graph Visualization application.
- For rpm installation:
https://localhost:7007/ui
- For Apache Tomcat Server:
https://localhost:8080/ui
- For Oracle WebLogic Server:
https://<<fqdn-ip>>:<<port>>/ui
The Graph Visualization Login screen opens as shown:
- For rpm installation:
- Enter your Username and Password.
- Optionally, provide the PGX Session ID.
- Click Submit to sign in to the Graph Visualization application.
See Using the Graph Visualization Application for more information on how to visualize graphs using the web application.
Parent topic: Oracle Graph Client Installation
14.4 Setting Up Transport Layer Security
The graph server (PGX), by default, allows only encrypted connections using Transport Layer Security (TLS). TLS requires the server to present a server certificate to the client and the client must be configured to trust the issuer of that certificate.
In this release of Graph Server and Client, the RPM file
installation, will generate a self-signed server keystore file by default. This
server_keystore.jks
file contains the server certificate and server private
key and is generated into /etc/oracle/graph
, for the server to enable TLS.
Note that the default password for the generated keystore is changeit
and
this is configured using an environment variable PGX_SERVER_KEYSTORE_PASSWORD
in /etc/systemd/system/pgx.service
file as shown:
[Service]
Environment="PGX_SERVER_KEYSTORE_PASSWORD=changeit"
If this default keystore configuration is sufficient for you to get started and
if your connections are only to localhost
, you can skip to Configuring a Client to Trust the Self-Signed Keystore.
If you prefer to use a self-signed server certificate, then refer to Using a Self-Signed Server Certificate
for more information. However, it is important to note that the server configuration fields,
server_cert
and server_private_key
are deprecated and will
be desupported in a future release. After that, you will be required to use the server
keystore to store the server certificate and the server private key.
- Using a Self-Signed Server Keystore
This section describes the steps to generate a self-signed keystore into/etc/oracle/graph
and configure the graph server (PGX) and client to use the keystore. - Using a Self-Signed Server Certificate
This section describes the steps to generate a self-signed certificate into/etc/oracle/graph
and configure the graph server (PGX) to use this certificate.
Parent topic: Oracle Graph Server and Client Installation
14.4.1 Using a Self-Signed Server Keystore
This section describes the steps to generate a self-signed keystore into
/etc/oracle/graph
and configure the graph server (PGX) and
client to use the keystore.
- Generating a Self-Signed Server Keystore
You can create a server key store using thekeytool
command. - Configuring the Graph Server (PGX) When Using a Server Keystore
You must specify the path to the server keystore in the graph server (PGX) configuration file. - Configuring a Client to Trust the Self-Signed Keystore
You must configure your client application to accept the self-signed keystore.
Parent topic: Setting Up Transport Layer Security
14.4.1.1 Generating a Self-Signed Server Keystore
You can create a server key store using the keytool
command.
Parent topic: Using a Self-Signed Server Keystore
14.4.1.2 Configuring the Graph Server (PGX) When Using a Server Keystore
You must specify the path to the server keystore in the graph server (PGX) configuration file.
Note:
If you deploy the graph server into your web server using the web applications download package, then this section does not apply. Please refer to the manual of your web server for instructions on how to configure TLS.Parent topic: Using a Self-Signed Server Keystore
14.4.1.3 Configuring a Client to Trust the Self-Signed Keystore
You must configure your client application to accept the self-signed keystore.
- For a Java or a Python client, you must import the root certificate
to all the Java installations used by all the clients.
Note:
The JShell client requires Java 11 or later. - For the Graph Visualization application, you must import the root certificate to the system Java installation of the environment running the graph server (PGX) or the web server serving the graph visualization application. That is, the JDK installation which is used by the OS user running the server that serves the Graph Visualization application.
- For the Graph Zeppelin interpreter client, you must import the root certificate to the Java installation used by the Zeppelin server.
You can import the root certificate as shown in the following step:
Parent topic: Using a Self-Signed Server Keystore
14.4.2 Using a Self-Signed Server Certificate
This section describes the steps to generate a self-signed certificate into
/etc/oracle/graph
and configure the graph server (PGX) to
use this certificate.
- Generating a Self-Signed Server Certificate
You can create a self-signed server certificate using theopenssl
command. - Configuring the Graph Server (PGX)
You must specify the path to the server certificate and the server's private key in PEM format in the graph server (PGX) configuration file. - Configuring a Client to Trust the Self-Signed Certificate
You must configure your client application to accept the self-signed graph server (PGX) certificate.
Parent topic: Setting Up Transport Layer Security
14.4.2.1 Generating a Self-Signed Server Certificate
You can create a self-signed server certificate using the openssl
command.
Parent topic: Using a Self-Signed Server Certificate
14.4.2.2 Configuring the Graph Server (PGX)
You must specify the path to the server certificate and the server's private key in PEM format in the graph server (PGX) configuration file.
Note:
If you deploy the graph server into your web server using the web applications download package, then this section does not apply. Please refer to the manual of your web server for instructions on how to configure TLS.Parent topic: Using a Self-Signed Server Certificate
14.4.2.3 Configuring a Client to Trust the Self-Signed Certificate
You must configure your client application to accept the self-signed graph server (PGX) certificate.
- For a Java or a Python client, you must import the root certificate
to all the Java installations used by all the clients.
Note:
The JShell client requires Java 11 or later. - For the Graph Visualization application, you must import the root certificate to the system Java installation of the environment running the graph server (PGX) or the web server serving the graph visualization application. That is, the JDK installation which is used by the OS user running the server that serves the Graph Visualization application.
- For the Graph Zeppelin interpreter client, you must import the root certificate to the Java installation used by the Zeppelin server.
You can import the root certificate as shown in the following step:
Parent topic: Using a Self-Signed Server Certificate