ติดตั้งใช้งานและจัดการสคีมาและเครื่องมือเชื่อมต่อของ Data Connect

Firebase Data Connectบริการมีองค์ประกอบหลัก 3 อย่าง ได้แก่

  • ฐานข้อมูล PostgreSQL พื้นฐานที่มีสคีมา SQL ของตัวเอง
  • Data Connect สคีมาแอปพลิเคชัน (ประกาศในไฟล์ .gql)
  • ตัวเชื่อมต่อจำนวนหนึ่ง (ประกาศในไฟล์ .gql และกำหนดค่าในไฟล์ connector.yaml)

สคีมา SQL คือแหล่งข้อมูลที่เชื่อถือได้สำหรับข้อมูลของคุณ สคีมา Data Connect คือวิธีที่เครื่องมือเชื่อมต่อจะดูข้อมูลนั้นได้ และเครื่องมือเชื่อมต่อจะประกาศ API ที่ไคลเอ็นต์ใช้เพื่อเข้าถึงข้อมูลนั้นได้

เมื่อติดตั้งใช้งานบริการ Data Connect ด้วย CLI คุณจะต้อง ย้ายข้อมูลสคีมา SQL จากนั้นอัปเดตสคีมา Data Connect แล้ว อัปเดตเครื่องมือเชื่อมต่อแต่ละตัว

แนวคิดสำคัญในการติดตั้งใช้งาน

หากต้องการทำความเข้าใจการทำให้ใช้งานได้อย่างถ่องแท้ คุณควรทราบแนวคิดสำคัญเกี่ยวกับสคีมาและเครื่องมือเชื่อมต่อ

การทำให้สคีมาใช้งานได้

การติดตั้งใช้งานสคีมา Data Connect จะส่งผลต่อสคีมา SQL สำหรับฐานข้อมูล Cloud SQL Data Connect ช่วยให้คุณย้ายข้อมูลสคีมา ระหว่างการติดตั้งใช้งาน ไม่ว่าคุณจะทำงานกับฐานข้อมูลใหม่หรือต้องการ ปรับฐานข้อมูลที่มีอยู่โดยไม่ทำให้ข้อมูลเสียหาย

Data Connectการย้ายข้อมูลสคีมามีโหมดการตรวจสอบสคีมา 2 โหมด ได้แก่ เข้มงวดและเข้ากันได้

  • การตรวจสอบโหมดเข้มงวดกำหนดให้สคีมาฐานข้อมูลต้องตรงกับสคีมาแอปพลิเคชันทุกประการก่อนจึงจะอัปเดตสคีมาแอปพลิเคชันได้ ระบบจะลบตารางหรือคอลัมน์ที่ไม่ได้ใช้ในData Connectสคีมา ออกจากฐานข้อมูล

  • การตรวจสอบโหมดที่เข้ากันได้กำหนดให้สคีมาฐานข้อมูลต้องเข้ากันได้ กับสคีมาแอปพลิเคชันก่อนที่จะอัปเดตสคีมาแอปพลิเคชันได้ การเปลี่ยนแปลงเพิ่มเติมใดๆ ที่ดรอปสคีมา ตาราง หรือคอลัมน์เป็นตัวเลือก

    ความเข้ากันได้หมายความว่าการย้ายข้อมูลสคีมาจะมีผลเฉพาะตารางและคอลัมน์ ที่อ้างอิงในสคีมาแอปพลิเคชัน ระบบจะไม่แก้ไของค์ประกอบในฐานข้อมูลที่ไม่ได้ใช้โดยสคีมาแอปพลิเคชัน ดังนั้นหลังจาก การติดตั้งใช้งาน ฐานข้อมูลอาจมีรายการที่ไม่ได้ใช้ต่อไปนี้

    • สคีมา
    • ตาราง
    • คอลัมน์

การติดตั้งใช้งานเครื่องมือเชื่อมต่อ

Data Connect ไม่มีการส่งการค้นหาและการเปลี่ยนแปลงโดยโค้ดฝั่งไคลเอ็นต์ และดำเนินการในเซิร์ฟเวอร์ แต่เมื่อใช้งานแล้ว ระบบจะจัดเก็บData Connect การดำเนินการเหล่านี้ไว้ในเซิร์ฟเวอร์ เช่น Cloud Functions ซึ่งหมายความว่า การติดตั้งใช้งานอาจทำให้ผู้ใช้เดิมใช้งานไม่ได้

Data Connect ผสานรวมการวิเคราะห์การเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นในระบบในการอัปเดตเครื่องมือเชื่อมต่อเข้ากับ Firebase CLI

CLI จะวิเคราะห์การเปลี่ยนแปลงของตัวเชื่อมต่อแต่ละรายการที่เกี่ยวข้องกับสคีมาของคุณ และออกชุดข้อความการประเมินที่เกี่ยวข้องกับการเปลี่ยนแปลงของตัวเชื่อมต่อที่อาจเปลี่ยนลักษณะการทำงานของไคลเอ็นต์ (ข้อความอยู่ในระดับคำเตือน) หรืออาจหรือจะทำให้โค้ดไคลเอ็นต์เวอร์ชันก่อนหน้าใช้งานไม่ได้ (ข้อความอยู่ในระดับการหยุดทำงาน)

เช่น

  • การเปลี่ยนแปลงตัวเชื่อมต่อที่อาจเปลี่ยนลักษณะการทำงานของไคลเอ็นต์ ได้แก่ การนำฟิลด์ที่อนุญาตให้เป็น Null ออกจากคําค้นหาโดยไม่มี@retiredคำอธิบายประกอบของสคีมา
  • การเปลี่ยนแปลงตัวเชื่อมต่อที่อาจหรือจะทำให้ไคลเอ็นต์ใช้งานไม่ได้ ได้แก่ การเปลี่ยนตัวแปรการดำเนินการที่อนุญาตให้เป็น Null เป็นตัวแปรที่ไม่ใช่ Null โดยไม่มีค่าเริ่มต้น หรือการเปลี่ยนประเภทข้อมูลของฟิลด์เป็นประเภทที่ไม่เข้ากัน (เช่น String เป็น Int)

ดูรายการสถานการณ์ระดับคำเตือนและระดับการหยุดทำงานที่ครอบคลุมมากขึ้นได้ ในคู่มืออ้างอิง CLI

ทำตามเวิร์กโฟลว์การติดตั้งใช้งาน

คุณสามารถทำงานในData Connectโปรเจ็กต์ได้ทั้งในไดเรกทอรีโปรเจ็กต์ที่อยู่ในเครื่อง และในคอนโซล Firebase

ขั้นตอนการติดตั้งใช้งานที่แนะนำมีดังนี้

  1. แสดงสคีมาและตัวเชื่อมต่อที่ทำให้ใช้งานได้อยู่ในปัจจุบันด้วย firebase dataconnect:services:list
  2. การจัดการการอัปเดตสคีมา
    1. ตรวจสอบความแตกต่างของสคีมา SQL ระหว่างฐานข้อมูล Cloud SQL กับสคีมา Data Connect ในเครื่องด้วย firebase dataconnect:sql:diff
    2. หากจำเป็น ให้ทำการย้ายข้อมูลสคีมา SQL ด้วย dataconnect:sql:migrate
  3. การติดตั้งใช้งานสคีมาและการเชื่อมต่อโดยการเรียกใช้ firebase deploy สำหรับสคีมา ตัวเชื่อมต่อ หรือการผสมผสานของทรัพยากร

นำData Connectทรัพยากรไปใช้และจัดการ

คุณควรตรวจสอบทรัพยากร Production ก่อนทำการติดตั้งใช้งาน

firebase dataconnect:services:list

เมื่อทำงานในไดเรกทอรีโปรเจ็กต์ที่อยู่ในเครื่อง โดยทั่วไปคุณจะใช้คำสั่ง firebase deploy เพื่อทำให้สคีมาและตัวเชื่อมต่อใช้งานได้ในเวอร์ชันที่ใช้งานจริง พร้อมความคิดเห็นแบบอินเทอร์แอกทีฟ

การใช้คำสั่ง deploy ใดก็ตาม แฟล็ก --only dataconnect จะช่วยให้คุณแยกการติดตั้งใช้งาน Data Connect ออกจากผลิตภัณฑ์อื่นๆ ในโปรเจ็กต์ได้

การติดตั้งใช้งานปกติ

firebase deploy --only dataconnect

ในการทำให้ใช้งานได้ตามปกติ Firebase CLI จะพยายามทำให้ใช้งานได้สคีมา และเครื่องมือเชื่อมต่อ

ซึ่งจะตรวจสอบว่าสคีมาใหม่ไม่ทำให้ตัวเชื่อมต่อที่มีอยู่เสียหาย ทำตามแนวทางปฏิบัติแนะนำเมื่อทำการเปลี่ยนแปลงที่ทำให้เกิดข้อผิดพลาด

นอกจากนี้ยังตรวจสอบว่าได้ย้ายข้อมูลสคีมา SQL แล้วก่อนที่จะอัปเดตData Connectสคีมา หากยังไม่ได้ดำเนินการ ระบบจะแจ้งให้คุณทำตามขั้นตอนที่จำเป็นเพื่อย้ายข้อมูลสคีมาโดยอัตโนมัติ

การเปิดตัวฟีเจอร์ที่อยู่ภายใต้--force

firebase deploy --only dataconnect --force

หากไม่กังวลเกี่ยวกับการตรวจสอบตัวเชื่อมต่อหรือสคีมา SQL คุณสามารถ เรียกใช้คำสั่งอีกครั้งด้วย --force เพื่อไม่สนใจการตรวจสอบดังกล่าว

--force deploy ยังคงตรวจสอบว่าสคีมา SQL ตรงกับสคีมา Data Connect หรือไม่ เตือนถึงความไม่เข้ากัน และแจ้งให้ดำเนินการ

ทำให้ทรัพยากรที่เลือกใช้งานได้

หากต้องการทำให้ใช้งานได้ด้วยการควบคุมแบบละเอียดมากขึ้น ให้ใช้แฟล็ก --only กับอาร์กิวเมนต์ serviceId หากต้องการใช้เฉพาะการเปลี่ยนแปลงสคีมาสำหรับบริการหนึ่งๆ ให้ทำดังนี้

firebase deploy --only dataconnect:serviceId:schema

นอกจากนี้ คุณยังสามารถทำให้ใช้งานได้ทรัพยากรทั้งหมดสำหรับเครื่องมือเชื่อมต่อและบริการที่ระบุได้ด้วย

firebase deploy --only dataconnect:serviceId:connectorId

สุดท้าย คุณสามารถทำให้ใช้งานได้สคีมาและเครื่องมือเชื่อมต่อทั้งหมดสำหรับบริการเดียวได้

firebase deploy --only dataconnect:serviceId

ย้อนกลับการทำให้ใช้งานได้

หากต้องการย้อนกลับด้วยตนเอง ให้ตรวจสอบโค้ดเวอร์ชันก่อนหน้าแล้วทำให้ใช้งานได้ หากการติดตั้งใช้งานเดิมมีการเปลี่ยนแปลงที่ทำให้เกิดข้อขัดข้องที่ทำลายข้อมูล คุณอาจกู้คืนข้อมูลที่ลบไปแล้วทั้งหมดไม่ได้

ย้ายสคีมาฐานข้อมูล

หากคุณกำลังสร้างต้นแบบอย่างรวดเร็ว ทดลองใช้สคีมา และทราบว่าการเปลี่ยนแปลงสคีมา จะทำให้เกิดความเสียหาย คุณสามารถวางแผนที่จะใช้Data Connectเครื่องมือเพื่อ ยืนยันการเปลี่ยนแปลงและดูแลการอัปเดตได้

เปรียบเทียบการเปลี่ยนแปลงสคีมา SQL

คุณยืนยันการเปลี่ยนแปลงได้โดยทำดังนี้

firebase dataconnect:sql:diff

คุณส่งรายการบริการที่คั่นด้วยคอมมาได้

คำสั่งจะเปรียบเทียบสคีมาในเครื่องสำหรับบริการกับสคีมาปัจจุบันของฐานข้อมูล Cloud SQL ที่เกี่ยวข้อง หากมีความแตกต่าง ระบบจะพิมพ์คำสั่ง SQL ที่จะเรียกใช้เพื่อแก้ไขความแตกต่างนั้น

ใช้การเปลี่ยนแปลง

เมื่อพอใจและพร้อมที่จะนำการเปลี่ยนแปลงไปใช้กับสคีมาในอินสแตนซ์ Cloud SQL แล้ว ให้เรียกใช้firebase dataconnect:sql:migrateคำสั่ง ระบบจะแจ้งให้คุณอนุมัติการเปลี่ยนแปลง

firebase dataconnect:sql:migrate [serviceId]

ในสภาพแวดล้อมแบบอินเทอร์แอกทีฟ ระบบจะแสดงคำสั่งการย้ายข้อมูล SQL และพรอมต์การดำเนินการ

ย้ายข้อมูลในโหมดเข้มงวดหรือโหมดที่เข้ากันได้

ในโปรเจ็กต์ใหม่เอี่ยม โหมดการตรวจสอบสคีมาเริ่มต้นจะมีผล ลักษณะการทำงานของคำสั่ง migrate คือการใช้การเปลี่ยนแปลงสคีมาฐานข้อมูลทั้งหมดที่สคีมาแอปพลิเคชันของคุณต้องการ จากนั้นจะแจ้งให้คุณอนุมัติการดำเนินการที่ไม่บังคับซึ่งจะทิ้งสคีมา ตาราง หรือคอลัมน์ เพื่อบังคับให้สคีมาฐานข้อมูลตรงกับสคีมาแอปพลิเคชันของคุณอย่างแน่นอน

คุณปรับลักษณะการทำงานนี้ได้โดยแก้ไขไฟล์ dataconnect.yaml ยกเลิกการแสดงความคิดเห็นของคีย์ schemaValidation และประกาศ COMPATIBLE เพื่อให้ระบบใช้เฉพาะการเปลี่ยนแปลงที่จำเป็นในการย้ายข้อมูล

schemaValidation: "COMPATIBLE"

หรือตั้งค่าลักษณะการทำงานเป็น STRICT เพื่อให้ระบบใช้การเปลี่ยนแปลงสคีมาทั้งหมด และบังคับให้สคีมาฐานข้อมูลตรงกับสคีมาแอปพลิเคชัน

schemaValidation: "STRICT"

ดูข้อมูลเพิ่มเติมได้ที่การอ้างอิง CLI ของ Data Connect

อัปเดตเครื่องมือเชื่อมต่อ

เมื่อเรียกใช้ firebase deploy CLI จะเริ่มอัปเดตตัวเชื่อมต่อที่เกี่ยวข้องและออกข้อความการประเมินระดับคำเตือนที่เกี่ยวข้อง (อาจส่งผลต่อลักษณะการทำงานของไคลเอ็นต์) และระดับการหยุดทำงาน (อาจหรือหยุดทำงานอย่างแน่นอน)

จัดการการอัปเดตตัวเชื่อมต่อด้วย CLI

CLI จะมีลักษณะการทำงานที่แตกต่างกันเล็กน้อยในโหมดอินเทอร์แอกทีฟและโหมดที่ไม่ใช่ อินเทอร์แอกทีฟ

ในโหมดอินเทอร์แอกทีฟ CLI จะแจ้งให้คุณยอมรับข้อความทั้งหมด ตามที่คาดไว้ คุณสามารถลบล้างและบังคับใช้การทำให้ใช้งานได้ของตัวเชื่อมต่อด้วย--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

ในโหมดที่ไม่โต้ตอบ CLI จะทำให้ใช้งานได้ตัวเชื่อมต่อของคุณตราบใดที่ไม่มีการประเมินระดับการหยุดทำงาน มิเช่นนั้น สคริปต์จะออกพร้อมกับบันทึก การเปลี่ยนแปลงที่ทำให้เกิดข้อขัดข้อง คุณลบล้างและทำให้ใช้งานได้โดยตั้งค่าแฟล็ก --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

ดูข้อมูลเพิ่มเติมได้ที่คู่มืออ้างอิง CLI

แนวทางปฏิบัติแนะนำสำหรับการจัดการสคีมาและตัวเชื่อมต่อ

Firebase ขอแนะนำแนวทางปฏิบัติบางอย่างที่ควรทำตามในData Connect โปรเจ็กต์

ลดการเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นในระบบ

  • Firebase ขอแนะนำให้เก็บData Connectสคีมาและไฟล์ตัวเชื่อมต่อไว้ในการควบคุมแหล่งที่มา
  • หลีกเลี่ยงการเปลี่ยนแปลงที่ทำให้เกิดข้อขัดข้องเมื่อเป็นไปได้ ตัวอย่างการเปลี่ยนแปลงที่ทำให้เกิดข้อขัดข้องที่พบบ่อยมีดังนี้
    • การนำฟิลด์ออกจากสคีมา
    • การทำให้ฟิลด์ที่อนุญาตให้เป็นค่าว่างในสคีมาเป็นฟิลด์ที่ไม่อนุญาตให้เป็นค่าว่าง (เช่น Int -> Int!)
    • การเปลี่ยนชื่อฟิลด์ในสคีมา
  • หากจำเป็นต้องนำฟิลด์ออกจากสคีมา ให้พิจารณาแยกฟิลด์ ออกเป็นการติดตั้งใช้งาน 2-3 รายการเพื่อลดผลกระทบ
    • ก่อนอื่น ให้นำการอ้างอิงฟิลด์ในเครื่องมือเชื่อมต่อออก แล้วจึงนำการเปลี่ยนแปลงไปใช้
    • จากนั้นอัปเดตแอปเพื่อใช้ SDK ที่สร้างขึ้นใหม่
    • สุดท้าย ให้นำฟิลด์ในไฟล์สคีมา .gql ออก ย้ายข้อมูลสคีมา SQL แล้วทําการติดตั้งใช้งานอีกครั้ง

ใช้โหมดเข้มงวดเมื่อทำงานกับฐานข้อมูลใหม่

หากคุณใช้ Data Connect กับฐานข้อมูลใหม่และกำลังพัฒนาสคีมาแอปพลิเคชันอยู่ และต้องการให้สคีมาฐานข้อมูล สอดคล้องกับสคีมาแอปพลิเคชันทุกประการ คุณสามารถระบุ schemaValidation: "STRICT" ใน dataconnect.yaml ได้

ซึ่งจะช่วยให้มั่นใจได้ว่าระบบจะใช้การเปลี่ยนแปลงที่ไม่บังคับด้วย

ใช้โหมดที่เข้ากันได้เมื่อมีข้อมูลการผลิตในฐานข้อมูล

หากคุณทำการเปลี่ยนแปลงฐานข้อมูลที่มีข้อมูลการผลิต เราขอแนะนำให้คุณดำเนินการย้ายข้อมูลสคีมาในโหมดที่เข้ากันได้ เพื่อให้มั่นใจว่าระบบจะไม่ทิ้งข้อมูลที่มีอยู่ คุณระบุ schemaValidation: "COMPATIBLE" ใน dataconnect.yaml ได้

ในโหมดที่เข้ากันได้ ระบบจะใช้การเปลี่ยนแปลงการย้ายข้อมูลสคีมาที่จำเป็นเท่านั้นกับฐานข้อมูล

  • DROP SCHEMA, DROP TABLE และ DROP COLUMN ถือเป็นคำสั่งที่ไม่บังคับ และจะไม่สร้างขึ้นสำหรับแผนของคุณ แม้ว่าสคีมาฐานข้อมูล จะมีสคีมา ตาราง หรือคอลัมน์ที่ไม่ได้กำหนดไว้ในสคีมาแอปพลิเคชันก็ตาม
  • หากตารางฐานข้อมูลมีคอลัมน์ที่ไม่ใช่ค่า Null ซึ่งไม่ได้รวมอยู่ในสคีมาแอปพลิเคชัน ระบบจะนำข้อจํากัด NOT NULL ออกเพื่อให้ยังคงเพิ่มข้อมูลลงในตารางด้วยตัวเชื่อมต่อที่คุณกําหนดได้

ขั้นตอนต่อไปคืออะไร