שילוב של 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.

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