Configuring an Oracle Net Client in Oracle AI Database 26ai

Now that the Oracle Net listener on the server is configured to accept connection requests for an instance such as your COIN database, it's time to configure a client PC to actually connect to it. If you're working through this course on just one machine, this lesson is still relevant — you'll have client software installed that can be configured exactly the same way it would be on any other PC on the network. Oracle is flexible about this: client and server software can run on the same machine without any conflict.

To configure a client PC, you add an entry for the database service to a file named tnsnames.ora^[1] that resides on the client PC. This lesson uses Local Naming throughout — the tnsnames.ora-based approach that's been this course's default since Lesson 1. It's worth remembering that Local Naming is one of four naming methods Oracle Net supports, not the only one: Directory Naming (via an LDAP directory), Centralized Configuration Provider (via a cloud config store), and Easy Connect (no file at all) are the other three. Local Naming works well for the small number of clients this course deals with; larger environments sometimes lean on the others specifically to avoid distributing and keeping a tnsnames.ora file in sync across dozens or hundreds of machines.

The file conventionally sits in the network/admin directory underneath the Oracle home, but that's actually the fallback location, not a hardcoded one. Oracle Net looks for tnsnames.ora in this order:

1. The directory named by the TNS_ADMIN environment variable, if it's set.
2. If TNS_ADMIN isn't set, or the file isn't found there: ORACLE_HOME/network/admin on Linux/UNIX, or ORACLE_HOME\network\admin on Windows.

This matters in practice more than it might seem: if you ever edit tnsnames.ora and your changes don't seem to take effect, checking whether TNS_ADMIN is set to point somewhere unexpected is one of the first things worth ruling out — you may be editing a file the client isn't actually reading. On Windows specifically, if TNS_ADMIN isn't set in the process environment, Oracle falls back to scanning the Windows Registry for a TNS_ADMIN value before defaulting to the Oracle home location.

Here's the entry that gets added for the COIN instance:

COIN =
  (DESCRIPTION =
    (ADDRESS_LIST =
      (ADDRESS = (PROTOCOL = TCP)(HOST = 10.11.49.239)(PORT = 1521))
    )
    (CONNECT_DATA =
      (SERVER = DEDICATED)
      (SERVICE_NAME = COIN)
    )
  )

Notice the entry connects using SERVICE_NAME, not a bare SID. That's worth being deliberate about, not just a syntax preference: in Oracle AI Database 26ai, every database is a multitenant container database, and clients connect to a service — typically a specific PDB's service — rather than to a raw instance identifier. SID still exists as a parameter and you'll see it in older material, but Oracle's own current documentation builds essentially every connect-descriptor example around SERVICE_NAME instead, for exactly this reason.

When you connect using Oracle client software, you ask to connect to a service named COIN. Oracle Net takes that service name, reads tnsnames.ora, and finds that the COIN service is reachable at the host with IP address 10.11.49.239, port 1521, using a dedicated server process. That's the entire mechanism — a friendly name in your connect string, resolved through a local file into the actual network address and connection details.

This service name isn't something the client invents on its own — it has to correspond to a service the listener actually knows about. Lesson 5 covered how the database registers COIN's service with the listener dynamically, through the LREG background process; Lesson 6 covered how to bounce the listener when configuration changes need to take effect. Client and server configuration are really two halves of the same picture: the listener has to know a service exists (server side, Lessons 5 and 6), and the client has to know how to ask for it (client side, right here).

You can edit tnsnames.ora by hand, and experienced DBAs often do exactly that. For getting started, though, it's easier to use Oracle's supplied configuration tool: the Oracle Net Configuration Assistant (NETCA).

An older tool called Oracle Net Easy Config handled this job in earlier Oracle releases, but it was deprecated as of Oracle Database 10g and has no place in current material — NETCA has been its replacement for a very long time now. NETCA is a graphical, guided tool for configuring Oracle Net components, offering a considerably friendlier experience than hand-editing configuration files while you're still getting comfortable with the syntax. Run it, and it walks you through adding a new service entry to your tnsnames.ora file — prompting for the service name, host, port, and connection type, then writing the resulting entry (in the same SERVICE_NAME-based form shown above) into the file for you.

A third option worth knowing about, useful once a database already exists locally: the connstr command-line utility displays Oracle connect strings for every network service name available on that installation. You can use the strings it produces directly in a client tool — SQL*Plus, Python, JDBC Thin — or copy them straight into a tnsnames.ora entry for Local Naming, which makes it a handy shortcut when you already have working connection details on one machine and just need to replicate them onto a client.

Three paths exist for managing this file, then, each suited to a different situation:

• Oracle Net Configuration Assistant (NETCA) — guided, GUI-based, the easiest starting point.
• connstr — quick, scriptable, useful for pulling correct connect strings from an existing installation rather than typing them from scratch.
• Manual configuration — directly editing tnsnames.ora. Less convenient at first, but what experienced DBAs do once comfortable with the syntax, since it's faster for small, targeted changes than launching a guided tool.

Once you've added the entry, it's worth confirming it actually works before building anything on top of it — and there are two useful checks from two different directions.

From the client side, tnsping (introduced back in Lesson 1) confirms the listener is reachable using the exact entry you just added:

tnsping COIN

A successful tnsping confirms network reachability and that your tnsnames.ora syntax resolves correctly — but it doesn't guarantee the service itself is registered and ready. For that, check from the server side with the Listener Control commands covered in Lessons 4 through 6:

lsnrctl services

If COIN doesn't appear in the Services Summary there, the problem isn't your client configuration at all — it's that the service hasn't registered with the listener, which points you back to Lesson 5's dynamic registration coverage rather than anything covered in this lesson.

One more option worth knowing for quick, throwaway testing, before you commit to a permanent tnsnames.ora entry: Easy Connect needs no configuration file at all. The syntax is:

CONNECT username/password@host[:port][/service_name]

For the COIN example above, that would look like:

sqlplus username@"10.11.49.239:1521/COIN"

This is genuinely useful for a fast sanity check — confirming a service is reachable at all — before you invest in a permanent, named tnsnames.ora entry for it. It's not a replacement for Local Naming in this course, since a memorable service alias like COIN is easier to work with day to day than typing out a host and port every time, but it's worth having in your toolkit for troubleshooting or one-off connections.

Click on the exercise link below to edit your tnsnames.ora file and add an entry for the COIN database.
Configuring Oracle Net Client - Exercise

[1]tnsnames.ora: A configuration file that contains net service names mapped to connect descriptors for the local naming method, or net service names mapped to listener protocol addresses. A net service name is an alias mapped to a database network address contained in a connect descriptor.