TuneVault Setup Guide

Connect your Oracle database to TuneVault in 5 steps. Covers direct TNS connections and the proxy agent for environments without inbound network access.

Oracle 12.1+ ~15 min setup For DBAs and sysadmins

On this page

01 Create Oracle Reader Account
02 Choose Your Connection Method
03 Direct Connection Setup (TNS)
04 Proxy Agent Installation
05 Connect in TuneVault Dashboard

Step 01

Create Oracle Reader Account

TuneVault uses a dedicated, read-only Oracle user to run diagnostic queries. This keeps your application credentials separate and limits the scope of database access to monitoring only.

Connect as SYS or SYSTEM and run each SQL statement below. Execute them one at a time.

SQL — Run as SYS or SYSTEM

-- Create the dedicated read-only user
CREATE USER tunevault_reader IDENTIFIED BY 'YourSecurePassword123!';

-- Allow the user to log in to the database
GRANT CREATE SESSION TO tunevault_reader;

-- Grant read access to DBA_ data dictionary views
GRANT SELECT ANY DICTIONARY TO tunevault_reader;

-- Grant access to V$ dynamic performance views
GRANT SELECT_CATALOG_ROLE TO tunevault_reader;

-- Required for alert log checks (V$DIAG_ALERT_EXT)
GRANT SELECT ON V_$DIAG_ALERT_EXT TO tunevault_reader;

What each permission does:

CREATE SESSION — allows the user to connect to the database. Without this, nothing else works.

SELECT ANY DICTIONARY — read access to DBA_ views including DBA_TABLESPACES, DBA_SEGMENTS, DBA_INDEXES, DBA_JOBS, and hundreds of others needed for health checks.

SELECT_CATALOG_ROLE — read access to V$ dynamic performance views including V$SQL, V$SESSION, V$SYSSTAT, V$RMAN_BACKUP_JOB_DETAILS, and AWR-related views.

GRANT SELECT ON V_$DIAG_ALERT_EXT — required for alert log analysis. This view requires an explicit grant even with SELECT_CATALOG_ROLE. Without it, alert log checks will show "insufficient privileges" instead of real log data.

Replace YourSecurePassword123! with a strong password of your choosing. Keep it — you'll enter it in TuneVault in Step 5.

Step 02

Choose Your Connection Method

TuneVault supports two ways to reach your Oracle database. Choose based on your network setup.

Option A

Direct Connection (TNS)

TuneVault connects directly to your Oracle listener on port 1521. Use this when your database host is reachable from TuneVault's servers — for example, a cloud-hosted database or a server with port 1521 accessible from the internet.

Option B

TuneVault Agent Proxy

A lightweight proxy runs on your database server (or inside your network) and opens an outbound HTTPS connection to TuneVault. No inbound firewall rules needed. Use this for on-premises databases or when port 1521 is not publicly reachable.

Not sure which to use? If you can run telnet your-oracle-host 1521 from outside your network and get a response, use Option A (Direct). If not — or if your Oracle host is on-premises — use Option B (Proxy).

Step 03

Direct Connection Setup (TNS)

If you chose Option A, no software installation is needed. Gather your TNS details and enter them directly in the TuneVault dashboard in Step 5.

Field	Description	Example
Host	Hostname or IP address of the Oracle server	db.example.com
Port	Oracle listener port — default is 1521	1521
Service Name / SID	Oracle service name (e.g. `ORCL`, `ORCLPDB1`) or SID. Prefer service name for Oracle 12+.	ORCL
Username	The read-only account created in Step 1	tunevault_reader
Password	Password set in Step 1	YourSecurePassword123!

Using direct connection? Skip Step 4 entirely — proxy installation is only needed for Option B. Go straight to Step 5.

Step 04

Proxy Agent Installation

If you chose Option B, install the TuneVault proxy on your Oracle server or on any server inside your network that can reach Oracle on port 1521. Requires root / sudo access.

4a. Download the proxy script

Choose the language that fits your environment. All three are functionally identical.

🐍

↓

4b. Edit proxy.env with your credentials

Create a file called proxy.env in the same directory as the proxy script. Fill in each value:

proxy.env

# Required: API key (enter this in TuneVault when adding the connection)
export TUNEVAULT_API_KEY="your-secret-key-here"

# Oracle connection details
export ORACLE_HOST="localhost"
export ORACLE_PORT="1521"
export ORACLE_SERVICE="ORCL"
export ORACLE_USER="tunevault_reader"
export ORACLE_PASSWORD="your-oracle-password"

# Optional: listen port (default 3100)
export PROXY_PORT="3100"

Where to get TUNEVAULT_API_KEY: In the TuneVault dashboard, click Add Connection and switch to the Proxy / HTTPS Proxy tab. Your unique API key will be displayed automatically — copy it into your proxy.env file before running the install script.

4c. Run the install script

The install script registers the proxy as a system service and starts it. Run it as root or with sudo:

Terminal — run as root or with sudo

# Make the install script executable
chmod +x oracle-proxy-install.sh

# Run the installer — registers and starts the systemd service
sudo ./oracle-proxy-install.sh

Root access required. The install script writes to /etc/systemd/system/ to register the proxy as a service. It must be run by a sysadmin with root or sudo privileges.

4d. Restart after configuration changes

If you update proxy.env after the initial install, restart the service for changes to take effect:

Terminal

sudo systemctl restart tunevault-proxy

Once running, the proxy listens on http://your-server:3100 and forwards diagnostic queries from TuneVault to your Oracle instance. All traffic is outbound HTTPS from your server to TuneVault — no inbound firewall rules are required.

Step 05

Connect in TuneVault Dashboard

With your Oracle reader account ready and your connection method set up, add the connection in TuneVault.

Sign in at tunevault.app and open your dashboard.
Click Add Connection (or the + New Connection button).
Click the Direct TCP or Proxy / HTTPS Proxy tab to match your setup from Step 2.
Enter the connection details — see the tables below.
Click Test Connection — you should see a green confirmation.
Save the connection and click Run Health Check.

For Direct TCP connections (Option A)

Field	What to enter
Host	Oracle server hostname or IP (e.g. `db.example.com`)
Port	Listener port — almost always `1521`
Service / SID	Oracle service name or SID (e.g. `ORCL`, `ORCLPDB1`)
Username	`tunevault_reader` (the account from Step 1)
Password	The password you set in Step 1

For Proxy Agent connections (Option B)

Field	What to enter
Proxy URL	Address where the proxy is listening — e.g. `http://your-server:3100`
API Key	The `TUNEVAULT_API_KEY` value from your `proxy.env` file in Step 4

Connection test failing?

Direct TCP: Verify port 1521 is reachable from outside your network with telnet your-oracle-host 1521. Also confirm the tunevault_reader account was created and has the grants from Step 1.

Proxy Agent: Check that the proxy service is running with sudo systemctl status tunevault-proxy. Verify ORACLE_HOST and ORACLE_PORT in proxy.env point to the correct Oracle server on your network.

All set — run your first health check and see what TuneVault finds.

Run Health Check →