שגיאות נפוצות ב-SQLite: מסד נעול, readonly, malformed ועוד

שגיאות הן פשוט SQLite שמנסה להגיד לכם משהו

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

מחרוזות השגיאה מגיעות יחד עם קודים מספריים (קודים מורחבים ספציפיים עוד יותר). תראו את שתי הצורות בלוגים:

Error: database is locked          -- קוד 5 (SQLITE_BUSY)
Error: unable to open database     -- קוד 14 (SQLITE_CANTOPEN)
Error: attempt to write a readonly -- קוד 8 (SQLITE_READONLY)
Error: database disk image is      -- קוד 11 (SQLITE_CORRUPT)

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

database is locked (SQLITE_BUSY)

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

שלושה תיקונים, לפי סדר ההשפעה:

-- 1. הפעילו מצב WAL. קוראים כבר לא חוסמים כותבים,
--    וכותב אחד כבר לא חוסם קוראים.
PRAGMA journal_mode = WAL;

-- 2. הגדילו את זמן ההמתנה (busy timeout) כדי שכתיבות מתחרות יחכו
--    במקום להיכשל מיד. 5000 = 5 שניות.
PRAGMA busy_timeout = 5000;

-- 3. ודאו ששתי ההגדרות נשמרו.
PRAGMA journal_mode;
PRAGMA busy_timeout;

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

unable to open database file (SQLITE_CANTOPEN)

SQLite ניסתה לפתוח את הקובץ ומערכת ההפעלה סירבה. ב-95% מהמקרים הבעיה היא נתיב הקובץ או התיקייה שלו:

-- מה לבדוק:
-- 1. האם הנתיב קיים?                ls -l /path/to/db.sqlite
-- 2. האם תיקיית האב קיימת? SQLite יוצרת את הקובץ
--    אבל לא את התיקייה שמעליו.
-- 3. האם למשתמש שמריץ את התהליך שלכם יש הרשאת קריאה+כתיבה
--    על התיקייה (לא רק על הקובץ)?
-- 4. האם הכונן מחובר, לא מלא, ולא לקריאה בלבד?

מקרה עדין: SQLite צריכה ליצור קבצים נלווים (-journal, -wal, -shm) ליד מסד הנתונים. אם אפשר לכתוב לקובץ עצמו אבל לא לתיקייה, הפתיחה מצליחה והכתיבות נכשלות. תנו תמיד הרשאת כתיבה ברמת התיקייה.

attempt to write a readonly database (SQLITE_READONLY)

בן דוד קרוב של הקודמת. הקובץ נפתח בסדר אבל הכתיבות נכשלות. הסיבות, לפי שכיחות:

• למשתמש מערכת ההפעלה אין הרשאת כתיבה על הקובץ או על התיקייה שלו.
• החיבור נפתח עם דגל לקריאה בלבד (SQLITE_OPEN_READONLY, או mode=ro ב-URI).
• הכונן מחובר לקריאה בלבד (נפוץ ב-bind mounts של Docker ובחלק ממערכות הקבצים בענן).
• מסד הנתונים נמצא על מערכת קבצים ברשת שלא תומכת בנעילות ש-SQLite צריכה.

-- בדקו אם SQLite עצמה חושבת שמסד הנתונים הוא לקריאה בלבד:
PRAGMA query_only;

-- ואיזה קובץ היא פתחה בפועל:
PRAGMA database_list;

תקנו את ההרשאות או חברו מחדש את הכונן. אם אתם ב-Docker, ודאו שה-bind mount אינו :ro ושמשתמש הקונטיינר הוא הבעלים של התיקייה.

database disk image is malformed (SQLITE_CORRUPT)

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

קודם כול, אשרו את הנזק:

PRAGMA integrity_check;

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

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

sqlite3 corrupt.db ".recover" | sqlite3 recovered.db
sqlite3 recovered.db "PRAGMA integrity_check;"

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

no such table ו-no such column

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

-- ראו לאיזה קובץ אתם באמת מחוברים:
PRAGMA database_list;

-- ראו מה יש בו:
SELECT name FROM sqlite_master WHERE type = 'table';

-- ראו את העמודות של טבלה מסוימת:
SELECT name, type FROM pragma_table_info('users');

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

גם מירכאות סביב מזהים חשובות. שמות בלי מירכאות לא מבחינים בין אותיות גדולות לקטנות, אבל "User" ו-"user" הם מזהים שונים. אם יצרתם טבלה עם מירכאות סביב השם, תצטרכו להמשיך לשים אותן.

הפרות של אילוצים

SQLite מסרבת לכתיבות שהיו שוברות אילוץ. הודעת השגיאה מציינת איזה מהם:

CREATE TABLE users (
    id INTEGER PRIMARY KEY,
    email TEXT NOT NULL UNIQUE,
    age INTEGER CHECK (age >= 0)
);

INSERT INTO users (email, age) VALUES ('a@x.com', 30);
INSERT INTO users (email, age) VALUES ('a@x.com', 25);
-- Error: UNIQUE constraint failed: users.email

INSERT INTO users (email, age) VALUES ('b@x.com', -5);
-- Error: CHECK constraint failed: age >= 0

INSERT INTO users (age) VALUES (40);
-- Error: NOT NULL constraint failed: users.email

כל כישלון הוא קוד שונה מאחורי הקלעים (SQLITE_CONSTRAINT_UNIQUE, SQLITE_CONSTRAINT_CHECK, SQLITE_CONSTRAINT_NOTNULL). התיקון כמעט תמיד נמצא בשכבת האפליקציה: אמתו את הקלט לפני הכתיבה, או השתמשו ב-INSERT ... ON CONFLICT כדי לטפל בכפילויות באופן מכוון.

FOREIGN KEY constraint failed ראויה להערה משלה: מפתחות זרים כבויים כברירת מחדל ב-SQLite. אם לא מפעילים אותם, הפניות לא תקינות נכנסות בשקט, ונכשלות מאוחר יותר כשסוף סוף מפעילים את האכיפה. הגדירו את ה-pragma בכל חיבור:

PRAGMA foreign_keys = ON;

CREATE TABLE author (id INTEGER PRIMARY KEY, name TEXT);
CREATE TABLE book (
    id INTEGER PRIMARY KEY,
    author_id INTEGER REFERENCES author(id)
);

INSERT INTO book (author_id) VALUES (999);
-- Error: FOREIGN KEY constraint failed

cannot start a transaction within a transaction

קראתם ל-BEGIN כשטרנזקציה כבר הייתה פתוחה. SQLite לא מאפשרת טרנזקציות מקוננות, אבל היא כן מאפשרת savepoints מקוננים, שנותנים את אותה תוצאה:

CREATE TABLE users (id INTEGER PRIMARY KEY, email TEXT);

BEGIN;
INSERT INTO users (email) VALUES ('outer@x.com');

SAVEPOINT inner_work;
INSERT INTO users (email) VALUES ('inner@x.com');
RELEASE inner_work;       -- או: ROLLBACK TO inner_work;

COMMIT;

SELECT * FROM users;

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

disk I/O error (SQLITE_IOERR)

מערכת ההפעלה דחתה קריאה או כתיבה. דיסק מלא, תקלה רגעית במערכת קבצים ברשת, או שהקובץ נמחק מתחת לרגליים של SQLite. הדבר הראשון לבדוק הוא df -h. השני הוא אם מסד הנתונים יושב על משהו לא יציב כמו NFS או תיקייה שמסונכרנת לענן: SQLite מניחה מערכת קבצים מקומית מסוג POSIX עם fsync שעובד. אם אי אפשר להעביר אותו, קבלו את זה שהסיכון לפגיעה בקובץ עולה.

syntax error near "..."

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

-- מילים שמורות כשמות עמודות צריכות מירכאות:
CREATE TABLE events (
    id INTEGER PRIMARY KEY,
    "order" INTEGER,
    "from" TEXT
);

INSERT INTO events ("order", "from") VALUES (1, 'web');
SELECT "order", "from" FROM events;

השתמשו בקשירת פרמטרים (מצייני מקום ?) לקלט של משתמשים במקום לבנות SQL בשרשור מחרוזות: כך תתחמקו בבת אחת מקטגוריה שלמה של שגיאות תחביר ומ-SQL injection.

רשימת בדיקה לאבחון

כשמשהו נשבר בפרודקשן, הרצף הזה מכסה את רוב המקרים בפחות מדקה:

-- איפה אני?
PRAGMA database_list;

-- האם הקובץ תקין?
PRAGMA integrity_check;

-- באיזה מצב נמצא ה-journal?
PRAGMA journal_mode;

-- האם מפתחות זרים נאכפים?
PRAGMA foreign_keys;

-- כמה זמן כותבים יחכו לפני SQLITE_BUSY?
PRAGMA busy_timeout;

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

סיכום תוכנית הלימודים

זה הסיור. עברתם מ-CREATE TABLE דרך JOIN, אינדקסים, טרנזקציות, מצב WAL וגיבויים, ועכשיו גם דרך דפוסי הכישלון שמופיעים כש-SQLite פוגשת את העולם האמיתי. הדפוסים חוזרים על עצמם: טרנזקציות קצרות, מפתחות זרים מופעלים, מצב WAL, גיבויים קבועים וכבוד בריא ל-PRAGMA integrity_check. שמרו על ההרגלים האלה ו-SQLite תרוץ בשקט במשך שנים.