שילוב של Spanner עם Liquibase

בדף הזה מוסבר איך לנהל שינויים בסכימת מסד נתונים של Spanner באמצעות Liquibase עבור מסדי נתונים עם ניב GoogleSQL ומסדי נתונים עם ניב PostgreSQL.

‫Liquibase היא ספרייה בקוד פתוח שאינה תלויה במסד נתונים, ומאפשרת לעקוב אחרי שינויים בסכימת מסד נתונים, לנהל אותם ולהחיל אותם. הוא תומך ב-SQL וגם בפורמטים הצהרתיים כמו XML,‏ YAML ו-JSON.

‫Liquibase יכול לטרגט מסדי נתונים של Spanner. הוא תומך בכל התכונות של Spanner, עם כמה מגבלות.

  • מידע על מגבלות כלליות מופיע במאמר בנושא מגבלות.
  • מידע נוסף על מסדי נתונים בניב PostgreSQL, כמו דרישות Liquibase, סוגי שינויים נתמכים ומגבלות, זמין במאמר PGAdapter ו-Liquibase.

התקנת Liquibase

כדי להשתמש ב-Liquibase עם מסדי נתונים בניב GoogleSQL, צריך להתקין את התוסף Spanner Liquibase. במסדי נתונים של ניב PostgreSQL, ‏ Liquibase יכול להשתמש בתמיכה המובנית שלו ב-PostgreSQL בשילוב עם PGAdapter.

GoogleSQL

  1. פועלים לפי ההוראות במסמכי Liquibase כדי להתקין ולהגדיר את Liquibase, וכדי לצלם תמונת מצב של מסד הנתונים.

  2. עוברים לדף הגרסאות של Spanner Liquibase Extension ב-GitHub ובוחרים את הגרסה האחרונה.

  3. בוחרים ומורידים את קובץ ה-JAR עם השם liquibase-spanner-x.y.z-all.jar, כאשר x.y.z מייצג את מספר הגרסה של התוסף. לדוגמה, liquibase-spanner-4.17.0-all.jar.

  4. ממקמים את קובץ ה-JAR שהורדתם בספריית lib של Liquibase. קובץ ה-JAR כולל את התוסף, את Spanner SDK ואת מנהל ההתקן של Spanner JDBC.

בקובץ התצורה liquibase.properties, מגדירים את המאפיין url באופן הבא.

 jdbc:cloudspanner:/projects/PROJECT/instances/INSTANCE/databases/DATABASE

קובץ התצורה liquibase.properties יכול להכיל רק את המאפיין הזה. מאפיינים אחרים הם אופציונליים.

PostgreSQL

  1. מוודאים ש-PGAdapter מופעל ופועל במחשב שבו מתקינים את Liquibase. מידע נוסף זמין במאמר בנושא הפעלת PGAdapter.

  2. פועלים לפי ההוראות במסמכי Liquibase כדי להתקין ולהגדיר את Liquibase, וכדי לצלם תמונת מצב של מסד הנתונים.

בקובץ התצורה liquibase.properties, מגדירים את המאפיין url באופן הבא.

  jdbc:postgresql://localhost:5432/DATABASE_NAME?options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction

קובץ התצורה liquibase.properties יכול להכיל רק את המאפיין הזה. מאפיינים אחרים הם אופציונליים.

url המחרוזת חייבת לכלול options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction כי Spanner לא תומך בעסקאות DDL, והמחרוזת הזו מבטיחה שעסקאות DDL יומרו לחבילות DDL. מידע נוסף זמין במאמר בנושא אפשרויות DDL ל-PGAdapter.

עיון בדוגמאות של Liquibase

GoogleSQL

קובץ יומן השינויים לדוגמה changelog.yaml שכלול בתוסף GoogleSQL Liquibase מדגים הרבה מהתכונות של Liquibase ומראה איך להשתמש בהן עם Spanner.

PostgreSQL

בקובץ יומן השינויים לדוגמה dbchangelog.xml שזמין במאגר GitHub של PGAdapter ו-Liquibase מודגמות רבות מהתכונות של Liquibase ומוסבר איך להשתמש בהן עם Spanner.

מדריך למתחילים בנושא Liquibase

במדריך למתחילים הזה מוסבר איך להשתמש ב-Liquibase כדי להוסיף טבלה Singers למסד נתונים.

לפני שמתחילים

  • חשוב לוודא שהשלמתם את השלבים הקודמים להתקנה של Liquibase.

  • יוצרים מכונת Spanner.

  • יוצרים מסד נתונים בניב GoogleSQL או בניב PostgreSQL.

  • במסדי נתונים של ניב PostgreSQL בלבד, מוודאים ש-PGAdapter מופעל ופועל באותו מחשב שבו מותקן Liquibase. מידע נוסף זמין במאמר בנושא הפעלת PGAdapter.

  • במסדי נתונים של ניב PostgreSQL בלבד, משתמשים בסקריפט create_database_change_log.sql כדי ליצור את טבלאות המטא-נתונים databasechangeloglock ו-databasechangelog. צריך ליצור את הטבלאות האלה כדי להחליף את הטבלאות ש-Liquibase יוצר באופן אוטומטי במסד הנתונים. הסיבה לכך היא לוודא שנעשה שימוש בסוגי הנתונים הנכונים של PostgreSQL עבור Spanner בטבלאות האלה.

    אפשר להריץ את הסקריפט באמצעות הפקודה הבאה:

    psql -h localhost -d DATABASE_NAME -f create_database_change_log.sql

  • כדי לתת לתוסף Spanner Liquibase גישה זמנית ל-API באמצעות פרטי הכניסה שלכם ב-Spanner, מריצים את הפקודה gcloud הבאה:

    gcloud auth application-default login

יצירת קובץ changelog.yaml

  1. מזינים את קוד ה-YAML הבא בעורך המועדף.

    databaseChangeLog:
  - preConditions:
     onFail: HALT
     onError: HALT

  - changeSet:
     id: create-singers-table
     author: spanner-examples
     changes:
       - createTable:
          tableName: Singers
          columns:
            -  column:
                name:    SingerId
                type:    BIGINT
                constraints:
                  primaryKey: true
                  primaryKeyName: pk_Singers
            -  column:
                name:    Name
                type:    VARCHAR(255)

    קובץ ה-YAML הזה מגדיר טבלה בשם Singers עם מפתח ראשי SingerId ועמודה בשם Name לאחסון שם הזמר.

    במסדי נתונים של ניב PostgreSQL, מומלץ להשתמש באותיות קטנות בלבד בשמות של טבלאות ועמודות. מידע נוסף זמין במאמר בנושא הבחנה בין אותיות רישיות לרגילות ב-PostgreSQL.

    שימו לב שקבוצת השינויים createTable חייבת לכלול אילוץ של מפתח ראשי, ושם האילוץ של המפתח הראשי חייב להיות pk_table_name.

  2. שומרים את השינויים כ-changelog.yaml.

הפעלת Liquibase

מריצים את הפקודה הבאה כדי להחיל את השינויים ב-changelog.yaml:

liquibase --changeLogFile changelog.yaml update

‫Liquibase משתמש בכתובת ה-URL שהגדרתם בקובץ liquibase.properties. אפשר לשנות את הערך בקובץ על ידי הוספת הארגומנט הבא לפקודה הקודמת:

--url URL

בדיקת השינויים

העדכונים בשלב הקודם גרמו להוספת הטבלה Singer למסד הנתונים. בנוסף, הטבלאות DATABASECHANGELOG ו-DATABASECHANGELOGLOCK נוספו (מסד נתונים עם ניב GoogleSQL) או עודכנו (מסד נתונים עם ניב PostgreSQL).

אפשר לוודא שהטבלאות האלה קיימות דרך Google Cloud המסוף או ה-CLI של gcloud. לדוגמה, הרצת שאילתת ה-SQL SELECT * FROM INFORMATION_SCHEMA.TABLES מחזירה רשימה של כל הטבלאות במסד הנתונים.

gcloud spanner databases execute-sql DATABASE_NAME --instance=INSTANCE \
    --sql='SELECT * FROM INFORMATION_SCHEMA.TABLES'

כדי לראות תיעוד של השינויים שהוחלו, אפשר לשלוח שאילתה לגבי התוכן של DATABASECHANGELOG.

המאמרים הבאים