Oracle DB Skills를 Codex에 넣고 SQLcl을 통해 HR 스키마의 실행 계획(Execution Plan) 리뷰를 시도해 보았다

Oracle DB Skills는 Oracle Database를 위한 AI 에이전트용 지식 집합 / Skill 집합입니다.

Codex나 Claude Code와 같은 AI 코딩 에이전트에게 "Oracle DB에서는 이렇게 생각하고, 이렇게 쓰고, 이렇게 확인한다"라는 실무 지식을 학습시키기 위한 Markdown 가이드 모음입니다.

리포지토리의 README에서는 SQL/PLSQL, 성능 튜닝 (Performance Tuning), 보안 (Security), 관리 (Management), 모니터링 (Monitoring), 아키텍처 (Architecture), DevOps, 마이그레이션 (Migration), SQLcl, ORDS 등의 영역으로 나뉜 "100개 이상의 실용 가이드"를 제공합니다.

이번에는 일본어로 읽기 쉽게 만들기 위한 목적으로 Oracle Skills의 Oracle Database용 가이드를 기반으로 한 일본어판 리포지토리 engchina/oracle-db-skills-ja를 Mac상의 Codex에 Skill로 도입하여 테스트합니다.

공식 Oracle Skills 리포지토리에서 Oracle Database용 내용은 db/ 도메인으로 제공되고 있습니다.

카테고리	파일 수	경로
데이터베이스 설계 및 모델링	4	skills/design/
...

이 기사에서는 그중에서도 Oracle Database용 내용에 주목하여, 일본어판 리포지토리 oracle-db-skills-ja를 Mac상의 Codex에 Skill로 설치해 보겠습니다.

따라서 이번에는 새로 생성한 Oracle Database의 HR 스키마에 SQLcl로 접속하여, Codex + Oracle DB Skills를 사용하여 스키마 확인부터 실행 계획 (Execution Plan) 리뷰까지 시도해 보겠습니다.

참고로, AWR / ASH / DBA_HIST_*를 사용하는 성능 진단은 수행하지 않으며, HR 사용자로 실행할 수 있는 SELECT와 DBMS_XPLAN.DISPLAY를 중심으로 확인합니다.

MacBook의 Codex에 Oracle DB Skills를 Skill로 설치합니다.

python3 $HOME/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \--repo engchina/oracle-db-skills-ja \--path . \...

shirok@macbook ~ % python3 $HOME/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \--repo engchina/oracle-db-skills-ja \--path . \...

설치 위치는 보통 여기입니다.

SKILL.md나 skills/ 디렉토리가 보이면 OK입니다.

이 리포지토리는 루트 직하에 SKILL.md가 있으므로, --path .를 통해 리포지토리 전체를 하나의 skill로 넣는 형태가 됩니다.

shirok@macbook ~ % ls -l ~/.codex/skills/oracle-db-skills-ja
total 160
-rw-r--r-- 1 shirok staff 4827 May 28 22:14 AGENTS.md
...

완료 후 Codex를 재시작해 주세요. 재시작하면 oracle-db-skills-ja가 skill로 인식됩니다.

이번에는 SQLcl의 저장된 연결 (Saved Connection)을 생성한 후, Codex에서도 동일한 연결 이름을 사용할 수 있는 상태로 만들었습니다. 이후의 확인에서는 SQLcl로 실행한 SQL 결과와 Codex + Oracle DB Skills에 의한 리뷰 결과를 조합하여 확인합니다.

SQLcl MCP Server에서 사용하기 위해, 사전에 SQLcl의 저장된 연결을 생성해 둡니다.

SQLcl 측에 저장된 연결을 만들고, Codex에는 연결 이름만 전달할 수 있습니다.

SQLcl MCP Server는 ~/.dbtools 하위의 SQLcl 연결 스토어에 저장된 연결을 사용하는 구조이며, MCP 클라이언트에서 사용하려면 -savepwd로 비밀번호를 안전하게 저장해야 합니다.

참고:

・ Preparing Your Environment

・ 格納された接続の管理

0) SQLcl 설치

MacBook에 SQLcl을 설치하려면 다음 내용을 참고하세요.

1) sqlcl 실행

shirok@macbook ~ % sql /nolog
SQLcl: Release 25.4 Production on Wed Jun 03 19:00:24 2026
Copyright (c) 1982, 2026, Oracle. All rights reserved.

2) SQLcl 내에서 저장된 연결 (Saved Connection) 생성

여기서 비밀번호 입력을 요구받으면 그 자리에서 직접 입력합니다.

SQL> conn -save hr_local -savepwd HR@my_connection
Password? (**********?) ********************
Name: hr_local
...

3) 저장된 연결 확인

SQL> connmgr list
.
├── cline_mcp
...

4) 다른 터미널에서 접속

새 터미널을 열고, conn -name <저장된_연결_이름>을 통해 비밀번호 없이 접속할 수 있는지 확인합니다.

shirok@macbook ~ % sql /nolog
SQLcl: Release 25.4 Production on Wed Jun 03 19:16:29 2026
Copyright (c) 1982, 2026, Oracle. All rights reserved.
...

Oracle Database에 HR 스키마를 설치하려면 다음 내용을 참고하세요.

1) SQLcl로 접속 가능한지 확인

먼저, SQLcl의 저장된 연결인 hr_local을 사용하여 HR 스키마에 접속할 수 있는지 확인합니다.

Codex에는 비밀번호를 전달하지 않고, 저장된 연결 이름만 전달하는 방식으로 구성했습니다.

shirok@macbook ~ % sql /nolog
SQLcl: Release 25.4 Production on Wed Jun 03 19:16:29 2026
Copyright (c) 1982, 2026, Oracle. All rights reserved.
...

2) Codex에 던진 프롬프트 (Prompt)

oracle-db-skills-ja 를 사용하여, SQLcl을 통해 Oracle Database의 HR 스키마 접속 확인을 해주세요.
전제 조건:
- MacBook에 SQLcl은 설치되어 있습니다
...

3) Codex가 제시한 SQL

-- 1. 접속 사용자, 현재 스키마, DB/PDB/인스턴스
SELECT
SYS_CONTEXT('USERENV', 'SESSION_USER') AS session_user,
...

4) SQLcl에서 실행한 결과

SQL> @hr.sql
SESSION_USER CURRENT_SCHEMA DB_NAME PDB_NAME INSTANCE_NAME
_______________ _________________ ___________ ___________ ________________
...

다음 HR 스키마를 쿼리하는 SQL과 그 실행 계획 (Execution Plan)을 가져와서, 그 결과를 Codex로 분석합니다.

1) 리뷰 대상 SQL

SELECT
e.employee_id,
e.first_name,
...

2) 튜닝 포인트 (Tuning Point)

• UPPER(e.last_name)로 인해, 일반적인 last_name 인덱스가 있어도 사용하기 어려움
• TO_CHAR(e.hire_date, 'YYYY')로 인해, hire_date의 범위 검색을 하기 어려움
• NVL(e.commission_pct, 0)으로 인해, commission_pct 조건의 평가가 불분명함
• 조회 컬럼이 많음
• 여러 개의 JOIN이 있어, Join 순서나 Join 방식의 확인 과제로 적합함
• ORDER BY가 있어, SORT ORDER BY의 유무를 확인할 수 있음

1) DBMS_XPLAN.DISPLAY로 확인

다음 SQL을 HR 스키마에서 실행하여 실행 계획을 가져옵니다.

SQL> EXPLAIN PLAN FOR
SELECT
e.employee_id,
...

1) Codex에 문의하는 프롬프트

1) Codex에 문의하는 프롬프트

oracle-db-skills-ja 의 SQL 튜닝 (SQL Tuning) / 실행 계획 리뷰 (Execution Plan Review) 관점에서,
다음의 HR 스키마용 SQL과 실행 계획을 리뷰해 주세요.
목적:
...```

**1) 개선 후 SQL의 실행 및 실행 계획 취득**

SQL> EXPLAIN PLAN FOR
2 SELECT
3 e.employee_id, e.first_name, e.last_name, e.email, e.phone_number,
...

**3) 개선 전후의 차이**

이번 예시에서는 HR 스키마의 작은 데이터를 사용하고 있기 때문에, 실행 시간 면에서 큰 차이는 나타나지 않습니다.

하지만 실행 계획 (Execution Plan)을 보면 개선 전후의 차이를 확인할 수 있었습니다.

개선 전 SQL에서는 `UPPER(e.last_name)`, `TO_CHAR(e.hire_date, 'YYYY')`, `NVL(e.commission_pct, 0)`와 같이 컬럼 측에 함수를 적용했습니다.

그 때문에 Predicate Information에서는 이러한 조건들이 `filter`로서 평가되었습니다.

반면, 개선 후 SQL에서는 `e.last_name LIKE 'S%'`, `e.hire_date >= DATE '2005-01-01'`와 같이 컬럼 측에 함수를 적용하지 않는 형태로 다시 작성했습니다.

그 결과, `EMP_NAME_IX`에 대한 `INDEX RANGE SCAN`이 사용되었고, `LAST_NAME LIKE 'S%'`가 `access` 조건으로 표시되었습니다.

HR 스키마는 데이터량이 적기 때문에 비용 (Cost) 차이는 작지만, Oracle DB Skills를 사용함으로써 실행 계획의 어느 부분을 보아야 하는지, Predicate Information의 `access` / `filter`를 어떻게 읽어야 하는지, SQL을 어떻게 다시 작성해야 하는지를 확인할 수 있었습니다.

참고로, `UPPER(e.last_name)`를 제거하면 대소문자를 구분하지 않는 검색이 아니게 되므로, 실제 요구사항에 따라 함수 기반 인덱스 (Function-Based Index)나 정렬 순서 (Collation) 설계도 검토가 필요합니다.

**4) Codex로의 문의 프롬프트**

SQL 개선 전후의 분석을 Codex에게 시킵니다.

oracle-db-skills-ja 의 SQL 튜닝 (SQL Tuning) / 실행 계획 리뷰 (Execution Plan Review) 관점에서,
개선 전 SQL의 실행 계획 sql01-Explained.log와
개선 후 SQL의 실행 계획 sql02-Explained.log를 비교해 주세요.
...

**6) Oracle DB Skills의 지적 사항 요약**

Oracle DB Skills의 리뷰에서는 주로 다음과 같은 점들이 지적되었습니다.

- WHERE 절에서 컬럼 측에 함수를 사용하면 일반 인덱스 (Index)를 사용하기 어려워진다
- 날짜 컬럼은 `TO_CHAR`로 문자열화하지 말고, DATE 타입의 범위 조건으로 비교하는 것이 좋다
- `NVL(column, value)`를 조건으로 사용할 경우, 인덱스 활용 및 NULL 처리에 주의가 필요하다
- 실행 계획에서는 Predicate Information의 `access` / `filter`를 확인한다
- HR 스키마는 작기 때문에 실행 시간 차이는 작지만, SQL 리뷰의 관점은 확인할 수 있다

이번 개선 후 SQL에서는 `EMP_NAME_IX`를 사용한 `INDEX RANGE SCAN`으로 변경되었고, `LAST_NAME LIKE 'S%'`가 `access` 조건으로 표시되었습니다.

이로 인해 Oracle DB Skills를 사용함으로써 단순히 SQL을 다시 작성하는 것뿐만 아니라, 실행 계획상 어디에서 차이가 발생했는지까지 확인할 수 있었습니다.

skills/performance/explain-plan.md
skills/performance/index-strategy.md
skills/performance/optimizer-stats.md
...

oracle-db-skills-ja 의 실행 계획 (Execution Plan) / SQL 튜닝 (SQL Tuning) 관점에서,
필요에 따라 AWR 사용 가능 여부도 확인하면서,
다음 SQL과 실행 계획을 리뷰해 주세요.
...

**・실행 계획을 이제부터 취득할 경우의 프롬프트**

oracle-db-skills-ja 를 사용하여, 다음 SQL의 실행 계획 (Execution Plan) 취득 방법을 알려주세요.
가능하다면 DBMS_XPLAN.DISPLAY_CURSOR 를 우선하여, ALLSTATS LAST / IOSTATS / PEEKED_BINDS 를 포함한 취득 SQL을 주세요.
SQL: <여기에 SQL 문>

skills/sqlcl/sqlcl-mcp-server.md

※ 여기서는 별도의 환경이나 별도의 접속으로 SQLcl MCP Server를 사용하는 경우의 범용 프롬프트 예시로 정리하고 있습니다.

이번 HR 스키마 확인에서는 저장된 접속(Saved Connection)인 `hr_local`을 사용하여 접속하고 있습니다.

oracle-db-skills-ja 의 SQLcl MCP Server 절차에 따라,
저장된 접속을 사용한 Oracle DB 접속 확인을 수행해 주세요.
전제 조건:
...

**・ AWR/성능 진단 데모용의 경우**

SQLcl MCP Server를 통해 Oracle에 접속하여, oracle-db-skills-ja 의 AWR 분석 관점에서
경량 성능 확인을 수행해 주세요.
제약 사항:
...

주의:

AWR / ASH / DBA_HIST_* / DBMS_WORKLOAD_REPOSITORY 등을 이용할 경우에는 Oracle Diagnostics Pack의 이용 가능 여부를 사전에 확인하십시오.

검증 환경이라 하더라도, 이용 가능한 라이선스나 `CONTROL_MANAGEMENT_PACK_ACCESS` 설정을 확인한 후 실행하는 것이 안전합니다.

SQLcl MCP Server를 사용하여 실제 DB에 접속할 경우에는, 먼저 검증용 DB, 읽기 전용(read-only) 사용자, 최소 권한으로 시도하는 것을 권장합니다.

운영 DB(Production DB)에 직접 연결하는 것이 아니라, 필요에 따라 정제된(sanitized) 검증 데이터나 읽기 전용 레플리카(read-only replica)를 사용하고, 실행된 SQL을 감사(audit)할 수 있는 상태로 만들어 두십시오.

SQLcl MCP Server는 `-mcp`로 실행했을 경우, 기본적으로 Restrict Level 4가 됩니다.

단, Restrict Level에만 의존하지 말고, DB 측에서도 읽기 전용(read-only)에 준하는 최소 권한 사용자를 사용하는 것이 안전합니다.

skills/migrations/

oracle-db-skills-ja 의 migration-assessment 관점에서,
PostgreSQL에서 Oracle로의 이관 어세스먼트(migration assessment)를 수행해 주세요.
대상:
...

-
**Oracle Skills**

・ Oracle Skills 공식 리포지토리

・ Oracle DB Skills 일본어판 -
**Oracle Database Skills series**

1. AI agents know SQL. Oracle Database Skills teach them Oracle

2. Route, Don’t Flood: Using db/SKILL.md to Steer Oracle‑Aware Assistants

3. Controlled Oracle Actions with SQLcl MCP

4. Managed MCP in Autonomous AI Database: remote, governed tools per database

5. Safer NL2SQL with Select AI and AI Profiles

6. Vector‑native RAG on Oracle: embeddings, HNSW/IVF, and hybrid search under database governance

7. Agent‑safe change delivery on Oracle: discovery, online mechanics, idempotent migrations, and provable rollbacks