How to install Oracle SQL Developer and connect to a database

gs steps Install Oracle SQL Developer in six steps

From a blank machine to a live database connection. Each step below matches the HowTo structured data on this page exactly.

1. Pick your platform and build

   Decide which build you need. The Windows x64 and macOS downloads bundle JDK 17, so they need nothing else installed; the Linux RPM and the Windows no-JRE build need your own JDK 17 or newer. Use the download grid to compare sizes and Java requirements at a glance.

2. Install a JDK if needed

   Only if your build does not bundle Java. The Linux RPM and the Windows no-JRE build need a JDK 17 or newer installed first; the Windows x64 and macOS downloads already include one, so you can skip straight to downloading.

3. Download from Oracle

   Click through to Oracle’s official download page and choose the file for your platform. No Oracle account or sign-in is needed — the link serves the file directly. Confirm the address bar shows oracle.com before downloading.

4. Unzip to a folder

   Extract the downloaded zip to a permanent folder such as C:\sqldeveloper on Windows or your Applications folder on macOS. There is no installer — the unzipped folder is the whole program.

5. Launch SQL Developer

   Run sqldeveloper.exe on Windows, the SQLDeveloper app on macOS, or sqldeveloper.sh on Linux. On first launch it asks for the path to your JDK if one was not bundled — point it at your JDK 17+ install.

6. Create a database connection

   In the Connections panel, click the green plus, then enter a name, your username and password, and the host, port (1521 by default) and service name of your Oracle Database. Click Test to check it, then Connect.

gs connection Your first database connection

A connection needs five things: a name you choose, your database username and password, and the host, port and service name of the Oracle Database. For a local Oracle XE install the host is localhost, the port is 1521, and the service name is often XEPDB1.

gs sid service Service name or SID: which one do you need?

The Oracle SQL Developer connection dialog offers both, and choosing the wrong one fails even when every other detail is correct — the host and port connect, then the database rejects the identifier. They identify the database in two different ways, and which applies depends on how the database was set up rather than on anything you can choose.

• Service name — how modern Oracle databases identify themselves, and the right choice almost every time. On Oracle XE the pluggable database is usually XEPDB1.
• SID — the older instance-level identifier, still used by legacy setups and some training environments. On XE, the SID of the container database is XE.

If you are handed connection details by a DBA, use exactly the field they specify. If you are connecting to your own XE install and XEPDB1 as a service name is refused, try XE as a SID before assuming anything else is broken.

gs test connection Testing the connection before you save it

The dialog has a Test button that tries the connection without saving it. Use it every time — the status message underneath tells you precisely which part is wrong, which is far faster than guessing. These are the errors worth recognising on sight — each code is documented in full in Oracle’s Error Help portal:

• ORA-12541: TNS no listener — nothing is accepting connections on that host and port. The database is not running, or the port is wrong.
• ORA-12514: listener does not currently know of service — host and port are right, so you reached the database, but the service name is wrong. See the section above.
• ORA-01017: invalid username/password — you reached the database and it rejected your credentials. Oracle passwords are case-sensitive.
• ORA-28000: the account is locked — the user exists but is locked; a DBA has to unlock it, or use a different account.
• IO Error / connection timed out — usually a firewall, a VPN that is not connected, or a hostname that does not resolve.

gs first query Running your first query

Once a connection is saved, expand it in the Connections panel on the left and open a worksheet — the tab where you type SQL. Everything you do in Oracle SQL Developer happens either in that worksheet or in the object browser beside it.

1. Select the connection, then press Alt and F10, or use Tools → SQL Worksheet, to open a worksheet against it.
2. Type a statement, for example SELECT sysdate FROM dual;.
3. Press Ctrl and Enter to run the single statement your cursor sits in, and read the result in the grid below.
4. Press F5 instead to run the whole worksheet as a script, with output shown as text rather than a grid.

The difference between Ctrl+Enter and F5 is easy to miss, because both appear to “run” the worksheet. Ctrl+Enter runs one statement and gives you a browsable result grid; F5 runs everything in the worksheet in order and prints plain script output. Reach for F5 when you are running a file of DDL, and Ctrl+Enter when you are exploring data.

gs next Where to go next

• Nothing installed yet? Start with the build for your platform — the Windows, macOS and Linux guides each cover the JDK question and the platform-specific traps.
• Connection refused and you are stuck? Re-read the error in the Test dialog against the list above; the ORA number identifies the failure precisely.
• Working over SSH with no desktop? Oracle SQL Developer needs a display. Use SQLcl, Oracle’s command-line client, which is a much smaller download.