Skip to main content

Oracle Database

Connect an Oracle database so NudgeBee can analyse its health and query it from workflows.

info

Oracle is always reached through the Proxy Agent — there is no in-cluster secret mode.

Prerequisites​

  • A Proxy Agent that can reach the listener.
  • An Oracle user NudgeBee can authenticate as, with CREATE SESSION and read access to the dynamic performance views.
  • The service name of the database — not the SID. For a pluggable database this is typically something like XEPDB1 or ORCLPDB1.
CREATE USER nudgebee IDENTIFIED BY "<YOUR_PASSWORD>";
GRANT CREATE SESSION TO nudgebee;
GRANT SELECT_CATALOG_ROLE TO nudgebee;

-- Only if you want NudgeBee to query application data as well as diagnose the instance:
GRANT SELECT ON <app_schema>.<table> TO nudgebee;

SELECT_CATALOG_ROLE covers every dictionary view NudgeBee reads for diagnostics — V$SESSION, GV$SESSION, V$SQL, V$LOCKED_OBJECT, V$ACTIVE_SESSION_HISTORY and DBA_OBJECTS — and nothing beyond the data dictionary. It grants no access to application data.

That last point matters: SELECT_CATALOG_ROLE alone lets NudgeBee analyse sessions, locks and SQL statistics, but a question about your own tables will fail with ORA-00942. Grant SELECT explicitly on the tables you want readable. NudgeBee's schema introspection uses USER_TABLES and USER_TAB_COLUMNS, which describe the nudgebee user's own schema, so it will report an empty schema until such grants exist.

note

V$ACTIVE_SESSION_HISTORY is part of the Oracle Diagnostics Pack. The grant above makes it readable, but querying it on an instance without that licence is a licensing violation. Everything else NudgeBee reads is licence-free.

Step 1: Open the Configuration Form​

Navigate to Admin > Integrations > Databases and select Oracle, then click Add Oracle Account.

The Oracle tile in the Databases tab of the integrations catalog

Step 2: Fill In the Connection​

  • Oracle host — Hostname or IP of the listener, e.g. db.example.com or 10.0.1.5.
  • Oracle port — Typically 1521.
  • Oracle service name — The service name, e.g. ORCL or XEPDB1. Using a SID here is the most common cause of a failed connection.
  • Credential Source, Database username *, Database password *, TLS Enabled, Read Only, Maximum open connections in the pool — see common fields.

The Oracle configuration form, showing the service name field that must not be given a SID

Step 3: Test and Save​

Click Test Connection, then Save.

What Gets Connected​

CapabilityWhat NudgeBee reads
Health checkV$SESSION, V$LOCK, tablespace usage and wait events
Slow queriesV$SQL and V$SQLSTATS
Workflow queriesAny SQL you supply via dbms.query with dbms_type: oracle

Verify the Integration​

  1. Click Test Connection on the form — it should succeed before you save.
  2. Ask NuBi to check the health of the database by the name you gave it.
  3. In a workflow, run a dbms.query task with SELECT 1 FROM DUAL.

Troubleshooting​

See the shared troubleshooting table first. Oracle-specific cases:

SymptomLikely CauseFix
ORA-12514: listener does not currently know of serviceA SID was entered instead of a service nameUse the service name. lsnrctl services on the database host lists them.
ORA-01017: invalid username/passwordPassword case, or a quoted identifierOracle passwords are case-sensitive by default; enter it exactly as created.
ORA-00942: table or view does not exist on V$ viewsMissing catalog accessGRANT SELECT_CATALOG_ROLE TO nudgebee;
ORA-12541: no listenerWrong port, or the listener is not runningConfirm the listener port and that it is reachable from the Forager host.
ORA-28000: the account is lockedFailed login attempts locked the userALTER USER nudgebee ACCOUNT UNLOCK; and correct the stored password.