---
title: "Oracle Protocol Configuration"
---

# Oracle Protocol Configuration

The Oracle TNS listener of HeliosDB Full is configured with `heliosdb-full` startup
flags and environment variables. There is no `[oracle]` section in the config file:
the server reads only `[storage]` keys from it and refuses to start when a file sets
keys it does not honour.

## Table of Contents

- [Enabling the Listener](#enabling-the-listener)
- [Authentication](#authentication)
- [Network Security](#network-security)
- [Client Configuration](#client-configuration)
- [Session Behaviour](#session-behaviour)
- [Troubleshooting](#troubleshooting)

## Enabling the Listener

| Setting | Flag | Environment variable | Default |
|---------|------|----------------------|---------|
| Enable | `--enable-oracle` | — | off |
| Port | `--oracle-port` | `HELIOSDB_ORACLE_PORT` | 1521 |
| Bind address (all listeners) | `--bind-addr` | `HELIOSDB_BIND_ADDR` | `127.0.0.1` |
| Allow a non-loopback bind | `--allow-external` | `HELIOSDB_ALLOW_EXTERNAL` | off |
| Logon password | — | `HELIOSDB_ORACLE_NATIVE_PASSWORD` | the user name; always set it |
| Connections (all listeners) | `--max-connections` | `HELIOSDB_MAX_CONNECTIONS` | 10000 |
| New connections per client IP | `--conn-rate-limit` | `HELIOSDB_CONN_RATE_LIMIT` | 500 per minute |
| Handshake deadline | `--startup-timeout-secs` | `HELIOSDB_STARTUP_TIMEOUT_SECS` | 30 |

```bash
export HELIOSDB_ORACLE_NATIVE_PASSWORD='a-long-random-password'
heliosdb-full --data-dir /var/lib/heliosdb --enable-oracle
# Oracle (TNS) protocol listening on 127.0.0.1:1521
```

The listener negotiates a TNS version of 12.1 or later with the client and the 4-byte
packet framing that 12.2+ clients use. Service names and SIDs in the connect
descriptor are accepted without being checked, so one listener serves any service
name.

## Authentication

Logons use Oracle's O5LOGON challenge-response: the password never crosses the network
in clear text. The listener has one password, `HELIOSDB_ORACLE_NATIVE_PASSWORD`, which
any user name may log on with; it does not use the PostgreSQL role catalog. Set the
variable from your secrets store, rotate it like any shared credential (change it and
restart the server), and restrict who can reach the port.

## Network Security

- The listener has no TLS and no Oracle native network encryption; statements and
  results travel in plaintext.
- Bind to loopback or a private interface, and firewall port 1521 to the application
  hosts.
- For traffic between sites, use a VPN, an SSH tunnel or a TLS proxy.

## Client Configuration

The service name can be anything; `heliosdb` is the convention in these docs.

**Easy Connect**

```
host:1521/heliosdb
```

**tnsnames.ora**

```
HELIOSDB =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCP)(HOST = db.internal)(PORT = 1521))
    (CONNECT_DATA = (SERVICE_NAME = heliosdb))
  )
```

**python-oracledb (thin mode, tested)**

```python
import os, oracledb
conn = oracledb.connect(user="app", password=os.environ["HELIOSDB_ORACLE_NATIVE_PASSWORD"],
                        dsn="db.internal:1521/heliosdb")
conn.autocommit = True
```

**JDBC thin**

```
jdbc:oracle:thin:@//db.internal:1521/heliosdb
```

## Session Behaviour

- Statements run on the same SQL engine as the PostgreSQL listener and see the same
  tables, without Oracle-dialect translation; the
  [Oracle Quick Start](/docs/full/quick-starts/protocols/oracle_quick_start/) lists
  what runs and what to rewrite.
- Each statement commits as it runs; use autocommit. Driver `commit()`/`rollback()`
  calls are not supported yet.
- Open a new cursor for each statement.
- Bind variables (`:1`, `:name`) and `executemany` are supported.

## Troubleshooting

| Symptom | Check |
|---------|-------|
| `ORA-12541` / connection refused | Server started with `--enable-oracle`; log shows `Oracle (TNS) protocol listening on ...`; firewall and `--bind-addr` |
| `Failed to bind Oracle port` in the log | Another process uses the port; change `--oracle-port` |
| `DPY-4035` or logon failure | The client password does not match `HELIOSDB_ORACLE_NATIVE_PASSWORD` |
| `DPY-3010` (version not supported) | Use a client that supports TNS 12.1 or later |
| `ORA-00900` on a statement | The statement uses Oracle-only syntax; see the quick start's rewrite table |
| A call hangs until timeout | Re-executing a statement on the same cursor, or a driver `commit()`/`rollback()`; use a new cursor and autocommit |

Run the server with `--verbose` (debug logging) to log the statements the listener
receives in detail.

## Related

- [Oracle Quick Start](/docs/full/quick-starts/protocols/oracle_quick_start/)
- [Connecting](/docs/full/guides/user/connecting/)
- [Server Configuration Reference](/docs/full/reference/configuration/)