echoss-db 1.2.2__tar.gz → 1.2.3__tar.gz

{echoss_db-1.2.2 → echoss_db-1.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: echoss-db
-Version: 1.2.2
+Version: 1.2.3
 Summary: echoss AI Bigdata Solution - Database Query Package
 Home-page: https://github.com/12cmlab/echoss-query
 Author: ckkim
@@ -8,15 +8,16 @@ Author-email: ckkim@12cm.co.kr
 License: Apache License 2.0
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
-Requires-Python: >3.7
+Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 Requires-Dist: pandas>=1.5.3
 Requires-Dist: pymongo>=4.3.3
 Requires-Dist: sqlalchemy>=2.0.0
 Requires-Dist: PyMySQL>=1.0.2
-Requires-Dist: PyYAML>=6.0
 Requires-Dist: opensearch-py>=2.2.0
 Requires-Dist: echoss-fileformat>=1.1.2
+Requires-Dist: psycopg2-binary<3.0.0,>=2.9.11
+Requires-Dist: qdrant-client[fastembed]<2.0.0,>=1.14.1
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -136,15 +137,12 @@ To install this package, please use Python 3.8 or higher.
     # Ping
     mysql.ping()
 
-    # get connection cursor
-    mysql.conn_cursor(cursorclass=None)
-
     # Close
     # crash process close
     mysql.close()
 
     # debug query : default True
-    mysql.debug_query(False)
+    mysql.query_debug(False)
 ```
 
 ### MongoDB
@@ -196,7 +194,7 @@ To install this package, please use Python 3.8 or higher.
     elastic.search_field(field='FIELD_NAME',value='VALUE') -> list
 
     # INSERT
-    elastic.create(id='ID', body='JSON_BODY')
+    elastic.index(index='INDEX_NAME', body='JSON_BODY', id='ID')
 
     #UPDATE
     elastic.update(id='ID', body='JSON_BODY')
@@ -209,8 +207,8 @@ To install this package, please use Python 3.8 or higher.
     chunk_list = elastic.next_scroll_chunk()
 
     # BULK 
-    success, error_list = bulk_insert("farm_index", doc_list, id_field="farm_id")
-    success, error_list = bulk_upsert("farm_index", doc_list, id_field="farm_id")
+    success, error_list = elastic.bulk_insert("farm_index", doc_list, id_field="farm_id")
+    success, error_list = elastic.bulk_upsert("farm_index", doc_list, id_field="farm_id")
   
     # Ping
     elastic.ping()
@@ -219,6 +217,77 @@ To install this package, please use Python 3.8 or higher.
     elastic.info()
 ```
 
+### Qdrant
+
+---
+
+`QdrantVector`는 기본적으로 FastEmbed 모델을 사용합니다.
+
+Tutorial 실행 순서:
+1. `tutorial/example_postgres_qdrant_ingest.py` (테스트용 충분한 chunk 데이터 생성)
+2. `tutorial/example_qdrant.py` (Qdrant 업서트/검색 확인)
+
+1. `fastembed_model` 미설정
+- 기본값 `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2`가 자동 적용됩니다.
+- 단, 설치된 `qdrant-client/fastembed` 조합에서 미지원일 수 있으므로 아래 메서드로 확인하세요.
+  - 모델 상세(설명 포함) 목록: `list_supported_models_by_class("TextEmbedding")`
+- `vector` 입력 없이 원문 텍스트(`document`/`text`/`content`)를 전달합니다.
+- 명시 메서드 `upsert_texts()` / `search_text()` 사용을 권장합니다.
+- `create_collection()`의 차원은 모델에서 자동 추론합니다.
+
+2. `fastembed_model` 설정
+- 지정한 모델로 동작합니다.
+- `create_collection()`의 차원은 설정 모델 기준으로 자동 추론합니다.
+
+3. `fastembed_model: null`
+- FastEmbed를 비활성화하고 벡터 직접 주입 모드로 동작합니다.
+- 이 경우 `upsert_vectors()` / `search_vector()` 사용을 권장합니다.
+- `create_collection(dim=...)`에서 `dim`은 필수입니다.
+
+Config example:
+
+```yaml
+qdrant:
+  host: <IP addrress or domain>
+  port: 6333
+  scheme: http
+  collection: ai_rag_chunks
+  timeout: 5
+  default_limit: 10
+  fastembed_model: sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
+```
+
+Text-input upsert example (`fastembed_model` enabled):
+
+```python
+points = [
+    {"id": 1, "document": "RAG 시스템 설계 문서", "payload": {"source": "wiki"}},
+    {"id": 2, "text": "Qdrant 검색 예제", "payload": {"source": "blog"}},
+]
+qv.upsert_texts(points, collection="ai_rag_chunks")
+
+hits = qv.search_text(query_text="RAG 아키텍처", limit=5, collection="ai_rag_chunks")
+```
+
+External vector-input mode is documented as a code pattern only (for lightweight tutorial runtime):
+
+```python
+qv = QdrantVector({
+    "qdrant": {
+        "host": "<host>",
+        "port": 6333,
+        "scheme": "http",
+        "collection": "ai_rag_chunks_external",
+        "fastembed_model": None
+    }
+})
+
+points = [{"id": 1, "vector": your_embed_fn("문서"), "payload": {"source": "external"}}]
+qv.create_collection(dim=len(points[0]["vector"]))
+qv.upsert_vectors(points)
+hits = qv.search_vector(vector=your_embed_fn("질의"))
+```
+
 ### Code Quality
 
 When creating new functions, please follow the Google style Python docstrings. See example below:

{echoss_db-1.2.2 → echoss_db-1.2.3}/README.md

@@ -106,15 +106,12 @@ To install this package, please use Python 3.8 or higher.
     # Ping
     mysql.ping()
 
-    # get connection cursor
-    mysql.conn_cursor(cursorclass=None)
-
     # Close
     # crash process close
     mysql.close()
 
     # debug query : default True
-    mysql.debug_query(False)
+    mysql.query_debug(False)
 ```
 
 ### MongoDB
@@ -166,7 +163,7 @@ To install this package, please use Python 3.8 or higher.
     elastic.search_field(field='FIELD_NAME',value='VALUE') -> list
 
     # INSERT
-    elastic.create(id='ID', body='JSON_BODY')
+    elastic.index(index='INDEX_NAME', body='JSON_BODY', id='ID')
 
     #UPDATE
     elastic.update(id='ID', body='JSON_BODY')
@@ -179,8 +176,8 @@ To install this package, please use Python 3.8 or higher.
     chunk_list = elastic.next_scroll_chunk()
 
     # BULK 
-    success, error_list = bulk_insert("farm_index", doc_list, id_field="farm_id")
-    success, error_list = bulk_upsert("farm_index", doc_list, id_field="farm_id")
+    success, error_list = elastic.bulk_insert("farm_index", doc_list, id_field="farm_id")
+    success, error_list = elastic.bulk_upsert("farm_index", doc_list, id_field="farm_id")
   
     # Ping
     elastic.ping()
@@ -189,6 +186,77 @@ To install this package, please use Python 3.8 or higher.
     elastic.info()
 ```
 
+### Qdrant
+
+---
+
+`QdrantVector`는 기본적으로 FastEmbed 모델을 사용합니다.
+
+Tutorial 실행 순서:
+1. `tutorial/example_postgres_qdrant_ingest.py` (테스트용 충분한 chunk 데이터 생성)
+2. `tutorial/example_qdrant.py` (Qdrant 업서트/검색 확인)
+
+1. `fastembed_model` 미설정
+- 기본값 `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2`가 자동 적용됩니다.
+- 단, 설치된 `qdrant-client/fastembed` 조합에서 미지원일 수 있으므로 아래 메서드로 확인하세요.
+  - 모델 상세(설명 포함) 목록: `list_supported_models_by_class("TextEmbedding")`
+- `vector` 입력 없이 원문 텍스트(`document`/`text`/`content`)를 전달합니다.
+- 명시 메서드 `upsert_texts()` / `search_text()` 사용을 권장합니다.
+- `create_collection()`의 차원은 모델에서 자동 추론합니다.
+
+2. `fastembed_model` 설정
+- 지정한 모델로 동작합니다.
+- `create_collection()`의 차원은 설정 모델 기준으로 자동 추론합니다.
+
+3. `fastembed_model: null`
+- FastEmbed를 비활성화하고 벡터 직접 주입 모드로 동작합니다.
+- 이 경우 `upsert_vectors()` / `search_vector()` 사용을 권장합니다.
+- `create_collection(dim=...)`에서 `dim`은 필수입니다.
+
+Config example:
+
+```yaml
+qdrant:
+  host: <IP addrress or domain>
+  port: 6333
+  scheme: http
+  collection: ai_rag_chunks
+  timeout: 5
+  default_limit: 10
+  fastembed_model: sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
+```
+
+Text-input upsert example (`fastembed_model` enabled):
+
+```python
+points = [
+    {"id": 1, "document": "RAG 시스템 설계 문서", "payload": {"source": "wiki"}},
+    {"id": 2, "text": "Qdrant 검색 예제", "payload": {"source": "blog"}},
+]
+qv.upsert_texts(points, collection="ai_rag_chunks")
+
+hits = qv.search_text(query_text="RAG 아키텍처", limit=5, collection="ai_rag_chunks")
+```
+
+External vector-input mode is documented as a code pattern only (for lightweight tutorial runtime):
+
+```python
+qv = QdrantVector({
+    "qdrant": {
+        "host": "<host>",
+        "port": 6333,
+        "scheme": "http",
+        "collection": "ai_rag_chunks_external",
+        "fastembed_model": None
+    }
+})
+
+points = [{"id": 1, "vector": your_embed_fn("문서"), "payload": {"source": "external"}}]
+qv.create_collection(dim=len(points[0]["vector"]))
+qv.upsert_vectors(points)
+hits = qv.search_vector(vector=your_embed_fn("질의"))
+```
+
 ### Code Quality
 
 When creating new functions, please follow the Google style Python docstrings. See example below:

{echoss_db-1.2.2 → echoss_db-1.2.3}/echoss_db/__init__.py

@@ -1,3 +1,5 @@
 from .mysql_query import MysqlQuery
 from .mongo_query import MongoQuery
 from .elastic_search import ElasticSearch
+from .postgres_query import PostgresQuery
+from .qdrant_vector import QdrantVector

echoss_db-1.2.3/echoss_db/postgres_query.py

@@ -0,0 +1,419 @@
+from __future__ import annotations
+from functools import wraps
+import pandas as pd
+import time
+from typing import Any, Optional, Union
+
+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
+
+logger = get_logger("echoss_db")
+
+
+# --------------------------------------------------------------------------------------
+# 공통 Decorator (mysql_query.py와 동일)
+# --------------------------------------------------------------------------------------
+def log_execution_time(func):
+    @wraps(func)
+    def wrapper(self, *args, **kwargs):
+        if not getattr(self, 'use_query_debug', False):
+            return func(self, *args, **kwargs)
+
+        start_time = time.time()
+        try:
+            return func(self, *args, **kwargs)
+        finally:
+            elapsed = time.time() - start_time
+            logger.debug(f"{func.__name__}() executed in {elapsed:.3f} seconds")
+    return wrapper
+
+
+def _safe_log_param(p):
+    return '<binary>' if isinstance(p, (bytes, bytearray)) else repr(p)
+
+
+def parse_query(keyword):
+    def decorator(func):
+        @wraps(func)
+        def wrapper(self, query_str: str, params=None, *args, **kwargs):
+            if keyword not in query_str.upper():
+                raise ValueError(f"Input query does not include '{keyword}'")
+
+            query_str = query_str.strip().rstrip(";").rstrip()
+
+            if getattr(self, 'use_query_debug', False):
+                if params and isinstance(params, list):
+                    rows = len(params)
+                    if rows > 0:
+                        first_param = params[0]
+                        if isinstance(first_param, (list, tuple)):
+                            safe_example = [_safe_log_param(p) for p in first_param]
+                        elif isinstance(first_param, dict):
+                            safe_example = {k: _safe_log_param(v) for k, v in first_param.items()}
+                        else:
+                            safe_example = first_param
+                        logger.debug(
+                            f'postgres_query.{func.__name__}() bulk example """{query_str}""" '
+                            f'with {safe_example} for {rows} rows'
+                        )
+                    else:
+                        logger.warning(f'postgres_query.{func.__name__}() bulk query """{query_str}""" with empty params')
+                else:
+                    if isinstance(params, tuple):
+                        safe_example = [_safe_log_param(p) for p in params]
+                    elif isinstance(params, dict):
+                        safe_example = {k: _safe_log_param(v) for k, v in params.items()}
+                    else:
+                        safe_example = params
+                    logger.debug(f'postgres_query.{func.__name__}() parsed """{query_str}""" with {safe_example}')
+
+            return func(self, query_str, params, *args, **kwargs)
+        return wrapper
+    return decorator
+
+
+class PostgresQuery:
+    """
+    Postgres SQLAlchemy 2.x 기반 래퍼.
+    MysqlQuery와 동일한 메서드/반환 타입을 최대한 유지.
+    - exec_driver_sql 로 %s 파라미터 스타일(=psycopg2) 호환
+    - :name 스타일도 지원(use_percent_param=False)
+    """
+    engine: Optional[Engine] = None
+    empty_dataframe = pd.DataFrame()
+    use_query_debug: bool = True
+    use_percent_param: bool = True
+
+    def __init__(self, conn_info: Union[str, dict], compress=False,
+                 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)
+        elif not isinstance(conn_info, dict):
+            raise TypeError("PostgresQuery support type 'str' and 'dict'")
+
+        self.pool_size = pool_size
+        self.pool_timeout = pool_timeout
+        self.pool_recycle = pool_recycle if pool_recycle is not None else pool_timeout * 60
+        self.use_percent_param = use_percent_param
+
+        required_keys = ['user', 'passwd', 'host', 'db']
+        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.host = p['host']
+            self.port = p.get('port', 5432)
+            self.db = p['db']
+            self.application_name = p.get('application_name', 'echoss_db')
+            # 스키마/서치패스가 필요하면 옵션으로 받기
+            self.schema = p.get("schema")  # 예: ai_rag
+            self.options = p.get("options")
+            if self.schema:
+                sp = f"-c search_path={self.schema},public"
+                if not self.options:
+                    self.options = sp
+                else:
+                    # 이미 options가 있으면, search_path가 없을 때만 추가
+                    if "search_path" not in self.options:
+                        self.options = f"{self.options} {sp}"
+            self.sslmode = p.get('sslmode')  # 필요시 "require"
+        else:
+            logger.error(f'[Postgres] config info not exist or required keys missing {required_keys}')
+            raise ValueError("invalid conn_info")
+
+        self._connect_db()
+
+    def __str__(self):
+        if self.engine:
+            return f"Postgres connected(host={self.host}, port={self.port}, db={self.db})"
+        return f"Postgres disconnected(host={self.host}, port={self.port}, db={self.db})"
+
+    def query_debug(self, use_query_debug=False):
+        if isinstance(use_query_debug, bool):
+            self.use_query_debug = use_query_debug
+        logger.debug(f"use_query_debug = {self.use_query_debug}")
+
+    def ping(self) -> bool:
+        try:
+            with self.engine.connect() as conn:
+                self._execute_query(conn, "SELECT 1")
+            logger.debug(f"[Postgres] database {self.__str__()} connection success")
+            return True
+        except SQLAlchemyError as e:
+            logger.error(f"[Postgres] database {self.__str__()} connection fail: {e}")
+            return False
+
+    def _connect_db(self):
+        from urllib.parse import quote_plus
+        escaped_passwd = quote_plus(str(self.passwd))
+        url = f"postgresql+psycopg2://{self.user}:{escaped_passwd}@{self.host}:{self.port}/{self.db}"
+
+        connect_args = {
+            "application_name": self.application_name,
+        }
+        if self.options:
+            connect_args["options"] = self.options
+        if self.sslmode:
+            connect_args["sslmode"] = self.sslmode
+
+        try:
+            self.engine = create_engine(
+                url,
+                echo=False,
+                pool_size=self.pool_size,
+                max_overflow=self.pool_size * 2,
+                pool_timeout=self.pool_timeout,
+                pool_recycle=self.pool_recycle,
+                pool_pre_ping=True,
+                connect_args=connect_args,
+            )
+            logger.info("[Postgres] DB connected.")
+        except SQLAlchemyError as e:
+            logger.error(f"[Postgres] DB connection failed. {self.__str__()} : {e}")
+            raise
+
+    @log_execution_time
+    def _execute_query(self, conn: Connection, query_str: str, params=None) -> Result[Any]:
+        if self.use_percent_param:
+            # psycopg2는 %s 스타일이 기본이라 exec_driver_sql과 궁합이 좋음
+            if params is None or isinstance(params, (list, tuple)):
+                return conn.exec_driver_sql(query_str, params)
+            return conn.exec_driver_sql(query_str, (params,))
+        else:
+            if params is not None and not isinstance(params, dict):
+                raise TypeError("When use_percent_param=False, params must be a dict for :name binding.")
+            return conn.execute(text(query_str), parameters=params)
+
+    @log_execution_time
+    def _fetch_one(self, rs: Result):
+        return rs.fetchone()
+
+    @log_execution_time
+    def _fetch_all(self, rs: Result):
+        return rs.fetchall()
+
+    @log_execution_time
+    def _fetch_many(self, rs: Result, fetch_size):
+        return rs.fetchmany(size=fetch_size)
+
+    # -------------------------------------------------------------------------
+    # Meta
+    # -------------------------------------------------------------------------
+    def databases(self) -> pd.DataFrame:
+        try:
+            with self.engine.connect() as conn:
+                return pd.read_sql(
+                    "SELECT datname AS database FROM pg_database WHERE datistemplate = false ORDER BY datname",
+                    conn
+                )
+        except SQLAlchemyError as e:
+            logger.error(f"[Postgres] databases Exception: {e}")
+            return self.empty_dataframe
+
+    def tables(self) -> pd.DataFrame:
+        try:
+            with self.engine.connect() as conn:
+                return pd.read_sql(
+                    """
+                    SELECT table_schema, table_name
+                    FROM information_schema.tables
+                    WHERE table_type='BASE TABLE'
+                      AND table_schema NOT IN ('pg_catalog','information_schema')
+                    ORDER BY table_schema, table_name
+                    """,
+                    conn
+                )
+        except SQLAlchemyError as e:
+            logger.error(f"[Postgres] tables Exception: {e}")
+            return self.empty_dataframe
+
+    def current_schema(self) -> str:
+        with self.engine.connect() as conn:
+            rs = conn.exec_driver_sql("SELECT current_schema()")
+            return rs.scalar_one()
+
+    # -------------------------------------------------------------------------
+    # DDL
+    # -------------------------------------------------------------------------
+    @parse_query('CREATE')
+    def create(self, query_str: str, params=None) -> None:
+        try:
+            with self.engine.begin() as conn:
+                self._execute_query(conn, query_str, params)
+        except SQLAlchemyError as e:
+            logger.debug(f"[Postgres] Create Exception : {e}")
+
+    @parse_query('DROP')
+    def drop(self, query_str: str, params=None) -> None:
+        try:
+            with self.engine.begin() as conn:
+                self._execute_query(conn, query_str, params)
+        except SQLAlchemyError as e:
+            logger.debug(f"[Postgres] Drop Exception : {e}")
+
+    @parse_query('TRUNCATE')
+    def truncate(self, query_str: str, params=None) -> None:
+        try:
+            with self.engine.begin() as conn:
+                self._execute_query(conn, query_str, params)
+        except SQLAlchemyError as e:
+            logger.debug(f"[Postgres] Truncate Exception : {e}")
+
+    @parse_query('ALTER')
+    def alter(self, query_str: str, params=None) -> None:
+        try:
+            with self.engine.begin() as conn:
+                self._execute_query(conn, query_str, params)
+        except SQLAlchemyError as e:
+            logger.debug(f"[Postgres] Alter Exception : {e}")
+
+    # -------------------------------------------------------------------------
+    # SELECT
+    # -------------------------------------------------------------------------
+    @parse_query('SELECT')
+    def select_one(self, query_str: str, params=None) -> dict:
+        try:
+            with self.engine.connect() as conn:
+                rs = self._execute_query(conn, query_str, params)
+                row = self._fetch_one(rs)
+                return row._asdict() if row else {}
+        except SQLAlchemyError as e:
+            logger.debug(f"[Postgres] SELECT Exception: {e}")
+            return {}
+
+    @parse_query('SELECT')
+    def select_list(self, query_str: str, params=None) -> list:
+        try:
+            with self.engine.connect() as conn:
+                rs = self._execute_query(conn, query_str, params)
+                rows = self._fetch_all(rs)
+                if not rows:
+                    return []
+                return [r._asdict() for r in rows] if isinstance(rows, list) else [rows._asdict()]
+        except SQLAlchemyError as e:
+            logger.debug(f"[Postgres] SELECT_LIST Exception : {e}")
+            return []
+
+    @parse_query('SELECT')
+    def select(self, query_str: str, params=None) -> pd.DataFrame:
+        try:
+            with self.engine.connect() as conn:
+                rs = self._execute_query(conn, query_str, params)
+                rows = self._fetch_all(rs)
+                if rows:
+                    columns = list(rs.keys())
+                    return pd.DataFrame(rows, columns=columns)
+                return self.empty_dataframe
+        except SQLAlchemyError as e:
+            logger.error(f"[Postgres] SELECT Exception : {e}")
+            return self.empty_dataframe
+
+    @parse_query('SELECT')
+    @log_execution_time
+    def faster_select(self, query_str: str, params=None, fetch_size=1000) -> pd.DataFrame:
+        total_size = 0
+        results = []
+        try:
+            with self.engine.connect() as conn:
+                conn = conn.execution_options(stream_results=True)
+                rs = self._execute_query(conn, query_str, params)
+                columns = list(rs.keys())
+
+                while True:
+                    rows = self._fetch_many(rs, fetch_size)
+                    if not rows:
+                        break
+                    total_size += len(rows)
+                    results.extend(rows)
+                    if self.use_query_debug:
+                        logger.debug(f"fetch {len(rows)} rows, total fetched size = {total_size}")
+
+                return pd.DataFrame(results, columns=columns) if results else self.empty_dataframe
+        except SQLAlchemyError as e:
+            logger.debug(f"[Postgres] FASTER_SELECT Exception : {e}")
+            self.close()
+            return self.empty_dataframe
+
+    @parse_query('SELECT')
+    def faster_select_generator(self, query_str: str, params=None, fetch_size=1000):
+        try:
+            with self.engine.connect() as conn:
+                conn = conn.execution_options(stream_results=True)
+                rs = self._execute_query(conn, query_str, params)
+                maps = rs.mappings()
+
+                while True:
+                    part = maps.fetchmany(fetch_size)
+                    if not part:
+                        break
+                    rows = [dict(r) for r in part]
+                    if self.use_query_debug:
+                        logger.debug(f"fetch {len(rows)} rows chunk")
+                    yield rows
+        except SQLAlchemyError as e:
+            logger.debug(f"[Postgres] faster_select_generator Exception : {e}")
+            return
+
+    # -------------------------------------------------------------------------
+    # INSERT/UPDATE/DELETE
+    # -------------------------------------------------------------------------
+    @parse_query('INSERT')
+    def insert(self, query_str: str, params=None, return_lastrowid=False) -> int:
+        """
+        Postgres에서 lastrowid는 일반적으로 RETURNING을 써야 안정적입니다.
+        - 기존 호환 위해 return_lastrowid True면:
+          1) 쿼리에 RETURNING이 있으면 scalar 반환
+          2) 없으면 rowcount 반환
+        """
+        try:
+            with self.engine.begin() as conn:
+                rs = self._execute_query(conn, query_str, params)
+
+                if return_lastrowid:
+                    # RETURNING 이 있을 때만 의미 있음
+                    try:
+                        v = rs.scalar_one()
+                        return int(v)
+                    except Exception:
+                        return int(rs.rowcount or 0)
+                return int(rs.rowcount or 0)
+        except SQLAlchemyError as e:
+            logger.error(f"[Postgres] INSERT Exception : {e}")
+            return 0
+
+    @parse_query('UPDATE')
+    def update(self, query_str: str, params=None) -> int:
+        try:
+            with self.engine.begin() as conn:
+                rs = self._execute_query(conn, query_str, params)
+                return int(rs.rowcount or 0)
+        except SQLAlchemyError as e:
+            logger.error(f"[Postgres] UPDATE Exception : {e}")
+            return 0
+
+    @parse_query('DELETE')
+    def delete(self, query_str: str, params=None) -> int:
+        try:
+            with self.engine.begin() as conn:
+                rs = self._execute_query(conn, query_str, params)
+                return int(rs.rowcount or 0)
+        except SQLAlchemyError as e:
+            logger.debug(f"[Postgres] DELETE Exception : {e}")
+            return 0
+
+    def close(self, close_log=True):
+        if self.engine:
+            self.engine.dispose()
+            self.engine = None
+            if close_log:
+                logger.debug("[Postgres] DB Connection closed.")
+
+    def __del__(self):
+        try:
+            self.close(close_log=False)
+        except Exception:
+            pass