StrokeStroke
Blog

How to connect to Oracle from a Mac

Oracle Database on macOS, from a local container to a remote server, with the one setting that trips everyone up.

broisnees2 min read

Oracle is the database people most often tell me they can't open on a Mac. The client tools assume Windows or Linux, and the error messages assume you already know Oracle. Here is the path that works, start to finish.

1. get a database to talk to

If you already have a server, skip this. For a local one, Oracle Database Free runs in Docker:

docker run -d --name oracle -p 1521:1521 -e ORACLE_PASSWORD=oracle gvenzl/oracle-free:slim

It takes a minute or two the first time. docker logs -f oracle prints DATABASE IS READY TO USE! when it's up. In Stroke, ⌘K → Docker → Oracle Database Free does the same thing and connects when it's ready.

2. install oracle instant client

Stroke talks to Oracle through Oracle's own client library, which Oracle doesn't allow anyone to bundle. Download Instant Client Basic (or Basic Light) for macOS from Oracle's site and unzip it. If the folder lands in your home folder, ~/Downloads or ~/oracle, Stroke finds it by itself. Anywhere else, point the connection's Instant Client folder at it.

3. connect to the right container

This is the part that catches everyone. An Oracle server holds a root container (CDB$ROOT) and one or more pluggable databases. Your tables live in a pluggable database, usually called FREEPDB1, XEPDB1 or ORCLPDB1.

Leave the service name blank and many servers put you in the root, where you see thousands of Oracle's own tables and none of yours. So set:

FieldValue
Hostlocalhost
Port1521
Service nameFREEPDB1
Usersystem, or your app user

Stroke's status bar shows the container you landed in, and warns you if it's the root.

4. pasting a string instead

Every one of these works in the paste box on Stroke's connection screen:

  • oracle://app:secret@localhost:1521/FREEPDB1
  • jdbc:oracle:thin:@//localhost:1521/FREEPDB1
  • an Easy Connect string, localhost:1521/FREEPDB1

When it still won't connect

  • DPI-1047: Instant Client wasn't found. Check the folder.
  • ORA-12514: the listener doesn't know that service name. Check FREEPDB1 against your server.
  • ORA-01017: wrong user or password.

More from the blog