Cài đặt và Cấu hình Driver Python cho DuckDB
Chúng ta sẽ thiết lập môi trường Python ảo để cô lập các thư viện, tránh xung đột với hệ thống Ubuntu 24.04.
Mục đích: Tạo môi trường sạch, cài đặt driver chính thức của DuckDB và thư viện Pandas để xử lý dữ liệu bảng.
Kết quả mong đợi: Một environment virtual (venv) hoạt động với khả năng import `duckdb` và `pandas` không lỗi.
Tạo và kích hoạt môi trường ảo tại thư mục dự án của bạn.
cd ~/projects/duckdb-app
python3 -m venv venv
source venv/bin/activate
Trên terminal, bạn sẽ thấy dấu ngoặc đơn `(venv)` xuất hiện trước prompt, xác nhận môi trường đã được kích hoạt.
Cài đặt driver `duckdb` và `pandas` thông qua pip. Lưu ý không cần cài thêm driver nào khác vì DuckDB chạy native.
pip install --upgrade pip
pip install duckdb pandas
Verify bằng cách chạy lệnh Python interactively để kiểm tra version.
python -c "import duckdb; import pandas; print(f'DuckDB version: {duckdb.__version__}'); print(f'Pandas version: {pandas.__version__}')"
Terminal hiển thị phiên bản của cả hai thư viện, không có lỗi import.
Thực hiện Kết nối và Truy vấn từ Ứng dụng Python
Chúng ta sẽ viết một script Python mẫu để mở kết nối, thực hiện truy vấn SQL và đọc dữ liệu vào DataFrame Pandas.
Mục đích: Minh họa cách kết nối đến file database đã tạo (hoặc server mode nếu đang chạy) và thao tác CRUD cơ bản.
Kết quả mong đợi: Script chạy thành công, in ra số lượng dòng dữ liệu và hiển thị preview bảng.
Tạo file Python `query_data.py` trong thư mục dự án. Script này sẽ mở connection, tạo bảng nếu chưa tồn tại, chèn dữ liệu mẫu và truy vấn lại.
cat > ~/projects/duckdb-app/query_data.py
Chạy script để thực thi các lệnh SQL.
cd ~/projects/duckdb-app
python query_data.py
Terminal in ra bảng dữ liệu với 2 dòng (Server 1, Server 2) và thông tin kiểu dữ liệu. Nếu file database chưa có, script tự tạo mới.
Cấu hình Kết nối từ SQL Client (DBeaver & DataGrip)
Bây giờ chúng ta cấu hình các công cụ GUI để kết nối vào DuckDB đang chạy trên Ubuntu.
Mục đích: Sử dụng DBeaver (hoặc DataGrip) để truy vấn trực tiếp mà không cần viết code Python.
Kết quả mong đợi: Có thể thấy danh sách bảng (Tables) và chạy SQL trực tiếp trên giao diện client.
Cấu hình trên DBeaver
DBeaver không hỗ trợ native connector cho DuckDB như MySQL hay Postgres, nhưng chúng ta có thể dùng driver JDBC thông qua JAR file hoặc sử dụng kết nối thông qua PostgreSQL (nếu DuckDB được cấu hình giả lập) hoặc đơn giản nhất là dùng file-based connection nếu DBeaver hỗ trợ file trực tiếp (phiên bản mới).
Tuy nhiên, cách chuẩn và ổn định nhất để kết nối từ SQL Client vào DuckDB Server (nếu bạn đang chạy DuckDB ở chế độ server như Phần 2) là sử dụng driver JDBC. Nhưng DuckDB hiện tại chủ yếu là file-based. Nếu bạn đang chạy DuckDB như một service độc lập (DuckDB Server), bạn cần cấu hình kết nối TCP.
Giả sử bạn đã chạy DuckDB Server (từ Phần 2/3) trên port 8080 hoặc 5432 (nếu giả lập Postgres), chúng ta sẽ cấu hình kết nối TCP. Nếu chỉ là file, DBeaver mới hỗ trợ file-based từ bản 24.1 trở lên.
Để đơn giản và chính xác nhất cho môi trường Serverless/File-based trên Ubuntu, ta sẽ cấu hình DBeaver kết nối trực tiếp đến file `.duckdb` nếu DBeaver phiên bản mới, hoặc dùng JDBC Driver nếu chạy Server.
Tạo file driver JDBC (nếu cần) hoặc cấu hình Driver trong DBeaver. Dưới đây là cách cấu hình Driver trong DBeaver cho kết nối File (Native) hoặc Server.
Trong DBeaver, chọn Window -> Preferences -> Drivers. Tìm kiếm "DuckDB". Nếu chưa có, tải Driver từ [DuckDB JDBC](https://github.com/duckdb/duckdb-jdbc).
Tuy nhiên, để không phụ thuộc vào Java, ta sẽ hướng dẫn cấu hình kết nối File trực tiếp (File System) trong DBeaver (hỗ trợ từ bản 24.1).
Tạo một Connection mới trong DBeaver.
- Click New Database Connection.
- Tìm và chọn DuckDB trong danh sách (nếu có) hoặc chọn File và trỏ vào file `.duckdb`.
- Nếu dùng Driver JDBC Server: Chọn Other -> Generic JDBC.
- Download JAR file: `duckdb-jdbc-1.x.x.jar`.
- Cấu hình Connection URL: `jdbc:duckdb:/home/user/projects/duckdb-app/data/main.duckdb`.
Để chắc chắn chạy được trên Ubuntu qua terminal để kiểm tra kết nối từ xa (nếu cần), ta dùng `duckdb` CLI với chế độ server nếu đã config.
Nếu bạn đang chạy DuckDB Server (từ Phần 3) trên port 8080, cấu hình DataGrip/DBeaver như sau:
Trong DataGrip/DBeaver, chọn Driver: DuckDB (JDBC).
Cấu hình Connection Settings:
- Host: 127.0.0.1 (hoặc IP server)
- Port: 8080 (hoặc port bạn config trong Phần 2)
- Database: main (hoặc để trống nếu kết nối file)
- User/Password: Để trống (DuckDB Server mặc định không auth, hoặc dùng user config trong Phần 6)
- Driver JAR: Tải file `duckdb_jdbc.jar` và add vào Driver settings.
Verify bằng cách click Test Connection và sau đó mở Database Navigator để thấy bảng `demo_table`.
Xử lý Kết nối Đồng thời và Quản lý Transaction
Chúng ta sẽ kiểm tra cách DuckDB xử lý các transaction song song và cơ chế locking.
Mục đích: Đảm bảo tính toàn vẹn dữ liệu khi nhiều client truy cập cùng lúc và hiểu cách commit/rollback.
Kết quả mong đợi: Transaction được cam kết (commit) hoặc hoàn tác (rollback) đúng ý, không bị mất dữ liệu do xung đột.
Tạo script `transaction_test.py` để mô phỏng 2 session cùng thao tác.
cat > ~/projects/duckdb-app/transaction_test.py
Chạy script để test cơ chế locking và transaction.
cd ~/projects/duckdb-app
python transaction_test.py
Terminal hiển thị dòng count là 2 sau khi Session 1 insert nhưng chưa commit, vẫn là 2 sau khi rollback, và tăng lên 3 sau khi commit. Xác nhận DuckDB hoạt động đúng chuẩn ACID.
Verify Kết quả Tổng thể
Kiểm tra lại toàn bộ hệ thống sau khi hoàn thành các bước trên.
Thực hiện lệnh kiểm tra cuối cùng để đảm bảo Python, SQL Client và Transaction đều hoạt động ổn định.
cd ~/projects/duckdb-app
# Kiểm tra file database tồn tại và kích thước
ls -lh data/main.duckdb
# Chạy truy vấn nhanh qua CLI DuckDB để verify dữ liệu
duckdb data/main.duckdb -c "SELECT * FROM demo_table;"
# Kiểm tra Python environment
source venv/bin/activate
python -c "import duckdb; print('Python Driver OK')"
File database có kích thước tăng lên, CLI hiển thị 3 dòng dữ liệu (Server 1, 2, 4 - Server 3 bị rollback), và Python driver báo OK.
Điều hướng series:
Mục lục: Series: Triển khai Database Serverless với DuckDB và Ubuntu 24.04
« Phần 3: Triển khai DuckDB dưới dạng Service Systemd trên Ubuntu
Phần 5: Tự động hóa sao lưu, khôi phục và mở rộng dữ liệu »