יצירת מחבר Generic PostgreSQL Source

במאמר הזה מוסבר איך ליצור מחבר Generic PostgreSQL Source.

מחבר גנרי של מקור PostgreSQL הוא מופע של מחבר Debezium PostgreSQL. הוא קורא שינויים ברמת השורה ממסד נתונים של PostgreSQL וכותב אותם לנושאים באשכול של שירות מנוהל ל-Apache Kafka.

הערה: כדי לקרוא שינויים ממסד נתונים של Cloud SQL ל-PostgreSQL, צריך להשתמש במחבר המקור של Cloud SQL ל-PostgreSQL.

תרחישי שימוש במחבר הזה כוללים:

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

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

לפני שיוצרים מחבר Generic PostgreSQL Source, צריך לוודא שיש לכם את הדברים הבאים:

• מסד נתונים של PostgreSQL.

• אשכול Connect שמשויך לאשכול Kafka.

• יוצרים סוד ב-Secret Manager שבו מאוחסנת הסיסמה של מסד הנתונים. אם ההגדרה שלכם משתמשת ב-SSL של מסד נתונים, צריך גם ליצור סוד לסיסמת ה-SSL של מסד הנתונים. מגדירים את אשכול Connect עם הסודות. מידע נוסף זמין במאמר בנושא משאבים ב-Secret Manager.

  הערה: אין תמיכה בסיסמאות בטקסט פשוט. ב-database.password ובהגדרות של database.sslpassword יש תמיכה רק בנתיבי סודות. במערכת העורפית, ההגדרות האלה צריכות להיות בפורמט הבא: ${directory:/var/secrets:PROJECT_ID-SECRET_NAME-SECRET_VERSION}.

תפקידים והרשאות נדרשים

כדי לקבל את ההרשאות שנדרשות ליצירת מחבר, צריך לבקש מהאדמין להקצות לכם ב-IAM את התפקיד עורך מחברים מנוהלים של Kafka (roles/managedkafka.connectorEditor) בפרויקט. כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

זהו תפקיד שמוגדר מראש וכולל את ההרשאות שנדרשות ליצירת מחבר. כדי לראות בדיוק אילו הרשאות נדרשות, אפשר להרחיב את הקטע ההרשאות הנדרשות:

ההרשאות הנדרשות

כדי ליצור מחבר, צריך את ההרשאות הבאות:

• יצירת מחבר: managedkafka.connectors.create

יכול להיות שתקבלו את ההרשאות האלה באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש אחרים.

הענקת הרשאות גישה לסודות ב-Secret Manager

לחשבון השירות של שירות Kafka המנוהל צריכה להיות הרשאה לצפייה בסודות ששמורים ב-Secret Manager ולגישה אליהם. מקצים לחשבון השירות את התפקידים הבאים ב-IAM:

• צפייה ב-Secret Manager (roles/secretmanager.viewer)
• Secret Manager Secret Accessor (roles/secretmanager.secretAccessor)

חשבון השירות המנוהל של Kafka הוא בפורמט הבא: [e-mail], כאשר PROJECT_NUMBER הוא מספר הפרויקט של אשכול Connect.

אם אשכול Connect נמצא בפרויקט אחר מאשכול השירות המנוהל ל-Apache Kafka, אפשר לעיין במאמר בנושא יצירת אשכול Connect בפרויקט אחר.

הגדרת מסד הנתונים של PostgreSQL

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

1. מגדירים את wal_level של השרת לערך logical.

   ALTER SYSTEM SET wal_level = logical;
   

   מפעילים מחדש את השרת כדי שההגדרה תחול.

2. יוצרים משתמש במסד הנתונים כדי שהמחבר יוכל לבצע אימות ב-PostgreSQL. משתמש מסד הנתונים צריך להיות תפקיד שכפול, כדי שיוכל להתחבר לשרת במצב שכפול.

   CREATE ROLE ROLE_NAME WITH REPLICATION LOGIN PASSWORD 'ROLE_PASSWORD';
   

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫ROLE_NAME: שם המשתמש, לדוגמה debezium_user.
   • ‫ROLE_PASSWORD: הסיסמה של המשתמש.

3. יוצרים פרסום לטבלאות שרוצים לצלם. המחבר נרשם לפרסום כדי לקבל אירועים של שינוי נתונים.

   CREATE PUBLICATION dbz_publication FOR TABLE "SCHEMA_NAME"."TABLE_NAME";
   

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫SCHEMA_NAME: הסכימה של הטבלה.

   • ‫TABLE_NAME: שם הטבלה.

   מומלץ להוסיף מרכאות כפולות לשמות הסכימה והטבלה, כמו בדוגמה, כדי למנוע שגיאות תחביר אם השמות מכילים תווים מיוחדים או אותיות רישיות.

   אפשרות אחרת היא ליצור פרסום שמשכפל שינויים לכל הטבלאות במסד הנתונים:

   CREATE PUBLICATION dbz_publication FOR ALL TABLES;
   

   בהתאם להגדרה של publication.autocreate.mode המחבר, אפשר ליצור את הפרסום באופן ידני או לאפשר למחבר ליצור אותו באופן אוטומטי. מידע נוסף זמין במאמר בנושא מצב פרסום.

4. לכל טבלה, מעניקים הרשאות SELECT למשתמש במסד הנתונים.

   GRANT SELECT ON TABLE "SCHEMA_NAME"."TABLE_NAME" TO ROLE_NAME;
   

   לחלופין, אפשר להעניק הרשאת SELECT לכל הטבלאות בסכימה:

   GRANT SELECT ON ALL TABLES IN SCHEMA "SCHEMA_NAME" TO ROLE_NAME;
   

5. לכל טבלה, מעניקים הרשאות USAGE בסכימת הטבלה למשתמש במסד הנתונים. אפשר לדלג על השלב הזה אם הטבלה נמצאת בסכימה public שמוגדרת כברירת מחדל.

   GRANT USAGE ON SCHEMA "SCHEMA_NAME" TO ROLE_NAME;
   

יצירת מחבר Generic PostgreSQL Source

כדי ליצור מחבר Generic PostgreSQL Source, מבצעים את השלבים הבאים.

כשהמחבר מאותחל, הוא מבצע את הפעולות הבאות:

1. יוצר קובץ snapshot ראשוני של מסד הנתונים.
2. יוצר נושא Kafka לכל טבלה שיש בה שורות.
3. לכל שורה במסד הנתונים, נשלח אירוע שינוי לנושא המתאים.

בזמן שהמחבר פועל, הוא ממשיך לשלוח אירועי שינוי לנושאים. מידע נוסף על תמונת המצב הראשונית זמין במאמר Snapshots במסמכי Debezium.

המסוף

1. נכנסים לדף Connect Clusters במסוף Google Cloud .

   מעבר אל Connect Clusters

2. לוחצים על אשכול החיבורים שבו רוצים ליצור את המחבר.

3. לוחצים על יצירת מחבר.

4. בשדה 'שם המחבר', מזינים מחרוזת.

   הנחיות לשמות של מחברים זמינות במאמר הנחיות לשמות של משאבים בשירות מנוהל ל-Apache Kafka.

5. בקטע Connector plugin (פלאגין של מחבר), בוחרים באפשרות Generic PostgreSQL Source (מקור PostgreSQL כללי).

6. בשדה Database hostname, מזינים את שם המארח או את כתובת ה-IP של שרת PostgreSQL.

7. בשדה Database name, מזינים את שם מסד הנתונים.

8. בשדה משתמש במסד הנתונים, מזינים את השם של תפקיד הרפליקה. המחבר מאמת את השרת של PostgreSQL באמצעות התפקיד הזה.

9. בשדה Topic prefix, מזינים קידומת שתשמש לשמות של נושאי Kafka.

10. ברשימה סוד, בוחרים את הסוד שמכיל את סיסמת מסד הנתונים.

11. אופציונלי: בתיבה Configurations, מוסיפים מאפייני הגדרה או עורכים את מאפייני ברירת המחדל. מידע נוסף מופיע במאמר בנושא הגדרת המחבר.

12. אופציונלי: בוחרים את מדיניות ההפעלה מחדש של המשימה. מידע נוסף זמין במאמר בנושא מדיניות הפעלה מחדש של משימות.

13. לוחצים על יצירה.

gcloud

1. במסוף Google Cloud , מפעילים את Cloud Shell.

   הפעלת Cloud Shell

   בחלק התחתון של Google Cloud המסוף יתחיל סשן של Cloud Shell ותופיע הודעה של שורת הפקודה. Cloud Shell היא סביבת מעטפת שבה ה-CLI של Google Cloud מותקן ומוגדרים ערכים לפרויקט הקיים. הסשן יופעל תוך כמה שניות.

2. מריצים את הפקודה gcloud managed-kafka connectors create:

   gcloud managed-kafka connectors create CONNECTOR_ID \
       --location=LOCATION \
       --connect-cluster=CONNECT_CLUSTER_ID \
       --config-file=CONFIG_FILE
   

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫CONNECTOR_ID: המזהה או השם של המחבר. הנחיות לשמות של מחברים זמינות במאמר הנחיות לשמות של משאבים בשירות מנוהל ל-Apache Kafka. אי אפשר לשנות את השם של מחבר.

   • ‫LOCATION: המיקום שבו יוצרים את מחבר. המיקום הזה צריך להיות זהה למיקום שבו יצרתם את אשכול Connect.

   • ‫CONNECT_CLUSTER_ID: המזהה של אשכול Connect שבו נוצר המחבר.

   • ‫CONFIG_FILE: הנתיב לקובץ ההגדרות של המחבר בפורמט YAML.

   דוגמה לקובץ הגדרות למחבר Generic PostgreSQL Source:

   connector.class: io.debezium.connector.postgresql.PostgresConnector
   database.dbname: DATABASE_NAME
   database.hostname: HOSTNAME
   database.password: CREDENTIALS
   database.user: DATABASE_USER
   key.converter: org.apache.kafka.connect.json.JsonConverter
   key.converter.schemas.enable: "false"
   plugin.name: pgoutput
   topic.prefix: TOPIC_PREFIX
   value.converter: org.apache.kafka.connect.json.JsonConverter
   value.converter.schemas.enable: "true"
   

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫HOSTNAME: שם המארח של מסד הנתונים של PostgreSQL שממנו מתבצעת הקריאה.

   • ‫DATABASE_NAME: השם של מסד הנתונים של PostgreSQL שממנו רוצים לקרוא.

   • ‫DATABASE_USER: המשתמש במסד הנתונים של PostgreSQL שבו יש להשתמש לאימות במסד הנתונים.

   • ‫CREDENTIALS: נתיב לסוד ב-Secret Manager שמכיל את הסיסמה למסד הנתונים. מציינים את הסוד בפורמט הבא:

     ${directory:/var/secrets:PROJECT_ID-SECRET_NAME-SECRET_VERSION}
     

   • ‫TOPIC_PREFIX: קידומת לשימוש בשמות של נושאי Kafka.

הגדרת המחבר

בקטע הזה מתוארים כמה מאפייני הגדרה שאפשר להגדיר במחבר. רשימה מלאה זמינה במאמר Debezium connector for PostgreSQL במסמכי Debezium.

הגדרות סיסמה וסיסמת SSL

רק נתיבים של סודות נתמכים בהגדרות database.password ו-database.sslpassword. הקצה העורפי מצפה שההגדרות האלה יהיו בפורמט הבא: ${directory:/var/secrets:PROJECT_ID-SECRET_NAME-SECRET_VERSION}.

סוגים של כתובות IP

המאפיין driver.ipTypes מציין את סוג כתובת ה-IP שבה משתמש המחבר כדי להתחבר למסד הנתונים:

• ‫PRIVATE: כתובת IP פרטית
• ‫PSC: Private Service Connect
• ‫PUBLIC: כתובת IP ציבורית

המאפיין driver.ipTypes מכיל רשימה מופרדת בפסיקים של סוגי IP בסדר מועדף. לדוגמה, driver.ipTypes=PRIVATE,PUBLIC.

מצב פרסום

מחבר Generic PostgreSQL Source מעביר בסטרימינג אירועי שינוי מפרסום במסד הנתונים. אתם יכולים ליצור את הפרסום באופן ידני, או לאפשר לכלי החיבור ליצור אותו באופן אוטומטי.

ההגדרה publication.autocreate.mode קובעת איך המחבר צריך ליצור פרסום, ואם הוא צריך לעשות זאת.

• ‫filtered. אם הפרסום לא קיים, המחבר יוצר פרסום חדש שכולל רק את הטבלאות שנתפסו. למשתמש במסד הנתונים צריכות להיות הרשאות CREATE במסד הנתונים, והוא צריך להיות הבעלים של הטבלאות הכלולות.

  אם הפרסום כבר קיים, המחבר משנה אותו כך שיכלול את הטבלאות שנתפסו. כדי לשנות פרסום קיים, משתמש מסד הנתונים צריך להיות הבעלים של הפרסום ושל הטבלאות הכלולות בו.

• ‫all_tables. אם הפרסום לא קיים, המחבר יוצר פרסום חדש באמצעות הפרמטר FOR ALL TABLES. למשתמש במסד הנתונים צריכה להיות הרשאת סופר-אדמין.

  תפקידי סופר-משתמש עוקפים את כל בדיקות ההרשאות במסד נתונים, ולכן לא מומלץ להעניק את ההרשאה SUPERUSER למשתמש במסד הנתונים. במקום זאת, אפשר ליצור את אתר החדשות באופן ידני או להגדיר את publication.autocreate.mode=filtered.

• ‫disabled. אם אתר החדשות לא קיים, מתרחשת שגיאה. המחבר לא יוצר אתר חדשות חדש.

ערך ברירת המחדל הוא all_tables.

שם אתר החדשות

כברירת מחדל, המחבר מנסה להזרים מפרסום בשם dbz_publication. כדי לציין פרסום אחר, מוסיפים publication.name=PUBLICATION_NAME להגדרה, כאשר PUBLICATION_NAME הוא שם הפרסום. לדוגמה: publication.name=my_publication.

משבצות שכפול

‫PostgreSQL משתמש במשבצות שכפול כדי להזרים שינויים בטבלאות של מסד הנתונים. כברירת מחדל, המחבר יוצר משבט שכפול בשם debezium. כדי להשתמש בשם משבצת אחר, מגדירים את המאפיין slot.name.

אם יוצרים שני מופעים של המחבר לאותו מסד נתונים, צריך לציין שם ייחודי של משבצת לכל מחבר.

אזהרה: אם מחברים מושהים, נכשלים או נמחקים, משבצת השכפול שלהם לא נמחקת אוטומטית. מסד הנתונים ממשיך לשמור קבצים של יומן פעולות (WAL) ללא הגבלת זמן, מה שעלול לגרום למילוי מהיר של הדיסק בשרת מסד הנתונים ולשיבוש פעולת מסד הנתונים.

כברירת מחדל, המחבר מגדיר את הנכס slot.drop.on.stop לערך false כדי למנוע אובדן נתונים. כשמוחקים מחבר באופן סופי, צריך להפיל ידנית את משבצת השכפול שבה המחבר השתמש. שם יחידת הקיבולת לשכפול הוא debezium כברירת מחדל, אלא אם הוגדר אחרת באמצעות המאפיין slot.name.

מומלץ להגדיר התראות כדי לעקוב אחרי השימוש בדיסק של WAL בשרת מסד הנתונים של PostgreSQL במקור, ולמחוק משבצות שכפול שלא נעשה בהן שימוש.

מסנן טבלה

כברירת מחדל, המחבר מתעד נתוני שינויים מכל טבלה שאינה טבלת מערכת במסד הנתונים. כדי לסנן את הטבלאות שמתועדות, מציינים אחת או יותר מההגדרות הבאות:

• ‫schema.include.list. רשימה של סכימות שרוצים לכלול.
• schema.exclude.list. רשימה של סכימות להחרגה. אי אפשר להשתמש ב-schema.include.list.
• ‫table.include.list. רשימה של טבלאות שרוצים לכלול.
• ‫table.exclude.list. רשימה של טבלאות להחרגה. אי אפשר להשתמש ב-table.include.list.

שמות הנושאים

כברירת מחדל, המחבר יוצר נושאי Kafka לפי מוסכמת השמות הבאה: topic_prefix.schema.table_name, כאשר topic.prefix הוא הערך של ההגדרה topic.prefix.

מידע נוסף זמין במאמר שמות של נושאים במסמכי התיעוד של Debezium.

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

• פתרון בעיות במחבר של מקור PostgreSQL
• פתרון בעיות בחיבור של אשכולות ומחברים
• יצירת מחבר של מקור Cloud SQL ל-PostgreSQL