Tải và chuẩn bị source code Spanner
Mục đích: Lấy mã nguồn chính thức của Google Cloud Spanner từ repository Git để có thể biên dịch phiên bản Local Emulator.
Lý do: Spanner Local không có binary đóng gói sẵn cho Linux. Bạn bắt buộc phải build từ source code để tạo ra file thực thi `spanner_emulator`.
Kết quả mong đợi: Thư mục `spanner-emulator` được tạo trên home directory của bạn, chứa toàn bộ code nguồn C++ và các file cấu hình build.
Trước khi clone, hãy đảm bảo bạn đã cài đặt Git (đã làm ở Phần 1). Di chuyển đến thư mục home và clone repository.
cd ~
git clone https://github.com/google/spanner-emulator.git
cd spanner-emulator
Sau khi chạy lệnh, bạn sẽ thấy thư mục `spanner-emulator` được tạo ra. Kiểm tra bằng lệnh `ls` để xác nhận.
Cài đặt các thư viện phụ thuộc (Dependencies)
Mục đích: Cài đặt các thư viện C++ và công cụ build cần thiết để compile Spanner Local trên Ubuntu 24.04.
Lý do: Source code Spanner sử dụng nhiều thư viện bên ngoài như `protobuf`, `gRPC`, `abseil`, và `boringssl`. Nếu thiếu các thư viện này, bước build sẽ bị lỗi ngay lập tức.
Kết quả mong đợi: Tất cả các package dependency được cài đặt vào hệ thống, không còn cảnh báo thiếu package.
Ubuntu 24.04 có sẵn các package mới, nhưng Spanner Local yêu cầu phiên bản cụ thể của một số thư viện. Chạy lệnh sau để cài đặt toàn bộ:
sudo apt update
sudo apt install -y \
build-essential \
cmake \
git \
protobuf-compiler \
libprotobuf-dev \
libgrpc-dev \
libgrpc++-dev \
libabsl-dev \
libssl-dev \
libboost-dev \
libboost-filesystem-dev \
libboost-system-dev \
libboost-program-options-dev \
libgoogle-glog-dev \
libgoogle-perftools-dev \
clang \
libclang-dev
Sau khi cài đặt xong, kiểm tra xem các công cụ đã sẵn sàng chưa bằng cách gõ `cmake --version` và `protoc --version`. Nếu không có lỗi, bạn đã sẵn sàng cho bước build.
Biên dịch và Build Spanner Local từ nguồn
Mục đích: Sử dụng CMake để tạo file cấu hình build và dùng Make/Clang để biên dịch source code thành binary.
Lý do: Google sử dụng hệ thống build riêng dựa trên CMake. Việc tạo một thư mục `build` riêng biệt giúp giữ source code gốc sạch sẽ và dễ dàng xóa bỏ khi cần rebuild.
Kết quả mong đợi: File binary `spanner_emulator` được tạo ra trong thư mục `build/` hoặc `build/bin/`.
Tạo thư mục build, chạy CMake để cấu hình, sau đó chạy Make để biên dịch. Lưu ý: Quá trình này có thể mất từ 5 đến 15 phút tùy thuộc vào cấu hình máy.
mkdir -p build
cd build
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang ..
make -j$(nproc)
Sau khi build thành công, hãy xác nhận file thực thi đã tồn tại.
ls -lh spanner_emulator
Bạn sẽ thấy file `spanner_emulator` với kích thước khoảng 30MB-50MB. Đây là core của Local Emulator.
Cấu hình biến môi trường và đường dẫn
Mục đích: Thiết lập biến môi trường để hệ thống nhận diện Spanner Local như một dịch vụ thực tế và chỉ định đường dẫn binary.
Lý do: Các client SDK (Go, Python, Java) cần biết địa chỉ kết nối và thường tìm kiếm binary hoặc cấu hình tại các vị trí chuẩn. Việc set biến môi trường giúp tránh phải gõ đường dẫn dài mỗi khi chạy lệnh.
Kết quả mong đợi: Biến `SPANNER_EMULATOR_HOST` được set và file shell script để khởi động được tạo ra.
Tạo một thư mục cấu hình riêng trong home để quản lý các file của Spanner.
mkdir -p ~/spanner-local
cp build/spanner_emulator ~/spanner-local/
Bây giờ, hãy thêm biến môi trường vào file `~/.bashrc` (hoặc `~/.zshrc` nếu dùng Zsh) để set đường dẫn và host mặc định.
echo 'export SPANNER_EMULATOR_HOST="localhost:9010"' >> ~/.bashrc
echo 'export PATH="$HOME/spanner-local:$PATH"' >> ~/.bashrc
source ~/.bashrc
Kiểm tra xem biến đã được tải vào shell hiện tại chưa.
echo $SPANNER_EMULATOR_HOST
which spanner_emulator
Kết quả mong đợi: Dòng đầu tiên in ra `localhost:9010`, dòng thứ hai in ra đường dẫn đầy đủ `~/spanner-local/spanner_emulator`.
Khởi động dịch vụ Spanner Local
Mục đích: Chạy binary `spanner_emulator` với các tham số cần thiết để mở port và tạo instance.
Lý do: Spanner Local chạy dưới dạng một tiến trình đơn lẻ. Nó cần biết port để listen (mặc định là 9010 cho gRPC và 9020 cho HTTP REST) và cần một instance ID để tạo schema.
Kết quả mong đợi: Terminal hiển thị log khởi động thành công, dịch vụ đang listen trên port 9010 và sẵn sàng nhận kết nối.
Khởi động emulator trong background để không bị khóa terminal. Chúng ta sẽ dùng `nohup` và `&` để chạy ngầm.
cd ~/spanner-local
nohup ./spanner_emulator --port=9010 --grpc_port=9010 --rest_port=9020 --project_id=my-local-project --instance_id=my-local-instance > spanner.log 2>&1 &
Chờ khoảng 2-3 giây để dịch vụ khởi động hoàn toàn.
sleep 3
tail -n 20 spanner.log
Trong log, bạn sẽ thấy các dòng như "Spanner emulator started" hoặc "Listening on port 9010". Nếu có lỗi, log sẽ báo rõ nguyên nhân (thường là port bị chiếm hoặc thiếu quyền).
Kiểm tra trạng thái hoạt động của Emulator
Mục đích: Xác minh rằng Spanner Local đã chạy, đang listen đúng port và phản hồi yêu cầu kết nối.
Lý do: Trước khi viết code ứng dụng (Phần 3), bạn cần chắc chắn rằng dịch vụ backend đang hoạt động ổn định.
Kết quả mong đợi: Port 9010 ở trạng thái LISTEN và lệnh kiểm tra trạng thái trả về kết quả thành công.
Kiểm tra xem port 9010 đã được mở chưa bằng công cụ `ss` hoặc `netstat`.
ss -tlnp | grep 9010
Kết quả mong đợi: Bạn thấy dòng output chứa `LISTEN` và `0.0.0.0:9010` (hoặc `127.0.0.1:9010`) cùng với tên tiến trình `spanner_emulator`.
Tiếp theo, sử dụng `grpc_health_probe` (nếu đã cài) hoặc đơn giản hơn là dùng `curl` để gọi endpoint REST để kiểm tra.
curl -v http://localhost:9020/v1/projects/my-local-project/instances/my-local-instance/databases -H "Authorization: Bearer oauth2:dummy"
Lưu ý: Spanner Local thường chấp nhận các token giả (dummy) cho mục đích dev. Nếu bạn thấy phản hồi JSON (có thể là lỗi 401 nhưng cấu trúc JSON trả về chứng tỏ server đã nhận request) hoặc lỗi 404 (chưa có database), điều đó chứng tỏ server đang chạy.
Cách kiểm tra chính xác nhất là dùng `ps` để xem tiến trình.
ps aux | grep spanner_emulator
Kết quả: Dòng output hiển thị tiến trình `spanner_emulator` đang chạy với các tham số bạn đã set. Nếu bước này thành công, môi trường Spanner Local của bạn đã sẵn sàng cho Phần 3.
Điều hướng series:
Mục lục: Series: Triển khai Database NewSQL với Google Spanner và Ubuntu 24.04
« Phần 1: Chuẩn bị môi trường Ubuntu 24.04 và yêu cầu hệ thống cho Google Spanner
Phần 3: Cấu hình kết nối và quản lý cơ sở dữ liệu Spanner »