The TNSNAMES.

ORA file

Networking Tips

The TNSNAMES.ORA file

What is it?
When clients want to connect to an Instance, they need to know where the connection request should be made, and how it should be made. The TNSNAMES.ORA file is a text file, located on each client machine, which gives the client these two crucial pieces of information. Strictly speaking, clients dont connect directly to an Instance at all. Instead, they connect to a Listener process, which knows where to establish the connection to the Instance on the clients behalf. Therefore, a large part of the where information in TNSNAMES.ORA is related to identifying the machine on which the Listener is running, and the port it is listening on. There is also an element which specifies which particular Instance the client wishes to connect to, since a single Listener process can be listening on behalf of many Instances. The how information in the TNSNAMES.ORA file relates mainly to the networking protocol by which the client wishes to connect to the Instance (should it be TCP/IP, SPX/IPX and so on). There is also a part which informs the Listener whether the client is seeking a dedicated or shared server connection.

Basic Configuration
We can see most of these elements coming together in the following simple example: DB9 = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = mozart)(PORT = 1521)) ) (CONNECT_DATA = (SERVICE_NAME = db9.aldeburgh.local) ) ) Whilst the layout is a bit convoluted (it doesnt strictly need all those indents!), the basic information is straightforward enough. The Listener we are hoping to use to establish our connection is to be contacted using the TCP/IP protocol. Its running on a machine called MOZART, and its listening on port number 1521 (which happens to be the default port number). That gives us nearly everything we need to get in touch with the Listener itself.
Copyright Howard Rogers 2002 3/4/2002 Page 1 of 6

The TNSNAMES.ORA file

Networking Tips

I say nearly everything, because the use of the machine name MOZART is a bit of a problem: that actually needs to be turned into an IP address somehow. Oracle has no mechanism for resolving server names into IP addresses of its own, but instead relies on standard, external network resolution methods. For example, if youre using Windows 2000, you may well have Active Directory installed in which case, it is up to Microsofts networking software to convert MOZART into the IP address 192.168.0.1. If youre not using Active Directory, you might have configured a local lmhosts file to resolve the name, or be using DNS. In the absence of any such external naming resolution mechanism, its legitimate to include the hard-coded IP address itself within the TNSNAMES.ORA file. Some would argue, indeed, that this is preferable because then theres no need to perform name resolution, and that should mean that User connections can be made faster than they otherwise would be. Thats a fair point but it also means that if your Server changes IP address one day (DHCP, anyone??!), none of your Users will be able to connect at all until theyve manually altered the TNSNAMES file which is not a very desirable outcome. Nevertheless, assuming we can work out a physical IP address from the name MOZART, we can connect to the Listener. Our sample TNSNAMES.ORA then tells us that once were talking to the Listener, we should request a connection to the db9.aldeburgh.local service. Its up to the Listener to work out what this actually means in practice and it will use the configuration information in its LISTENER.ORA file to do so. In this particular case, the LISTENER.ORA contains these lines: SID_LIST_LISTENER = (SID_LIST = (SID_DESC = (GLOBAL_DBNAME = db9.aldeburgh.local) (ORACLE_HOME = d:\oracle\ora91) (SID_NAME = DB9) ) ) which means that a request to connect to db9.aldeburgh.local actually is interpreted to mean connect me to the Instance called DB9. This example TNSNAMES.ORA doesnt explicitly say whether the connection to DB9 should use dedicated or shared server connections, which means well use a dedicated server connection, because thats the default. If our database was configured to run in shared server mode, then we could have requested a dedicated connection, like this: DB9 = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = mozart)(PORT = 1521))
Copyright Howard Rogers 2002 3/4/2002 Page 2 of 6

The TNSNAMES.ORA file

Networking Tips

) (CONNECT_DATA = (SERVICE_NAME = db9.aldeburgh.local) (SERVER=DEDICATED) ) ) Notice the new parameter SERVER=, which goes under the connect_data bit of the file. We could also have explicitly set SERVER=SHARED, to force shared server connections (but remember: this only works when youve already configured the entire database to run in shared server mode). This brings us to an interesting feature of the TNSNAMES.ORA file: its perfectly legitimate to have the one file reference the same Instance multiple times. Youd do that to give yourself a choice of how to connect to it. For example, we might have this sort of arrangement: USR = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = mozart)(PORT = 1521)) ) (CONNECT_DATA = (SERVICE_NAME = db9.aldeburgh.local) (SERVER=SHARED) ) ) DBA = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = mozart)(PORT = 1521)) ) (CONNECT_DATA = (SERVICE_NAME = db9.aldeburgh.local) (SERVER=DEDICATED) ) ) Again, this example only makes sense if we assume that the DB9 database has already been configured to run in shared server mode. What were doing here is referencing the same Instance twice (db9.aldeburgh.local), once forcing shared server connections, and once forcing dedicated server connections. Why would you want to do this? The clue is in the names Ive given to each of the connections: ordinary users might be expected to share server processes. But when I connect as a DBA to perform maintenance tasks, I really want my own dedicated set of database resources.
Copyright Howard Rogers 2002 3/4/2002 Page 3 of 6

The TNSNAMES.ORA file

Networking Tips

The USR and DBA names Ive used in this example are therefore known as aliases (more fully, tnsnames aliases), because they are just hooks by which we indicate which of the connections available in the TNSNAMES.ORA file we actually want to use at any given time. You choose which alias to use when you actually request the connection. In SQL*Plus, for example, an ordinary user would type connect fred/bloggs@USR, whereas when I, the DBA, which to connect to do some heavy-duty maintenance, Id type connect sys/oracle@DBA. In both cases, we end up connected to the DB9 Instance, because both aliases point to the same Instance in the TNSNAMES.ORA. But I get a dedicated server process, the humble user gets a shared one. In a similar sort of way, its perfectly legitimate for a TNSNAMES.ORA file to contain connection information for many completely different Instances. Your Users might need to connect to a SALES database sometimes, and then to a PURCHASES database at others. The TNSNAMES.ORA that would allow them to do this might look like this: SALES = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = mozart)(PORT = 1521)) ) (CONNECT_DATA = (SERVICE_NAME = db9.aldeburgh.local) ) ) PURCH = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = monteverdi)(PORT = 1521)) ) (CONNECT_DATA = (SERVICE_NAME = db8.aldeburgh.local) ) ) The Users would then either type connect fred/bloggs@SALES or connect fred/bloggs@PURCH to switch between either database. Notice in this example, too, that its also permissible to have one TNSNAMES.ORA referencing databases which happen to be housed on entirely different servers SALES is running on MOZART, PURCH on MONTEVERDI.

Copyright Howard Rogers 2002

3/4/2002

Page 4 of 6

The TNSNAMES.ORA file

Networking Tips

Advanced Configurations
In more advanced configurations, you can also arrange the TNSNAMES.ORA to allow for whats called connect time failover, meaning that if the Users attempt to communicate with the first Listener fails (perhaps because that Listener is, for some reason, not running), the connection request will automatically be directed to a second (and third, fourth and so on) Listener on a different machine. Such a TNSNAMES.ORA file might look like this: SALES = (DESCRIPTION = (FAILOVER = ON) (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = mozart)(PORT = 1521)) (ADDRESS = (PROTOCOL = TCP)(HOST = monteverdi)(PORT = 1521)) ) (CONNECT_DATA = (SERVICE_NAME = db9.aldeburgh.local) ) ) The key parameter here is failover=on, which resides in the description part of the file, rather than the connect data bit. Its actually on by default if you include the address_list parameter though my earlier examples have already shown you that you can use the address_list parameter, and then only include one actual address in which case, theres nothing to failover to, and therefore, failover is effectively non-functioning. There are two caveats to mention about this sort of failover. Its not the same thing as a User losing a connection to one Instance, and being able to continue without interruption on another. Thats called transparent application failover, and is configured completely differently. The second thing to mention is that connect time failover only works when youre using the automatic instance registration feature that was introduced in 8i. Thats because the Listener on the MONTEVERDI server can only know about the DB9 Instance running on MOZART if the Instance itself has told MONTEVERDIs Listener that it is available. See my paper What is 'automatic instance registration', and is it useful? for full details on this feature. There are other advanced things you can configure in the TNSNAMES.ORA, such as connection load balancing but again, Ill leave the details to another paper, How do I configure failover and load balancing options?

Copyright Howard Rogers 2002

3/4/2002

Page 5 of 6

The TNSNAMES.ORA file

Networking Tips

Location
The TNSNAMES.ORA file is therefore a key component of what is generically called local naming meaning that each client does its own working out where to direct connection requests. That means the TNSNAMES.ORA file must reside on each Users machine. Specifically, it has to reside in the ORACLE_HOME\network\admin directory, unless you set an operating system environment variable (called TNS_ADMIN) to point to some other directory. In other words, if I do this: C:\> set TNS_ADMIN=D:\ANYWHERE\WEIRD then I can house my TNSNAMES.ORA in the d:\anywhere\weird directory (the equivalent command on Unix is, of course, export TNS_ADMIN). Dont run away with the idea that TNSNAMES.ORA is only for client PCs, though. When you want databases to talk to other databases (using database links, for example), a Server itself needs to know how to connect to another Server. Similarly, when an Instance on MONTEVERDI needs to automatically register with a Listener on MOZART, it needs to know how to connect to the Listener on MOZART. In such cases, a copy of TNSNAMES.ORA also needs to reside on the Server and again, it will reside in ORACLE_HOME\network\admin, or wherever the TNS_ADMIN environment variable is set to.

Alternatives
Having one copy of the TNSNAMES.ORA on every single Users PC is OK when youve only got 10 Users. But when youve got 50 or 100 (or more, of course), maintaining that many copies of the file becomes a right royal pain. At which point, you probably drop any idea of using local naming and instead start to think of configuring a central naming method, which is what the Oracle Names Server does for you. Again, I discuss Names Server in detail in another paper. The point Id make here is that if you ever do decide to configure a Names Server, the principles on which it works are practically identical to the ones Ive discussed here: it might be a different method of telling us what to connect to, and how to do it, but the core information it uses is just the same as what TNSNAMES.ORA provides so understanding how the TNSNAMES.ORA does its stuff is still extremely useful.

Copyright Howard Rogers 2002

3/4/2002

Page 6 of 6