# Oracle

- Updated on Oct 21, 2025
- Published on Sep 17, 2024

- 2 minute(s) read

For a list of supported versions, see [Infrastructure Requirements](https://help.hyperscience.ai/deployment/docs/infrastructure-requirements).

Note that the standard convention for Oracle DB names includes the host in front of it so you must include that in the ".env" file:

```bash
FORMS_DB_TYPE=oracle
FORMS_DB_HOST=:<port>
FORMS_DB_NAME=:<port>/<DB>
FORMS_DB_USER=<username>
FORMS_DB_PASS=<password>
```

In v32 and later, you can choose to store your system-level credentials in a secrets manager. To learn more about our secrets-management integration, see [Secrets Management](https://help.hyperscience.ai/deployment/docs/secrets-management).

If you would like to specify the tablespace where the database tables will be created, you can use the following optional parameters in the ".env" file. Note that the specified tablespaces need to be created by the database administrator.

```bash
DEFAULT_TABLESPACE=<tablespace>
DEFAULT_INDEX_TABLESPACE=<index_tablespace>
```

## Oracle NNE (Network Native Encryption)

Hyperscience supports NNE when encryption settings are managed on the server side. Any desired encryption settings should be set to `REQUIRED` on the server side.

## Oracle SSL/TLS connections

SSL/TLS encryption is supported, but SSL/TLS authentication (a.k.a. two-way or mutual TLS) is **not** supported.

In order to use SSL/TLS encryption, you must supply a certificate wallet file and ".env" configuration.

The wallet file must be named "cwallet.sso" and be on the host file system in the following directory:

```bash
$HS_PATH/certs/oracle_ssl_wallet/
```

If SELinux is enabled, execute:

```bash
chcon -t container_file_t -R /mnt/hs/certs/oracle_ssl_wallet
```

The file must be readable by UID 1000, unless user namespaces are used. In those cases, refer to your namespace configuration.

To set the permissions, execute the following:

```bash
chown -R 1000:1000 /mnt/hs/certs/oracle_ssl_wallet
chmod u+r -R /mnt/hs/certs/oracle_ssl_wallet
```

The following minimum configuration is required in the ".env" file:

```bash
ORACLE_ENABLE_SSL=true
```

It is required to set `FORMS_DB_NAME` in Oracle DSN (Data Source Name) format. In this case, the `FORMS_DB_HOST` value will be ignored:

```bash
FORMS_DB_HOST=

FORMS_DB_NAME=(DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCPS) (HOST = )
(PORT = )))(CONNECT_DATA = (SID = )) (SECURITY = (SSL_SERVER_CERT_DN = "")))
```

The following optional configurations are also supported. They are passed to `sqlnet.ora` to configure Oracle database connections from the application (see Oracle’s [Parameters for the sqlnet.ora File](https://docs.oracle.com/en/database/oracle/oracle-database/19/netrf/parameters-for-the-sqlnet.ora.html) for valid values and more context):

| **Hyperscience configuration** | **Corresponding Oracle configuration** |
| `ORACLE_SSL_VERSION` | `SSL_VERSION` |
| `ORACLE_SSL_CIPHER_SUITES` | `SSL_CIPHER_SUITES` |
| `ORACLE_SSL_SERVER_DN_MATCH` | `SSL_SERVER_DN_MATCH` |

## Oracle time-zone file version

Oracle mandates matching time-zone file versions on both server and client. If your Oracle server version does not match the version in your Hyperscience instance, the application will fail to start. You may see an error like the one shown below.

```python
ORA-01805: possible error in date/time operation
```

To prevent this issue from occurring, follow these steps:

1.  Determine the Oracle server time-zone file in use by running the following query:

```sql
SELECT * FROM v$timezone_file;
```

The result should be similar to the one shown below.

```sql
FILENAME                VERSION     CON_ID
-------------------- ---------- ----------
timezone_36.dat              36          0
```

2.  Obtain the time-zone file (e.g., `timezone_36.dat`) from the Oracle server. It can be found in `ORACLE_HOME/oracore/zoneinfo/`.

3.  Copy the file to `$HS_PATH/certs` on every machine running Hyperscience.

4.  Set the proper permissions for the folder by running these commands, replacing `<file_name>` with the name of the time-zone file:

```bash
chown -R 1000:1000 $HS_PATH/certs
chmod 644 $HS_PATH/certs/<file_name>
```

If SELinux is enabled, run the following command:

```bash
chcon -t container_file_t -R $HS_PATH/certs
```

5.  Add the following to your ".env" file, replacing `<file_name>` with the name of the time-zone file:

```bash
ORACLE_ZONEINFO_FILE=<file_name>
```

6.  Run these commands to restart the application:

```bash
sudo bash run.sh init
sudo bash run.sh --restart
```