כלי שורת הפקודה psql

‫psql הוא ממשק קצה של שורת הפקודה ל-PostgreSQL. בדף הזה מוסבר על הפקודות שממשק PostgreSQL ל-Spanner תומך בהן.psql הנחיות לחיבור ל-psql מופיעות במאמר חיבור psql למסד נתונים של ניב PostgreSQL.

פקודות מטא

ממשק PostgreSQL תומך בקטגוריות הבאות של פקודות מטא psql:

הערה: מזינים את הפקודה \? כדי לראות את הפקודות בכל קטגוריה.

• כללי
• עזרה
• מאגר שאילתות
• קלט/פלט
• מותנה
• מידע (רק חלק מפקודות \d)
• עיצוב
• מערכת הפעלה
• משתנים

אין תמיכה בקטגוריות הבאות:

• חיבור
• אובייקטים גדולים

יש תמיכה בפקודות המידע הבאות:

פקודה	תיאור
‫‎\d	הצגת רשימת הטבלאות (למעט טבלאות מערכת)
‫‎\d table	הצגת רשימה של עמודות בטבלה
\dt	רשימת טבלאות בכל הסכימות (מפורט)
\dt table	טבלת רשימה (מפורטת)
‫‎\dn	הצגת סכימות

הצהרות בנושא ניהול סשנים

‫psql מתקשר עם Spanner דרך PGAdapter, שמשתמש במנוע הליבה של מנהל ההתקן Spanner JDBC. הדרייבר תומך בהצהרות לניהול סשנים שמתוארות במאמר הצהרות לניהול סשנים. לכן, אפשר להשתמש בהצהרות האלה עם psql.

איגוד של הצהרות SQL

‫psql ו-PGAdapter תומכים בחבילות של הצהרות SQL מרובות. כדי להוסיף כמה הצהרות בבת אחת, משתמשים באפשרות psql -c. האפשרות הזו מאפשרת להעביר הצהרה אחת או יותר של SQL או של ניהול סשנים, שמופרדות באמצעות נקודה-פסיק (;), כבקשת ביצוע אחת. אצווה יכולה לכלול כל הצהרה נתמכת, ויכולה לערבב DDL,‏ DML ו-DQL.

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

נתמכים אמצעי בקרה מפורשים על טרנזקציות של BEGIN ושל COMMIT, אבל חסימה מפורשת של טרנזקציה לא יכולה להכיל הצהרות DDL.

דוגמאות

DML

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

psql -h localhost -p 5432 -c "INSERT INTO users (id, age, firstname) VALUES (1, 25, 'Alex'); \
 INSERT INTO users (id, age, firstname) VALUES (2, 31, 'Dana'); \
 INSERT INTO users (id, age, firstname) VALUES (3, 54, 'Izumi');"

בדוגמה הבאה אפשר לראות איך מריצים את הצהרות ה-SQL בקובץ insert_contacts.sql.

psql -h localhost -c "$(cat contacts_insert.sql)"

DDL

בדוגמה הזו, נשלחת קבוצה של ALTER TABLE הצהרות.

psql -h localhost -p 5432 test-db -c "ALTER TABLE users ADD col1 integer; \
 ALTER TABLE users ADD col2 text; ALTER TABLE users ADD col3 float8;"

פקודת COPY לייבוא נתונים

משתמשים בפקודה COPY FROM STDIN כדי לייבא נתונים מקובץ טקסט או CSV למסד נתונים של ניב PostgreSQL. למרות שרק STDIN נתמך, אפשר לייבא באמצעות COPY על ידי העברת קבצים ל-psql.

יש שתי דרכים להריץ את הפקודה COPY:

• אטומי COPY

  הנתונים מועתקים בעסקה אחת. (זוהי ברירת המחדל) מגבלות העסקאות הרגילות של Spanner חלות על העסקה. כלומר, אפשר לכלול בפעולה אחת של COPY לכל היותר 80,000 מוטציות או 100MB של נתונים.

• לא אטומי COPY

  ‫COPY מפצל אוטומטית את הנתונים על פני כמה טרנזקציות אם הקובץ מכיל יותר מ-80,000 שינויים או יותר מ-100MB.

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

הפעלת COPY לא אטומי

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

SET SPANNER.AUTOCOMMIT_DML_MODE='PARTITIONED_NON_ATOMIC'

תחביר

COPY table_name [ ( column_name [, ...] ) ]
    FROM STDIN
    [ [ WITH ] ( option [, ...] ) ]

where option is one of:

    FORMAT format_name
    DELIMITER 'delimiter_character'
    NULL 'null_string'
    QUOTE 'quote_character'
    ESCAPE 'escape_character'
    HEADER [boolean]

and format_name is:
    {text|csv}

and delimiter_character is:
    [!-~] except ' " \

and null_string is:
    {a—z|A—Z|0—9|_}+

and quote_character is:
    [!-~] except ' " \

and escape_character is:
    [!-~] except ' " \

and boolean is:
    {TRUE|ON|1|FALSE|OFF|0}

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

ערך ברירת המחדל של FORMAT הוא text.

delimiter_character חייב להיות תו באורך בית אחד. ברירת המחדל היא התו Tab לפורמט טקסט ופסיק לפורמט CSV.

‫NULL מציין את המחרוזת שמייצגת ערך null. ברירת המחדל היא ‎\N (קו נטוי הפוך + N) בפורמט טקסט, ומחרוזת ריקה ללא גרשיים בפורמט CSV. יכול להיות שתעדיפו מחרוזת ריקה גם בפורמט טקסט במקרים שבהם אתם לא רוצים להבחין בין ערכי null לבין מחרוזות ריקות.

QUOTE מציין את תו המירכאות שבו צריך להשתמש כשמצטטים ערך נתונים. ברירת המחדל היא גרשיים כפולים. התו המפריד חייב להיות תו יחיד באורך בית אחד. האפשרות הזו מותרת רק כשמשתמשים בפורמט CSV.

‫ESCAPE מציין את התו שיופיע לפני תו נתונים שתואם לערך QUOTE. ברירת המחדל זהה לערך של QUOTE (כך שאם תו המירכאות מופיע בנתונים, הוא מוכפל). התו המפריד חייב להיות תו יחיד באורך בית אחד. האפשרות הזו מותרת רק כשמשתמשים בפורמט CSV.

‫HEADER מציין אם הרשומה הראשונה בקובץ הקלט היא כותרת (מכילה שמות של עמודות). ברירת המחדל היא TRUE.

דוגמאות

בדוגמה הזו, הנתונים מיובאים מהקובץ בפורמט טקסט שנקרא mydata.txt לטבלה mytable. ‫PGAdapter צריך לפעול. מידע נוסף זמין במאמר הפעלת PGAdapter.

cat mydata.txt | psql -h localhost -c "COPY mytable FROM STDIN;"

בדוגמה הבאה, mydata.csv הוא בפורמט CSV והשורה הראשונה שלו היא כותרת עם שמות עמודות שמופרדים בפסיקים.

cat mydata.csv | psql -h localhost \
  -c "COPY mytable FROM STDIN WITH (FORMAT csv, ESCAPE '~', HEADER TRUE);"

בדוגמה הבאה אפשר לראות איך מתחילים פעולת COPY לא אטומית.

cat mydata.txt | psql -h localhost \ 
  -c "SET SPANNER.AUTOCOMMIT_DML_MODE='PARTITIONED_NON_ATOMIC'" -c "COPY mytable FROM STDIN;"

פתרון בעיות

ריכזנו כאן כמה שגיאות נפוצות.

תחביר קלט לא תקין

השגיאה הבאה מתרחשת:

Invalid input syntax for type <type>:"<table_name>"

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

נתוני העתקה לא תקינים

השגיאה הבאה מתרחשת:

Invalid COPY data: Row length mismatched. Expected <number> columns, but only found <number>

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

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

• איך מתחברים למסד נתונים של ניב PostgreSQL באמצעות psql
• PGAdapter