Let’s face it, as cool as our Mac’s are, they’re not cool enough to be top of mind for Oracle. (I think they need another serving of Apple Kool-Aid over there in Redwood Shores…) Anyway, getting things working on Mac OS X isn’t terribly difficult unless you’re still a little wet behind the ears. I’ve been a Mac fan and occasional user for years, but this was my first attempt at configuring it to connect to Oracle. Now that I’ve got it working, I’ll share what I’ve learned and hopefully save a few of you the trouble of stumbling around the interwebs in the dark…

Step 1: Installing Prerequisites

If you’re new to Eclipse, there are three things you’ll need to get started (skip to Step 2 if you already have Eclipse):

  • the latest update of Java for Mac OS X,
  • and an Eclipse distribution.

On Mac OS X, Apple provides the Java JVM through Software Updates. If you haven’t already, go ahead and check for updates to ensure your version of Java is up to date. 

Once that’s done, visit the Eclipse Foundation’s website to download the latest release of Eclipse:

Eclipse Indigo: http://www.eclipse.org/downloads/packages/eclipse-ide-java-developers/indigor

Simply pick the Eclipse distribution to match your architecture and you’re done. Unzip the archive and place the /eclipse folder in a convenient location. I chose to use /Applications/eclipse in my case. That’s it – there’s no real install, per se. 

Step 2: Installing Oracle’s Instant Client & setting environment variables

You’ll need to download two things from Oracle (http://www.oracle.com/technetwork/topics/intel-macsoft-096467.html):

  • Instant Client Package - Basic
  • Instant Client Package - SQL*Plus

CAUTION: If you’re running Lion (Mac OS X 10.7), as of this writing, the 64-bit Instant Client is currently incompatible. No worries – you can download the 32-bit Instant Client and use that just fine. For those of you with a 64-bit Eclipse distribution, this means if you configure tnsnames.ora and try to use the “Oracle Client Connection” (with your 32-bit Instant Client), you’ll get architecture mismatch errors… just use the “Direct TCP/IP Connection” type and you’ll be fine. 

Once those are downloaded, unzip them both into the same directory. (You can use separate directories if you want, just be sure to update the directory locations in the following steps.) Next, move the directory to /Library/Oracle/instantclient_10_2 (note: /Oracle does not exist by default in Mac OS X, so you’ll need to create it).
Now create a /network/admin folder inside there. This is where we’ll place the tnsnames.ora file (which we have to create). Open your favorite text editor (mine’s
TextWrangler) and create your tnsnames.ora file using this structure. Be sure to replace hostname and SID with the appropriate data for your Oracle instance.
  ORCL =
    (ADDRESS = (PROTOCOL = TCP)(HOST = hostname)(PORT = 1521))

CAUTION: If you’re using TextEdit, stop. TextEdit likes to default to RTF formatting which will wreak havoc with Oracle’s OCI. Save yourself the headache of troubleshooting connection problems and avoid using RTF format…

Next, you should set the privileges to root:wheel 755. This is where we get to start having fun by using Terminal!! Open a new Terminal window and enter the following commands. (Sudo will prompt you for your password – you'll need administrator privs for this step.)

Sudo chgrp –R wheel /Library/Oracle
Chmod –R 755 /Library/Oracle

The chgrp –R command sets the group ownership to wheel for the folder and it’s contents. The chmod command modifies the file access permissions for the folder and it’s contents as well. We’re setting the privs to read-write-execute for owner, read-execute for group, and read-execute for everyone else (-rwxr-xr-x).

With that complete, let’s set our environment variables to make sure Eclipse knows where we hid our instant client. There are several which need to be created or altered:


For the first one, I’ve found that the easiest way to set it is by using ~/.MacOSX/environment.plist (another file not present in a default OS X installation). Plists are different from the text files Mac OS X often uses. You can create these with Xcode if you have it installed, but RCEnvironment is an awesome little freeware utility that lets you easily manage environment variables from the System Preferences panel. (And this has to be one area where Windows is better than Mac… setting PATH in Windows is cake.) You can download it free from here: http://www.rubicode.com/Software/RCEnvironment. If you choose to use RCEnvironment, it creates ~/.MacOSX/environment.plist for you automatically. All you need to do is add the ORACLE_HOME variable and click save

Now we move back to TextWrangler for the rest of our environment variables. Open ~/.bash_profile and place the text below inside. If it’s not there, just start with a blank text file and save it to that location. (And, if you didn’t already know, the ~ character tells Mac OS X to look inside of your user folder…)

export TNS_ADMIN
export PATH

To avoid a reboot at this point, you can source the file so the shell can pick up the variables. I’d still recommend a reboot here though… a few of these vars need it.

$ . ~/.bash_profile

You can execute echo $TNS_ADMIN (or any other variable) to test that everything’s working.


Step 3: FINALLY! We get to install Toad Extension for Eclipse!

(Tired of reading? Watch a video: http://toadextensions.com/entry.jspa?externalID=3921&categoryID=396)

To install the Toad plugin for Eclipse, simply Drag this image   onto your Eclipse toolbar and you should see this after a moment:

(Alternately, visit the Eclipse Marketplace and grab the update URL from here: http://marketplace.eclipse.org/content/toad-extension-eclipse)

By default, you’ll be able to install the Oracle and PostgreSQL providers. Just uncheck PostgreSQL is you don’t have a use for it. After clicking through a few screens you’ll be asked to restart Eclipse – go ahead and do that.

Once Eclipse has restarted, open the Toad Extension perspective by navigating to Window > Open Perspective > Other > Toad Extension. Then, open the Eclipse preferences window and navigate to Toad Extension > Database Specific Settings > Oracle and enter the path to your JDBC driver (/Library/Oracle/instantclient_10_2/ojdbc14.jar for us). Aaaaand restart Eclipse once more.

And finally, we get to create our first Oracle connection. My machine is running Lion, so as I explained above, I need to connect using the “Direct TCP/IC Connection” method. To do this we can click on the connection icon and choose “Oracle Platform.”

This will present you with the connection properties screen where you can enter your login details as well as server/instance information.

If the architecture of your instant client and Eclipse matches (yep, see above), you can use the “Oracle Client Connection” method instead of TCP/IP. If you haven’t rebooted your machine yet, you probably won’t see tnsnames.ora in the “Oracle Client Connection” until you do.

Assuming you didn’t hit any snags along the way, you should now be able to nerd it up with Oracle and Toad on your Mac! Enjoy!! 

Credit for help along the way (as I stumbled around the interwebs in the dark…) goes to @cjtravis and @MattH.

-- Daniel