Connecting to Oracle

This page is an outline. What is here is accurate, but it is not yet the whole story — each section ends with a note on what is still to be written. For anything it does not answer, DEPLOYMENT.md and USING-MCP.md in the repository are the complete references.

The Oracle connection is configuration, not something anyone types into a form. The Design pages have no connect form: host, port, SID, username and an optional second schema all come from the environment. Everything except the password is shown in the console so an operator can check what they are pointed at.

  -e MCPDBWIZARD_ORACLE_HOST=db.example.com \
  -e MCPDBWIZARD_ORACLE_PORT=1521 \
  -e MCPDBWIZARD_ORACLE_SID=/PDB1 \
  -e MCPDBWIZARD_ORACLE_USER=appuser \
  -e DB_PASS_FILE=/run/secrets/oracle

SID or service name

A leading / selects the service-name form; without it the SID form is used. They are not interchangeable, and picking the wrong one is the commonest connection failure after a password.

MCPDBWIZARD_ORACLE_SID=/FREEPDB1     ->  jdbc:oracle:thin:@//host:1521/FREEPDB1
MCPDBWIZARD_ORACLE_SID=ORCL          ->  jdbc:oracle:thin:@host:1521:ORCL

The password is the one Oracle secret

Supply it as DB_PASS, or better as DB_PASS_FILE pointing at a Docker or Kubernetes secret. That form stays out of docker inspect, is not inherited by every child process, is tmpfs-backed rather than written to a disk layer, and can be rotated by replacing the file.

Set exactly one. Setting both is an error rather than a precedence rule, because two sources for one secret hides which credential is in use. A trailing newline is stripped; a trailing space is not, because it may be part of the password.

A config saved from the console never contains a password. It records a FROM_ENV_VARIABLE_DB_PASS placeholder where the password would go, so there is nothing on the volume to leak.

When it cannot connect

The console becomes a single error screen naming the reason, what it is pointed at, and whether reloading will help — a missing setting is read once at startup and needs a restart, while a database that is down is retried on every page load.

Servers that were already running are not affected. Each holds its own connection and keeps answering agents.

To write. TNS and wallet support; TLS to the database; RAC and SCAN addresses; what the second schema setting is for and when to use it.