Getting Started with Hasura and Oracle in Docker

Available on: Enterprise (Self-hosted)

Alpha

Introduction

This guide will help you get set up with the Enterprise Edition of Hasura GraphQL Engine with our Oracle integration using Docker Compose. This is the easiest way to set up Hasura Enterprise Edition and the Oracle GraphQL Data Connector.

Supported versions

1. Hasura GraphQL Engine v2.21.0 onwards
2. Oracle version 18.0 and higher

Alpha version supported features

Hasura currently supports queries, table relationships and permissions on Oracle.

Note that Hasura doesn't yet support the ability to modify the database schema for Oracle, so the database you connect to should already contain tables and data. You should also ideally have access to it outside of Hasura to modify the schema.

Deploying Hasura Enterprise with Docker

Prerequisites

This tutorial assumes that the following prerequisites have been met:

• To deploy Hasura EE, you will need a license key. Please contact Hasura Sales if you do not already have one.
• You have Docker and Docker Compose working on your machine.
• You have access to a Oracle database for which you would like to create an API.

Step 1: Get the Docker Compose file

The install manifests directory contains all installation manifests required to deploy Hasura anywhere. The Docker Compose manifest also contains a Postgres database in order to store the Hasura metadata and a Redis instance for caching.

# in a new directory run
wget https://raw.githubusercontent.com/hasura/graphql-engine/master/install-manifests/enterprise/oracle/docker-compose.yaml
# or run
curl https://raw.githubusercontent.com/hasura/graphql-engine/master/install-manifests/enterprise/oracle/docker-compose.yaml

Step 2: Set the Hasura EE license key and the admin secret

Edit the downloaded docker-compose.yaml and set the license key and admin secret.

An admin secret key is required to make sure that your GraphQL endpoint and the Hasura Console are not publicly accessible.

Edit the Docker Compose file to include the license key and admin secret environment variables

...
graphql-engine:
  image: hasura/graphql-engine:v2.12.0
  environment:
    HASURA_GRAPHQL_EE_LICENSE_KEY: <your_license_key>
    HASURA_GRAPHQL_ADMIN_SECRET: <your_secret_key>
...

Secure the admin secret

The HASURA_GRAPHQL_ADMIN_SECRET should never be passed from the client to the Hasura GraphQL Engine as it would give the client full admin rights to your Hasura instance. See Authentication & Authorization for information on setting up auth in Hasura.

Step 3: Run Hasura GraphQL Engine

The following command will create and run the containers in the Docker Compose manifest:

docker compose up -d

Check that the containers are running:

docker ps

CONTAINER ID IMAGE                              ... CREATED STATUS PORTS          ...
097f58433a2b hasura/graphql-engine              ... 1m ago  Up 1m  8080->8080/tcp ...
b0b1aac0508d postgres                           ... 1m ago  Up 1m  5432/tcp ...
3a29aa348999 redis:7                            ... 1m ago  Up 1m  6379/tcp ...
7b5b2ee70ece hasura/graphql-data-connector      ... 1m ago  Up 1m  5005/tcp ..

Step 5: Load the Hasura Console

Open the Hasura Console by navigating to http://localhost:8080/console. You will need to input your admin secret key as set in your Docker Compose file to log in.

Step 6: Connect to a Oracle database

From the Console, click the Data tab:

Select the Oracle (Alpha) data source driver, enter in a display name for the database and set the JDBC Connection URL for your Oracle instance.

The JDBC connection URL should look like this:

jdbc:oracle:thin:<username>/<password>@<hostname>:<port>:<service-name>

For example:

jdbc:oracle:thin:myuser/[email protected]:oracletest # assuming the default port 1521
jdbc:oracle:thin:myuser/[email protected]:1234:oracletest # assuming Oracle is running on port 1234

Click Connect Database.

Step 7: Track tables and run GraphQL API queries

Now that you have successfully connected your Oracle database to Hasura, you can track tables and use Hasura to automatically build a full-featured GraphQL API for it.

Step 8 (optional): Use managed PostgreSQL and Redis instances

The Hasura EE Docker compose files come with containerized open-source versions of PostgreSQL and Redis.

We highly recommend using managed PostgreSQL and Redis instances especially when running in production.

To switch to using your PostgreSQL or Redis instances, set the following environment variables:

HASURA_GRAPHQL_METADATA_DATABASE_URL
HASURA_GRAPHQL_REDIS_URL
HASURA_GRAPHQL_RATE_LIMIT_REDIS_URL

For example:

...
graphql-engine:
  image: hasura/graphql-engine:v2.12.0
  environment:
    HASURA_GRAPHQL_METADATA_DATABASE_URL: postgres://postgres:[email protected]:5432/postgres
    HASURA_GRAPHQL_REDIS_URL: "redis://redis:6379"
    HASURA_GRAPHQL_RATE_LIMIT_REDIS_URL: "redis://redis:6379"
...

Resources

• Hasura GraphQL Engine logs for more details on log types.
• Docker logs for more details on logging in Docker.