Oracle

To add an Oracle database, go to Instances, click Connect instance, and choose Oracle.

Supported versions

Bytebase supports Oracle Database 11g and later. It connects through a built-in driver, so there is no Oracle Client, Instant Client, or JDBC driver to install.

Create a user for Bytebase

Create the user in the database Bytebase connects to, which is the pluggable database you enter as Service name. Grant it broad privileges so that Bytebase can manage the schemas there. The examples name the user bytebase.

CREATE USER bytebase IDENTIFIED BY "<password>";
GRANT ALL PRIVILEGES TO bytebase;

Put the password in double quotes. Single quotes fail with ORA-00988: missing or invalid passwords. On Amazon RDS for Oracle, the master user can’t grant ALL PRIVILEGES, because RDS withholds GRANT ANY PRIVILEGE from it. Grant the DBA role instead:

GRANT DBA TO bytebase;

Connection details

Hostname

The host name or IP address of the Oracle listener, such as db.example.com. For a TCPS connection, it must also be one of the names in the server’s certificate, as described in Step 1.

Port

The listener port. Oracle’s default is 1521. A TCPS listener has its own port, often 2484.

Username

The Oracle account Bytebase connects as. Leave it empty only for certificate login.

Password

The account’s password. You can also read it from a secret manager. With a wallet that stores the password, you can leave this field empty.

Connect using

Choose how the listener identifies the database:

Service name: the database service, such as a pluggable database (FREEPDB1) or a service your DBA created (sales.example.com). Use a service name to reach a pluggable database.
SID: the instance’s system identifier, such as ORCL.

Bytebase lists the user-owned schemas in that database as Bytebase databases. See Database.

TLS

Bytebase does not use the TLS settings for Oracle, so leave TLS mode at Disabled. To encrypt the connection, use an Oracle wallet as described in Connect over TCPS with an Oracle wallet.

Extra Parameters

Options that Bytebase passes to its built-in driver, go-ora, as key-value pairs. Click Add parameter to add one. Keys aren’t case-sensitive. The wallet keys are listed in Step 3.

Connect over TCPS with an Oracle wallet

Requires self-hosted Bytebase 3.5.1 or later. Bytebase reads the wallet from its own file system, which Bytebase Cloud doesn’t provide.

TCPS is Oracle Net over TLS. Your DBA enables it by adding a TCPS endpoint to the listener, backed by a server wallet that holds the server’s certificate and private key. Bytebase connects with a client wallet of its own.

How wallets work

An Oracle wallet is a directory of certificate files. The client wallet you give Bytebase can hold three kinds of entries:

Trusted certificates: the server’s certificate, or the certificate authority (CA) that signed it. Every wallet needs one so that Bytebase can verify the server. A wallet with only trusted certificates gives you one-way TLS.
A client certificate and its private key: needed when the listener requires client certificates, which is called mutual TLS (mTLS). Bytebase presents the certificate automatically. Autonomous Database wallets include one.
Stored passwords: database logins saved with mkstore, which Bytebase can use instead of the Password field.

Bytebase opens cwallet.sso, the auto-login file, or ewallet.p12 when you give it the wallet password. It doesn’t read tnsnames.ora, sqlnet.ora, the TNS_ADMIN environment variable, or the .jks and .pem files that some wallets include.

A tnsnames.ora entry supplies Hostname, Port and Service name, which you copy into the Bytebase form. Bytebase opens cwallet.sso from the wallet directory and ignores the other files.

Step 1: Copy the connection values from tnsnames.ora

Bytebase doesn’t read tnsnames.ora, so copy the values from your entry into the form. For example:

SALES_TCPS =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCPS)(HOST = db.example.com)(PORT = 2484))
    (CONNECT_DATA = (SERVICE_NAME = sales.example.com))
  )

In `tnsnames.ora`	In Bytebase
`HOST`	Hostname
`PORT`	Port
`SERVICE_NAME`	Connect using > Service name
`SID`	Connect using > SID

Bytebase checks Hostname against the Subject Alternative Names (SANs) in the server’s certificate and ignores the certificate’s Common Name. Use a host name listed there, or an IP address listed as an IP entry. If Bytebase reaches the database through another name, such as a load balancer or host.docker.internal, ask your DBA to add that name to the certificate.

Step 2: Make the wallet readable by Bytebase

The wallet must be a directory on the machine or container that runs Bytebase, readable by the user that runs it. On a host. Copy the wallet to a local directory and use that directory’s path. In Docker. Mount the wallet directory read-only by adding one --volume line to the Docker command. The wallet path is then /etc/oracle-wallet.

docker run --rm --init \
  --name bytebase \
  --publish 8080:8080 --pull always \
  --volume ~/.bytebase/data:/var/opt/bytebase \
  --volume <wallet_directory>:/etc/oracle-wallet:ro \
  bytebase/bytebase:latest

If you can’t change how the container starts, copy the wallet into the data directory you already mount, such as ~/.bytebase/data/oracle-wallet, and use /var/opt/bytebase/oracle-wallet. This works only when the data directory is a directory on the host, not a named Docker volume. On Kubernetes. Mount the wallet into the Bytebase pod, for example from a Secret, and use the mount path. The Bytebase container runs as root by default. If you run it as the image’s bytebase user (--user bytebase, uid 113), make the wallet readable by that user, for example with chmod -R a+rX <wallet_directory>.

Step 3: Add the extra parameters

In Extra Parameters, click Add parameter for each key:

Key	Value	When to set it
`SSL`	`TRUE`	Always. Without it, Bytebase connects without TLS, even when `WALLET` is set.
`WALLET`	The wallet directory, such as `/etc/oracle-wallet`	Always. Bytebase opens `cwallet.sso` in it.
`WALLET PASSWORD`	The wallet password	Only when the directory has `ewallet.p12` but no `cwallet.sso`. Bytebase then opens `ewallet.p12`.
`SSL VERIFY`	`FALSE`	Only to diagnose a certificate error. It turns off the certificate and hostname checks, so remove it afterward.

Leave the TLS section at Disabled.

Step 4: Choose how Bytebase signs in

Password. Fill in Username and Password. Bytebase always uses a filled-in password, even when the wallet stores a different one. Password stored in the wallet. Fill in Username and leave Password empty. Bytebase uses the wallet entry for that user whose connect descriptor has the same host, port, and service name as the form. Entries can’t match a connection that uses a SID. To add an entry, run the following command; mkstore prompts for the wallet password:

mkstore -wrl <wallet_directory> -createCredential "(DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS)(HOST=<host>)(PORT=<port>))(CONNECT_DATA=(SERVICE_NAME=<service_name>)))" <user> <password>

Certificate. Add AUTH TYPE with the value TCPS to Extra Parameters, and leave Username and Password empty. Oracle signs Bytebase in as the database user identified by the wallet’s client certificate. This needs:

A wallet with a client certificate, and a listener that requires client certificates.
A database user created with IDENTIFIED EXTERNALLY AS '<certificate_dn>', such as 'CN=bytebase'.
TCPS in SQLNET.AUTHENTICATION_SERVICES in the server’s sqlnet.ora.

Step 5: Test the connection

Click Test Connection, then Create. To confirm that the session is encrypted, open one of the instance’s databases in SQL Editor and run:

SELECT SYS_CONTEXT('USERENV', 'NETWORK_PROTOCOL') AS protocol FROM dual;

The result is tcps.

Autonomous Database

By default, Autonomous Database accepts only mutual TLS connections, so Bytebase connects with the database’s wallet. To connect, follow these steps:

Download the wallet as described in Oracle’s instructions, and unzip it. Bytebase opens the auto-login cwallet.sso, so it doesn’t need the password you set during the download.
Make the unzipped directory readable by Bytebase, as described in Step 2.
Copy the host, port, and service name from the wallet’s tnsnames.ora entry you want to use, such as <database_name>_low. The host is the regional endpoint, such as adb.us-ashburn-1.oraclecloud.com, and the port is usually 1522. The regional endpoint is one of the names in the database’s certificate, so leave SSL VERIFY unset.
In Extra Parameters, set SSL to TRUE and WALLET to the wallet directory.
Sign in as ADMIN or another database user, with its password.

Troubleshooting

Test Connection shows the error from the driver:

Error	Cause	Fix
`connection reset by peer` or `EOF`	Bytebase and the listener disagree about TLS. Usually `SSL` is missing for a TCPS port, because `WALLET` alone doesn’t turn on TLS. It also happens when `SSL` is set for a port without TLS.	Add `SSL` with the value `TRUE`, and check that Port is the TCPS port.
`open …/cwallet.sso: no such file or directory`	There is no `cwallet.sso` at the `WALLET` path as Bytebase sees it, or the wallet has only `ewallet.p12`.	Check the path inside the Bytebase container. For a wallet with only `ewallet.p12`, add `WALLET PASSWORD`.
`open …/cwallet.sso/cwallet.sso: not a directory`	`WALLET` points at the `cwallet.sso` file instead of its directory.	Set `WALLET` to the directory.
`open …/cwallet.sso: permission denied`	The user that runs Bytebase can’t read the wallet.	Make the files readable, for example with `chmod -R a+rX <wallet_directory>`.
`x509: certificate signed by unknown authority`	TLS is on, but Bytebase didn’t load a wallet, or the wallet doesn’t trust the server’s certificate.	Set `WALLET`, and make sure the wallet holds the server’s certificate or its CA.
`x509: certificate is valid for …, not …`	Hostname isn’t among the SANs in the server’s certificate.	Use a name from the certificate, or have the certificate reissued. To confirm the cause, add `SSL VERIFY` with the value `FALSE`, then remove it.
`x509: certificate relies on legacy Common Name field, use SANs instead`	The server’s certificate has no SANs, and Bytebase doesn’t use the Common Name. The Autonomous Database Free container image issues a certificate like this.	Have the certificate reissued with SANs. For a local test database only, add `SSL VERIFY` with the value `FALSE`.
`remote error: tls: certificate required`	The listener requires a client certificate, and the wallet has none that the server trusts.	Use a wallet with a client certificate whose CA the server trusts.
`cannot find credentials for server: …`	Password is empty, and the wallet has no stored password for this user, host, port, and service name.	Fill in Password, or add a matching wallet entry.
`ORA-01017: invalid credential or not authorized; logon denied`	The password is wrong. With a wallet, Username may be empty without `AUTH TYPE`, or filled in with `AUTH TYPE`.	Check the password. For certificate login, leave Username and Password empty.
`invalid Wallet header version` or `can't read Wallet with auto login local properties`	The wallet was created with `orapki ... -auto_login_local`, which locks it to the machine that created it.	Create the wallet with `-auto_login` instead.

Read-only connection

A read-only connection has its own Extra Parameters. To use one with a TCPS listener, add the same SSL and WALLET entries to it.

Introduction

Quick Start

Bytebase Essentials

Install

Connect Databases

Onboarding Guides

Supported versions

Create a user for Bytebase

Connection details

Hostname

Port

Username

Password

Connect using

TLS

Extra Parameters

Connect over TCPS with an Oracle wallet

How wallets work

Step 1: Copy the connection values from tnsnames.ora

Step 2: Make the wallet readable by Bytebase

Step 3: Add the extra parameters

Step 4: Choose how Bytebase signs in

Step 5: Test the connection

Autonomous Database

Troubleshooting

Read-only connection

​Supported versions

​Create a user for Bytebase

​Connection details

​Hostname

​Port

​Username

​Password

​Connect using

​TLS

​Extra Parameters

​Connect over TCPS with an Oracle wallet

​How wallets work

​Step 1: Copy the connection values from tnsnames.ora

​Step 2: Make the wallet readable by Bytebase

​Step 3: Add the extra parameters

​Step 4: Choose how Bytebase signs in

​Step 5: Test the connection

​Autonomous Database

​Troubleshooting

​Read-only connection

Supported versions

Create a user for Bytebase

Connection details

Hostname

Port

Username

Password

Connect using

TLS

Extra Parameters

Connect over TCPS with an Oracle wallet

How wallets work

Step 1: Copy the connection values from tnsnames.ora

Step 2: Make the wallet readable by Bytebase

Step 3: Add the extra parameters

Step 4: Choose how Bytebase signs in

Step 5: Test the connection

Autonomous Database

Troubleshooting

Read-only connection