Oracle 23ai의 Phantom Vector Memory: 문제 해결 가이드

Source: Dev.to

(번역할 텍스트를 제공해 주시면 한국어로 번역해 드리겠습니다.)

사전 비행 체크리스트

활주로를 따라 택시하기 전에, 여기 당신의 비행 계획이 있습니다. 비행 경로를 탐색할 때 handy하게 보관하세요. 클라우드에 오신 것을 환영합니다!

목차

1. 전제 조건
2. Oracle Architecture에 대한 빠른 입문
3. 미션: Vector Memory 할당
4. 첫 번째 시도: ALTER SYSTEM
5. 장애물: 두 단계 문제
6. 돌파구: docker exec 복구
7. 증명: Parameter가 아니라 Startup Log를 신뢰하라
8. Oracle Parameter 및 Memory Views 이해
9. 복구 요령
10. 결론
11. “IAM Policy”: 왜 우리 dev 사용자가 GRANT가 필요했는가

Introduction

Oracle Cloud Infrastructure (OCI)와 그 강력한 데이터베이스 기능을 활용하면서 Oracle Database 23ai의 새로운 AI Vector Search 기능을 탐구하고 있습니다. 무료 컨테이너화 버전은 이를 실험하기에 완벽한 환경입니다.

고성능 HNSW 인덱스를 사용하려면 vector_memory_size 파라미터를 설정해 전용 메모리 풀을 할당해야 합니다. 단 한 줄의 SQL 명령과 재시작으로 저는 암호 같은 오류, 오해를 일으키는 출력, 그리고 잠긴 데이터베이스라는 미궁에 빠졌습니다. 이 과정은 Oracle 멀티테넌트 아키텍처, 특히 Free 에디션의 내부 작동 방식을 배우는 훌륭한 트러블슈팅 세션이 되었습니다.

vector_memory_size가 0으로 고집하거나 끔찍한 ORA‑12514 오류와 씨름한 적이 있다면, 이 트러블슈팅 여정 로그가 도움이 될 것입니다.

Assumptions

• 이미 The Ultimate Guide to Oracle 23ai on Apple Silicon에 설명된 대로 Oracle 23ai Free 컨테이너를 설치하고 실행하고 있습니다.
• Part 1의 환경이 정상적으로 가동 중입니다. 아직 dev 사용자를 설정하지 않았다면 여기서 멈추고 돌아가세요.

Oracle Terminology Primer

이 개념들을 이해하는 것은 문제가 왜 발생하는지, 그리고 해결 방법이 어떻게 작동하는지를 파악하는 데 필수적입니다.

미션: 벡터 메모리 할당

AI 벡터 검색을 사용하기 위한 첫 번째 단계는 vector_memory_size 매개변수를 설정하여 Oracle이 전용 RAM을 할당하도록 지시하는 것입니다.

⚡ 참고
23ai Free 에디션은 2 GB의 RAM으로 제한됩니다. 벡터에 너무 많은 메모리를 할당하면 다른 중요한 데이터베이스 프로세스가 메모리 부족에 처할 수 있습니다. 1 GB(전체 메모리의 ≈ 50 %) 설정은 위험합니다. 보다 보수적인 값부터 시작하는 것이 현명합니다.

나는 500 M부터 시작하기로 했습니다.

ALTER SYSTEM

-- Connect using my sql-sys alias or as SYS
ALTER SYSTEM SET vector_memory_size = 500M SCOPE = SPFILE;

시스템은 안심할 수 있는 “System altered.” 라는 응답을 반환했습니다. 변경 사항을 적용하려면 데이터베이스를 재시작해야 합니다. Docker를 사용할 경우 가장 쉬운 방법은 컨테이너 자체를 재시작하는 것입니다:

docker restart oracle-free

여기가 여정이 끝나야 하는 지점이었습니다. 하지만 여기서 문제가 시작되었습니다.

첫 번째 장벽: 권한

컨테이너가 재시작된 후, 개발자는 자연스럽게 일상적인 dev 사용자로 연결하여 vector_memory_size 매개변수가 적용되었는지 확인합니다.

-- Connecting as the dev user from Part 1
SQL> SHOW PARAMETER vector_memory_size;
ORA-00942: table or view does not exist

Lesson #1 – 기본 CONNECT와 RESOURCE 역할만 가진 우리의 dev 사용자는 테이블을 생성할 수 있지만 인스턴스 수준 설정을 볼 수 없습니다. 이는 버그가 아니라 보안 기능입니다.

SYS로 전환

-- Now connected as SYS (e.g., via sql-sys alias)
SQL> SHOW PARAMETER vector_memory_size;

NAME                 TYPE          VALUE
-------------------  ------------  ------------------------------
vector_memory_size   big integer   0

값이 여전히 0입니다 – 우리의 변경 사항이 사라진 것으로 보입니다.

두 번째 벽: 구성 레이어

-- 1️⃣ Check current container name
SQL> SHOW CON_NAME;

CON_NAME
--------
FREEPDB1

-- 2️⃣ Check if the parameter is PDB‑modifiable
SQL> SELECT NAME, ISPDB_MODIFIABLE
     FROM V$SYSTEM_PARAMETER
     WHERE NAME = 'vector_memory_size';

NAME                ISPDB_MODIFIABLE
------------------- ----------------
vector_memory_size  TRUE

Interpretation – 나는 PDB(FREEPDB1)에 연결되어 있었고, 해당 파라미터는 PDB‑modifiable 이다. 그러나 SHOW PARAMETER는 여전히 0을 보고했다. 저장된 파라미터 값과 실제 런타임 할당량 사이의 이 불일치는 Oracle Free 에디션에서 흔히 나타나는 특성이다.

dev 사용자를 위한 권한 수정

비‑관리자 사용자는 SHOW PARAMETER가 의존하는 데이터‑사전 뷰를 조회하기 위해 명시적인 권한 부여가 필요합니다.

-- Run as SYS
GRANT SELECT ON SYS.V_$PARAMETER          TO dev;
GRANT SELECT ON SYS.V_$SYSTEM_PARAMETER   TO dev;
GRANT CREATE INDEX                       TO dev;

이 권한 부여를 통해 dev 사용자는 SYS가 소유한 V$PARAMETER와 V$SYSTEM_PARAMETER를 조회할 수 있습니다.

돌파구: docker exec를 사용하여 시작 로그 검사하기

SHOW PARAMETER에 의존하는 대신, 컨테이너 내부의 시작 로그를 확인했으며, 이 로그는 SGA 구성을 정확히 반영합니다.

docker exec -it oracle-free bash
# Inside the container
cat $ORACLE_BASE/diag/rdbms/*/*/trace/alert*.log | grep -i vector_memory_size

로그에는 벡터 메모리 풀에 500 M가 올바르게 할당된 것이 표시되어 ALTER SYSTEM 명령이 성공했음을 확인했습니다; 문제는 dev 세션에서의 가시성에만 있었습니다.

복구 요약표

결론

• vector_memory_size 매개변수 적용되었습니다; 겉보이는 “0” 값은 가시성 문제 때문에 발생했습니다:
  1. CDB가 아니라 PDB에 연결했음.
  2. dev 사용자가 기본 V$ 뷰를 조회할 권한이 부족했음.
• 시작 로그는 Oracle 23ai Free 에디션에서 메모리 할당을 확인하는 가장 신뢰할 수 있는 소스입니다.
• dev 사용자에게 적절한 SELECT 권한을 부여하면 “매개변수가 보이지 않음” 증상이 해결되어 개발자가 전체 SYS 권한 없이 작업을 계속할 수 있습니다.

“IAM 정책”: 왜 우리 dev 사용자가 GRANT가 필요했는가

OCI에서는 IAM 정책이 클라우드 수준에서 사용자가 할 수 있는 일을 제어하지만, 데이터베이스 내부에서는 SQL 수준의 권한 부여가 여전히 필요합니다. dev 사용자는 설정 값을 읽기 위해 SYS.V_$PARAMETER와 SYS.V_$SYSTEM_PARAMETER에 대한 명시적인 SELECT 권한이 필요했고, 실제로 벡터 인덱스를 만들기 위해 CREATE INDEX 권한이 필요했습니다.

Happy Flying!

이제 벡터 메모리를 할당하고 검증하는 깔끔하고 재현 가능한 경로를 확보했으며, ORA‑12514 오류나 신비한 “0” 값에 머무르게 할 수 있는 일반적인 함정을 피할 수 있습니다. 안전한 여행 되세요! 🚀

개요

다음 메모는 CDB 전체 구성 변경 후 사용 불가능해진 Oracle Free Docker 컨테이너에 대한 문제 해결 세션을 문서화한 것입니다.

문제

CDB 루트에서 vector memory 를 변경하고 전체 SHUTDOWN/STARTUP 을 수행한 후, 인스턴스가 시작되지 않았습니다:

Database closed.
Database dismounted.
ORACLE instance shut down.
ERROR:
ORA-12514: Cannot connect to database. Service freepdb1 is not registered with
the listener at host 127.0.0.1 port 1521.

sql-sys 별칭으로 다시 연결을 시도해도 동일한 오류가 발생했습니다:

>>> sql-sys 

Copyright (c) 1982, 2025, Oracle. All rights reserved. 
ERROR: ORA-12514: Cannot connect to database. 
Service freepdb1 is not registered with the listener at host 127.0.0.1 port 1521. 
(CONNECTION_ID=Qgik7CZCByPgYwIAEaywBw==) 
Help: https://docs.oracle.com/error-help/db/ora-12514/ 

Enter user-name:

Docker 컨테이너 상태를 빠르게 확인한 결과 문제가 확인되었습니다:

docker ps

컨테이너가 비정상으로 표시되어 내부 데이터베이스가 완전히 작동하지 않음을 나타냅니다.

ORA‑12514가 실제 의미하는 바

ORA‑12514는 서비스 이름(freepdb1)이 리스너에 등록되지 않음을 의미합니다. 이는 다음과 같은 경우에 발생합니다:

• CDB 인스턴스가 다운된 경우, 또는
• 플러그형 데이터베이스(PDB) 가 닫혀 있는 경우.

Free 에디션에서는 CDB를 재시작한 후 PDB가 자동으로 열리지 않으므로 FREEPDB1이 닫힌 상태로 남아 리스너에 등록되지 않았습니다.

Note – Part 1에서 컨테이너를 재시작했으며, 이때 PDB도 함께 닫혔습니다. 그래서 이제 수동으로 열어야 합니다.

복구 단계

1. SYSDBA 로 컨테이너에 다시 진입

docker exec -it oracle-free sqlplus / as sysdba

다음과 같은 메시지가 표시됩니다:

Connected to an idle instance.

2. 데이터베이스 시작

STARTUP;

3. 플러그형 데이터베이스 열기

ALTER PLUGGABLE DATABASE ALL OPEN;

4. (선택 사항) PDB 전환

ALTER SESSION SET CONTAINER = FREEPDB1;

5. 벡터 메모리 할당 확인

SELECT pool, alloc_bytes, used_bytes
FROM V$VECTOR_MEMORY_POOL;

6. 전체 SGA 구성 확인

SHOW SGA;

GRANT 문 (참조)

이 GRANT 문은 개발자에게 관리자가 되지 않으면서도 필요한 특정 읽기 전용 접근 권한을 제공합니다.

GRANT SELECT ON v$vector_memory_pool TO dev_user;
GRANT SELECT ON v$pdbs               TO dev_user;
GRANT SELECT ON v$system_parameter   TO dev_user;

TL;DR

1. Shutdown the CDB caused the PDB to close → listener could not register FREEPDB1. → CDB를 Shutdown 하면 PDB가 닫히게 되고 → 리스너가 FREEPDB1을 등록하지 못했습니다.
2. Re‑enter the container as SYSDBA, STARTUP the instance. → SYSDBA로 컨테이너에 다시 들어가서 인스턴스를 STARTUP 합니다.
3. Open the PDB (ALTER PLUGGABLE DATABASE ALL OPEN). → PDB를 Open 합니다 (ALTER PLUGGABLE DATABASE ALL OPEN).
4. Verify vector memory allocation via V$VECTOR_MEMORY_POOL and SHOW SGA. → V$VECTOR_MEMORY_POOL와 SHOW SGA를 통해 벡터 메모리 할당을 확인합니다.

The vector memory pool is now correctly allocated (~512 MB), and the database is fully operational. → 벡터 메모리 풀은 이제 올바르게 할당되었으며(~512 MB), 데이터베이스가 완전히 정상 작동합니다.

Source: …

Oracle 뷰를 통한 Vector Memory 이해

V$PARAMETER

시스템 파라미터의 예정된 구성을 보여줍니다. ISPDB_MODIFIABLE 열은 파라미터를 PDB 수준에서 변경할 수 있는지를 나타냅니다.

V$SYSTEM_PARAMETER

V$PARAMETER와 유사하지만 현재 세션에 대한 실제 값을 표시합니다. vector_memory_size와 같은 시스템 수준 파라미터의 경우, 값이 V$PARAMETER와 거의 동일하게 나타납니다.

V$SGA

System Global Area (SGA) 구성 요소와 그 크기를 상세히 제공합니다. vector_memory_size를 설정한 상태에서 STARTUP이 성공하면, 할당된 크기와 함께 Vector Memory Area가 표시됩니다.

SQL> SHOW SGA;

예시 발췌

Total System Global Area   1603373280 bytes
Fixed Size                  5007584 bytes
Variable Size             352321536 bytes
Database Buffers          704643072 bytes
Redo Buffers                4530176 bytes
Vector Memory Area        536870912 bytes

V$VECTOR_MEMORY_POOL

활성화된 vector memory 할당을 확인할 수 있는 가장 직접적인 소스입니다.

SELECT pool, alloc_bytes, used_bytes
FROM V$VECTOR_MEMORY_POOL;

이 뷰에 설정한 크기가 표시되면, vector 검색 메모리가 정상적으로 활성화된 것을 확신할 수 있습니다.

ORA‑12514 오류로 잠겼을 때 복구 절차

1. Docker 컨테이너 상태 확인 (비정상일 가능성).

   docker ps

2. 유휴 인스턴스에 연결

   docker exec -it oracle-free sqlplus / as sysdba

3. 데이터베이스 시작

   STARTUP;

4. 플러그형 데이터베이스 열기

   ALTER PLUGGABLE DATABASE ALL OPEN;

5. (선택) 벡터 메모리 풀 할당 확인

   SELECT pool, alloc_bytes, used_bytes
   FROM V$VECTOR_MEMORY_POOL;

6. (선택) 전체 SGA 구분 확인

   SHOW SGA;

⚡️ 권한에 대한 주의

위의 트러블슈팅 단계는 SYSDBA 권한으로 수행되었습니다. 이는 최소 권한 원칙을 보여줍니다:

• 일상적인 개발자는 시스템 파라미터를 변경하거나 데이터베이스를 재시작할 권한이 없어야 합니다.
• 관리 작업은 슈퍼유저에게만 허용되어, 실험적 접근과 운영 접근을 분리하는 안전한 워크플로를 보장합니다.

핵심 정리

• 시작 로그, V$SGA, V$VECTOR_MEMORY_POOL을 신뢰하여 SGA에서 실제로 일어나는 일을 파악합니다.
• SHOW PARAMETER와 V$SYSTEM_PARAMETER는 의도된 설정을 확인하는 데 유용하지만, 시작 순서와 직접 메모리 풀 조회가 실제 런타임 할당을 보여줍니다.
• CDB와 PDB의 역할을 이해하고 Docker‑exec 워크플로를 숙달하면 잠금 상황을 방지하고 벡터 메모리 프로비저닝을 효율화할 수 있습니다.