echoss-db 2.2.1__tar.gz → 2.3.0__tar.gz

{echoss_db-2.2.1/echoss_db.egg-info → echoss_db-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: echoss-db
-Version: 2.2.1
+Version: 2.3.0
 Summary: echoss AI Bigdata Solution - Database Query Package
 Author-email: ckkim <ckkim@12cm.co.kr>
 License-Expression: Apache-2.0
@@ -13,13 +13,14 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: pandas>=1.5.3
+Requires-Dist: pandas>=3.0
 Requires-Dist: sqlalchemy>=2.0.0
 Requires-Dist: PyMySQL>=1.0.2
 Requires-Dist: opensearch-py<3.0.0,>=2.8.0
-Requires-Dist: echoss-fileformat>=1.1.2
+Requires-Dist: echoss-common<3,>=1.2.0
 Requires-Dist: psycopg[binary]<4.0.0,>=3.2
 Requires-Dist: qdrant-client[fastembed]<2.0.0,>=1.14.1
+Requires-Dist: python-dotenv>=1.0.0
 Provides-Extra: mapping
 Requires-Dist: pydantic<3.0.0,>=2.0.0; extra == "mapping"
 Provides-Extra: mongo
@@ -36,16 +37,24 @@ MySQL, PostgreSQL, OpenSearch, Qdrant compatible query/vector access package
 > ⚠️ **MongoDB support is deprecated** (v2.2.0) and will be removed in v3.0.0.
 > `pymongo` is now an optional dependency: `pip install echoss-db[mongo]`.
 
+> 작업 이력(완료된 결론·미착수 백로그)은 [`prior-work.jsonl`](./prior-work.jsonl)에 기록됩니다.
+> 조회: `/prior-work <주제어>` (예: `qdrant`, `.env`, `mysql passwd`).
+
 ## Prepare
 
 사용 전 config(인증 정보) 유무를 확인한 뒤 사용해야 합니다.
 `config/config.example.yaml`을 `config/config.yaml`로 복사해 실제 값을 채우세요 (실 config는 gitignore 대상).
 `config/config.yaml` 기준의 credential 제거 예시는 아래와 같습니다.
 
+credential 필드(`passwd`, `api_key`, `read_only_api_key`)는 평문 대신 `${VAR_NAME}` 형태로
+적으면 `.env`(또는 OS 환경변수)에서 값을 읽어 채웁니다. `.env`는 git에 추적되지 않으므로
+`.env.example`을 `.env`로 복사해 실제 값을 채우세요. host/port 등 credential이 아닌 필드는
+지금처럼 평문 값을 직접 씁니다.
+
 ```yaml
 mysql:
   user: <MYSQL_USER>
-  passwd: <MYSQL_PASSWORD>
+  passwd: ${MYSQL_PASSWD}
   host: <MYSQL_HOST>
   port: <MYSQL_PORT>
   db: <MYSQL_DB>
@@ -58,7 +67,7 @@ mongo:
 
 elastic:
   user: <ELASTIC_USER>
-  passwd: <ELASTIC_PASSWORD>
+  passwd: ${ELASTIC_PASSWD}
   host: <ELASTIC_HOST>
   port: <ELASTIC_PORT>
   scheme: <http|https>
@@ -66,7 +75,7 @@ elastic:
 
 postgres:
   user: <POSTGRES_USER>
-  passwd: <POSTGRES_PASSWORD>
+  passwd: ${POSTGRES_PASSWD}
   host: <POSTGRES_HOST>
   port: <POSTGRES_PORT>
   db: <POSTGRES_DB>
@@ -81,8 +90,31 @@ qdrant:
   default_limit: <DEFAULT_LIMIT>
   # fastembed_model omitted -> default FastEmbed model automatically applied
   # fastembed_model: null -> external vector mode (no FastEmbed)
+  api_key: ${QDRANT_API_KEY}                  # optional, admin/전체 권한
+  read_only_api_key: ${QDRANT_READ_ONLY_API_KEY}  # optional, 조회 전용
 ```
 
+`.env` 예시(`.env.example` 참고, 실값은 커밋하지 않음):
+
+```
+MYSQL_PASSWD=
+ELASTIC_PASSWD=
+POSTGRES_PASSWD=
+QDRANT_API_KEY=
+QDRANT_READ_ONLY_API_KEY=
+```
+
+Qdrant는 role로 admin/조회 인스턴스를 나눠 생성할 수 있습니다:
+
+```python
+from echoss_db.qdrant_vector import QdrantVector
+
+admin = QdrantVector("config/config.yaml")                    # role 기본값 "admin" -> qdrant.api_key 사용
+readonly = QdrantVector("config/config.yaml", role="readonly")  # qdrant.read_only_api_key 사용
+```
+
+`api_key`/`read_only_api_key`를 둘 다 설정하지 않으면 기존과 동일하게 무인증으로 연결됩니다.
+
 ## Installation
 
 ---
@@ -106,6 +138,9 @@ Python 3.11 or lower is not supported in `echoss-db>=2.2.0`; use the `1.x` line
     pip install -U echoss-db
 ```
 
+`echoss-db>=2.3.0` requires pandas `>=3.0`. Environments pinned to pandas 2 (e.g. AutoGluon, PyCaret 3.x) should pin `"echoss-db<2.3"`.
+`echoss-db>=2.3.0` no longer installs `echoss-fileformat`; declare it directly if your code imports it.
+
 If your environment previously used legacy PostgreSQL drivers, clean them first:
 
 ```bash
@@ -596,3 +631,5 @@ v1.2.3 add postgres DB and qdrant vector storage support
 v2.0.0 add optional `echoss_db.mapping` (dataclass default, pydantic optional)
 v2.1.0 raise Python baseline to 3.11, standardize on psycopg3, and keep Qdrant fastembed as default runtime
 v2.2.0 qdrant generalized dict filter (breaking behavior: previously ignored keys now applied) and get_collection_info, postgres upsert/parse_json options, upsert retry/backoff/batch_size, deprecate MongoQuery (pymongo moved to optional extra [mongo]), raise Python floor to 3.12
+v2.2.2 qdrant admin/read-only API key support (`role` param, `api_key`/`read_only_api_key` config fields), config.yaml credential fields (mysql/postgres/elastic `passwd`, qdrant `api_key`/`read_only_api_key`) now accept `${VAR_NAME}` placeholders resolved from `.env`/OS env (new `python-dotenv` dependency)
+v2.3.0 config loading and logger now imported from `echoss-common` (`>=1.2.0,<3`) instead of `echoss-fileformat`; `echoss-fileformat` removed from install dependencies (declare it directly if you use it); raise pandas floor to 3.0. XML config files are now read by `echoss-common` (result keys may differ from the previous `echoss-fileformat` XML reader). With `echoss-common` 2.0: no default `logs/echoss.log` file (console only), and a missing config file path raises `FileNotFoundError` (previously `ValueError`/`TypeError`)

{echoss_db-2.2.1 → echoss_db-2.3.0}/README.md

@@ -5,16 +5,24 @@ MySQL, PostgreSQL, OpenSearch, Qdrant compatible query/vector access package
 > ⚠️ **MongoDB support is deprecated** (v2.2.0) and will be removed in v3.0.0.
 > `pymongo` is now an optional dependency: `pip install echoss-db[mongo]`.
 
+> 작업 이력(완료된 결론·미착수 백로그)은 [`prior-work.jsonl`](./prior-work.jsonl)에 기록됩니다.
+> 조회: `/prior-work <주제어>` (예: `qdrant`, `.env`, `mysql passwd`).
+
 ## Prepare
 
 사용 전 config(인증 정보) 유무를 확인한 뒤 사용해야 합니다.
 `config/config.example.yaml`을 `config/config.yaml`로 복사해 실제 값을 채우세요 (실 config는 gitignore 대상).
 `config/config.yaml` 기준의 credential 제거 예시는 아래와 같습니다.
 
+credential 필드(`passwd`, `api_key`, `read_only_api_key`)는 평문 대신 `${VAR_NAME}` 형태로
+적으면 `.env`(또는 OS 환경변수)에서 값을 읽어 채웁니다. `.env`는 git에 추적되지 않으므로
+`.env.example`을 `.env`로 복사해 실제 값을 채우세요. host/port 등 credential이 아닌 필드는
+지금처럼 평문 값을 직접 씁니다.
+
 ```yaml
 mysql:
   user: <MYSQL_USER>
-  passwd: <MYSQL_PASSWORD>
+  passwd: ${MYSQL_PASSWD}
   host: <MYSQL_HOST>
   port: <MYSQL_PORT>
   db: <MYSQL_DB>
@@ -27,7 +35,7 @@ mongo:
 
 elastic:
   user: <ELASTIC_USER>
-  passwd: <ELASTIC_PASSWORD>
+  passwd: ${ELASTIC_PASSWD}
   host: <ELASTIC_HOST>
   port: <ELASTIC_PORT>
   scheme: <http|https>
@@ -35,7 +43,7 @@ elastic:
 
 postgres:
   user: <POSTGRES_USER>
-  passwd: <POSTGRES_PASSWORD>
+  passwd: ${POSTGRES_PASSWD}
   host: <POSTGRES_HOST>
   port: <POSTGRES_PORT>
   db: <POSTGRES_DB>
@@ -50,8 +58,31 @@ qdrant:
   default_limit: <DEFAULT_LIMIT>
   # fastembed_model omitted -> default FastEmbed model automatically applied
   # fastembed_model: null -> external vector mode (no FastEmbed)
+  api_key: ${QDRANT_API_KEY}                  # optional, admin/전체 권한
+  read_only_api_key: ${QDRANT_READ_ONLY_API_KEY}  # optional, 조회 전용
 ```
 
+`.env` 예시(`.env.example` 참고, 실값은 커밋하지 않음):
+
+```
+MYSQL_PASSWD=
+ELASTIC_PASSWD=
+POSTGRES_PASSWD=
+QDRANT_API_KEY=
+QDRANT_READ_ONLY_API_KEY=
+```
+
+Qdrant는 role로 admin/조회 인스턴스를 나눠 생성할 수 있습니다:
+
+```python
+from echoss_db.qdrant_vector import QdrantVector
+
+admin = QdrantVector("config/config.yaml")                    # role 기본값 "admin" -> qdrant.api_key 사용
+readonly = QdrantVector("config/config.yaml", role="readonly")  # qdrant.read_only_api_key 사용
+```
+
+`api_key`/`read_only_api_key`를 둘 다 설정하지 않으면 기존과 동일하게 무인증으로 연결됩니다.
+
 ## Installation
 
 ---
@@ -75,6 +106,9 @@ Python 3.11 or lower is not supported in `echoss-db>=2.2.0`; use the `1.x` line
     pip install -U echoss-db
 ```
 
+`echoss-db>=2.3.0` requires pandas `>=3.0`. Environments pinned to pandas 2 (e.g. AutoGluon, PyCaret 3.x) should pin `"echoss-db<2.3"`.
+`echoss-db>=2.3.0` no longer installs `echoss-fileformat`; declare it directly if your code imports it.
+
 If your environment previously used legacy PostgreSQL drivers, clean them first:
 
 ```bash
@@ -565,3 +599,5 @@ v1.2.3 add postgres DB and qdrant vector storage support
 v2.0.0 add optional `echoss_db.mapping` (dataclass default, pydantic optional)
 v2.1.0 raise Python baseline to 3.11, standardize on psycopg3, and keep Qdrant fastembed as default runtime
 v2.2.0 qdrant generalized dict filter (breaking behavior: previously ignored keys now applied) and get_collection_info, postgres upsert/parse_json options, upsert retry/backoff/batch_size, deprecate MongoQuery (pymongo moved to optional extra [mongo]), raise Python floor to 3.12
+v2.2.2 qdrant admin/read-only API key support (`role` param, `api_key`/`read_only_api_key` config fields), config.yaml credential fields (mysql/postgres/elastic `passwd`, qdrant `api_key`/`read_only_api_key`) now accept `${VAR_NAME}` placeholders resolved from `.env`/OS env (new `python-dotenv` dependency)
+v2.3.0 config loading and logger now imported from `echoss-common` (`>=1.2.0,<3`) instead of `echoss-fileformat`; `echoss-fileformat` removed from install dependencies (declare it directly if you use it); raise pandas floor to 3.0. XML config files are now read by `echoss-common` (result keys may differ from the previous `echoss-fileformat` XML reader). With `echoss-common` 2.0: no default `logs/echoss.log` file (console only), and a missing config file path raises `FileNotFoundError` (previously `ValueError`/`TypeError`)

{echoss_db-2.2.1 → echoss_db-2.3.0}/echoss_db/elastic_search.py

@@ -4,7 +4,9 @@ from opensearchpy.helpers import bulk as helpers_bulk
 from opensearchpy.exceptions import NotFoundError
 from typing import Any, List, Tuple, Dict, Optional, Union
 
-from echoss_fileformat import FileUtil, get_logger, set_logger_level
+from echoss_common import dict_load, get_logger, set_logger_level
+
+from .env_config import resolve_credential
 
 logger = get_logger("echoss_query")
 
@@ -33,7 +35,7 @@ class ElasticSearch:
 
         """
         if isinstance(conn_info, str):
-            conn_info = FileUtil.dict_load(conn_info)
+            conn_info = dict_load(conn_info)
         elif not isinstance(conn_info, dict):
             raise TypeError("ElasticSearch support type 'str' and 'dict'")
 
@@ -44,7 +46,7 @@ class ElasticSearch:
             raise TypeError("[Elastic] config info not exist")
 
         self.user = es_config.get('user')
-        self.passwd = es_config.get('passwd')
+        self.passwd = resolve_credential(es_config.get('passwd'), section='elastic', field='passwd')
         self.auth = (self.user, self.passwd) if self.user and self.passwd else None
 
         self.host = es_config['host']

echoss_db-2.3.0/echoss_db/env_config.py

@@ -0,0 +1,53 @@
+"""PLACEHOLDER 치환 공용 헬퍼.
+
+Design Ref: §4.1, §9 — mysql/postgres/elastic/qdrant 4개 DB 모듈이 공통으로 import하는
+credential 치환 로직. config.yaml의 값이 '${VAR_NAME}' 전체 패턴과 일치하면 .env/OS
+환경변수에서 VAR_NAME을 찾아 치환하고, 아니면 원본 값을 그대로 반환한다(평문 하위 호환).
+"""
+from __future__ import annotations
+
+import os
+import re
+from typing import Optional
+
+from dotenv import find_dotenv, load_dotenv
+
+PLACEHOLDER_PATTERN = re.compile(r"^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$")
+
+_dotenv_loaded = False
+
+
+def _ensure_dotenv_loaded() -> None:
+    # Design Ref: §4.1 — 프로세스당 1회만 로드, OS 환경변수가 .env보다 우선(override=False, FR-04).
+    global _dotenv_loaded
+    if _dotenv_loaded:
+        return
+    load_dotenv(find_dotenv(usecwd=True), override=False)
+    _dotenv_loaded = True
+
+
+def resolve_credential(value: Optional[str], *, section: str, field: str) -> Optional[str]:
+    """value가 '${VAR_NAME}' 전체 일치 패턴이면 .env/OS 환경변수에서 VAR_NAME을 찾아 반환한다.
+
+    패턴이 아니면 value를 그대로 반환한다(평문 config 하위 호환). value가 None이거나
+    문자열이 아니면 그대로 반환한다.
+
+    Raises:
+        ValueError: PLACEHOLDER이지만 .env/OS 어디에도 VAR_NAME이 없을 때(fail-closed, FR-06).
+    """
+    if not isinstance(value, str):
+        return value
+
+    match = PLACEHOLDER_PATTERN.match(value)
+    if not match:
+        return value
+
+    _ensure_dotenv_loaded()
+    var_name = match.group(1)
+    resolved = os.environ.get(var_name)
+    if resolved is None:
+        raise ValueError(
+            f"[{section}.{field}] environment variable '{var_name}' not found "
+            f"(.env / OS env). Set it before creating this connection."
+        )
+    return resolved

{echoss_db-2.2.1 → echoss_db-2.3.0}/echoss_db/mongo_query.py

@@ -5,7 +5,7 @@ from pymongo import MongoClient
 from pymongo.errors import PyMongoError
 from typing import Any, List, Tuple, Union
 
-from echoss_fileformat import FileUtil, get_logger, set_logger_level
+from echoss_common import dict_load, get_logger, set_logger_level
 
 logger = get_logger("echoss_query")
 
@@ -34,7 +34,7 @@ class MongoQuery:
             stacklevel=2,
         )
         if isinstance(conn_info, str):
-            conn_info = FileUtil.dict_load(conn_info)
+            conn_info = dict_load(conn_info)
         elif not isinstance(conn_info, dict):
             raise TypeError("[Mongo] support type 'str' and 'dict'")
         required_keys = ['db']

{echoss_db-2.2.1 → echoss_db-2.3.0}/echoss_db/mysql_query.py

@@ -9,7 +9,8 @@ from sqlalchemy import create_engine, text
 from sqlalchemy.engine import Engine, Connection, Result 
 from sqlalchemy.exc import SQLAlchemyError, DBAPIError
 
-from echoss_fileformat import FileUtil, get_logger
+from echoss_common import dict_load, get_logger
+from .env_config import resolve_credential
 from .sql_transaction import SQLTransaction
 
 logger = get_logger("echoss_db")
@@ -130,7 +131,7 @@ class MysqlQuery:
             use_percent_param:  use %s param style, if false sqlalchemy :name tag style query param
         """
         if isinstance(conn_info, str):
-            conn_info = FileUtil.dict_load(conn_info)
+            conn_info = dict_load(conn_info)
         elif not isinstance(conn_info, dict):
             raise TypeError("MysqlQuery support type 'str' and 'dict'")
         
@@ -143,7 +144,7 @@ class MysqlQuery:
         if (len(conn_info) > 0) and ('mysql' in conn_info) and all(key in conn_info['mysql'] for key in required_keys):
             m = conn_info["mysql"]
             self.user = m['user']
-            self.passwd = m['passwd']
+            self.passwd = resolve_credential(m['passwd'], section='mysql', field='passwd')
             self.host = m['host']
             self.port = m.get('port', 3306)
             self.db = m['db']

{echoss_db-2.2.1 → echoss_db-2.3.0}/echoss_db/postgres_query.py

@@ -10,7 +10,8 @@ from sqlalchemy import create_engine, text
 from sqlalchemy.engine import Engine, Connection, Result
 from sqlalchemy.exc import SQLAlchemyError
 
-from echoss_fileformat import FileUtil, get_logger
+from echoss_common import dict_load, get_logger
+from .env_config import resolve_credential
 from .sql_transaction import SQLTransaction
 
 logger = get_logger("echoss_db")
@@ -94,7 +95,7 @@ class PostgresQuery:
                  pool_size: int = 5, pool_timeout: int = 30, pool_recycle: Optional[int] = None,
                  use_percent_param: bool = True):
         if isinstance(conn_info, str):
-            conn_info = FileUtil.dict_load(conn_info)
+            conn_info = dict_load(conn_info)
         elif not isinstance(conn_info, dict):
             raise TypeError("PostgresQuery support type 'str' and 'dict'")
 
@@ -107,7 +108,7 @@ class PostgresQuery:
         if (len(conn_info) > 0) and ('postgres' in conn_info) and all(k in conn_info['postgres'] for k in required_keys):
             p = conn_info["postgres"]
             self.user = p['user']
-            self.passwd = p['passwd']
+            self.passwd = resolve_credential(p['passwd'], section='postgres', field='passwd')
             self.host = p['host']
             self.port = p.get('port', 5432)
             self.db = p['db']

{echoss_db-2.2.1 → echoss_db-2.3.0}/echoss_db/qdrant_vector.py

@@ -3,13 +3,15 @@ import time
 import pandas as pd
 from typing import Any, Dict, List, Optional, Union
 
-from echoss_fileformat import FileUtil, get_logger
+from echoss_common import dict_load, get_logger
 
 logger = get_logger("echoss_query")
 
 from qdrant_client import QdrantClient
 from qdrant_client.http import models as qm
 
+from .env_config import resolve_credential
+
 
 class QdrantVector:
     conn = None
@@ -17,7 +19,7 @@ class QdrantVector:
     default_limit = 10
     default_fastembed_model = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
 
-    def __init__(self, conn_info: Union[str, dict]):
+    def __init__(self, conn_info: Union[str, dict], role: str = "admin"):
         """
         Args:
             conn_info:
@@ -28,12 +30,16 @@ class QdrantVector:
                   'scheme': 'http',
                   'collection': 'ai_rag_chunks',
                   'timeout': 5,
-                  'default_limit': 10
+                  'default_limit': 10,
+                  'api_key': '${QDRANT_API_KEY}',                 # admin, optional
+                  'read_only_api_key': '${QDRANT_READ_ONLY_API_KEY}',  # readonly, optional
                 }
               }
+            role: "admin"(기본값) 또는 "readonly". config의 qdrant.api_key/read_only_api_key
+              중 role에 대응하는 필드를 연결에 사용한다. Design Ref: §4.2.
         """
         if isinstance(conn_info, str):
-            conn_info = FileUtil.dict_load(conn_info)
+            conn_info = dict_load(conn_info)
         elif not isinstance(conn_info, dict):
             raise TypeError("QdrantVector support type 'str' and 'dict'")
 
@@ -43,6 +49,23 @@ class QdrantVector:
         else:
             raise TypeError("[Qdrant] config info not exist")
 
+        if role not in ("admin", "readonly"):
+            raise ValueError(f"QdrantVector role must be 'admin' or 'readonly', got '{role}'")
+        self.role = role
+
+        # Design Ref: §4.2 — role에 대응하는 키 필드가 없고 다른 role의 키만 있으면 에러(FR-03).
+        # 둘 다 없으면 기존과 동일하게 무인증 연결(하위 호환).
+        key_field = "api_key" if role == "admin" else "read_only_api_key"
+        other_field = "read_only_api_key" if role == "admin" else "api_key"
+        if key_field in q_config:
+            self.api_key = resolve_credential(q_config[key_field], section="qdrant", field=key_field)
+        elif other_field in q_config:
+            raise ValueError(
+                f"role='{role}' requires qdrant.{key_field}, but only qdrant.{other_field} is configured"
+            )
+        else:
+            self.api_key = None
+
         self.host = q_config['host']
         self.port = q_config.get('port', 6333)
         self.scheme = q_config.get('scheme', 'http')
@@ -82,7 +105,7 @@ class QdrantVector:
 
     def connect(self):
         try:
-            cli = QdrantClient(url=self.url, timeout=self.timeout)
+            cli = QdrantClient(url=self.url, api_key=self.api_key, timeout=self.timeout)
             # 간단 ping: collections 호출
             cli.get_collections()
             return cli

{echoss_db-2.2.1 → echoss_db-2.3.0/echoss_db.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: echoss-db
-Version: 2.2.1
+Version: 2.3.0
 Summary: echoss AI Bigdata Solution - Database Query Package
 Author-email: ckkim <ckkim@12cm.co.kr>
 License-Expression: Apache-2.0
@@ -13,13 +13,14 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: pandas>=1.5.3
+Requires-Dist: pandas>=3.0
 Requires-Dist: sqlalchemy>=2.0.0
 Requires-Dist: PyMySQL>=1.0.2
 Requires-Dist: opensearch-py<3.0.0,>=2.8.0
-Requires-Dist: echoss-fileformat>=1.1.2
+Requires-Dist: echoss-common<3,>=1.2.0
 Requires-Dist: psycopg[binary]<4.0.0,>=3.2
 Requires-Dist: qdrant-client[fastembed]<2.0.0,>=1.14.1
+Requires-Dist: python-dotenv>=1.0.0
 Provides-Extra: mapping
 Requires-Dist: pydantic<3.0.0,>=2.0.0; extra == "mapping"
 Provides-Extra: mongo
@@ -36,16 +37,24 @@ MySQL, PostgreSQL, OpenSearch, Qdrant compatible query/vector access package
 > ⚠️ **MongoDB support is deprecated** (v2.2.0) and will be removed in v3.0.0.
 > `pymongo` is now an optional dependency: `pip install echoss-db[mongo]`.
 
+> 작업 이력(완료된 결론·미착수 백로그)은 [`prior-work.jsonl`](./prior-work.jsonl)에 기록됩니다.
+> 조회: `/prior-work <주제어>` (예: `qdrant`, `.env`, `mysql passwd`).
+
 ## Prepare
 
 사용 전 config(인증 정보) 유무를 확인한 뒤 사용해야 합니다.
 `config/config.example.yaml`을 `config/config.yaml`로 복사해 실제 값을 채우세요 (실 config는 gitignore 대상).
 `config/config.yaml` 기준의 credential 제거 예시는 아래와 같습니다.
 
+credential 필드(`passwd`, `api_key`, `read_only_api_key`)는 평문 대신 `${VAR_NAME}` 형태로
+적으면 `.env`(또는 OS 환경변수)에서 값을 읽어 채웁니다. `.env`는 git에 추적되지 않으므로
+`.env.example`을 `.env`로 복사해 실제 값을 채우세요. host/port 등 credential이 아닌 필드는
+지금처럼 평문 값을 직접 씁니다.
+
 ```yaml
 mysql:
   user: <MYSQL_USER>
-  passwd: <MYSQL_PASSWORD>
+  passwd: ${MYSQL_PASSWD}
   host: <MYSQL_HOST>
   port: <MYSQL_PORT>
   db: <MYSQL_DB>
@@ -58,7 +67,7 @@ mongo:
 
 elastic:
   user: <ELASTIC_USER>
-  passwd: <ELASTIC_PASSWORD>
+  passwd: ${ELASTIC_PASSWD}
   host: <ELASTIC_HOST>
   port: <ELASTIC_PORT>
   scheme: <http|https>
@@ -66,7 +75,7 @@ elastic:
 
 postgres:
   user: <POSTGRES_USER>
-  passwd: <POSTGRES_PASSWORD>
+  passwd: ${POSTGRES_PASSWD}
   host: <POSTGRES_HOST>
   port: <POSTGRES_PORT>
   db: <POSTGRES_DB>
@@ -81,8 +90,31 @@ qdrant:
   default_limit: <DEFAULT_LIMIT>
   # fastembed_model omitted -> default FastEmbed model automatically applied
   # fastembed_model: null -> external vector mode (no FastEmbed)
+  api_key: ${QDRANT_API_KEY}                  # optional, admin/전체 권한
+  read_only_api_key: ${QDRANT_READ_ONLY_API_KEY}  # optional, 조회 전용
 ```
 
+`.env` 예시(`.env.example` 참고, 실값은 커밋하지 않음):
+
+```
+MYSQL_PASSWD=
+ELASTIC_PASSWD=
+POSTGRES_PASSWD=
+QDRANT_API_KEY=
+QDRANT_READ_ONLY_API_KEY=
+```
+
+Qdrant는 role로 admin/조회 인스턴스를 나눠 생성할 수 있습니다:
+
+```python
+from echoss_db.qdrant_vector import QdrantVector
+
+admin = QdrantVector("config/config.yaml")                    # role 기본값 "admin" -> qdrant.api_key 사용
+readonly = QdrantVector("config/config.yaml", role="readonly")  # qdrant.read_only_api_key 사용
+```
+
+`api_key`/`read_only_api_key`를 둘 다 설정하지 않으면 기존과 동일하게 무인증으로 연결됩니다.
+
 ## Installation
 
 ---
@@ -106,6 +138,9 @@ Python 3.11 or lower is not supported in `echoss-db>=2.2.0`; use the `1.x` line
     pip install -U echoss-db
 ```
 
+`echoss-db>=2.3.0` requires pandas `>=3.0`. Environments pinned to pandas 2 (e.g. AutoGluon, PyCaret 3.x) should pin `"echoss-db<2.3"`.
+`echoss-db>=2.3.0` no longer installs `echoss-fileformat`; declare it directly if your code imports it.
+
 If your environment previously used legacy PostgreSQL drivers, clean them first:
 
 ```bash
@@ -596,3 +631,5 @@ v1.2.3 add postgres DB and qdrant vector storage support
 v2.0.0 add optional `echoss_db.mapping` (dataclass default, pydantic optional)
 v2.1.0 raise Python baseline to 3.11, standardize on psycopg3, and keep Qdrant fastembed as default runtime
 v2.2.0 qdrant generalized dict filter (breaking behavior: previously ignored keys now applied) and get_collection_info, postgres upsert/parse_json options, upsert retry/backoff/batch_size, deprecate MongoQuery (pymongo moved to optional extra [mongo]), raise Python floor to 3.12
+v2.2.2 qdrant admin/read-only API key support (`role` param, `api_key`/`read_only_api_key` config fields), config.yaml credential fields (mysql/postgres/elastic `passwd`, qdrant `api_key`/`read_only_api_key`) now accept `${VAR_NAME}` placeholders resolved from `.env`/OS env (new `python-dotenv` dependency)
+v2.3.0 config loading and logger now imported from `echoss-common` (`>=1.2.0,<3`) instead of `echoss-fileformat`; `echoss-fileformat` removed from install dependencies (declare it directly if you use it); raise pandas floor to 3.0. XML config files are now read by `echoss-common` (result keys may differ from the previous `echoss-fileformat` XML reader). With `echoss-common` 2.0: no default `logs/echoss.log` file (console only), and a missing config file path raises `FileNotFoundError` (previously `ValueError`/`TypeError`)

{echoss_db-2.2.1 → echoss_db-2.3.0}/echoss_db.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ pyproject.toml
 requirements.txt
 echoss_db/__init__.py
 echoss_db/elastic_search.py
+echoss_db/env_config.py
 echoss_db/mongo_query.py
 echoss_db/mysql_query.py
 echoss_db/postgres_query.py
@@ -26,6 +27,7 @@ package_tests/test_package_imports.py
 tests/__init__.py
 tests/integration/__init__.py
 tests/integration/conftest.py
+tests/integration/test_env_config_integration.py
 tests/integration/test_postgres_integration.py
 tests/integration/test_qdrant_integration.py
 tests/manual/__init__.py
@@ -42,5 +44,7 @@ tests/manual/example_postgres_qdrant_ingest.py
 tests/manual/example_qdrant.py
 tests/manual/setup_ai_rag_test_schema.sql
 tests/unit/__init__.py
+tests/unit/test_env_config.py
+tests/unit/test_qdrant_role.py
 tests/unit/mapping/__init__.py
 tests/unit/mapping/test_param_mapper.py

{echoss_db-2.2.1 → echoss_db-2.3.0}/echoss_db.egg-info/requires.txt

@@ -1,10 +1,11 @@
-pandas>=1.5.3
+pandas>=3.0
 sqlalchemy>=2.0.0
 PyMySQL>=1.0.2
 opensearch-py<3.0.0,>=2.8.0
-echoss-fileformat>=1.1.2
+echoss-common<3,>=1.2.0
 psycopg[binary]<4.0.0,>=3.2
 qdrant-client[fastembed]<2.0.0,>=1.14.1
+python-dotenv>=1.0.0
 
 [all]
 pydantic<3.0.0,>=2.0.0

{echoss_db-2.2.1 → echoss_db-2.3.0}/echoss_db.egg-info/top_level.txt

@@ -1,3 +1,4 @@
+build
 config
 dist
 echoss_db

{echoss_db-2.2.1 → echoss_db-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "echoss-db"
-version = "2.2.1"
+version = "2.3.0"
 description = "echoss AI Bigdata Solution - Database Query Package"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "Apache-2.0"
@@ -20,13 +20,14 @@ classifiers = [
     "Operating System :: OS Independent",
 ]
 dependencies = [
-    "pandas>=1.5.3",
+    "pandas>=3.0",
     "sqlalchemy>=2.0.0",
     "PyMySQL>=1.0.2",
     "opensearch-py>=2.8.0,<3.0.0",
-    "echoss-fileformat>=1.1.2",
+    "echoss-common>=1.2.0,<3",
     "psycopg[binary]>=3.2,<4.0.0",
     "qdrant-client[fastembed]>=1.14.1,<2.0.0",
+    "python-dotenv>=1.0.0",
 ]
 
 [project.optional-dependencies]

{echoss_db-2.2.1 → echoss_db-2.3.0}/requirements.txt

@@ -1,7 +1,7 @@
-pandas>=1.5.3
+pandas>=3.0
 PyMySQL>=1.0.2
 sqlalchemy>=2.0.0
 opensearch-py>=2.8.0,<3.0.0
-echoss-fileformat>=1.1.2
+echoss-common>=1.2.0,<3
 qdrant-client[fastembed]>=1.14.1,<2.0.0
 psycopg[binary]>=3.2,<4.0.0

{echoss_db-2.2.1 → echoss_db-2.3.0}/tests/integration/conftest.py

@@ -15,7 +15,7 @@ import os
 
 import pytest
 
-from echoss_fileformat import FileUtil
+from echoss_common import dict_load
 
 from echoss_db.postgres_query import PostgresQuery
 from echoss_db.qdrant_vector import QdrantVector
@@ -23,14 +23,14 @@ from echoss_db.qdrant_vector import QdrantVector
 PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
 CONFIG_PATH = os.path.join(PROJECT_ROOT, "config", "config_dev.yaml")
 
-POSTGRES_TEST_SCHEMA = "ai_rag_test"
-QDRANT_TEST_COLLECTION = "echoss_it_vectors"
+POSTGRES_TEST_SCHEMA = "ai_push_rag_test"
+QDRANT_TEST_COLLECTION = "ai_push_chunks_test"
 
 
 def load_config_section(section: str) -> dict:
     if not os.path.exists(CONFIG_PATH):
         pytest.skip(f"config/config_dev.yaml not found — required for {section} integration tests")
-    config = FileUtil.dict_load(CONFIG_PATH)
+    config = dict_load(CONFIG_PATH)
     if section not in config:
         pytest.skip(f"'{section}' section missing in config/config_dev.yaml")
     return dict(config[section])

echoss_db-2.3.0/tests/integration/test_env_config_integration.py

@@ -0,0 +1,71 @@
+"""Real Postgres integration tests for env_config PLACEHOLDER credential resolution.
+
+Verifies that a config.yaml credential field using '${VAR_NAME}' connects exactly like a
+plaintext credential, using the real config_dev.yaml postgres section as the source of
+truth for actual credentials (no fake DB, per [[no-fake-db-tests]]).
+Run: pytest -m integration tests/integration/test_env_config_integration.py
+
+Design Ref: §8.4. Both tests run an actual SELECT — PostgresQuery.connect_db() only
+builds a lazy SQLAlchemy Engine and does not validate credentials at construction time,
+so asserting on `client.engine` alone would not prove a real, correctly-authenticated
+connection.
+"""
+from __future__ import annotations
+
+import pytest
+
+from echoss_db.env_config import resolve_credential
+from echoss_db.postgres_query import PostgresQuery
+
+from .conftest import POSTGRES_TEST_SCHEMA, load_config_section
+
+pytestmark = pytest.mark.integration
+
+
+def test_postgres_connects_with_placeholder_passwd():
+    # config_dev.yaml의 postgres.passwd는 실제로 "${AI_PUSH_PG_PASSWD}" PLACEHOLDER다.
+    # .env/OS env에 실값이 없으면 이 시나리오 자체를 검증할 수 없으므로 skip한다.
+    pg_cfg = dict(load_config_section("postgres"))
+    pg_cfg["schema"] = POSTGRES_TEST_SCHEMA
+
+    try:
+        client = PostgresQuery({"postgres": pg_cfg})
+    except ValueError as e:
+        pytest.skip(f"PLACEHOLDER env var not set — cannot verify: {e}")
+
+    try:
+        df = client.select("SELECT 1 AS ok")
+        assert df.loc[0, "ok"] == 1
+    finally:
+        client.close()
+
+
+def test_postgres_still_connects_with_plaintext_passwd():
+    # 기존 평문 config 하위 호환 회귀 확인 (FR-07) — 실 패스워드를 평문으로 config에 직접
+    # 넣어도 동작해야 한다. config_dev.yaml 자체는 이제 PLACEHOLDER를 쓰므로, 진짜 비밀값은
+    # resolve_credential로 한 번 해석해서(값을 출력/로그에 남기지 않고) 평문으로 재사용한다.
+    pg_cfg = dict(load_config_section("postgres"))
+    try:
+        real_passwd = resolve_credential(pg_cfg["passwd"], section="postgres", field="passwd")
+    except ValueError as e:
+        pytest.skip(f"cannot resolve real postgres passwd for plaintext regression test: {e}")
+
+    pg_cfg["passwd"] = real_passwd  # 평문 — PLACEHOLDER 아님
+    pg_cfg["schema"] = POSTGRES_TEST_SCHEMA
+
+    client = PostgresQuery({"postgres": pg_cfg})
+    try:
+        df = client.select("SELECT 1 AS ok")
+        assert df.loc[0, "ok"] == 1
+    finally:
+        client.close()
+
+
+def test_missing_placeholder_env_var_raises(monkeypatch):
+    pg_cfg = dict(load_config_section("postgres"))
+    monkeypatch.delenv("ECHOSS_IT_NONEXISTENT_VAR", raising=False)
+    pg_cfg["passwd"] = "${ECHOSS_IT_NONEXISTENT_VAR}"
+    pg_cfg["schema"] = POSTGRES_TEST_SCHEMA
+
+    with pytest.raises(ValueError, match="ECHOSS_IT_NONEXISTENT_VAR"):
+        PostgresQuery({"postgres": pg_cfg})

{echoss_db-2.2.1 → echoss_db-2.3.0}/tests/integration/test_qdrant_integration.py

@@ -3,11 +3,18 @@
 Exercises actual create_collection -> upsert -> get_collection_info -> search(filter)
 -> delete against a live Qdrant in external (precomputed) vector mode.
 Run: pytest -m integration tests/integration/test_qdrant_integration.py
+
+Design Ref: §8.3 — role-based API key scenarios are skipped when config_dev.yaml's
+qdrant section has no api_key/read_only_api_key (this dev instance has no auth enabled).
 """
 from __future__ import annotations
 
 import pytest
 
+from echoss_db.qdrant_vector import QdrantVector
+
+from .conftest import QDRANT_TEST_COLLECTION, load_config_section
+
 pytestmark = pytest.mark.integration
 
 DIM = 8
@@ -64,3 +71,59 @@ def test_search_passthrough_raw_filter(qv):
     raw = qm.Filter(must_not=[qm.FieldCondition(key="doc_type", match=qm.MatchValue(value="b"))])
     hits = qv.search_vector(_vec(0.1), filter_=raw, limit=10)
     assert {h.id for h in hits} == {1}
+
+
+def _role_test_config():
+    q_cfg = dict(load_config_section("qdrant"))
+    if "api_key" not in q_cfg and "read_only_api_key" not in q_cfg:
+        pytest.skip(
+            "qdrant.api_key/read_only_api_key not configured in config_dev.yaml — "
+            "this dev Qdrant instance has no API key auth enabled"
+        )
+    q_cfg["collection"] = QDRANT_TEST_COLLECTION
+    q_cfg["fastembed_model"] = None
+    q_cfg.setdefault("timeout", 30)
+    return q_cfg
+
+
+def test_admin_role_connects_and_can_write():
+    q_cfg = _role_test_config()
+    client = QdrantVector({"qdrant": q_cfg}, role="admin")
+    try:
+        client.delete_collection()
+        client.create_collection(dim=DIM)
+        client.upsert_vectors([{"id": 1, "vector": _vec(0.1)}], wait=True)
+        assert client.get_collection_info()["points_count"] >= 1
+    finally:
+        try:
+            client.delete_collection()
+        except Exception:
+            pass
+        client.close()
+
+
+def test_readonly_role_connects_and_can_search_but_not_write():
+    q_cfg = _role_test_config()
+    if "read_only_api_key" not in q_cfg:
+        pytest.skip("qdrant.read_only_api_key not configured in config_dev.yaml")
+
+    admin = QdrantVector(dict({"qdrant": q_cfg}), role="admin")
+    try:
+        admin.delete_collection()
+        admin.create_collection(dim=DIM)
+        admin.upsert_vectors([{"id": 1, "vector": _vec(0.1)}], wait=True)
+
+        readonly = QdrantVector({"qdrant": q_cfg}, role="readonly")
+        try:
+            hits = readonly.search_vector(_vec(0.1), limit=10)
+            assert {h.id for h in hits} == {1}
+            with pytest.raises(Exception):
+                readonly.create_collection(dim=DIM, collection="echoss_it_readonly_should_fail")
+        finally:
+            readonly.close()
+    finally:
+        try:
+            admin.delete_collection()
+        except Exception:
+            pass
+        admin.close()

echoss_db-2.3.0/tests/unit/test_env_config.py

@@ -0,0 +1,65 @@
+"""Pure function tests for echoss_db.env_config.resolve_credential.
+
+No DB involved — this is a pure function (PLACEHOLDER regex + env var lookup), so unit
+testing it here is not a fake-DB test (see [[no-fake-db-tests]]).
+Design Ref: §8.2.
+"""
+from __future__ import annotations
+
+import pytest
+
+from echoss_db import env_config
+from echoss_db.env_config import resolve_credential
+
+
+@pytest.fixture(autouse=True)
+def reset_dotenv_cache(monkeypatch):
+    # _dotenv_loaded is a process-wide singleton flag; reset per test for isolation.
+    monkeypatch.setattr(env_config, "_dotenv_loaded", False)
+
+
+def test_resolves_from_os_env(monkeypatch):
+    monkeypatch.setenv("MYSQL_PASSWD", "secret")
+    monkeypatch.setattr(env_config, "find_dotenv", lambda usecwd=True: "")
+    assert resolve_credential("${MYSQL_PASSWD}", section="mysql", field="passwd") == "secret"
+
+
+def test_os_env_overrides_dotenv(monkeypatch, tmp_path):
+    dotenv_file = tmp_path / ".env"
+    dotenv_file.write_text("MYSQL_PASSWD=fromdotenv\n")
+    monkeypatch.setattr(env_config, "find_dotenv", lambda usecwd=True: str(dotenv_file))
+    monkeypatch.setenv("MYSQL_PASSWD", "fromos")
+
+    assert resolve_credential("${MYSQL_PASSWD}", section="mysql", field="passwd") == "fromos"
+
+
+def test_loads_from_dotenv_when_os_env_absent(monkeypatch, tmp_path):
+    dotenv_file = tmp_path / ".env"
+    dotenv_file.write_text("MYSQL_PASSWD=fromdotenv\n")
+    monkeypatch.delenv("MYSQL_PASSWD", raising=False)
+    monkeypatch.setattr(env_config, "find_dotenv", lambda usecwd=True: str(dotenv_file))
+
+    assert resolve_credential("${MYSQL_PASSWD}", section="mysql", field="passwd") == "fromdotenv"
+
+
+def test_missing_variable_raises(monkeypatch):
+    monkeypatch.delenv("MYSQL_PASSWD", raising=False)
+    monkeypatch.setattr(env_config, "find_dotenv", lambda usecwd=True: "")
+
+    with pytest.raises(ValueError, match="MYSQL_PASSWD"):
+        resolve_credential("${MYSQL_PASSWD}", section="mysql", field="passwd")
+
+
+def test_plaintext_passthrough():
+    assert resolve_credential("plaintext-password", section="mysql", field="passwd") == "plaintext-password"
+
+
+def test_none_passthrough():
+    assert resolve_credential(None, section="mysql", field="passwd") is None
+
+
+def test_partial_placeholder_not_substituted(monkeypatch):
+    monkeypatch.setenv("VAR", "value")
+    value = "prefix-${VAR}-suffix"
+
+    assert resolve_credential(value, section="mysql", field="passwd") == value

echoss_db-2.3.0/tests/unit/test_qdrant_role.py

@@ -0,0 +1,30 @@
+"""Unit tests for QdrantVector role/api_key validation logic.
+
+These raise before any network connection is attempted (see qdrant_vector.py:__init__),
+so they need no live Qdrant server — not a fake-DB test, just constructor logic.
+Design Ref: §4.2, §8.3 (client-side portion).
+"""
+from __future__ import annotations
+
+import pytest
+
+from echoss_db.qdrant_vector import QdrantVector
+
+
+def test_invalid_role_raises():
+    conn_info = {"qdrant": {"host": "localhost", "port": 6333}}
+    with pytest.raises(ValueError, match="role must be 'admin' or 'readonly'"):
+        QdrantVector(conn_info, role="superadmin")
+
+
+def test_readonly_role_requires_read_only_api_key_field():
+    # api_key(admin)만 있고 read_only_api_key가 없는 상태에서 role="readonly" 요청 (FR-03).
+    conn_info = {"qdrant": {"host": "localhost", "port": 6333, "api_key": "admin-key"}}
+    with pytest.raises(ValueError, match="read_only_api_key"):
+        QdrantVector(conn_info, role="readonly")
+
+
+def test_admin_role_requires_api_key_field_when_only_readonly_configured():
+    conn_info = {"qdrant": {"host": "localhost", "port": 6333, "read_only_api_key": "ro-key"}}
+    with pytest.raises(ValueError, match="qdrant.api_key"):
+        QdrantVector(conn_info, role="admin")