Giới thiệu Py-SQL-cleaner: Công cụ dòng lệnh giúp định dạng SQL nhúng trong mã nguồn Python

Giới thiệu Py-SQL-cleaner: Công cụ dòng lệnh giúp định dạng SQL nhúng trong mã nguồn Python

Trong quá trình phát triển phần mềm, đặc biệt là với các ứng dụng xử lý dữ liệu, các lập trình viên thường phải viết các câu lệnh SQL dài trực tiếp bên trong mã nguồn Python. Tuy nhiên, các công cụ định dạng (formatter) phổ biến cho Python như Black hay Autopep8 thường chỉ xử lý cú pháp Python và bỏ qua các chuỗi chứa SQL. Ngược lại, các công cụ định dạng SQL lại hoạt động tốt nhất trên các tệp .sql riêng biệt chứ không phải SQL nhúng trong code.

Để giải quyết vấn đề này, một công cụ dòng lệnh (CLI) mới mang tên Py-SQL-cleaner đã được ra mắt, giúp phát hiện, định dạng và làm sạch các đoạn SQL nhúng trong các tệp Python một cách tự động và an toàn.

Tính năng nổi bật

Py-SQL-cleaner được thiết kế đặc biệt cho các codebase Python sử dụng các câu truy vấn SQL dài nằm trong các chuỗi ba ngoặc kép (triple-quoted strings). Công cụ này hoạt động dựa trên thư viện SQLGlot để xử lý việc định dạng.

Dưới đây là những tính năng chính của Py-SQL-cleaner:

• Định dạng tại chỗ (In-place formatting): Công cụ có thể quét và định dạng lại các câu lệnh SQL ngay trong tệp Python mà không làm thay đổi logic của code.
• Trích xuất SQL: Cho phép tách các câu lệnh SQL nhúng ra thành các tệp .sql bên ngoài và thay thế chúng trong code bằng tham chiếu đến tệp tương ứng.
• Hỗ trợ nhiều phương ngữ cơ sở dữ liệu: Ngoài SQL chung (generic), công cụ hỗ trợ các phương ngữ cụ thể như MySQL, PostgreSQL và Redshift thông qua cờ --dialect.
• Chế độ an toàn: Py-SQL-cleaner hoạt động thận trọng bằng mặc định. Nó sẽ tự động bỏ qua (không viết lại) các đoạn SQL chứa f-strings, biến mẫu Jinja (như {{ ds }}), hoặc các tham số runtime (như %s hoặc :name) để tránh làm hỏng hành vi của ứng dụng.
• Tích hợp CI: Hỗ trợ chế độ check để xác định xem code có tuân thủ định dạng hay không, rất hữu ích cho các pipeline CI/CD.

Cách sử dụng

Bạn có thể cài đặt Py-SQL-cleaner dễ dàng qua PyPI hoặc pipx:

pip install py-sql-cleaner
# hoặc
pipx install py-sql-cleaner

Ngoài ra, bạn có thể chạy công cụ này mà không cần cài đặt thông qua uvx:

uvx py-sql-cleaner --help

Các lệnh cơ bản

Để liệt kê các khối SQL được tìm thấy trong một tệp:

py-sql-cleaner list path/to/file.py

Để xem trước các thay đổi định dạng trước khi áp dụng (dry-run):

py-sql-cleaner format path/to/file.py --dry-run

Để định dạng SQL trực tiếp trong tệp:

py-sql-cleaner format path/to/file.py

Để trích xuất SQL ra tệp ngoài:

py-sql-cleaner extract path/to/file.py --out-dir sql

Ví dụ minh họa

Trước khi sử dụng Py-SQL-cleaner, một đoạn code Python chứa SQL có thể trông lộn xộn như sau:

query = """
select user_id, updated_at
from users
qualify row_number() over(partition by user_id order by updated_at desc)=1
"""

Sau khi chạy lệnh định dạng, đoạn code sẽ trở nên rõ ràng và chuẩn tắc hơn:

query = """
SELECT
    user_id,
    updated_at
FROM users
QUALIFY
    ROW_NUMBER() OVER (PARTITION BY user_id ORDER BY updated_at DESC) = 1
"""

Lưu ý về an toàn

Đội ngũ phát triển nhấn mạnh rằng Py-SQL-cleaner không kết nối với cơ sở dữ liệu, không thực thi SQL và không xác thực lược đồ (schema). Mục tiêu chính của công cụ là cải thiện tính đọc được của mã nguồn và duy trì sự nhất quán về phong cách viết SQL trong dự án, đồng thời ưu tiên việc bảo toàn hành vi runtime của ứng dụng bằng cách bỏ qua các đoạn code phức tạp hoặc không an toàn để định dạng tự động.

Nếu bạn thường xuyên phải làm việc với các câu lệnh SQL nhúng trong Python, Py-SQL-cleaner là một công cụ bổ trợ hữu ích để giữ cho codebase luôn gọn gàng và chuyên nghiệp.