【Oracle】ORA-12154 完全ガイド｜TNS: could not resolve the connect identifier specified の原因と解決方法

# 基本的な書き方
ORCL =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCP)(HOST = db-server.example.com)(PORT = 1521))
    (CONNECT_DATA =
      (SERVER = DEDICATED)
      (SERVICE_NAME = orcl.example.com)
    )
  )

# 複数の接続先を定義する例
PROD_DB =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCP)(HOST = 192.168.1.100)(PORT = 1521))
    (CONNECT_DATA =
      (SERVICE_NAME = proddb)
    )
  )

DEV_DB =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCP)(HOST = 192.168.1.200)(PORT = 1521))
    (CONNECT_DATA =
      (SERVICE_NAME = devdb)
    )
  )

# よくある間違い①: 括弧の不一致（閉じ括弧が足りない）
# NG:
# ORCL =
#   (DESCRIPTION =
#     (ADDRESS = (PROTOCOL = TCP)(HOST = server1)(PORT = 1521))
#     (CONNECT_DATA =
#       (SERVICE_NAME = orcl)  ← ここで閉じ括弧が1つ足りない

# よくある間違い②: SID と SERVICE_NAME の取り違え
# SID は古い形式（Oracle 8i 以前）:
#   (CONNECT_DATA = (SID = orcl))
# SERVICE_NAME は新しい形式（推奨）:
#   (CONNECT_DATA = (SERVICE_NAME = orcl))
# ※ RAC 環境では SERVICE_NAME の使用が必須

# よくある間違い③: ネットサービス名の前後に余分なスペース
# NG: " ORCL " = ...   ← 前後のスペースが原因で一致しない場合がある

# TNS_ADMIN の現在値を確認する
echo $TNS_ADMIN
# 空の場合は $ORACLE_HOME/network/admin が使われる

# ORACLE_HOME を確認する
echo $ORACLE_HOME
# 例: /u01/app/oracle/product/19.3.0/dbhome_1

# tnsnames.ora の実際の場所を確認する
ls -la $TNS_ADMIN/tnsnames.ora 2>/dev/null || ls -la $ORACLE_HOME/network/admin/tnsnames.ora

# Oracle Instant Client を使っている場合は TNS_ADMIN を明示的に設定する
export TNS_ADMIN=/opt/oracle/instantclient_19_22/network/admin
# ~/.bashrc や ~/.bash_profile に追記して永続化する
echo 'export TNS_ADMIN=/opt/oracle/instantclient_19_22/network/admin' >> ~/.bashrc

# tnsnames.ora の内容を確認する
cat $TNS_ADMIN/tnsnames.ora

# TNS_ADMIN の現在値を確認する（コマンドプロンプト）
echo %TNS_ADMIN%

# PowerShell で確認する
$env:TNS_ADMIN

# ORACLE_HOME を確認する
echo %ORACLE_HOME%
# 例: C:\app\oracle\product\19.3.0\dbhome_1

# tnsnames.ora の場所
# %TNS_ADMIN%\tnsnames.ora
# または %ORACLE_HOME%\network\admin\tnsnames.ora

# レジストリに設定されている場合もある
# HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\KEY_OraClient19Home1\TNS_ADMIN

# 環境変数を設定する（システムのプロパティ → 環境変数）
# 変数名: TNS_ADMIN
# 変数値: C:\app\oracle\product\19.3.0\dbhome_1\network\admin

# tnsnames.ora で定義したネットサービス名を指定する
tnsping ORCL

# 成功時の出力例:
# TNS Ping Utility for Linux: Version 19.0.0.0.0 - Production
# Used parameter files:
# /u01/app/oracle/product/19.3.0/dbhome_1/network/admin/sqlnet.ora
#
# Used TNSNAMES adapter to resolve the alias
# Attempting to contact (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = db-server)(PORT = 1521))
# (CONNECT_DATA = (SERVICE_NAME = orcl)))
# OK (10 msec)

# 失敗時の出力例（ORA-12154）:
# TNS-03505: Failed to resolve name

# tnsping で確認できるポイント:
# 1. "Used parameter files:" → sqlnet.ora のパス（TNS_ADMIN が正しいか）
# 2. "Used TNSNAMES adapter" → tnsnames.ora を使って解決を試みたか
# 3. "Attempting to contact" → 解決された接続情報（HOST/PORT/SERVICE_NAME）
# 4. "OK (xx msec)" → 名前解決＋リスナーへの疎通が成功

# tnsping は名前解決とリスナー接続を確認する
# DB への認証（ユーザー名/パスワード）は確認しない
# → tnsping が成功しても ORA-01017 が出る場合は認証の問題

# tnsping が失敗する場合のチェックリスト:
# 1. 指定した名前のスペルが tnsnames.ora と一致しているか
# 2. TNS_ADMIN が正しいか（echo $TNS_ADMIN で確認）
# 3. tnsnames.ora の構文にエラーがないか（括弧の対応）
# 4. sqlnet.ora の NAMES.DIRECTORY_PATH に TNSNAMES が含まれているか

# sqlnet.ora の場所: $TNS_ADMIN/sqlnet.ora または $ORACLE_HOME/network/admin/sqlnet.ora

# NAMES.DIRECTORY_PATH: 名前解決の方式と優先順位を設定する
NAMES.DIRECTORY_PATH = (TNSNAMES, LDAP, EZCONNECT)

# TNSNAMES: tnsnames.ora ファイルを使う（最も一般的）
# LDAP: Oracle Internet Directory（OID）を使う
# EZCONNECT: Easy Connect 方式を使う（host:port/service_name）

# ★ ORA-12154 の原因: TNSNAMES が含まれていない場合
# NG（TNSNAMES がないので tnsnames.ora が参照されない）:
# NAMES.DIRECTORY_PATH = (LDAP)

# ★ 修正: TNSNAMES を追加する
# NAMES.DIRECTORY_PATH = (TNSNAMES, LDAP, EZCONNECT)

# sqlnet.ora がない場合はデフォルトで (TNSNAMES, EZCONNECT) が使われる
# → ファイルがない場合に ORA-12154 が出るなら tnsnames.ora 側の問題

# その他の関連設定
SQLNET.AUTHENTICATION_SERVICES = (NTS)   # Windows 認証を使う場合
# SQLNET.AUTHENTICATION_SERVICES = (NONE) # パスワード認証のみ

# Easy Connect の基本構文
# sqlplus ユーザー名/パスワード@ホスト名:ポート/サービス名

# SQL*Plus での接続例
sqlplus hr/password@db-server.example.com:1521/orcl

# IP アドレスで接続する
sqlplus hr/password@192.168.1.100:1521/orcl

# ポート番号を省略する（デフォルト 1521 が使われる）
sqlplus hr/password@db-server.example.com/orcl

# Oracle 19c 以降の Easy Connect Plus（追加オプション）
sqlplus hr/password@"db-server.example.com:1521/orcl?connect_timeout=10&transport_connect_timeout=3"

# Python（python-oracledb / cx_Oracle）での Easy Connect
# import oracledb
# conn = oracledb.connect(
#     user="hr",
#     password="password",
#     dsn="db-server.example.com:1521/orcl"
# )

# tnsping でも Easy Connect を確認できる
tnsping db-server.example.com:1521/orcl

-- JDBC Thin ドライバ（tnsnames.ora 不要）
-- jdbc:oracle:thin:@ホスト名:ポート:SID
-- jdbc:oracle:thin:@ホスト名:ポート/サービス名（推奨）
-- jdbc:oracle:thin:@//ホスト名:ポート/サービス名（URL 形式）

-- 例:
-- String url = "jdbc:oracle:thin:@db-server.example.com:1521/orcl";
-- String url = "jdbc:oracle:thin:@//db-server.example.com:1521/orcl";

-- TNS 名を使う場合（tnsnames.ora が必要）
-- String url = "jdbc:oracle:thin:@ORCL";
-- → TNS_ADMIN が Java プロセスから参照できる必要がある
-- System.setProperty("oracle.net.tns_admin", "/path/to/tns_admin");

-- 接続記述子を直接 JDBC 文字列に埋め込む
-- String url = "jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)"
--     + "(HOST=db-server.example.com)(PORT=1521))"
--     + "(CONNECT_DATA=(SERVICE_NAME=orcl)))";

# python-oracledb（推奨・Oracle 公式）
import oracledb

# Thin モード（Oracle Client 不要・tnsnames.ora 不要）
conn = oracledb.connect(
    user="hr",
    password="password",
    dsn="db-server.example.com:1521/orcl"  # Easy Connect 形式
)

# Thick モード（Oracle Client 必要）
# oracledb.init_oracle_client(lib_dir="/opt/oracle/instantclient_19_22")
# conn = oracledb.connect(user="hr", password="password", dsn="ORCL")

# 接続記述子を直接指定する（tnsnames.ora 不要）
dsn = """(DESCRIPTION=
    (ADDRESS=(PROTOCOL=TCP)(HOST=db-server.example.com)(PORT=1521))
    (CONNECT_DATA=(SERVICE_NAME=orcl)))"""
conn = oracledb.connect(user="hr", password="password", dsn=dsn)

# TNS_ADMIN を明示的に設定する（Thick モード + tnsnames.ora 使用時）
# oracledb.init_oracle_client(
#     lib_dir="/opt/oracle/instantclient_19_22",
#     config_dir="/opt/oracle/instantclient_19_22/network/admin"
# )