Oracle

Covers Oracle Database 12.2 or later. Tested on Oracle AI Database 26ai Free (release 23.26).

Before you start

• Oracle 12.2 or later, with a TLS (TCPS) listener. Unless the database runs on the gateway’s own machine, the gateway connects only over TCPS.
• The listener’s certificate must come from a public CA and name the host you connect to. Oracle’s setup form has no field for a company CA.
• An administrator who can create a user and grant SELECT on the tables.
• The host name on the gateway’s allowed hosts (Allow the host).

Network access

The gateway connects to the listener’s TLS port, often 2484 or 1522. Open that port to the gateway as described in Network access.

Create a read-only login

Portward needs a separate user. Don’t use the schema that owns the tables, because an owner can change every table it owns. Connect to the pluggable database as an administrator and run this. Replace sales with the schema that owns the tables, list each table Portward may read, and replace <password> with a strong password.

CREATE USER portward_reader IDENTIFIED BY "<password>";
GRANT CREATE SESSION TO portward_reader;
GRANT SELECT ON sales.customers TO portward_reader;
GRANT SELECT ON sales.orders TO portward_reader;

On Oracle Database 23ai or later, one grant covers every table in the schema, now and later:

GRANT READ ANY TABLE ON SCHEMA sales TO portward_reader;

Grant nothing else. Setup refuses the user if it has a role such as DBA, a system privilege with ANY in it (other than SELECT ANY and READ ANY), or an administrator privilege such as ALTER SYSTEM or CREATE USER.

Connect it in setup

Choose Oracle and fill in Name (the name people and the AI see, such as sales), Host, Port (the TLS port), Service name (the pluggable database’s service, such as ORCLPDB1), Schema (the tables’ owner, such as SALES), User (portward_reader) and Password.

What the setup check tests

Before it saves, setup connects with the user and checks, in this order:

1. The host is on the allowed hosts (“isn’t in the hosts the gateway operator allowed for setup”).
2. It can connect over TLS. Each failure has its own message: “login failed; check the user and password”, “the database service isn’t known to the listener”, “the server didn’t answer; check the host, port and its firewall”, or “TLS failed; check the port”.
3. The schema exists (“not found”), and the user doesn’t own it (“the login owns schema”).
4. The user is not an administrator (“connect with a read-only user, not an administrator”): no administrator role or system privilege, and no ANY privilege that writes.
5. A token computed inside Oracle matches the gateway’s own (“in-database tokens don’t match Python”).
6. It lists the schema’s tables the user can see. A table the user could INSERT, UPDATE, DELETE, ALTER (or change in another way, including a column-level UPDATE grant) is listed as one it could change, and can’t be exposed.

Each query runs in a read-only transaction, so Oracle itself refuses a write.