Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

ממשק שורת הפקודה (CLI) של Spanner הוא ממשק שורת פקודה בתוך ה-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 עם חלוקה למחיצות בקנה מידה גדול. כשממשק ה-CLI של 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. זהה ליציאה.
המשך	`\g`	שולח ומריץ הצהרת SQL ב-Spanner.
עזרה	`\h`	הצגת מידע על עזרה. בדיוק כמו `\?`.
Notee	`\t`	משבית את הכתיבה לקובץ הפלט שמוגדר על ידי `\T`.
הנחיה	`\R`	משנה את ההנחיה למחרוזת הנחיה למשתמש.
יציאה	`\q`	יציאה מ-Spanner CLI. זהה ליציאה.
מקור	`\.`	מריץ SQL מקובץ קלט. הארגומנט הוא [שם הקובץ].
מערכת	`\!`	מריץ פקודת Shell של המערכת.
טי	`\T`	פלט פקודה מצורף ל[שם הקובץ] שצוין, יחד עם הפלט הסטנדרטי.
שימוש	`\u`	מתחבר למסד נתונים אחר. מקבל את השם החדש של מסד הנתונים כארגומנט.

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

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

פנייה לתמיכה

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