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

ติดตั้งใช้งานทรัพยากรที่เลือก

หากต้องการทำให้การทําให้ใช้งานได้มีการควบคุมที่ละเอียดยิ่งขึ้น ให้ใช้ Flag --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"

ดูข้อมูลเพิ่มเติมได้ที่Data Connect CLI Reference

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

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

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

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

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

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