sqlServerConnector 0.1.5__tar.gz → 0.1.6__tar.gz

{sqlserverconnector-0.1.5 → sqlserverconnector-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlServerConnector
-Version: 0.1.5
+Version: 0.1.6
 Summary: A custom SQL Server Connector for ETL processes with Pandas
 Author-email: Nguyen Minh Son <nguyen.minhson1511@gmail.com>
 Project-URL: Homepage, https://github.com/johnnyb1509/sqlServerConnector
@@ -20,6 +20,9 @@ Requires-Dist: jupyterlab
 # SQL Server Connector
 
 Thư viện kết nối SQL Server chuyên dụng cho các tác vụ ETL, được tối ưu hóa cho **Pandas**, hỗ trợ **Tiếng Việt (Unicode)** và **Upsert (Merge)** hiệu năng cao.
+## Update 0.1.6
+> Sửa lỗi nhỏ liên quan đến việc upsert với các bảng có cột chứa Tiếng việt
+
 
 ## 🚀 Tính năng nổi bật
 

{sqlserverconnector-0.1.5 → sqlserverconnector-0.1.6}/README.md

@@ -1,6 +1,9 @@
 # SQL Server Connector
 
 Thư viện kết nối SQL Server chuyên dụng cho các tác vụ ETL, được tối ưu hóa cho **Pandas**, hỗ trợ **Tiếng Việt (Unicode)** và **Upsert (Merge)** hiệu năng cao.
+## Update 0.1.6
+> Sửa lỗi nhỏ liên quan đến việc upsert với các bảng có cột chứa Tiếng việt
+
 
 ## 🚀 Tính năng nổi bật
 

{sqlserverconnector-0.1.5 → sqlserverconnector-0.1.6}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sqlServerConnector"
-version = "0.1.5"
+version = "0.1.6"
 description = "A custom SQL Server Connector for ETL processes with Pandas"
 readme = "README.md"
 requires-python = ">=3.8"

sqlserverconnector-0.1.6/src/connector.py

@@ -0,0 +1,192 @@
+import os
+import pandas as pd
+import numpy as np
+import uuid
+import sqlalchemy
+from typing import List, Optional, Dict, Union, Any
+from loguru import logger
+from sqlalchemy import create_engine, text, URL, inspect
+from sqlalchemy.types import NVARCHAR, FLOAT, INTEGER, DATE, DATETIME, BIGINT
+from sqlalchemy.exc import SQLAlchemyError
+
+class SQLServerConnector:
+    """
+    Trình kết nối SQL Server tối ưu cho ETL (Extract-Transform-Load).
+    
+    Tính năng:
+    - Hỗ trợ Upsert (Merge) hiệu năng cao qua bảng tạm.
+    - Hỗ trợ Unicode (Tiếng Việt) tự động bằng NVARCHAR.
+    - Tự động quản lý Schema và Primary Key.
+    """
+
+    def __init__(self, server: str, database: str, username: str, password: str, driver: str = 'ODBC Driver 17 for SQL Server'):
+        self.server = server
+        self.database = database
+        self.username = username
+        self.password = password
+        self.driver = driver
+        
+        # Tạo URL kết nối
+        self.connection_url = URL.create(
+            "mssql+pyodbc",
+            query={
+                "odbc_connect": (
+                    f"DRIVER={self.driver};"
+                    f"SERVER={self.server};"
+                    f"DATABASE={self.database};"
+                    f"UID={self.username};"
+                    f"PWD={self.password};"
+                    "Encrypt=no;TrustServerCertificate=yes;" # Cấu hình SSL linh hoạt
+                )
+            }
+        )
+        
+        # Tạo Engine với fast_executemany=True để tăng tốc độ Insert/Upsert
+        self.engine = create_engine(
+            self.connection_url,
+            fast_executemany=True, # QUAN TRỌNG: Tăng tốc độ ghi gấp nhiều lần
+            pool_pre_ping=True     # Tự động kết nối lại nếu mất kết nối
+        )
+
+    def get_data(self, query: str, params: Optional[Dict] = None, chunksize: Optional[int] = None) -> Union[pd.DataFrame, Any]:
+        """
+        Thực thi câu lệnh SELECT và trả về DataFrame.
+        """
+        try:
+            with self.engine.connect() as conn:
+                # Dùng text() để đảm bảo tương thích SQLAlchemy 2.0
+                sql_query = text(query)
+                return pd.read_sql(sql_query, conn, params=params, chunksize=chunksize)
+        except Exception as e:
+            logger.error(f"Failed to retrieve data: {e}")
+            raise
+
+    def execute_query(self, query: str, params: Optional[Dict] = None):
+        """Thực thi câu lệnh không trả về dữ liệu (UPDATE, DELETE, SP...)."""
+        try:
+            with self.engine.begin() as conn: # Tự động commit
+                conn.execute(text(query), params or {})
+        except Exception as e:
+            logger.error(f"Failed to execute query: {e}")
+            raise
+
+    def _generate_dtype_mapping(self, df: pd.DataFrame) -> Dict:
+        """
+        Tự động tạo mapping kiểu dữ liệu cho SQL.
+        QUAN TRỌNG: Map tất cả cột string/object sang NVARCHAR để hỗ trợ Tiếng Việt.
+        """
+        dtype_map = {}
+        for col in df.columns:
+            # Nếu là chuỗi -> NVARCHAR (hỗ trợ Unicode)
+            if df[col].dtype == 'object' or pd.api.types.is_string_dtype(df[col]):
+                # Tính độ dài max thực tế để tối ưu, hoặc để None (NVARCHAR(MAX))
+                max_len = df[col].astype(str).map(len).max()
+                if pd.isna(max_len) or max_len == 0:
+                    length = 255
+                else:
+                    length = int(max_len * 1.5) + 50 # Buffer thêm
+                    if length > 4000: length = None # NVARCHAR(MAX)
+                
+                dtype_map[col] = NVARCHAR(length=length)
+            
+            # Nếu là ngày tháng
+            elif pd.api.types.is_datetime64_any_dtype(df[col]):
+                dtype_map[col] = DATETIME()
+            
+            # Số thực
+            elif pd.api.types.is_float_dtype(df[col]):
+                dtype_map[col] = FLOAT()
+                
+            # Số nguyên
+            elif pd.api.types.is_integer_dtype(df[col]):
+                dtype_map[col] = BIGINT()
+                
+        return dtype_map
+
+    def upsert_data(self, df: pd.DataFrame, table_name: str, pk_cols: List[str]):
+        """
+        Thực hiện Upsert (Insert hoặc Update) dữ liệu vào bảng SQL Server.
+        Sử dụng cơ chế Bảng Tạm (Staging Table) + MERGE Statement.
+        """
+        if df.empty:
+            logger.warning(f"DataFrame for table {table_name} is empty. Skipping upsert.")
+            return
+
+        # 1. Chuẩn bị tên bảng tạm
+        staging_table = f"##Staging_{uuid.uuid4().hex[:8]}"
+        
+        # 2. Tạo mapping kiểu dữ liệu (Fix lỗi Unicode)
+        dtype_mapping = self._generate_dtype_mapping(df)
+
+        try:
+            with self.engine.begin() as conn:
+                # A. Đẩy dữ liệu vào bảng tạm (Staging)
+                # fast_executemany=True ở engine sẽ làm bước này cực nhanh
+                df.to_sql(
+                    name=staging_table,
+                    con=conn,
+                    if_exists='replace',
+                    index=False,
+                    dtype=dtype_mapping # Ép kiểu NVARCHAR tại đây
+                )
+
+                # B. Kiểm tra bảng đích có tồn tại không
+                inspector = inspect(conn)
+                if not inspector.has_table(table_name):
+                    logger.info(f"Table {table_name} does not exist. Creating from staging...")
+                    # Tạo bảng chính từ bảng tạm (Copy cấu trúc và dữ liệu)
+                    # Lưu ý: SELECT INTO sẽ tạo bảng mới
+                    create_sql = f"SELECT * INTO {table_name} FROM {staging_table}"
+                    conn.execute(text(create_sql))
+                    
+                    # Tạo Primary Key cho bảng mới
+                    if pk_cols:
+                        pk_str = ", ".join([f"[{c}]" for c in pk_cols])
+                        try:
+                            alter_pk = f"ALTER TABLE {table_name} ADD CONSTRAINT PK_{table_name}_{uuid.uuid4().hex[:4]} PRIMARY KEY ({pk_str})"
+                            conn.execute(text(alter_pk))
+                        except Exception as ex_pk:
+                            logger.warning(f"Could not create PK: {ex_pk}")
+                else:
+                    # C. Thực hiện MERGE (Upsert)
+                    # Lấy danh sách cột
+                    cols = [c for c in df.columns]
+                    
+                    # 1. Điều kiện ON (Primary Keys)
+                    on_clause = " AND ".join([f"Target.[{col}] = Source.[{col}]" for col in pk_cols])
+                    
+                    # 2. Điều kiện UPDATE (Các cột không phải PK)
+                    update_cols = [col for col in cols if col not in pk_cols]
+                    if update_cols:
+                        update_clause = ", ".join([f"Target.[{col}] = Source.[{col}]" for col in update_cols])
+                        matched_action = f"WHEN MATCHED THEN UPDATE SET {update_clause}"
+                    else:
+                        # Trường hợp bảng chỉ có PK (ít gặp), không làm gì khi match
+                        matched_action = ""
+
+                    # 3. Điều kiện INSERT (Tất cả cột)
+                    insert_cols_str = ", ".join([f"[{col}]" for col in cols])
+                    insert_vals_str = ", ".join([f"Source.[{col}]" for col in cols])
+
+                    merge_sql = f"""
+                    MERGE [{table_name}] AS Target
+                    USING {staging_table} AS Source
+                    ON {on_clause}
+                    {matched_action}
+                    WHEN NOT MATCHED BY TARGET THEN
+                        INSERT ({insert_cols_str}) 
+                        VALUES ({insert_vals_str});
+                    """
+                    
+                    conn.execute(text(merge_sql))
+                    logger.info(f"Upserted {len(df)} rows into {table_name}.")
+
+                # D. Xóa bảng tạm (Optional, vì temp table ## tự hủy khi đóng conn, nhưng xóa cho sạch)
+                conn.execute(text(f"DROP TABLE IF EXISTS {staging_table}"))
+                
+        except Exception as e:
+            logger.error(f"Upsert failed for {table_name}: {e}")
+            raise
+
+    def dispose(self):
+        self.engine.dispose()

{sqlserverconnector-0.1.5 → sqlserverconnector-0.1.6}/src/sqlServerConnector.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlServerConnector
-Version: 0.1.5
+Version: 0.1.6
 Summary: A custom SQL Server Connector for ETL processes with Pandas
 Author-email: Nguyen Minh Son <nguyen.minhson1511@gmail.com>
 Project-URL: Homepage, https://github.com/johnnyb1509/sqlServerConnector
@@ -20,6 +20,9 @@ Requires-Dist: jupyterlab
 # SQL Server Connector
 
 Thư viện kết nối SQL Server chuyên dụng cho các tác vụ ETL, được tối ưu hóa cho **Pandas**, hỗ trợ **Tiếng Việt (Unicode)** và **Upsert (Merge)** hiệu năng cao.
+## Update 0.1.6
+> Sửa lỗi nhỏ liên quan đến việc upsert với các bảng có cột chứa Tiếng việt
+
 
 ## 🚀 Tính năng nổi bật
 

sqlserverconnector-0.1.5/src/connector.py

@@ -1,222 +0,0 @@
-import os
-import numpy as np
-import pandas as pd
-import uuid
-from typing import List, Optional, Dict, Union, Any
-from loguru import logger
-from sqlalchemy import create_engine, inspect, text, URL
-from sqlalchemy.types import NVARCHAR, FLOAT, INTEGER, DATE, DATETIME, BIGINT
-from sqlalchemy.exc import SQLAlchemyError
-
-class SQLServerConnector:
-    """
-    A robust, SQLAlchemy 2.0 compliant connector for SQL Server designed for ETL processes.
-    
-    Features:
-    - High-performance Upserts (Merge) using Unique Staging Tables.
-    - Advanced Conflict Resolution: 'sum' (for finance) or 'last' (for metadata).
-    - Automatic Schema Evolution and Primary Key management.
-    - Unicode/Vietnamese support (NVARCHAR + UTF8).
-    """
-
-    def __init__(self, server: str, database: str, username: str, password: str, driver: str = 'ODBC Driver 17 for SQL Server'):
-        self.server = server
-        self.database = database
-        self.username = username
-        self.password = password
-        self.driver = driver
-        
-        self.connection_url = URL.create(
-            "mssql+pyodbc",
-            query={
-                "odbc_connect": (
-                    f"DRIVER={self.driver};"
-                    f"SERVER={self.server};"
-                    f"DATABASE={self.database};"
-                    f"UID={self.username};"
-                    f"PWD={self.password};"
-                    "Charsets=UTF-8;"
-                ),
-                "fast_executemany": "True" 
-            }
-        )
-        
-        self.engine = create_engine(
-            self.connection_url, 
-            pool_pre_ping=True,  
-            pool_size=20, 
-            max_overflow=10
-        )
-        
-    def dispose(self):
-        self.engine.dispose()
-        logger.info("Database engine disposed.")
-
-    # ========================================================
-    # SCHEMA HELPERS
-    # ========================================================
-
-    def check_table_exists(self, table_name: str) -> bool:
-        return inspect(self.engine).has_table(table_name)
-
-    def get_columns_info(self, table_name: str) -> Dict[str, str]:
-        inspector = inspect(self.engine)
-        return {col['name']: str(col['type']) for col in inspector.get_columns(table_name)}
-
-    # ========================================================
-    # CORE ETL METHODS
-    # ========================================================
-
-    def upsert_data(self, df: pd.DataFrame, target_table: str, primary_key: str = None, 
-                    match_columns: Optional[List[str]] = None, auto_evolve_schema: bool = True,
-                    conflict_strategy: str = 'sum'):
-        if df.empty: return
-
-        join_keys = match_columns if match_columns else ([primary_key] if primary_key else [])
-        
-        # 1. Sanitize & lọc lấy các cột cần thiết
-        # Chỉ giữ lại join_keys và các cột có dữ liệu để tránh "phân mảnh" dữ liệu khi gộp
-        df_clean = self._sanitize_dataframe(df, exclude_cols=join_keys)
-        
-        # 2. Xử lý trùng lặp triệt để
-        initial_len = len(df_clean)
-        if conflict_strategy == 'sum':
-            # Xác định cột số để cộng dồn
-            num_cols = df_clean.select_dtypes(include=[np.number]).columns.tolist()
-            num_cols = [c for c in num_cols if c not in join_keys]
-            
-            # Chỉ gộp trên các cột số, các cột text khác key sẽ bị loại bỏ hoặc lấy dòng đầu
-            # Điều này đảm bảo kết quả trả về CHỈ CÓ 1 DÒNG cho mỗi cặp Key
-            agg_logic = {col: 'sum' for col in num_cols}
-            
-            # Đối với các cột không phải số và không phải key, chúng ta lấy dòng đầu tiên
-            other_cols = [c for c in df_clean.columns if c not in join_keys and c not in num_cols]
-            for c in other_cols:
-                agg_logic[c] = 'first'
-                
-            df_clean = df_clean.groupby(join_keys, as_index=False).agg(agg_logic)
-        else:
-            df_clean = df_clean.drop_duplicates(subset=join_keys, keep='last')
-
-        if len(df_clean) < initial_len:
-            logger.info(f"Conflict Resolution ({conflict_strategy}): Combined {initial_len} -> {len(df_clean)} rows.")
-
-        # 3. Schema Management
-        if not self.check_table_exists(target_table):
-            self._create_table_from_df(df_clean, target_table, primary_key)
-        elif auto_evolve_schema:
-            self._sync_columns(df_clean, target_table)
-
-        # 4. Execute Merge
-        self._execute_merge_upsert(df_clean, target_table, join_keys)
-
-    def _execute_merge_upsert(self, df: pd.DataFrame, target_table: str, join_keys: List[str]):
-        # Use a unique staging name to support parallel tasks
-        unique_id = str(uuid.uuid4()).replace('-', '')[:10]
-        staging_table = f"##stg_{unique_id}_{target_table[:20]}"
-        
-        with self.engine.begin() as conn: 
-            try:
-                # Explicit mapping for Unicode
-                dtype_map = {col: NVARCHAR(None) for col in df.columns if df[col].dtype == 'object'}
-                df.to_sql(staging_table, conn, if_exists='replace', index=False, dtype=dtype_map)
-                
-                source_cols = list(df.columns)
-                on_clause = " AND ".join([f"Target.[{k}] = Source.[{k}]" for k in join_keys])
-                update_stmts = [f"Target.[{col}] = Source.[{col}]" for col in source_cols if col not in join_keys]
-                
-                insert_cols = ", ".join([f"[{col}]" for col in source_cols])
-                insert_vals = ", ".join([f"Source.[{col}]" for col in source_cols])
-                
-                sql = f"""
-                MERGE [{target_table}] AS Target USING [{staging_table}] AS Source
-                ON ({on_clause})
-                {f"WHEN MATCHED THEN UPDATE SET {', '.join(update_stmts)}" if update_stmts else ""}
-                WHEN NOT MATCHED BY TARGET THEN INSERT ({insert_cols}) VALUES ({insert_vals});
-                """
-                conn.execute(text(sql))
-                conn.execute(text(f"DROP TABLE [{staging_table}]"))
-                logger.success(f"Successfully upserted {len(df)} rows to {target_table}.")
-            except Exception as e:
-                logger.error(f"Merge execution failed for {target_table}: {e}")
-                raise
-
-    # ========================================================
-    # UTILS: CLEANING & SCHEMA
-    # ========================================================
-
-    def _sanitize_dataframe(self, df: pd.DataFrame, exclude_cols: List[str]) -> pd.DataFrame:
-        df = df.copy()
-        # Clean Dates
-        for col in df.select_dtypes(include=['datetime']).columns:
-            df[col] = df[col].replace({pd.NaT: None})
-        # Clean NaN/None
-        df = df.replace({np.nan: None})
-        df = df.where(pd.notnull(df), None)
-        return df
-
-    def _create_table_from_df(self, df: pd.DataFrame, table_name: str, primary_key: Optional[str]):
-        dtype_map = {col: NVARCHAR(None) for col in df.columns if df[col].dtype == 'object'}
-        df.to_sql(table_name, self.engine, index=False, dtype=dtype_map)
-        if primary_key and primary_key in df.columns:
-            self.set_primary_key(table_name, primary_key, df[primary_key].dtype)
-
-    def set_primary_key(self, table_name: str, column_name: str, source_dtype):
-        sql_type = "NVARCHAR(450)" if pd.api.types.is_string_dtype(source_dtype) else "BIGINT"
-        with self.engine.connect() as conn:
-            with conn.begin():
-                conn.execute(text(f"ALTER TABLE [{table_name}] ALTER COLUMN [{column_name}] {sql_type} NOT NULL"))
-                conn.execute(text(f"ALTER TABLE [{table_name}] ADD PRIMARY KEY ([{column_name}])"))
-
-    def _sync_columns(self, df: pd.DataFrame, table_name: str):
-        db_cols = {k.lower() for k in self.get_columns_info(table_name).keys()}
-        new_cols = [c for c in df.columns if c.lower() not in db_cols]
-        
-        if new_cols:
-            with self.engine.connect() as conn:
-                for col in new_cols:
-                    sql_type = "NVARCHAR(MAX)" if df[col].dtype == 'object' else "FLOAT"
-                    conn.execute(text(f"ALTER TABLE [{table_name}] ADD [{col}] {sql_type} NULL"))
-                conn.commit()
-
-    # ========================================================
-    # DATA RETRIEVAL METHODS
-    # ========================================================
-    def get_data(self,  query: str, params: Optional[Dict[str, Any]] = None, chunksize: Optional[int] = None) -> Union[pd.DataFrame, Any]:
-        """
-        Executes a SQL query and returns a Pandas DataFrame.
-        
-        Args:
-            query (str): The SQL query string. Use :param_name for parameters.
-            params (dict, optional): Dictionary of parameters to bind to the query.
-            chunksize (int, optional): If specified, returns an iterator where each chunk is the given size.
-        
-        Returns:
-            pd.DataFrame or Iterator[pd.DataFrame]
-        """
-        try:
-            with self.engine.connect() as conn:
-                # Use text() explicitly for SQLAlchemy 2.0 compatibility
-                sql_query = text(query)
-                
-                # If chunksize is provided, read_sql returns a generator
-                result = pd.read_sql(
-                    sql_query, 
-                    conn, 
-                    params=params, 
-                    chunksize=chunksize
-                )
-                
-                if chunksize is None:
-                    logger.info(f"Successfully retrieved {len(result)} rows.")
-                else:
-                    logger.info(f"Retrieving data in chunks of {chunksize} rows.")
-                    
-                return result
-                
-        except SQLAlchemyError as e:
-            logger.error(f"Failed to retrieve data: {e}")
-            raise
-        except Exception as e:
-            logger.error(f"An unexpected error occurred during get_data: {e}")
-            raise