Skip to content
HeliosDB HeliosDB Full

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

SettingFlagEnvironment variableDefault
Enable--enable-oracle—off
Port--oracle-portHELIOSDB_ORACLE_PORT1521
Bind address (all listeners)--bind-addrHELIOSDB_BIND_ADDR127.0.0.1
Allow a non-loopback bind--allow-externalHELIOSDB_ALLOW_EXTERNALoff
Logon password—HELIOSDB_ORACLE_NATIVE_PASSWORDthe user name; always set it
Connections (all listeners)--max-connectionsHELIOSDB_MAX_CONNECTIONS10000
New connections per client IP--conn-rate-limitHELIOSDB_CONN_RATE_LIMIT500 per minute
Handshake deadline--startup-timeout-secsHELIOSDB_STARTUP_TIMEOUT_SECS30
Terminal window
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)

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 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

SymptomCheck
ORA-12541 / connection refusedServer started with --enable-oracle; log shows Oracle (TNS) protocol listening on ...; firewall and --bind-addr
Failed to bind Oracle port in the logAnother process uses the port; change --oracle-port
DPY-4035 or logon failureThe 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 statementThe statement uses Oracle-only syntax; see the quick start’s rewrite table
A call hangs until timeoutRe-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.