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

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

תרחישים נפוצים לדוגמה לשימוש במחבר הזה:

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

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

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

לפני שיוצרים מחבר מקור גנרי של PostgreSQL, צריך לוודא שיש לכם:

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

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

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

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

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

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

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

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

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

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

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

מתן הרשאות גישה לסודות ב-Secret Manager

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

• צפייה ב-Secret Manager ‏ (roles/secretmanager.viewer)
• ממשק גישה לסודות ב-Secret Manager‏ (roles/secretmanager.secretAccessor)

חשבון השירות של Managed 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;
   

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

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

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

   GRANT USAGE ON SCHEMA "SCHEMA_NAME" TO ROLE_NAME;
   

יצירת מחבר גנרי למקור PostgreSQL

כדי ליצור מחבר Generic PostgreSQL Source:

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

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

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

המסוף

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

   מעבר אל Connect Clusters

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

3. לוחצים על Create connector.

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

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

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

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

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

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

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

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

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

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

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

gcloud

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

   הפעלת 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. ה-backend מצפה שההגדרות האלה ישתמשו בפורמט הבא: ${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.

מצב פרסום

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

ההגדרה 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.

למידע נוסף, קראו את הקטע Topic names במסמכי התיעוד של Debezium.

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

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

‫Apache Kafka®‎ הוא סימן מסחרי רשום של The Apache Software Foundation או של השותפים העצמאיים שלה בארצות הברית או במדינות אחרות.