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

บริการ Firebase SQL Connect มีคอมโพเนนต์หลัก 3 อย่าง ได้แก่

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

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

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

แนวคิดสำคัญเกี่ยวกับการทำให้ใช้งานได้

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

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

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

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

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

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

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

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

การทำให้เครื่องมือเชื่อมต่อใช้งานได้

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

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

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

ตัวอย่างเช่น

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

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

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

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

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

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

ทำให้ทรัพยากร SQL Connect ใช้งานได้และจัดการทรัพยากรดังกล่าว

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

firebase dataconnect:services:list

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

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

การทำให้ใช้งานได้ตามปกติ

firebase deploy --only dataconnect

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

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

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

การทำให้ใช้งานได้ด้วยแฟล็ก --force

firebase deploy --only dataconnect --force

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

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

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

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

firebase deploy --only dataconnect:serviceId:schema

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

firebase deploy --only dataconnect:serviceId:connectorId

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

firebase deploy --only dataconnect:serviceId

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

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

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

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

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

คุณสามารถตรวจสอบการเปลี่ยนแปลงได้ดังนี้

firebase dataconnect:sql:diff

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

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

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

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

firebase dataconnect:sql:migrate [serviceId]

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

ย้ายข้อมูลในโหมดจำกัดหรือโหมดเข้ากันได้

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

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

schemaValidation: "COMPATIBLE"

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

schemaValidation: "STRICT"

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

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

เมื่อคุณเรียกใช้ 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 แนะนำแนวทางปฏิบัติบางอย่างที่คุณควรทำตามในโปรเจ็กต์ SQL Connect

ลดการเปลี่ยนแปลงที่ทำให้ใช้งานไม่ได้

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

ใช้โหมดเข้มงวดเมื่อใช้ฐานข้อมูลใหม่

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

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

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

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

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

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

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

  • การทำให้โค้ดไคลเอ็นต์ที่คุณพัฒนาด้วย SDK ที่สร้างขึ้นใช้งานได้และการจัดการโค้ดดังกล่าวจะ อธิบายไว้ในคู่มือสำหรับ Android, iOS, เว็บ และ Flutter
  • ดูข้อมูลเพิ่มเติมเกี่ยวกับเครื่องมือการทำให้ใช้งานได้ในข้อมูลอ้างอิง SQL Connect CLI และข้อมูลอ้างอิงไฟล์การกำหนดค่า SQL Connect