// free tool

Oracle connection string builder

Build an Oracle Easy Connect string, TNS connect descriptor, JDBC thin URL or ODP.NET string from one form, or paste one to see the host, port and service name and catch the SID-versus-service-name mix-up. It all runs in your browser: nothing you type is sent anywhere.

Open this connection in SQLly

Opens SQLly's connection editor filled in.

Private by design. The builder and decoder are plain JavaScript running in this tab. The page sends no request with what you type, stores nothing (not even in your browser), and keeps working offline once loaded. The Open in SQLly link goes from your browser straight to the app on your computer.

Oracle connection string formats

Oracle clients name a database three ways: Easy Connect (host:1521/service_name), a full connect descriptor ((DESCRIPTION=(ADDRESS=...)(CONNECT_DATA=(SERVICE_NAME=...)))), or a TNS alias looked up in tnsnames.ora. JDBC thin, ODP.NET, python-oracledb and node-oracledb all accept the first two.

The classic mistake is mixing up a SID and a service name. Pluggable databases and cloud databases are reached by service name; Easy Connect cannot express a SID at all, and the legacy JDBC form host:port:SID fails with ORA-12505 when you give it a service name.

Easy Connect SQL*Plus, SQLcl, python-oracledb, node-oracledb, ODP.NET

db.example.com:1521/FREEPDB1

Easy Connect over TLS Easy Connect Plus

tcps://db.example.com:2484/FREEPDB1

Connect descriptor tnsnames.ora, every Oracle client

(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=db.example.com)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=FREEPDB1)))

JDBC thin Oracle JDBC (ojdbc)

jdbc:oracle:thin:@//db.example.com:1521/FREEPDB1

ADO.NET (ODP.NET) Oracle.ManagedDataAccess

User Id=app_user;Password=your_password;Data Source=db.example.com:1521/FREEPDB1;

SQLAlchemy URL python-oracledb

oracle+oracledb://app_user:[email protected]:1521/?service_name=FREEPDB1

Placeholders such as your_password are just that: build your own string with the form above. More about connecting SQLly to Oracle: SQLly for Oracle.

Easy Connect (Plus) syntax

[[protocol:]//]host[,host2][:port][/service_name][:server_type][/instance_name][?parameter=value&...]. The protocol is tcp (default) or tcps; the port defaults to 1521 for both. SIDs cannot be used in Easy Connect.

KeywordSynonymsDefaultWhat it does
protocol - tcp tcps:// uses TLS. TLS listeners commonly use 2484, Oracle's registered port, but you must write it.
port - 1521 Listener port.
service_name - - Database service, e.g. a PDB name such as FREEPDB1 or ORCLPDB1.
server_type - - dedicated, shared or pooled.
connect_timeout - none Seconds to establish the connection.
transport_connect_timeout - - Seconds for the TCP connection itself.
retry_count / retry_delay - - / 0 Connection retries and the delay between them.
ssl_server_dn_match - ON (19.2+ clients) Check the server certificate's DN against the host.
wallet_location - - Directory with the wallet for TCPS.

ODP.NET connection string attributes

ADO.NET style. Data Source takes an Easy Connect string, a TNS alias or a full descriptor.

KeywordSynonymsDefaultWhat it does
User Id - - Database user.
Password - - Password; quote it with double quotes if it contains special characters.
Data Source - - Easy Connect, alias, or descriptor.
DBA Privilege - - SYSDBA, SYSOPER, SYSASM, SYSBACKUP, SYSDG, SYSKM, SYSRAC.
Connection Timeout - 15 Seconds to wait for a pooled connection.
Pooling - true Connection pooling.
Max Pool Size - 100 Largest pool.
Min Pool Size - 1 Smallest pool.
Incr Pool Size - 5 Connections added when the pool grows.
Statement Cache Size - 0 Statements cached per connection.
Validate Connection - false Check a pooled connection before handing it out.
Connection Lifetime - 0 Seconds a pooled connection may live.

Oracle JDBC thin URL forms

Pass the user and password as connection properties rather than embedding them.

KeywordSynonymsDefaultWhat it does
jdbc:oracle:thin:@//host:port/service - - Service name (Easy Connect).
jdbc:oracle:thin:@tcps://host:port/service - - TLS; add ?wallet_location=/path for a wallet.
jdbc:oracle:thin:@(DESCRIPTION=...) - - Full connect descriptor.
jdbc:oracle:thin:@alias?TNS_ADMIN=/path - - TNS alias from tnsnames.ora in that directory (or the oracle.net.tns_admin property).
jdbc:oracle:thin:@host:port:SID - - Legacy SID form; prefer a service name.

Common Oracle connection errors

ORA-12154: TNS:could not resolve the connect identifier specified

Why: The client treated the string as a TNS alias and could not find it: no tnsnames.ora, TNS_ADMIN pointing elsewhere, or a typo in the alias or Easy Connect string.

Fix: Use Easy Connect (host:1521/service) or a full descriptor to skip tnsnames.ora, or set TNS_ADMIN to the directory that holds the file.

ORA-12514: TNS:listener does not currently know of service requested in connect descriptor

Why: The listener is reachable but no database has registered that service name with it: a wrong or misspelled service, a SID given as a service name, or the database is not open.

Fix: Run lsnrctl services (or ask the DBA) for the registered services and use one of those names.

ORA-12505: TNS:listener does not currently know of SID given in connect descriptor

Why: The string connects by SID (host:port:SID or (SID=...)) and the value is not a SID the listener knows, often because it is really a service name.

Fix: Switch to the service-name form: //host:port/service_name.

ORA-12541: TNS:no listener

Why: Nothing is listening at that host and port: the listener is down, the port is wrong, or a firewall blocks it.

Fix: Check lsnrctl status on the server, the port (1521 by default) and the firewall.

ORA-01017: invalid username/password; logon denied

Why: Wrong user name or password. Passwords are case-sensitive, and a password with special characters may need double quotes in SQL*Plus.

Fix: Check the credentials; quote the password in SQL*Plus as user/"p@ss"@host/service.

ORA-28000: the account is locked

Why: Too many failed logins or a DBA locked the account.

Fix: A DBA runs ALTER USER app_user ACCOUNT UNLOCK;.

Oracle connection string FAQ

What is an Oracle Easy Connect string?

A compact connect identifier, host[:port]/service_name, that needs no tnsnames.ora entry. Easy Connect Plus (19c and later) adds tcps://, several hosts and ?parameter=value options such as connect_timeout.

What is the difference between a SID and a service name?

A SID names one database instance; a service name is what clients ask the listener for, and one database (or pluggable database) can offer several. Modern and cloud databases are reached by service name. Easy Connect only takes service names.

What is Oracle's default port?

1521 for the listener. TLS (TCPS) uses the same default unless you configure another port; many sites use 2484, the port registered for Oracle over TLS.

How do I connect with python-oracledb without installing Oracle Client?

python-oracledb runs in Thin mode by default and needs no Oracle Client libraries: oracledb.connect(user=..., password=..., dsn="host:1521/service").

Can SQLly open an Oracle connection from a connection string?

SQLly connects to Oracle, but its paste-a-connection-string reader does not take Oracle strings yet, so the Open in SQLly button is off for Oracle. Enter the host, port and service name in SQLly's connection editor instead.

// skip the strings entirely

Connect once. Then just write SQL.

SQLly is a native SQL workbench for macOS, Windows and Linux. Paste a connection string into its connection editor, keep passwords in your system keychain, and get schema-aware IntelliSense on Oracle and more.