Triển khai và quản lý các giản đồ và trình kết nối Data Connect

Dịch vụ Firebase Data Connect có 3 thành phần chính:

  • Một cơ sở dữ liệu PostgreSQL cơ bản có giản đồ SQL riêng
  • một Data Connect giản đồ ứng dụng (được khai báo trong các tệp .gql)
  • một số trình kết nối (được khai báo trong các tệp .gql, được định cấu hình trong các tệp connector.yaml).

Giản đồ SQL là nguồn dữ liệu đáng tin cậy, giản đồ Data Connect là cách trình kết nối có thể xem dữ liệu đó và trình kết nối khai báo các API mà ứng dụng có thể dùng để truy cập vào dữ liệu đó.

Khi triển khai dịch vụ Data Connect bằng CLI, bạn sẽ di chuyển giản đồ SQL, sau đó cập nhật giản đồ Data Connect, rồi cập nhật từng trình kết nối.

Các khái niệm quan trọng về việc triển khai

Để hiểu đầy đủ về việc triển khai, bạn cần lưu ý các khái niệm chính về giản đồ và trình kết nối.

Triển khai giản đồ

Việc triển khai giản đồ Data Connect ảnh hưởng đến giản đồ SQL cho cơ sở dữ liệu Cloud SQL. Data Connect giúp bạn di chuyển giản đồ trong quá trình triển khai, cho dù bạn đang làm việc với một cơ sở dữ liệu mới hay cần điều chỉnh một cơ sở dữ liệu hiện có mà không làm mất dữ liệu.

Data Connect quá trình di chuyển giản đồ có 2 chế độ xác thực giản đồ: nghiêm ngặt và tương thích.

  • Chế độ xác thực nghiêm ngặt yêu cầu giản đồ cơ sở dữ liệu phải khớp chính xác với giản đồ ứng dụng thì mới có thể cập nhật giản đồ ứng dụng. Mọi bảng hoặc cột không được dùng trong giản đồ Data Connect của bạn sẽ bị xoá khỏi cơ sở dữ liệu.

  • Chế độ xác thực tương thích yêu cầu giản đồ cơ sở dữ liệu phải tương thích với giản đồ ứng dụng thì mới có thể cập nhật giản đồ ứng dụng; mọi thay đổi bổ sung làm giảm giản đồ, bảng hoặc cột đều là không bắt buộc.

    Tương thích có nghĩa là quá trình di chuyển giản đồ chỉ ảnh hưởng đến các bảng và cột được tham chiếu trong giản đồ ứng dụng. Các phần tử trong cơ sở dữ liệu không được giản đồ ứng dụng sử dụng sẽ không bị sửa đổi. Do đó, sau khi triển khai, cơ sở dữ liệu có thể chứa các phần tử không được sử dụng:

    • Giản đồ
    • Bảng
    • Cột

Triển khai trình kết nối

Các truy vấn và đột biến Data Connect không được mã ứng dụng gửi và thực thi trên máy chủ. Thay vào đó, khi được triển khai, các Data Connect thao tác này sẽ được lưu trữ trên máy chủ, chẳng hạn như Cloud Functions. Điều này có nghĩa là việc triển khai có thể làm hỏng người dùng hiện có.

Data Connect tích hợp tính năng phân tích các thay đổi gây lỗi trong bản cập nhật trình kết nối vào Firebase CLI.

CLI phân tích các thay đổi đối với từng trình kết nối liên quan đến giản đồ của bạn và đưa ra một tập hợp thông báo đánh giá liên quan đến các thay đổi của trình kết nối có thể làm thay đổi hành vi của ứng dụng (thông báo ở cấp cảnh báo) hoặc có thể hoặc sẽ làm hỏng (thông báo ở cấp gây lỗi) các phiên bản trước của mã ứng dụng.

Ví dụ:

  • Các thay đổi của trình kết nối có thể làm thay đổi hành vi của ứng dụng bao gồm việc xoá một trường có thể rỗng khỏi một truy vấn mà không có chú thích giản đồ @retired.
  • Các thay đổi của trình kết nối có thể hoặc sẽ làm hỏng ứng dụng bao gồm việc thay đổi một biến thao tác có thể rỗng thành không rỗng mà không có giá trị mặc định hoặc thay đổi kiểu dữ liệu của một trường thành kiểu không tương thích (ví dụ: String thành Int).

Danh sách đầy đủ hơn về các tình huống ở cấp cảnh báo và cấp gây lỗi được cung cấp trong hướng dẫn tham khảo về CLI.

Làm theo quy trình triển khai

Bạn có thể làm việc trên một dự án Data Connect cả trong thư mục dự án cục bộ và trong bảng điều khiển Firebase.

Quy trình triển khai được đề xuất bao gồm:

  1. Liệt kê giản đồ và trình kết nối hiện được triển khai bằng firebase dataconnect:services:list.
  2. Quản lý mọi nội dung cập nhật giản đồ.
    1. Kiểm tra sự khác biệt về giản đồ SQL giữa cơ sở dữ liệu Cloud SQL và giản đồ Data Connect cục bộ bằng firebase dataconnect:sql:diff.
    2. Nếu cần, hãy thực hiện quá trình di chuyển giản đồ SQL bằng dataconnect:sql:migrate.
  3. Thực hiện triển khai giản đồ và kết nối bằng cách chạy firebase deploy, chỉ cho giản đồ, chỉ cho trình kết nối hoặc kết hợp các tài nguyên.

Triển khai và quản lý tài nguyên Data Connect

Bạn nên xác minh tài nguyên sản xuất trước khi thực hiện triển khai.

firebase dataconnect:services:list

Khi làm việc trong thư mục dự án cục bộ, bạn thường sẽ sử dụng lệnh firebase deploy để triển khai giản đồ và trình kết nối vào môi trường thực tế, với phản hồi tương tác.

Khi sử dụng bất kỳ lệnh deploy nào, cờ --only dataconnect cho phép bạn tách Data Connect hoạt động triển khai khỏi các sản phẩm khác trong dự án.

Triển khai bình thường

firebase deploy --only dataconnect

Trong quá trình triển khai bình thường này, Firebase CLI sẽ cố gắng triển khai giản đồ và trình kết nối.

Công cụ này xác thực rằng giản đồ mới không làm hỏng bất kỳ trình kết nối hiện có nào. Hãy làm theo các phương pháp hay nhất khi thực hiện các thay đổi gây lỗi.

Công cụ này cũng xác minh rằng giản đồ SQL đã được di chuyển trước khi cập nhật Data Connect giản đồ. Nếu không, công cụ này sẽ tự động nhắc bạn thực hiện mọi bước cần thiết để di chuyển giản đồ.

Triển khai cờ --force

firebase deploy --only dataconnect --force

Nếu không lo ngại về việc xác thực trình kết nối hoặc giản đồ SQL, bạn có thể chạy lại lệnh bằng --force để bỏ qua các xác thực này.

Lệnh triển khai --force vẫn kiểm tra xem giản đồ SQL có khớp với giản đồ Data Connect hay không, cảnh báo về khả năng không tương thích và nhắc nhở.

Triển khai tài nguyên đã chọn

Để triển khai với khả năng kiểm soát chi tiết hơn, hãy sử dụng cờ --only với đối số serviceId. Cách chỉ triển khai các thay đổi về giản đồ cho một dịch vụ cụ thể:

firebase deploy --only dataconnect:serviceId:schema

Bạn cũng có thể triển khai tất cả tài nguyên cho một trình kết nối và dịch vụ được chỉ định.

firebase deploy --only dataconnect:serviceId:connectorId

Cuối cùng, bạn có thể triển khai giản đồ và tất cả trình kết nối cho một dịch vụ.

firebase deploy --only dataconnect:serviceId

Khôi phục hoạt động triển khai

Để thực hiện khôi phục thủ công, hãy kiểm tra phiên bản trước của mã và triển khai phiên bản đó. Nếu hoạt động triển khai ban đầu bao gồm các thay đổi gây lỗi mang tính phá huỷ, thì bạn có thể không khôi phục được hoàn toàn mọi dữ liệu đã xoá.

Di chuyển giản đồ cơ sở dữ liệu

Nếu đang nhanh chóng tạo mẫu thử, thử nghiệm với giản đồ và biết rằng các thay đổi về giản đồ sẽ mang tính phá huỷ, thì bạn có thể lên kế hoạch sử dụng các công cụ Data Connect để xác minh các thay đổi và giám sát cách thực hiện các bản cập nhật.

So sánh các thay đổi về giản đồ SQL

Bạn có thể xác minh các thay đổi:

firebase dataconnect:sql:diff

Bạn có thể truyền danh sách các dịch vụ được phân tách bằng dấu phẩy.

Lệnh này so sánh giản đồ cục bộ cho một dịch vụ với giản đồ hiện tại của cơ sở dữ liệu Cloud SQL tương ứng. Nếu có sự khác biệt, lệnh này sẽ in ra các lệnh SQL sẽ được chạy để khắc phục sự khác biệt đó

Áp dụng thay đổi

Khi bạn hài lòng và sẵn sàng triển khai các thay đổi đối với thực thể giản đồ Cloud SQL, hãy đưa ra lệnh firebase dataconnect:sql:migrate. Bạn sẽ được nhắc phê duyệt các thay đổi.

firebase dataconnect:sql:migrate [serviceId]

Trong môi trường tương tác, các câu lệnh di chuyển SQL và lời nhắc hành động sẽ được hiển thị.

Di chuyển ở chế độ nghiêm ngặt hoặc tương thích

Trong một dự án hoàn toàn mới, chế độ xác thực giản đồ mặc định sẽ được áp dụng. Hành vi của lệnh migrate là áp dụng tất cả các thay đổi về giản đồ cơ sở dữ liệu mà giản đồ ứng dụng yêu cầu, sau đó nhắc bạn phê duyệt các thao tác không bắt buộc làm giảm giản đồ, bảng hoặc cột để buộc giản đồ cơ sở dữ liệu khớp chính xác với giản đồ ứng dụng.

Bạn có thể điều chỉnh hành vi này bằng cách sửa đổi tệp dataconnect.yaml. Huỷ nhận xét khoá schemaValidation và khai báo COMPATIBLE để chỉ áp dụng các thay đổi bắt buộc trong quá trình di chuyển.

schemaValidation: "COMPATIBLE"

Hoặc đặt hành vi thành STRICT để tất cả các thay đổi về giản đồ được áp dụng và giản đồ cơ sở dữ liệu của bạn bị buộc phải khớp với giản đồ ứng dụng.

schemaValidation: "STRICT"

Hãy xem tài liệu tham khảo về Data Connect CLI để biết thêm thông tin.

Cập nhật trình kết nối

Khi bạn chạy firebase deploy, CLI sẽ bắt đầu cập nhật các trình kết nối có thể áp dụng và đưa ra các thông báo đánh giá ở cấp cảnh báo (có thể ảnh hưởng đến hành vi của ứng dụng) và cấp gây lỗi (có thể hoặc chắc chắn gây lỗi).

Quản lý bản cập nhật trình kết nối bằng CLI

CLI có hành vi hơi khác nhau ở chế độ tương tác và chế độ không tương tác.

Như bạn có thể thấy, ở chế độ tương tác, CLI sẽ nhắc bạn chấp nhận tất cả thông báo. Bạn có thể ghi đè và buộc triển khai trình kết nối bằng cờ --force.

# Prompts for acceptance for any warning-level or breaking-level changes prior
# to deploying connectors.
firebase deploy --only dataconnect
# Will deploy connectors without prompting.
firebase deploy --only dataconnect --force

Ở chế độ không tương tác, CLI sẽ triển khai trình kết nối của bạn miễn là không có đánh giá ở cấp gây lỗi. Nếu không, tập lệnh của bạn sẽ thoát với nhật ký các thay đổi gây lỗi. Bạn có thể ghi đè và triển khai bằng cách đặt cờ --force.

# Will deploy connectors with warning-level changes. If any breaking changes
# are present, the deploy will fail and output any breaking changes
firebase deploy --only dataconnect --non-interactive
# Will deploy the connectors from the previous step, if the same issues are present.
firebase deploy --only dataconnect --non-interactive --force

Để biết thêm thông tin, hãy xem hướng dẫn tham khảo về CLI.

Các phương pháp hay nhất để quản lý giản đồ và trình kết nối

Firebase đề xuất một số phương pháp cần làm theo trong các Data Connect dự án.

Giảm thiểu các thay đổi gây lỗi

  • Firebase khuyên bạn nên giữ các tệp giản đồ Data Connect và trình kết nối trong hệ thống kiểm soát nguồn.
  • Tránh các thay đổi gây lỗi khi có thể. Sau đây là một số ví dụ thường gặp về các thay đổi gây lỗi:
    • Xoá một trường khỏi giản đồ
    • Đặt một trường có thể rỗng trong giản đồ thành không thể rỗng (tức là Int -> Int!)
    • Đổi tên một trường trong giản đồ.
  • Nếu cần xoá một trường khỏi giản đồ, hãy cân nhắc chia trường đó thành một vài hoạt động triển khai để giảm thiểu tác động:
    • Trước tiên, hãy xoá mọi tham chiếu đến trường trong trình kết nối và triển khai thay đổi.
    • Tiếp theo, hãy cập nhật ứng dụng để sử dụng các SDK mới được tạo.
    • Cuối cùng, hãy xoá trường trong tệp .gql giản đồ, di chuyển giản đồ SQL và triển khai thêm một lần nữa.

Sử dụng chế độ nghiêm ngặt khi làm việc với cơ sở dữ liệu mới

Nếu đang sử dụng Data Connect với một cơ sở dữ liệu mới và đang tích cực phát triển giản đồ ứng dụng, đồng thời muốn đảm bảo giản đồ cơ sở dữ liệu luôn khớp chính xác với giản đồ ứng dụng, thì bạn có thể chỉ định schemaValidation: "STRICT" trong dataconnect.yaml.

Điều này sẽ đảm bảo các thay đổi không bắt buộc cũng được áp dụng.

Sử dụng chế độ tương thích khi có dữ liệu sản xuất trong cơ sở dữ liệu

Nếu đang thực hiện các thay đổi đối với cơ sở dữ liệu chứa dữ liệu sản xuất, bạn nên thực thi quá trình di chuyển giản đồ ở chế độ tương thích để đảm bảo dữ liệu hiện có không bị xoá. Bạn có thể chỉ định schemaValidation: "COMPATIBLE" trong dataconnect.yaml.

Ở chế độ tương thích, chỉ những thay đổi bắt buộc về quá trình di chuyển giản đồ mới được áp dụng cho cơ sở dữ liệu.

  • DROP SCHEMA, DROP TABLE và DROP COLUMN được coi là các câu lệnh không bắt buộc và sẽ không được tạo cho gói của bạn, ngay cả khi giản đồ cơ sở dữ liệu chứa các giản đồ, bảng hoặc cột không được xác định trong giản đồ ứng dụng.
  • Nếu bảng cơ sở dữ liệu chứa một cột không rỗng không có trong giản đồ ứng dụng, thì ràng buộc NOT NULL sẽ bị xoá để dữ liệu vẫn có thể được thêm vào bảng bằng các trình kết nối mà bạn đã xác định.

Bước tiếp theo là gì?

  • Việc triển khai và quản lý mã ứng dụng mà bạn phát triển bằng các SDK đã tạo được đề cập trong hướng dẫn dành cho Android, iOS, web, và Flutter.
  • Để biết thêm thông tin về công cụ triển khai, hãy xem tài liệu tham khảo về Data Connect CLI và Data Connect tệp cấu hình.