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

ממשק Spanner CLI הוא ממשק שורת פקודה (CLI) בתוך ה-CLI של gcloud, שמאפשר להתחבר למסדי הנתונים של Spanner ולבצע בהם פעולות. לדוגמה, אפשר להשתמש ב-CLI של Spanner כדי להריץ הצהרות של GoogleSQL ולהפוך משימות לאוטומטיות. במאמר הזה מוסבר איך להגדיר את Spanner CLI ולהשתמש בו.

ממשק ה-CLI של Spanner מבוסס על פרויקט הקוד הפתוח spanner-cli.

רשימה של כל הפקודות הנתמכות ב-Spanner CLI מופיעה במאמר בנושא פקודות gcloud spanner cli.

יתרונות מרכזיים

אפשר להשתמש ב-CLI של Spanner כדי לבצע את הפעולות הבאות:

להריץ פקודות SQL מסוג DDL,‏ DML ו-DQL.
לכתוב ולהריץ פקודות SQL בכמה שורות.
אפשר להשתמש בפקודות מטא כדי לבצע משימות מערכת כמו הפעלת פקודת מעטפת של המערכת והפעלת SQL מקובץ.
כדי להפוך את ההרצה של SQL לאוטומטית, כותבים סדרה של הצהרות SQL בקובץ סקריפט, ואז מנחים את Spanner CLI להריץ את הסקריפט. בנוסף, אפשר להפנות את הפלט לקובץ פלט.
להתחיל סשן אינטראקטיבי של Spanner CLI, שמאפשר להקליד ישירות הצהרות SQL ופקודות מטא ולראות את התוצאות ב-CLI.

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

לפני שמשתמשים ב-Spanner CLI, צריך לוודא שיש לכם את התפקיד הנדרש ושהתקנתם את ה-CLI.

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

כדי לקבל את ההרשאות שנדרשות להתקנת Spanner, צריך לבקש מהאדמין להקצות לכם ב-IAM את התפקיד אדמין של Cloud Spanner (roles/spanner.admin) ב-Spanner. להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

התקנת Spanner CLI

ה-CLI של Spanner זמין ב-CLI של gcloud. כשמריצים את הפקודה gcloud spanner cli בפעם הראשונה, ה-CLI של gcloud מתקין באופן אוטומטי את רכיב ה-CLI של Spanner.

כדי להתקין את Spanner CLI באופן ידני, מריצים את הפקודה הבאה:

gcloud components install spanner-cli

אם ההתקנה באמצעות פקודת Google Cloud CLI לא מצליחה או לא אפשרית בסביבת ה-Shell שלכם, Spanner מספק חבילות Debian ‏ (.deb) ו-RPM ‏ (.rpm) עצמאיות. אפשר להשתמש בחבילות האלה כדי להתקין באופן ידני במערכות תואמות. כדי להתקין, מריצים את הפקודה הבאה:

apt-get install google-cloud-cli-spanner-cli

אפשרויות להגדרות אישיות

ה-CLI של Spanner תומך באפשרויות ההגדרה הבאות:

אפשר לאחזר את אפשרות הפרויקט דרך המאפיין core/project, או לציין את הפרויקט באמצעות האפשרות --project.
אפשר לאחזר את האפשרות של המופע דרך הנכס core/instance, או לציין את המופע באמצעות האפשרות --instance.
נקודת הקצה ב-API מאוחזרת דרך הנכס api_endpoint_overrides/spanner. לחלופין, אפשר לציין את נקודת הקצה באמצעות האפשרויות --host ו---port. אם לא מציינים נקודת קצה, המערכת משתמשת בנקודת הקצה של Spanner שמוגדרת כברירת מחדל.

שימוש ב-CLI של Spanner

להגדיר Google Cloud פרויקט.
הגדרת אימות באמצעות ה-CLI של gcloud
יצירת מופע
יצירת מסד נתונים.
מריצים את הפקודה הבאה כדי להפעיל את Spanner CLI ולקיים אינטראקציה עם מסד הנתונים של Spanner:
```
gcloud spanner cli DATABASE_ID --instance=INSTANCE_ID
```
מחליפים את מה שכתוב בשדות הבאים:
- ‫DATABASE_ID: המזהה של מסד הנתונים של Spanner. זה השם שבו השתמשתם בשלב הקודם של יצירת מסד נתונים. אפשר להשתמש בפקודה gcloud spanner databases list כדי להציג את רשימת מסדי הנתונים של Spanner שכלולים במופע הנתון.
- ‫INSTANCE_ID: המזהה של מופע Spanner. זה השם שבו השתמשתם בשלב הקודם של יצירת מופע. אפשר להשתמש בפקודה gcloud spanner instances list כדי להציג את רשימת מופעי Spanner שנכללים בפרויקט הנתון.

הרצת SQL

אפשר להריץ הצהרות SQL ב-Spanner CLI באמצעות האפשרות execute או באמצעות שיטה של קלט ופלט מבוססי-קובץ. הצהרות ה-SQL יכולות לכלול DDL,‏ DML או DQL.

שימוש בדגל `execute`

כדי להשתמש בדגל execute להרצת SQL, מריצים את הפקודה gcloud spanner cli הבאה:

gcloud spanner cli DATABASE_ID --instance INSTANCE_ID \
    --execute "SQL"

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

‫DATABASE_ID: המזהה של מסד הנתונים של Spanner שאליו רוצים להתחבר.
‫INSTANCE_ID: המזהה של מופע Spanner שאליו רוצים להתחבר.
‫SQL: ה-SQL שרוצים להריץ.

לדוגמה, כדי להריץ הצהרת DDL:

gcloud spanner cli test-database --instance test-instance \
    --execute "CREATE TABLE Singers ( \
        SingerId   INT64 NOT NULL, \
        FirstName  STRING(1024), \
        LastName   STRING(1024), \
        SingerInfo STRING(1024), \
        BirthDate  DATE \
      ) PRIMARY KEY(SingerId);"

כדי להריץ פקודת DML:

gcloud spanner cli test-database --instance test-instance \
    --execute "INSERT INTO Singers (SingerId, FirstName, LastName, SingerInfo) \
        VALUES(1, 'Marc', 'Richards', 'nationality: USA'), \
              (2, 'Catalina', 'Smith', 'nationality: Brazil'), \
              (3, 'Andrew', 'Duneskipper', NULL);"

שימוש בקלט ובפלט מבוססי-קובץ

אם משתמשים בשיטת הקלט והפלט שמבוססת על קבצים, Spanner קורא את הקלט מקובץ וכותב את הפלט לקובץ אחר. כדי להשתמש בשיטת הקלט והפלט מבוססת-הקובץ כדי להריץ SQL, מריצים את הפקודה הבאה:

gcloud spanner cli DATABASE_ID --instance INSTANCE_ID \
    --source INPUT_FILE_PATH --tee OUTPUT_FILE_PATH

אפשר גם להשתמש בשיטת הקלט והפלט של הפניה אוטומטית מבוססת-קובץ:

gcloud spanner cli DATABASE_ID --instance INSTANCE_ID \
    < INPUT_FILE_PATH > OUTPUT_FILE_PATH

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

‫DATABASE_ID: המזהה של מסד הנתונים של Spanner שאליו רוצים להתחבר.
‫INSTANCE_ID: המזהה של מופע Spanner שאליו רוצים להתחבר.
‫SOURCE_FILE_PATH: הקובץ שמכיל את ה-SQL שרוצים להריץ.
‫OUTPUT_FILE_PATH: הקובץ שצוין שאליו יצורף עותק של פלט ה-SQL.

התחלת סשן אינטראקטיבי

אפשר להתחיל סשן אינטראקטיבי של Spanner CLI, שמאפשר להקליד ישירות הצהרות SQL ופקודות מטא ולראות את התוצאות ב-CLI. כדי לעשות זאת, מריצים את הפקודה הבאה:

gcloud spanner cli DATABASE_ID --instance=INSTANCE_ID

אחרי שהחיבור בין ה-CLI למסד הנתונים יצליח, תופיע הנחיה (לדוגמה, spanner-cli>) שבה תוכלו לבצע את הפעולות הבאות:

הקלדה ישירה של הצהרות GoogleSQL:
ביצוע עסקאות
שימוש בפקודות-על נתמכות

אחרי שלוחצים על המקש ENTER, ההצהרה או הפקודה נשלחות למסד הנתונים המתאים של Spanner. ‫Spanner מבצע את ההצהרה או הפקודה.

בדוגמה הבאה, מתחילים סשן אינטראקטיבי ב-test-database ואז מריצים את הפקודה SELECT 1;:

gcloud spanner cli test-database --instance test-instance

Welcome to Spanner-Cli Client.
Type 'help;' or '\h' for help.
Type 'exit;' or 'quit;' or '\q' to exit.

spanner-cli> SELECT 1;
+---+
|   |
+---+
| 1 |
+---+

1 rows in set (1.11 msecs)

ביצוע הצהרת DDL

כדי להריץ הצהרת DDL, אפשר להריץ את הפקודה הבאה:

spanner-cli> CREATE TABLE Singers (
          ->         SingerId   INT64 NOT NULL,
          ->         FirstName  STRING(1024),
          ->         LastName   STRING(1024),
          ->         SingerInfo STRING(1024),
          ->         BirthDate  DATE
          -> ) PRIMARY KEY(SingerId);

Query OK, 0 rows affected (17.08 sec)

ביצוע פקודת DML

כדי להריץ פקודת DML, אפשר להשתמש בפקודה הבאה:

spanner-cli> INSERT INTO Singers (SingerId, FirstName, LastName, SingerInfo)
          -> VALUES(1, 'Marc', 'Richards', 'nationality: USA'),
          -> (2, 'Catalina', 'Smith', 'nationality: Brazil'),
          -> (3, 'Andrew', 'Duneskipper', NULL);

Query OK, 3 rows affected (0.32 sec)

הפעלה של פקודת DML מחולקת למחיצות

ב-CLI של Spanner, אפשר להשתמש במילת המפתח PARTITIONED עם הפקודות UPDATE ו-DELETE כדי להריץ הצהרות יעילות של DML עם חלוקה למחיצות בקנה מידה גדול. כשממשק שורת הפקודה של Spanner נתקל ב-PARTITIONED UPDATE או ב-PARTITIONED DELETE, הוא מזהה אותם כפעולות DML מחולקות. מילות המפתח האלה שימושיות לפעולות שמשפיעות על חלק משמעותי בטבלה בלי לנעול את כל הטבלה למשך תקופה ממושכת. ‫Spanner לא מחיל את הצהרות ה-DML עם החלוקה למחיצות באופן אטומי על כל הטבלה. היא מחילה הצהרות DML מחולקות באופן אטומי על כל מחיצה.

כדי להריץ פקודת DML עם חלוקה למחיצות, אפשר להריץ את הפקודה הבאה:

-- Update all rows in the 'Products' table by multiplying the price by 2
spanner-cli> PARTITIONED UPDATE Products SET Price = Price * 2 WHERE Price > 100;

-- Delete all rows in the 'Products' table with price less than 500
spanner-cli> PARTITIONED DELETE FROM Products WHERE Price < 500;

פקודות-על נתמכות

ממשק ה-CLI של Spanner תומך בפקודות מטא של כלי השירות, שהן פקודות שפועלות בלקוח, ובמקרה הזה בממשק ה-CLI של Spanner. ממשק ה-CLI של Spanner תומך בפקודות המטא הבאות:

Command	תחביר	תיאור
?	`\?`	הצגת מידע על עזרה. בדיוק כמו `\h`.
תו מפריד	`\d`	מגדיר את התו המפריד בין הצהרות. תו ברירת המחדל להפרדה הוא נקודה-פסיק.
יציאה	`\q`	יציאה מ-Spanner CLI. זהה ליציאה.
Go	`\g`	שליחה והרצה של הצהרת SQL ב-Spanner.
עזרה	`\h`	הצגת מידע על עזרה. בדיוק כמו `\?`.
Notee	`\t`	ההגדרה הזו משביתה את הכתיבה לקובץ הפלט שמוגדר על ידי `\T`.
הנחיה	`\R`	ההנחיה משתנה למחרוזת הנחיה למשתמש.
יציאה	`\q`	יוצאים מ-Spanner CLI. כמו יציאה.
מקור	`\.`	מריץ SQL מקובץ קלט. הארגומנט הוא [שם הקובץ].
מערכת	`\!`	מריץ פקודת Shell של המערכת.
Tee	`\T`	מצרף את פלט הפקודה ל[שם הקובץ] שצוין, יחד עם הפלט הרגיל.
שימוש	`\u`	מתחבר למסד נתונים אחר. מקבל את השם החדש של מסד הנתונים כארגומנט.

פקודות נוספות שנתמכות

ממשק ה-CLI של Spanner תומך בפקודות נוספות. למידע נוסף, אפשר לעיין במאמר בנושא פקודות Spanner CLI.

פנייה לתמיכה

כדי לדווח על בעיה ב-CLI של Spanner, יוצרים בעיה חדשה.

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

רשימה של כל הפקודות הנתמכות ב-Spanner CLI
כאן מפורטת רשימה של כל הפקודות הנתמכות של gcloud spanner cli.