ติดตั้งใช้งานและจัดการสคีมาและเครื่องมือเชื่อมต่อของ 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ทรัพยากร

คุณควรยืนยันทรัพยากรการผลิตก่อนทำการติดตั้งใช้งาน

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

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

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

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

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

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

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

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

ขั้นตอนถัดไปคือ