> ## Documentation Index > Fetch the complete documentation index at: https://docs.bytebase.com/llms.txt > Use this file to discover all available pages before exploring further. # Oracle > Connect Bytebase to Oracle Database, including encrypted TCPS connections with an Oracle wallet. 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`. ```sql theme={null} CREATE USER bytebase IDENTIFIED BY ""; 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: ```sql theme={null} 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](#step-1-copy-the-connection-values-from-tnsnames-ora). ### 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](#step-4-choose-how-bytebase-signs-in). ### Password The account's password. You can also read it from a [secret manager](/get-started/connect/overview#secret-manager-integration). 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](/concepts/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](#connect-over-tcps-with-an-oracle-wallet). ### Extra Parameters Options that Bytebase passes to its built-in driver, [go-ora](https://github.com/sijms/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](#step-3-add-the-extra-parameters). ## 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: ```text theme={null} 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](/get-started/self-host/deploy-with-docker). The wallet path is then `/etc/oracle-wallet`. ```bash theme={null} docker run --rm --init \ --name bytebase \ --publish 8080:8080 --pull always \ --volume ~/.bytebase/data:/var/opt/bytebase \ --volume :/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 `. ### 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: ```bash theme={null} mkstore -wrl -createCredential "(DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS)(HOST=)(PORT=))(CONNECT_DATA=(SERVICE_NAME=)))" ``` **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 ''`, 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: ```sql theme={null} 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: 1. Download the wallet as described in [Oracle's instructions](https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/connect-download-wallet.html), and unzip it. Bytebase opens the auto-login `cwallet.sso`, so it doesn't need the password you set during the download. 2. Make the unzipped directory readable by Bytebase, as described in [Step 2](#step-2-make-the-wallet-readable-by-bytebase). 3. Copy the host, port, and service name from the wallet's `tnsnames.ora` entry you want to use, such as `_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. 4. In **Extra Parameters**, set `SSL` to `TRUE` and `WALLET` to the wallet directory. 5. 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 `. | | `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](/get-started/connect/overview#read-only-connections) has its own **Extra Parameters**. To use one with a TCPS listener, add the same `SSL` and `WALLET` entries to it. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.