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 tệp .gql)
  • một số trình kết nối (được khai báo trong tệp .gql, được định cấu hình trong tệp connector.yaml).

Giản đồ SQL là nguồn thông tin đáng tin cậy cho dữ liệu của bạn, 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à máy khách 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 rõ về việc triển khai, bạn cần lưu ý các khái niệm chính về lược đồ và trình kết nối.

Triển khai giản đồ

Việc triển khai giản đồ Data Connect sẽ ảnh hưởng đến giản đồ SQL cho cơ sở dữ liệu Cloud SQL của bạn. 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 cơ sở dữ liệu mới hay cần điều chỉnh cơ sở dữ liệu hiện có mà không làm mất dữ liệu.

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

  • Quy trình xác thực ở chế độ 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ì giản đồ ứng dụng mới có thể được cập nhật. Mọi bảng hoặc cột không được dùng trong giản đồ Data Connect sẽ bị xoá khỏi cơ sở dữ liệu.

  • Hoạt động xác thực chế độ 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 trước khi giản đồ ứng dụng có thể được cập nhật; 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à các hoạt động di chuyển giản đồ chỉ ảnh hưởng đến những bảng và cột được tham chiếu trong giản đồ ứng dụng của bạn. Các phần tử trong cơ sở dữ liệu không được giản đồ ứng dụng của bạn sử dụng sẽ không bị sửa đổi. Do đó, sau khi triển khai, cơ sở dữ liệu của bạn có thể chứa các mục không dùng đến:

    • 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 thao tác Data Connect 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 gián đoạn người dùng hiện tại.

Data Connect tích hợp quy trình 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 CLI Firebase.

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 bộ thông báo đánh giá liên quan đến các thay đổi của trình kết nối có thể thay đổi hành vi của ứng dụng (các thông báo ở cấp cảnh báo) hoặc có thể hoặc sẽ làm hỏng (các thông báo ở cấp làm hỏng) các phiên bản trước của mã ứng dụng.

Ví dụ:

  • Những thay đổi về 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 truy vấn mà không có chú thích giản đồ @retired.
  • Những thay đổi về trình kết nối có thể hoặc sẽ làm gián đoạn các ứ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 dữ liệu không tương thích (ví dụ: String thành Int).

Một danh sách đầy đủ hơn về các tình huống ở cấp cảnh báo và cấp thay đổi có thể 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 trong cả thư mục dự án cục bộ và bảng điều khiển Firebase.

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

  1. Liệt kê các giản đồ và trình kết nối hiện đang được triển khai bằng firebase dataconnect:services:list.
  2. Quản lý mọi bản 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 quy trình di chuyển giản đồ SQL bằng dataconnect:sql:migrate.
  3. Thực hiện việc triển khai giản đồ và kết nối bằng cách chạy firebase deploy, cho giản đồ, trình kết nối hoặc tổ hợp tài nguyên.

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

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

firebase dataconnect:services:list

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

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

Triển khai bình thường

firebase deploy --only dataconnect

Trong quá trình triển khai bình thường này, CLI Firebase sẽ tìm cách triển khai lược đồ và các trình kết nối của bạn.

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

Thao tác này cũng xác minh rằng lược đồ SQL đã được di chuyển trước khi cập nhật lược đồ Data Connect. 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 --force cờ

firebase deploy --only dataconnect --force

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

Hoạt động 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ề sự không tương thích và nhắc nhở.

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

Để triển khai với quyền 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ụ thể.

firebase deploy --only dataconnect:serviceId:connectorId

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

firebase deploy --only dataconnect:serviceId

Quay lại một đợt triển khai

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

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

Nếu đang tạo mẫu nhanh, thử nghiệm với các giản đồ và biết rằng các thay đổi về giản đồ của bạn có tính huỷ diệt, 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 một 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ộ của 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, nó 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 phiên bản Cloud SQL giản đồ, 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ẽ xuất hiện.

Di chuyển ở chế độ nghiêm ngặt hoặc chế độ 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 của bạn yêu cầu, sau đó nhắc bạn phê duyệt các thao tác không bắt buộc để loại bỏ giản đồ, bảng hoặc cột nhằm buộc giản đồ cơ sở dữ liệu khớp chính xác với giản đồ ứng dụng của bạn.

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 dấu 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 đồ đều được áp dụng và giản đồ cơ sở dữ liệu của bạn 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ề CLI Data Connect để biết thêm thông tin.

Cập nhật đầu 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 hiện hành 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 độ thay đổi có thể gây lỗi (có thể hoặc chắc chắn gây lỗi).

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

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

Như bạn có thể dự đoán, trong chế độ tương tác, CLI sẽ nhắc bạn chấp nhận tất cả cá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ó các đánh giá ở cấp độ ngắt. Nếu không, tập lệnh của bạn sẽ thoát với nhật ký về 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 tuân thủ trong các dự án Data Connect của bạn.

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

  • Firebase khuyến nghị bạn lưu giữ giản đồ Data Connect và các tệp trình kết nối trong tính nă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 ảnh hưởng:
    • Xoá một trường khỏi giản đồ
    • Chuyển một trường có thể rỗng trong lược đồ của bạn thành trường không thể rỗng (tức là Int -> Int!)
    • Đổi tên một trường trong giản đồ.
  • Nếu bạn cần xoá một trường khỏi giản đồ, hãy cân nhắc việc chia trường đó thành một vài lượt triển khai để giảm thiểu tác động:
    • Trước tiên, hãy xoá mọi thông tin tham chiếu đến trường này trong các trình kết nối của bạn 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 lược đồ .gql, di chuyển lược đồ SQL và triển khai lại.

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 bạn muốn đảm bảo giản đồ cơ sở dữ liệu hoàn toàn phù hợp với giản đồ ứng dụng, thì bạn có thể chỉ định schemaValidation: "STRICT" trong dataconnect.yaml.

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

Sử dụng chế độ tương thích khi bạn 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 một cơ sở dữ liệu chứa dữ liệu sản xuất, bạn nên thực thi các hoạt động di chuyển giản đồ ở chế độ tương thích để đảm bảo dữ liệu hiện có không bị loại bỏ. 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ề quy trình di chuyển giản đồ mới được áp dụng cho cơ sở dữ liệu của bạn.

  • 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 kế hoạch 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 của bạn chứa một cột không có giá trị rỗng như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.

Tiếp theo là gì?