sqlServerConnector 0.1.7__tar.gz → 0.1.9__tar.gz

{sqlserverconnector-0.1.7 → sqlserverconnector-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlServerConnector
-Version: 0.1.7
+Version: 0.1.9
 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,8 +20,10 @@ 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.7
+
+### **Update 0.1.9**
 > 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
+> Thay vì dùng bảng tạm (##Staging), sẽ dùng bảng vật lý tạm thời (Physical Staging Table) có tên chứa UUID (để đảm bảo duy nhất, không trùng lặp giữa các luồng chạy). Sau khi Upsert xong, ta sẽ DROP bảng này ngay lập tức. Cách này tương thích 100% với Pandas và SQLAlchemy.
 
 
 ## 🚀 Tính năng nổi bật
@@ -69,9 +71,10 @@ db_info:
 ## 📝 Hướng dẫn sử dụng nhanh
 
 1. Khởi tạo kết nối
-```python   
+```python
 import yaml
 from connector import SQLServerConnector
+
 # Load config
 with open('config/db_config.yaml', 'r') as f:
     conf = yaml.safe_load(f)['db_info']
@@ -88,47 +91,63 @@ db = SQLServerConnector(
 2. Lấy dữ liệu (Read)
 ```python
 # Cách 1: Lấy toàn bộ bảng
-df = db.get_data("DM_KhachHang")
+df = db.get_data("SELECT * FROM DM_KhachHang")
 
-# Cách 2: Dùng câu lệnh SQL tùy ý
+# Cách 2: Dùng câu lệnh SQL tuy bien
 query = """
-    SELECT TOP 100 * FROM Sales_Transaction 
-    WHERE created_date >= '2023-01-01'
+    SELECT TOP 100 * FROM Sales_Transaction
+    WHERE created_date >= :from_date
 """
-df_sales = db.get_data(query)
+df_sales = db.get_data(query, params={"from_date": "2023-01-01"})
 print(df_sales.head())
 ```
 
-3. Ghi dữ liệu (Upsert)
+3. Kiểm tra bảng tồn tại
+```python
+if not db.check_table_exists("Fact_Sales"):
+    print("Bang Fact_Sales chua ton tai")
+```
+
+4. Ghi du lieu (Upsert)
 ```python
 import pandas as pd
 
-# Giả lập dữ liệu
+# Gia lap du lieu
 data = {
     'TransactionID': [101, 102],
-    'Product': ['Laptop Dell', 'Chuột Logitech'], # Hỗ trợ tiếng Việt
+    'Product': ['Laptop Dell', 'Chuot Logitech'],  # Ho tro tieng Viet
     'Amount': [15000000, 250000]
 }
 df_new = pd.DataFrame(data)
 
-# Đẩy vào DB
+# Day vao DB
 db.upsert_data(
     df=df_new,
     target_table="Fact_Sales",
-    primary_key="TransactionID",  # Cột dùng để định danh (tránh trùng lặp)
-    auto_evolve_schema=True       # Tự động thêm cột nếu thiếu
+    match_columns=["TransactionID"],  # Khoa so khop (Primary Key)
+    conflict_strategy="last",         # "last" hoac "skip"
+    auto_evolve_schema=True            # Tu dong them cot neu thieu
+)
+print("Du lieu da duoc upsert thanh cong!")
+```
+
+5. Thuc thi cau lenh khong tra ve du lieu
+```python
+# Vi du: xoa du lieu cu
+db.execute_query(
+    "DELETE FROM Fact_Sales WHERE created_date < :cutoff",
+    params={"cutoff": "2023-01-01"}
 )
-print("Dữ liệu đã được upsert thành công!")
 ```
 
-4. Đóng kết nối
+6. Dong ket noi
 ```python
-# Luôn đóng kết nối khi hoàn tất để giải phóng tài nguyên
+# Luon dong ket noi khi hoan tat de giai phong tai nguyen
 db.dispose()
 ```
 
 ## ⚠️ Lưu ý quan trọng
-1. **Primary Key:** Khi dùng upsert_data, bắt buộc phải cung cấp primary_key. Nếu bảng chưa có Primary Key, thư viện sẽ tự set cột đó làm khóa chính khi tạo bảng mới.
+1. **Primary Key:** Khi dùng upsert_data, bat buoc phai cung cap `match_columns`. Neu bang chua co Primary Key, thu vien se co gang set cac cot nay lam khoa chinh khi tao bang moi.
 
 2. **Date Time:** Các cột ngày tháng nên được convert sang datetime64[ns] trong Pandas trước khi đẩy vào để đảm bảo tính chính xác.
 

{sqlserverconnector-0.1.7 → sqlserverconnector-0.1.9}/README.md

@@ -1,8 +1,10 @@
 # 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.7
+
+### **Update 0.1.9**
 > 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
+> Thay vì dùng bảng tạm (##Staging), sẽ dùng bảng vật lý tạm thời (Physical Staging Table) có tên chứa UUID (để đảm bảo duy nhất, không trùng lặp giữa các luồng chạy). Sau khi Upsert xong, ta sẽ DROP bảng này ngay lập tức. Cách này tương thích 100% với Pandas và SQLAlchemy.
 
 
 ## 🚀 Tính năng nổi bật
@@ -50,9 +52,10 @@ db_info:
 ## 📝 Hướng dẫn sử dụng nhanh
 
 1. Khởi tạo kết nối
-```python   
+```python
 import yaml
 from connector import SQLServerConnector
+
 # Load config
 with open('config/db_config.yaml', 'r') as f:
     conf = yaml.safe_load(f)['db_info']
@@ -69,47 +72,63 @@ db = SQLServerConnector(
 2. Lấy dữ liệu (Read)
 ```python
 # Cách 1: Lấy toàn bộ bảng
-df = db.get_data("DM_KhachHang")
+df = db.get_data("SELECT * FROM DM_KhachHang")
 
-# Cách 2: Dùng câu lệnh SQL tùy ý
+# Cách 2: Dùng câu lệnh SQL tuy bien
 query = """
-    SELECT TOP 100 * FROM Sales_Transaction 
-    WHERE created_date >= '2023-01-01'
+    SELECT TOP 100 * FROM Sales_Transaction
+    WHERE created_date >= :from_date
 """
-df_sales = db.get_data(query)
+df_sales = db.get_data(query, params={"from_date": "2023-01-01"})
 print(df_sales.head())
 ```
 
-3. Ghi dữ liệu (Upsert)
+3. Kiểm tra bảng tồn tại
+```python
+if not db.check_table_exists("Fact_Sales"):
+    print("Bang Fact_Sales chua ton tai")
+```
+
+4. Ghi du lieu (Upsert)
 ```python
 import pandas as pd
 
-# Giả lập dữ liệu
+# Gia lap du lieu
 data = {
     'TransactionID': [101, 102],
-    'Product': ['Laptop Dell', 'Chuột Logitech'], # Hỗ trợ tiếng Việt
+    'Product': ['Laptop Dell', 'Chuot Logitech'],  # Ho tro tieng Viet
     'Amount': [15000000, 250000]
 }
 df_new = pd.DataFrame(data)
 
-# Đẩy vào DB
+# Day vao DB
 db.upsert_data(
     df=df_new,
     target_table="Fact_Sales",
-    primary_key="TransactionID",  # Cột dùng để định danh (tránh trùng lặp)
-    auto_evolve_schema=True       # Tự động thêm cột nếu thiếu
+    match_columns=["TransactionID"],  # Khoa so khop (Primary Key)
+    conflict_strategy="last",         # "last" hoac "skip"
+    auto_evolve_schema=True            # Tu dong them cot neu thieu
+)
+print("Du lieu da duoc upsert thanh cong!")
+```
+
+5. Thuc thi cau lenh khong tra ve du lieu
+```python
+# Vi du: xoa du lieu cu
+db.execute_query(
+    "DELETE FROM Fact_Sales WHERE created_date < :cutoff",
+    params={"cutoff": "2023-01-01"}
 )
-print("Dữ liệu đã được upsert thành công!")
 ```
 
-4. Đóng kết nối
+6. Dong ket noi
 ```python
-# Luôn đóng kết nối khi hoàn tất để giải phóng tài nguyên
+# Luon dong ket noi khi hoan tat de giai phong tai nguyen
 db.dispose()
 ```
 
 ## ⚠️ Lưu ý quan trọng
-1. **Primary Key:** Khi dùng upsert_data, bắt buộc phải cung cấp primary_key. Nếu bảng chưa có Primary Key, thư viện sẽ tự set cột đó làm khóa chính khi tạo bảng mới.
+1. **Primary Key:** Khi dùng upsert_data, bat buoc phai cung cap `match_columns`. Neu bang chua co Primary Key, thu vien se co gang set cac cot nay lam khoa chinh khi tao bang moi.
 
 2. **Date Time:** Các cột ngày tháng nên được convert sang datetime64[ns] trong Pandas trước khi đẩy vào để đảm bảo tính chính xác.
 

{sqlserverconnector-0.1.7 → sqlserverconnector-0.1.9}/pyproject.toml

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

{sqlserverconnector-0.1.7 → sqlserverconnector-0.1.9}/src/connector.py

@@ -10,12 +10,13 @@ from sqlalchemy.types import NVARCHAR, FLOAT, INTEGER, DATE, DATETIME, BIGINT
 
 class SQLServerConnector:
     """
-    Trình kết nối SQL Server chuẩn hóa (Full Features).
+    Trình kết nối SQL Server chuẩn hóa (Full Features - Fixed Missing Attribute).
     Tích hợp:
     - Fast Executemany (Tốc độ cao).
     - Unicode Support (NVARCHAR).
-    - Upsert Strategy (Last/Sum/Skip).
-    - Schema Evolution (Tự động thêm cột).
+    - Upsert Strategy (Last/Skip).
+    - Schema Evolution.
+    - Helper methods: check_table_exists.
     """
 
     def __init__(self, server: str, database: str, username: str, password: str, driver: str = 'ODBC Driver 17 for SQL Server', **kwargs):
@@ -65,6 +66,17 @@ class SQLServerConnector:
             logger.error(f"Execute query error: {e}")
             raise e
 
+    # --- [ĐÃ BỔ SUNG LẠI HÀM NÀY] ---
+    def check_table_exists(self, table_name: str) -> bool:
+        """Kiểm tra bảng có tồn tại trong database không"""
+        try:
+            inspector = inspect(self.engine)
+            return inspector.has_table(table_name)
+        except Exception as e:
+            logger.error(f"Check table exists failed: {e}")
+            return False
+    # --------------------------------
+
     def _generate_dtype_mapping(self, df: pd.DataFrame) -> Dict:
         """Tự động map kiểu dữ liệu (NVARCHAR cho string)"""
         dtype_map = {}
@@ -107,18 +119,7 @@ class SQLServerConnector:
                     conflict_strategy: Literal['last', 'skip'] = 'last',
                     auto_evolve_schema: bool = False):
         """
-        Hàm Upsert mạnh mẽ (Khôi phục đầy đủ tính năng cũ).
-        
-        Args:
-            df: DataFrame cần upload.
-            target_table: Tên bảng đích.
-            match_columns: Danh sách cột dùng làm Key so khớp (Primary Key).
-            conflict_strategy: 
-                - 'last': Update ghi đè dữ liệu mới vào dòng cũ (Default).
-                - 'skip': Nếu trùng key thì bỏ qua, không update.
-            auto_evolve_schema: 
-                - True: Tự động thêm cột vào DB nếu DF có cột mới.
-                - False: Bỏ qua các cột trong DF mà DB không có (Strict Schema).
+        Hàm Upsert sửa lỗi 'Table not found'.
         """
         if df.empty:
             logger.warning(f"DataFrame for {target_table} is empty. Skip.")
@@ -127,17 +128,19 @@ class SQLServerConnector:
         # 1. Map Unicode Types
         dtype_mapping = self._generate_dtype_mapping(df)
         
-        # 2. Staging Table Name
-        staging_table = f"##Staging_{uuid.uuid4().hex[:8]}"
+        # [FIX] Dùng tên bảng thường (Staging_UUID) thay vì ##Staging
+        # Lý do: Pandas to_sql gặp lỗi khi check sự tồn tại của bảng ## trong transaction.
+        # Bảng này sẽ được drop thủ công ở khối finally.
+        staging_table = f"Staging_{uuid.uuid4().hex[:8]}"
 
         try:
             with self.engine.begin() as conn:
-                # --- A. Kiểm tra Schema & Table ---
+                # --- A. Kiểm tra & Tạo bảng đích ---
                 inspector = inspect(conn)
                 if not inspector.has_table(target_table):
                     logger.info(f"Table {target_table} not found. Creating new...")
                     df.to_sql(target_table, conn, index=False, dtype=dtype_mapping)
-                    # Tạo Primary Key nếu cần
+                    
                     if match_columns:
                         pk_str = ", ".join([f"[{c}]" for c in match_columns])
                         try:
@@ -146,25 +149,22 @@ class SQLServerConnector:
                             logger.warning(f"Could not create PK: {e}")
                     return
 
-                # --- B. Xử lý Schema Evolution ---
+                # --- B. Schema Evolution ---
                 db_cols = self._get_table_columns(target_table, conn)
                 df_cols = list(df.columns)
-                
-                # Tìm cột có trong DF mà không có trong DB
                 new_cols = [c for c in df_cols if c not in db_cols]
                 
                 if new_cols:
                     if auto_evolve_schema:
                         self._add_missing_columns(target_table, new_cols, dtype_mapping, conn)
-                        db_cols.extend(new_cols) # Update danh sách cột DB
+                        db_cols.extend(new_cols)
                     else:
-                        # Nếu không auto evolve, chỉ giữ lại các cột khớp với DB
                         valid_cols = [c for c in df_cols if c in db_cols]
                         if len(valid_cols) < len(df_cols):
-                            logger.warning(f"Schema strict: Dropping columns {new_cols} because they are not in DB.")
                             df = df[valid_cols]
-                
-                # --- C. Đẩy vào Staging (Fast Executemany) ---
+
+                # --- C. Đẩy vào Staging ---
+                # to_sql hoạt động tốt với bảng thường
                 df.to_sql(
                     name=staging_table,
                     con=conn,
@@ -173,60 +173,52 @@ class SQLServerConnector:
                     dtype=dtype_mapping
                 )
 
-                # --- D. Thực hiện MERGE ---
-                # Chỉ lấy các cột chung giữa DF và DB để Merge (tránh lỗi cột không tồn tại)
+                # --- D. MERGE ---
                 common_cols = [c for c in df.columns if c in db_cols]
-                
                 on_clause = " AND ".join([f"Target.[{col}] = Source.[{col}]" for col in match_columns])
                 
-                # Logic Insert
                 insert_cols = ", ".join([f"[{col}]" for col in common_cols])
                 insert_vals = ", ".join([f"Source.[{col}]" for col in common_cols])
 
-                # Logic Update
                 merge_sql = ""
-                
-                # Trường hợp 1: Update ('last')
                 if conflict_strategy == 'last':
                     update_cols = [c for c in common_cols if c not in match_columns]
                     if update_cols:
                         update_set = ", ".join([f"Target.[{col}] = Source.[{col}]" for col in update_cols])
                         merge_sql = f"""
-                        MERGE [{target_table}] AS Target
-                        USING {staging_table} AS Source
+                        MERGE [{target_table}] AS Target USING [{staging_table}] AS Source
                         ON {on_clause}
-                        WHEN MATCHED THEN
-                            UPDATE SET {update_set}
-                        WHEN NOT MATCHED BY TARGET THEN
-                            INSERT ({insert_cols}) VALUES ({insert_vals});
+                        WHEN MATCHED THEN UPDATE SET {update_set}
+                        WHEN NOT MATCHED BY TARGET THEN INSERT ({insert_cols}) VALUES ({insert_vals});
                         """
                     else:
-                        # Nếu chỉ có cột PK, không có gì để update -> Chỉ Insert if not exists
                         merge_sql = f"""
-                        MERGE [{target_table}] AS Target
-                        USING {staging_table} AS Source
+                        MERGE [{target_table}] AS Target USING [{staging_table}] AS Source
                         ON {on_clause}
-                        WHEN NOT MATCHED BY TARGET THEN
-                            INSERT ({insert_cols}) VALUES ({insert_vals});
+                        WHEN NOT MATCHED BY TARGET THEN INSERT ({insert_cols}) VALUES ({insert_vals});
                         """
                 
-                # Trường hợp 2: Skip (Chỉ Insert, không Update)
                 elif conflict_strategy == 'skip':
                     merge_sql = f"""
-                    MERGE [{target_table}] AS Target
-                    USING {staging_table} AS Source
+                    MERGE [{target_table}] AS Target USING [{staging_table}] AS Source
                     ON {on_clause}
-                    WHEN NOT MATCHED BY TARGET THEN
-                        INSERT ({insert_cols}) VALUES ({insert_vals});
+                    WHEN NOT MATCHED BY TARGET THEN INSERT ({insert_cols}) VALUES ({insert_vals});
                     """
 
                 conn.execute(text(merge_sql))
-                conn.execute(text(f"DROP TABLE IF EXISTS {staging_table}"))
-                logger.info(f"Upserted {len(df)} rows to {target_table} (Strategy: {conflict_strategy})")
+                logger.info(f"Upserted {len(df)} rows to {target_table}")
 
         except Exception as e:
             logger.error(f"Upsert failed for {target_table}: {e}")
             raise e
+        finally:
+            # [QUAN TRỌNG] Luôn luôn xóa bảng Staging rác dù thành công hay thất bại
+            # Sử dụng kết nối mới để đảm bảo lệnh Drop được thực thi
+            try:
+                with self.engine.begin() as conn:
+                    conn.execute(text(f"IF OBJECT_ID('{staging_table}', 'U') IS NOT NULL DROP TABLE [{staging_table}]"))
+            except Exception as e:
+                logger.warning(f"Could not clean up staging table {staging_table}: {e}")
 
     def dispose(self):
         self.engine.dispose()

{sqlserverconnector-0.1.7 → sqlserverconnector-0.1.9}/src/sqlServerConnector.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlServerConnector
-Version: 0.1.7
+Version: 0.1.9
 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,8 +20,10 @@ 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.7
+
+### **Update 0.1.9**
 > 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
+> Thay vì dùng bảng tạm (##Staging), sẽ dùng bảng vật lý tạm thời (Physical Staging Table) có tên chứa UUID (để đảm bảo duy nhất, không trùng lặp giữa các luồng chạy). Sau khi Upsert xong, ta sẽ DROP bảng này ngay lập tức. Cách này tương thích 100% với Pandas và SQLAlchemy.
 
 
 ## 🚀 Tính năng nổi bật
@@ -69,9 +71,10 @@ db_info:
 ## 📝 Hướng dẫn sử dụng nhanh
 
 1. Khởi tạo kết nối
-```python   
+```python
 import yaml
 from connector import SQLServerConnector
+
 # Load config
 with open('config/db_config.yaml', 'r') as f:
     conf = yaml.safe_load(f)['db_info']
@@ -88,47 +91,63 @@ db = SQLServerConnector(
 2. Lấy dữ liệu (Read)
 ```python
 # Cách 1: Lấy toàn bộ bảng
-df = db.get_data("DM_KhachHang")
+df = db.get_data("SELECT * FROM DM_KhachHang")
 
-# Cách 2: Dùng câu lệnh SQL tùy ý
+# Cách 2: Dùng câu lệnh SQL tuy bien
 query = """
-    SELECT TOP 100 * FROM Sales_Transaction 
-    WHERE created_date >= '2023-01-01'
+    SELECT TOP 100 * FROM Sales_Transaction
+    WHERE created_date >= :from_date
 """
-df_sales = db.get_data(query)
+df_sales = db.get_data(query, params={"from_date": "2023-01-01"})
 print(df_sales.head())
 ```
 
-3. Ghi dữ liệu (Upsert)
+3. Kiểm tra bảng tồn tại
+```python
+if not db.check_table_exists("Fact_Sales"):
+    print("Bang Fact_Sales chua ton tai")
+```
+
+4. Ghi du lieu (Upsert)
 ```python
 import pandas as pd
 
-# Giả lập dữ liệu
+# Gia lap du lieu
 data = {
     'TransactionID': [101, 102],
-    'Product': ['Laptop Dell', 'Chuột Logitech'], # Hỗ trợ tiếng Việt
+    'Product': ['Laptop Dell', 'Chuot Logitech'],  # Ho tro tieng Viet
     'Amount': [15000000, 250000]
 }
 df_new = pd.DataFrame(data)
 
-# Đẩy vào DB
+# Day vao DB
 db.upsert_data(
     df=df_new,
     target_table="Fact_Sales",
-    primary_key="TransactionID",  # Cột dùng để định danh (tránh trùng lặp)
-    auto_evolve_schema=True       # Tự động thêm cột nếu thiếu
+    match_columns=["TransactionID"],  # Khoa so khop (Primary Key)
+    conflict_strategy="last",         # "last" hoac "skip"
+    auto_evolve_schema=True            # Tu dong them cot neu thieu
+)
+print("Du lieu da duoc upsert thanh cong!")
+```
+
+5. Thuc thi cau lenh khong tra ve du lieu
+```python
+# Vi du: xoa du lieu cu
+db.execute_query(
+    "DELETE FROM Fact_Sales WHERE created_date < :cutoff",
+    params={"cutoff": "2023-01-01"}
 )
-print("Dữ liệu đã được upsert thành công!")
 ```
 
-4. Đóng kết nối
+6. Dong ket noi
 ```python
-# Luôn đóng kết nối khi hoàn tất để giải phóng tài nguyên
+# Luon dong ket noi khi hoan tat de giai phong tai nguyen
 db.dispose()
 ```
 
 ## ⚠️ Lưu ý quan trọng
-1. **Primary Key:** Khi dùng upsert_data, bắt buộc phải cung cấp primary_key. Nếu bảng chưa có Primary Key, thư viện sẽ tự set cột đó làm khóa chính khi tạo bảng mới.
+1. **Primary Key:** Khi dùng upsert_data, bat buoc phai cung cap `match_columns`. Neu bang chua co Primary Key, thu vien se co gang set cac cot nay lam khoa chinh khi tao bang moi.
 
 2. **Date Time:** Các cột ngày tháng nên được convert sang datetime64[ns] trong Pandas trước khi đẩy vào để đảm bảo tính chính xác.