# Connect Oracle Database with a token file

## When to use this

You want Oracle Database or Autonomous Database behind a swarmvia endpoint,
authenticating with an OCI IAM or Entra ID token rather than a database
password. Oracle's thin driver reads the token **from a file**, which is the
one JDBC login shape that is not a property; swarmvia writes it for every
connection.

## Setup

### 1. The identity and the user

For Autonomous Database, enable IAM authentication on the database and map
an IAM user or group to a database user; for Entra ID, register an app and
map it with `CREATE USER … IDENTIFIED GLOBALLY AS 'AZURE_USER=…'`. Grant the
user `CREATE SESSION` and `SELECT` on what it should read. Oracle honours
read-only connections and the user's grants are the boundary either way.

### 2. The source

**Sources → New source → JDBC data source → Oracle Database / Autonomous
Database.** The preset fetches `com.oracle.database.jdbc:ojdbc11`. Placeholders:
host, port `1521`, service name. The URL becomes:

```
jdbc:oracle:thin:@//adb.us-ashburn-1.oraclecloud.com:1521/abcdefg_sales_high.adb.oraclecloud.com
```

Autonomous Database with mutual TLS needs the wallet: upload `cwallet.sso`,
`tnsnames.ora` and `sqlnet.ora` as files on the credential and set the
public property `oracle.net.wallet_location` to the directory they share,
`(SOURCE=(METHOD=file)(METHOD_DATA=(DIRECTORY=${files})))`. Autonomous
Database with one-way TLS needs none of that.

### 3. The credential

**OAuth 2.0 client credentials** with your provider's token URL, client id
and secret, and the token **file** named `token`. The preset sets
`oracle.jdbc.tokenAuthentication=OAUTH` and
`oracle.jdbc.tokenLocation=${file:token}`, so the driver reads the token
swarmvia wrote for that connection.

A database password works as the public property `user` on the source and
the secret property `password` on the credential.

### 4. Query

```bash
curl https://oracle.swarmvia.cloud \
  -H "X-Swarmvia-Key: $SWARMVIA_KEY" \
  -H "content-type: application/json" \
  -d '{"queries":[{"sql":"SELECT order_id, customer_id, order_date FROM sales.orders WHERE order_date >= TO_DATE(?, ''YYYY-MM-DD'') FETCH FIRST 50 ROWS ONLY","params":["2026-01-01"]}]}'
```

Oracle's `NUMBER` and `DATE` arrive as the text the driver prints.

## Tips

- Oracle's driver caches the token file path per connection and the file is
  removed when the connection ends; a long statement keeps it in place.
- The Oracle driver is large. The first connection after an idle period pays
  the jar load; the runtime caches it by checksum for later ones.

## See also

- [JDBC sources](/docs/sources/jdbc)