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

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

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

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