Oracle Database

Connection settings, SSL modes, auth compatibility, and column type support for Oracle

The driver speaks TNS in pure Swift, so Instant Client and the rest of Oracle’s stack stay off your Mac. Logins work against Oracle Database 11.1 and later, on-premises, in Docker, or in Oracle Cloud.

Oracle 10g and earlier cannot connect. Their O3LOGON handshake is not implemented, and there is no setting that works around it.

A RAC SCAN listener, a shared server, or a load balancer in front of the database needs no configuration. Neither does a server that requires Native Network Encryption: AES with a SHA-2 checksum is offered on every connect, and the server turns it on when it wants it.

The driver is not in the app. Picking in the Choose a Database sheet offers the download before the form opens, and opening a saved connection installs it without asking. Settings > Plugins > Browse > installs it up front. See Plugins.

Connection settings

Field	Default	Notes
Host	localhost
Port	1521	Listener port
Connection Type	Service Name	Switch to SID for an instance that has no service
Service Name	-	Required. lsnrctl services on the server lists what the listener answers for
Username	-	Username and password only. There is no OS auth
Role	Normal	SYSDBA or SYSOPER for an administrative logon. The account needs the matching privilege, and the session runs as SYS rather than as the user you signed in with

There is no Database field. Each user is a schema, the sidebar lists them all, and Cmd+K or the Schema toolbar button switches the active one. A tab binds to a schema rather than a database, so nothing reconnects when you switch.

Oracle connection form

Connection URL

oracle://user:password@host:1521/service_name

See Connection URL Reference for all parameters.

Authentication

Username and password are the only credentials. Every verifier in dba_users.password_versions works, 10G included; external, Kerberos, and LDAP-managed accounts do not connect at all. A 10G-only account still connects, on DES-based hashing Oracle has deprecated; rotate it with ALTER USER … IDENTIFIED BY and check that password_versions then holds 11G or 12C.

CREATE USER app_user IDENTIFIED BY "Password1!";
GRANT CREATE SESSION, SELECT ANY TABLE TO app_user;
SELECT username, password_versions FROM dba_users WHERE username = 'APP_USER';

Common setups

Where	Settings
Oracle XE, local	localhost:1521, user system, service XEPDB1
Docker	gvenzl/oracle-xe:21-slim, same as local
Remote	Host, port, and credentials as usual; service name from the DBA
Oracle Cloud ADB	One-way TLS, no wallet. See Oracle Cloud (ADB)

A pluggable database has its own service name, and it is not the container’s: XEPDB1 is a PDB inside XE, and connecting to the container name gets you the CDB with none of the application schemas. lsnrctl services lists both.

Oracle Cloud (ADB)

Copy host, port, and service name (of the form mydb_tp) from the TLS connection string in the Oracle Cloud Console, not the mTLS one, then set SSL mode to Required, or Verify CA with the CA certificate. Wallet files are never read, which also makes this the way out of a wallet that has stopped working.

The database has to accept TLS without mutual TLS: set Mutual TLS (mTLS) authentication to Not Required and give the database an access control list or a private endpoint. Oracle rejects the connection otherwise.

Editing and queries

Table info carries columns, types, nullability, primary keys, indexes, foreign keys, and CREATE TABLE DDL. The structure editor writes ALTER TABLE with double-quoted identifiers for case-sensitive names: ADD, RENAME COLUMN, MODIFY, DROP, and CREATE INDEX.

The editor runs SQL and anonymous PL/SQL blocks, and grid paging is written as OFFSET … ROWS FETCH NEXT … ROWS ONLY. Import and export work as they do elsewhere, and a remote server reaches through an SSH tunnel.

Column type support

Oracle type	Display
VARCHAR2, NVARCHAR2, CHAR, NCHAR, LONG, CLOB, NCLOB, JSON	Text as stored
NUMBER	Exact integer up to Int64 range; decimals up to 17 digits of precision
BINARY_FLOAT, BINARY_DOUBLE	Native Swift Float/Double
DATE	yyyy-MM-dd
TIMESTAMP	ISO-8601 in UTC with fractional seconds
TIMESTAMP WITH TIME ZONE	ISO-8601 in the host’s local time zone with explicit offset
TIMESTAMP WITH LOCAL TIME ZONE	ISO-8601 in the host’s local time zone with explicit offset
INTERVAL DAY TO SECOND	D HH:MM:SS plus fractional seconds when non-zero (up to 9 digits, trailing zeros trimmed)
INTERVAL YEAR TO MONTH	Y-MM
RAW, LONG RAW, BLOB	Lowercase hex, truncated to 4 KB
ROWID	As stored
BOOLEAN	true / false
BFILE	<bfile> placeholder (locator only)

Anything else renders as <unsupported: type>. Report those through GitHub Issues.

SSL/TLS

New connections default to Disabled, and there is no opportunistic upgrade: Preferred connects in plain TCP, which is why the SSL pane flags it in red. Required is TCPS; Verify CA adds a CA certificate path for strict validation. See SSL/TLS.

On iPhone and iPad

The Oracle driver is compiled into TablePro Mobile, with no plugin to install. Browsing, queries, and row editing work; creating or altering tables and triggers stays on the Mac. See iPhone and iPad.

Limitations

• No OS auth, wallets, Kerberos, or LDAP. Create a database user with a password and connect as that.
• BFILE columns show the locator, never the file. There is no path to the contents from the app.
• PL/SQL runs as anonymous blocks. Create a procedure or package with a CREATE OR REPLACE statement in the editor.
• No Users & Roles pane. Manage accounts with CREATE USER and GRANT in the editor.

Troubleshooting

Connection refused: check the listener is up with lsnrctl status, that port 1521 is open, and, on Docker, that the container is running (docker start oracle-xe).

Invalid service name: the listener does not answer for that name. List what it does answer for with lsnrctl services.

Unsupported Password Verifier: the account’s verifier is one the driver cannot use, usually a new one such as 23ai. Read password_versions for that user and file an issue with the verifier flag the dialog shows.

Server Version Not Supported: the server is 10g or earlier. Nothing on this side helps; the database has to be 11.1 or later.

Login Handshake Timed Out: TCP connected but the login never finished, so the attempt stops after 30 seconds. Look for a firewall, VPN, or proxy that stalls traffic once the TCP handshake is done.

Connection Dropped During Handshake: the server closed the connection mid-login, and the dialog names the phase it stopped at (advancedNegotiation, dataTypeNegotiation, authentication). Look for a firewall, VPN, or proxy that resets traffic, and confirm the host and port reach the listener itself.

Native Network Encryption Not Completed: the server requires an encryption or checksum algorithm the driver does not offer. Ask the DBA which ones are set and file an issue with the reason the dialog shows. TLS is the alternative: set an SSL mode instead.