Database governance built for humans and agents — controlling changes and access across every major database.
Oracle TLS
Status: implemented in this PR · 2026-10-14 · BYT-10315
The instance form's TLS section (TLS mode, Verify server certificate, CA certificate, client certificate and key) has never reached the Oracle driver. The driver gives go-ora only the Extra Parameters, the SID and a dial timeout, so TLS mode TLS connects without TLS. The TLS section decides the connection: TLS mode TLS and Mutual TLS connect over TCPS with the section's certificates, Verify server certificate checks the certificate chain and the name of the server Bytebase connects to, and go-ora's own TLS keys in Extra Parameters give way to the section, with a notice under each. The upgrade turns TLS mode off and removes the certificates on existing Oracle data sources, where they never applied, so they keep connecting.
Problem
Verified on main at 53fb4815dc:
- TLS mode does nothing.
Driver.Openinbackend/plugin/db/oracle/oracle.gobuilds the go-ora URL from the Extra Parameters, the SID and the dial timeout. It never readsuse_ssl,verify_tls_certificate,ssl_ca,ssl_certorssl_key. The form shows the whole TLS section for Oracle (instanceV1HasSSL), so a user who turns TLS on and pastes a CA saves successfully and gets a connection without TLS. Against a TCPS port it fails withEOForconnection reset by peer(BYT-10206 lab, Bytebase 3.23.0). - Unused files can still fail the connection. With TLS on,
dbfactory.GetDataSourceDriverreads a CA or client certificate file path before it opens the driver, so a missing file fails a connection that would never use it. - A private CA or a client certificate needs a wallet.
SSL=TRUEin Extra Parameters connects over TCPS and checks the certificate against the system roots. Trusting any other CA, or sending a client certificate, takesWALLETtoo. A wallet is a directory on the Bytebase host, which Bytebase Cloud doesn't provide, and making one from a PEM CA takes Oracle'sorapki.
Oracle is the only engine in instanceV1HasSSL whose driver reads none of the TLS section.
Principle
What the TLS section shows is what the connection does. An upgrade doesn't break a connection that works today: where the stored settings and the connection disagreed, the upgrade changes the settings to match the connection, and the form shows it.
How go-ora reads the options
Bytebase links github.com/sijms/go-ora/v2 v2.9.0.
| Option | Effect |
|---|---|
SSL |
TRUE, ENABLE or ENABLED, in any case, connects over TCPS; any other value over TCP. Off by default. |
SSL VERIFY |
The same values. Checks the certificate chain and the server name. On by default. |
WALLET |
A wallet directory. go-ora opens cwallet.sso, or ewallet.p12 with WALLET PASSWORD. With SSL on, it trusts the wallet's certificates and sends its client certificate. With Username set and Password empty, it signs in with the wallet's stored password. |
- Keys. go-ora upper-cases each key. When two keys name the same option, which value wins depends on map order.
- A supplied TLS configuration.
OracleConnector.WithTLSConfiggives go-ora acrypto/tlsconfiguration. go-ora then uses it for the handshake instead ofSSL VERIFYand the wallet's certificates;SSLstill decides whether there is a handshake. Before each handshake, go-ora sets the configuration'sServerNameto the server it dialed: Hostname, an address fromSERVERorconnStr, or a listener's redirect target. go-ora's connector hands the same configuration to every connection. - Addresses that name a protocol. An address in a
connStrdescriptor or a listener redirect that namesPROTOCOL=TCPconnects over TCP, whateverSSLsays. go-ora reads the descriptor only from a key spelledconnStr.
Decisions
D1 · Build the TLS configuration from the section and give go-ora a copy per connection.
Bytebase builds it with util.GetTLSConfig, as MySQL and PostgreSQL do, and opens the database
through a connector that clones it for each connection. Rejected: go-ora's URL options alone. They
take certificates only from a wallet directory, which a pasted PEM isn't. Rejected: one shared
configuration through WithTLSConfig. go-ora writes ServerName on it at each connect, a data race
when the pool opens connections in parallel, and with SERVER addresses one connection can be
checked against another's name.
D2 · TLS mode TLS and Mutual TLS set SSL=TRUE. Mutual TLS also sends the section's client
certificate, which is the certificate AUTH TYPE=TCPS in Extra Parameters signs in with. An
address that names PROTOCOL=TCP is the exception go-ora keeps; see Not in this PR.
D3 · Verify server certificate checks the chain and the dialed server's name. The chain is
checked against the CA when one is set (pasted or file path), otherwise against the system roots.
The name is checked against the server go-ora dialed, as go-ora's own SSL VERIFY does, so a
standby in SERVER is checked against its own name. Rejected: util.GetTLSConfig's verifier as
is. It checks Host, so a standby whose certificate names only itself fails. With Verify off, the
certificate isn't checked, and the connection is still encrypted.
D4 · TLS mode Disabled keeps today's connection. Extra Parameters apply as given, including
SSL=TRUE with a wallet.
D5 · Under TLS mode TLS or Mutual TLS, the section replaces go-ora's own TLS keys. An SSL key
in any spelling is replaced by TRUE. SSL VERIFY and the wallet's certificates aren't used,
because the section's configuration replaces them. A password stored in the wallet still signs in
when Password is empty. Rejected: the wallet wins over the section, which lets the form show a CA
that the connection doesn't use. Rejected: an error on the combination, since a wallet that only
stores the password is a valid setup.
D6 · The form marks each Extra Parameter the section replaces. On an Oracle data source with
TLS mode TLS or Mutual TLS, a warning line appears under each SSL, SSL VERIFY and WALLET row,
in any spelling and whatever its value. Saving isn't blocked. Rejected: warning only when the value
disagrees with the section. A matching key does nothing either, and the form would have to parse
values as go-ora does. Rejected: one note under TLS mode, away from the row it is about.
D7 · The upgrade turns TLS mode off and removes the certificates on every Oracle data source.
Migration 3.24.2 removes useSsl, the CA and the client certificate, as turning TLS off in the
form does, also where TLS mode is already off: the API has cleared certificates on save only since
3.17.1 (#20062), so older data sources can still hold a CA. All Oracle data sources connect today
as if TLS mode were Disabled, so honoring the stored value would fail every one whose port serves
plain TCP or whose certificate doesn't verify; the form turns Verify on whenever TLS is turned on.
Data sources whose Extra Parameters set SSL=TRUE keep their TLS connection under D4. Rejected:
honoring the stored value. It is secure, but syncs, queries and rollouts would stop until someone
edits each data source. Rejected: keeping the certificates. Turning TLS mode on would then trust a
kept CA while the form showed System trust.
States
What Bytebase sends, by TLS section, with no Extra Parameters:
| TLS mode | Verify | CA | SSL |
Certificates trusted | Client certificate | Certificate check |
|---|---|---|---|---|---|---|
| Disabled | any | any | unset | None | None | None; no TLS |
| TLS | Off | any | TRUE |
Any | None | None |
| TLS | On | Pasted or file path | TRUE |
The CA | None | Chain to the CA; dialed server's name |
| TLS | On | System trust | TRUE |
System roots | None | Chain to the system roots; dialed server's name |
| Mutual TLS | As TLS | As TLS | TRUE |
As TLS | The section's | As TLS |
Extra Parameters under TLS mode TLS or Mutual TLS:
| Key | Result | Form notice |
|---|---|---|
SSL |
Replaced by TRUE |
Overridden by the TLS section. |
SSL VERIFY |
Not used; Verify server certificate decides | Overridden by the TLS section. |
WALLET |
Its certificates aren't used. A password stored in it still signs in when Password is empty, and go-ora still opens it, so a wallet it can't read fails the connection | Only its stored password is used. The TLS section supplies the certificates. |
Any other key, such as SERVER or AUTH TYPE |
Applies | None |
Under TLS mode Disabled, Extra Parameters apply as given, and the form shows no notice.
Upgrade and breaking changes
| Before the upgrade | After |
|---|---|
| TLS mode TLS or Mutual TLS | TLS mode shows Disabled. The connection is unchanged: plain TCP, or TLS through Extra Parameters. |
| A stored CA or client certificate, in any TLS mode | Removed |
| TLS mode Disabled, no certificates | Unchanged |
These changes can break a setup:
- TLS mode TLS now uses TLS. Set through the form, the API or Terraform, it connects over
TCPS. A port that serves plain TCP, usually 1521, fails with
EOForconnection reset by peer. - Verify server certificate now verifies. The certificate must chain to the CA, or to a system
root under System trust, and name the server Bytebase connects to. Typical failures are a
private CA with no CA pasted (
certificate signed by unknown authority), a name the certificate doesn't list (certificate is valid for …, not …), and an IP address it doesn't list (doesn't contain any IP SANs). - Terraform turns TLS mode back on. The provider sends every data source on update, and
use_ssldefaults tofalse. A configuration that setsuse_ssl = trueon an Oracle data source shows a diff after the upgrade, and the nextterraform applyturns TLS mode on. The apply succeeds, because updating an instance doesn't test the connection. Syncs, queries and rollouts then fail if 1 or 2 applies. Configurations that omit the field are unaffected. - go-ora's TLS keys give way under TLS mode TLS.
SSL=FALSEno longer turns TLS off,SSL VERIFYis ignored, and the wallet's certificates aren't used.
Release note draft:
Oracle: TLS settings now take effect. TLS mode TLS connects over TCPS, Verify server certificate checks the server's certificate against your CA, or the system's trusted CAs, and the host name, and Mutual TLS sends your client certificate, so TLS no longer needs an Oracle wallet. The upgrade turns TLS mode off and removes the stored certificates on existing Oracle data sources, which never applied them, so they keep connecting as before; turn TLS on and add your CA to use it. With TLS mode on,
SSL,SSL VERIFYand a wallet's certificates in Extra Parameters no longer apply. Terraform: if your configuration setsuse_ssl = trueon an Oracle data source, the nextterraform applyturns TLS on. Make sure the port serves TCPS and the certificate verifies first, or set it tofalse.
Scope
| File | Change |
|---|---|
backend/plugin/db/oracle/oracle.go |
Open builds the TLS configuration (D1 to D3) and opens through a connector that clones it per connection; connectionOptions sets SSL=TRUE and drops SSL keys under TLS mode TLS (D5) |
backend/migrator/migration/3.24/0002##oracle_tls_off.sql |
D7 |
frontend/src/components/instance/DataSourceForm.tsx, tls.ts |
D6 |
frontend/src/locales/*.json |
D6 notices |
Tests:
TestOpenAppliesTLSSettingsopens the driver against a TLS listener in the test that stands in for an Oracle TCPS port. Disabled doesn't start a handshake. TLS completes one, and with Verify on accepts the signing CA throughlocalhostand rejects127.0.0.1, an unrelated CA and system trust. ASERVERaddress is checked against its own name. Mutual TLS presents the client certificate, and TLS mode TLS presents none.SSL=FALSEandSSL VERIFY=FALSEin Extra Parameters can't turn TLS or verification off. Connecting leaves the connector's configuration unchanged, so each connection gets its own copy. The listener ends each connection after the handshake, so these tests stop short of the Oracle protocol.TestConnectionOptionsandTestConnectionOptionsAsReadByDrivercover theSSLkey under both TLS modes.TestMigration3_24_2_OracleTLSOffruns D7 against PostgreSQL.InstanceFormContext.test.tsxcovers D6: the notices on an Oracle data source with TLS mode TLS, none under Disabled or for another engine, and saving stays allowed.
Not in this PR
- The Oracle connection page (
docs/get-started/connect/oracle.mdxin bytebase/bytebase.com) says "Bytebase does not use the TLS settings for Oracle" in its field reference and "Leave the TLS section at Disabled" in the wallet steps. When this ships, describe the TLS section as the way to connect over TCPS with PEM certificates, keep the wallet steps for wallets, and add the new certificate errors to its troubleshooting table. - A wallet as a CA source in the TLS section, so wallet users set TLS mode instead of
SSL=TRUE. - An address that names
PROTOCOL=TCP, in aconnStrExtra Parameter or a listener redirect, still connects over TCP under TLS mode TLS. Bytebase doesn't rewrite descriptors or refuse a redirect. - go-ora's
BuildUrlwrites Extra Parameter keys andSERVERvalues into the URL unescaped, so a key such asS%53Lor aSERVERvalue containing&SSL=FALSEcan add a secondSSL, and the connection may then skip TLS. Only someone who can already turn TLS mode off can write either.