Typowe błędy SQLite: database is locked, readonly, malformed i inne

Błędy to po prostu SQLite, który coś ci mówi

Komunikaty błędów SQLite są krótkie i czasem zagadkowe, ale sprowadzają się do niewielkiego zestawu problemów. Większość tego, co spotkasz na produkcji, mieści się w pięciu kategoriach: blokady, uprawnienia, uszkodzenia, niezgodności schematu i naruszenia ograniczeń. Ta strona omawia każdą z nich: co ją wywołuje, co naprawdę oznacza i jak ją naprawić.

Komunikatom towarzyszą kody liczbowe (kody rozszerzone są jeszcze dokładniejsze). W logach zobaczysz obie formy:

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

Znajomość kodu pomaga przy wyszukiwaniu: SQLITE_BUSY daje znacznie lepsze wyniki niż zwykły angielski komunikat.

database is locked (SQLITE_BUSY)

Najczęstszy błąd SQLite w każdej aplikacji, która zapisuje dane z więcej niż jednego miejsca. SQLite wykonuje zapisy po kolei: blokadę zapisu może w danej chwili trzymać tylko jedno połączenie. Jeśli drugi zapisujący nie zdobędzie blokady w czasie busy timeout, dostajesz ten błąd.

Trzy rozwiązania, od największego wpływu:

-- 1. Włącz tryb WAL. Czytający nie blokują już zapisujących,
--    a zapisujący nie blokuje już czytających.
PRAGMA journal_mode = WAL;

-- 2. Zwiększ busy timeout, aby konkurujące zapisy czekały,
--    zamiast od razu zgłaszać błąd. 5000 = 5 sekund.
PRAGMA busy_timeout = 5000;

-- 3. Sprawdź, czy oba ustawienia zostały zapisane.
PRAGMA journal_mode;
PRAGMA busy_timeout;

Sam tryb WAL rozwiązuje problem blokad dla większości obciążeń. Busy timeout to siatka bezpieczeństwa na wypadek rzeczywistej rywalizacji o zapis. Poza ustawieniami przejrzyj kod: transakcja zostawiona otwarta, gdy program wykonuje operacje sieciowe, trzyma blokadę przez cały ten czas. Utrzymuj krótkie transakcje i wykonuj COMMIT (lub ROLLBACK), gdy tylko praca jest skończona.

unable to open database file (SQLITE_CANTOPEN)

SQLite próbował otworzyć plik, a system operacyjny odmówił. W 95% przypadków problemem jest ścieżka pliku lub jego katalog:

-- Co sprawdzić:
-- 1. Czy ścieżka istnieje?           ls -l /path/to/db.sqlite
-- 2. Czy istnieje katalog nadrzędny? SQLite tworzy plik,
--    ale nie katalog, w którym leży.
-- 3. Czy użytkownik, na którym działa proces, ma prawa
--    odczytu i zapisu do katalogu (nie tylko do pliku)?
-- 4. Czy wolumin jest zamontowany, niepełny i nie tylko do odczytu?

Subtelny przypadek: SQLite musi tworzyć obok bazy pliki pomocnicze (-journal, -wal, -shm). Jeśli sam plik jest zapisywalny, ale katalog nie, otwieranie się udaje, a zapisy nie. Zawsze nadawaj prawo zapisu na poziomie katalogu.

attempt to write a readonly database (SQLITE_READONLY)

Bliski krewny poprzedniego błędu. Plik otworzył się bez problemu, ale zapisy się nie udają. Przyczyny, od najczęstszej:

• Użytkownik systemu nie ma prawa zapisu do pliku lub jego katalogu.
• Połączenie zostało otwarte z flagą tylko do odczytu (SQLITE_OPEN_READONLY albo mode=ro w URI).
• Wolumin jest zamontowany tylko do odczytu (częste przy bind mountach w Dockerze i niektórych chmurowych systemach plików).
• Baza leży na sieciowym systemie plików, który nie obsługuje blokad potrzebnych SQLite.

-- Sprawdź, czy sam SQLite uważa bazę za tylko do odczytu:
PRAGMA query_only;

-- I jaki plik naprawdę otworzył:
PRAGMA database_list;

Popraw uprawnienia albo zamontuj wolumin ponownie. W Dockerze upewnij się, że bind mount nie ma :ro i że użytkownik kontenera jest właścicielem katalogu.

database disk image is malformed (SQLITE_CORRUPT)

Bajty pliku nie pasują już do formatu SQLite. Prawdziwe przyczyny zwykle leżą w środowisku: procesy zabite w trakcie zapisu na systemach plików bez prawidłowego fsync, kopiowanie bazy podczas aktywnego zapisu, awarie sprzętu albo synchronizacja pliku przez Dropbox/iCloud.

Najpierw potwierdź uszkodzenie:

PRAGMA integrity_check;

Jeśli integrity_check zwraca ok, baza jest w porządku, a błąd przyszedł skądinąd (często z nieaktualnego połączenia). Jeśli zwraca listę problemów, trzeba odzyskać dane.

Najczystsza ścieżka odzyskiwania to polecenie .recover w CLI, które wyciąga wszystkie dane, jakie się da, do nowej bazy:

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

Jeśli masz świeżą kopię zapasową, przywróć ją: to szybsze i pozwala uniknąć niepewności typu "odzyskaliśmy większość". Na stronie o kopiach zapasowych i przywracaniu znajdziesz właściwy sposób kopiowania działającej bazy (podpowiedź: nie cp).

no such table i no such column

Znaczą dokładnie to, co mówią, ale przyczyna to zwykle jedna z dwóch rzeczy: jesteś połączony z inną bazą, niż myślisz, albo migracja się nie wykonała.

-- Zobacz, z którym plikiem naprawdę masz połączenie:
PRAGMA database_list;

-- Zobacz, co w nim jest:
SELECT name FROM sqlite_master WHERE type = 'table';

-- Zobacz kolumny konkretnej tabeli:
SELECT name, type FROM pragma_table_info('users');

Sprawdź connection string swojej aplikacji: ścieżki względne są liczone od bieżącego katalogu roboczego, który jest inny w terminalu, w IDE i w procesie produkcyjnym. Baza w pamięci (:memory:) jest za każdym razem nowa, co zaskakuje osoby oczekujące trwałości.

Liczy się też cytowanie identyfikatorów. Nazwy bez cudzysłowów nie rozróżniają wielkości liter, ale "User" i "user" to różne identyfikatory. Jeśli tabela została utworzona z nazwą w cudzysłowach, trzeba ją dalej cytować.

Naruszenia ograniczeń

SQLite odrzuca zapisy, które złamałyby ograniczenie. Komunikat błędu mówi, które:

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

Pod spodem każdy błąd ma inny kod (SQLITE_CONSTRAINT_UNIQUE, SQLITE_CONSTRAINT_CHECK, SQLITE_CONSTRAINT_NOTNULL). Rozwiązanie prawie zawsze leży w warstwie aplikacji: waliduj dane przed zapisem albo używaj INSERT ... ON CONFLICT, aby świadomie obsługiwać duplikaty.

FOREIGN KEY constraint failed zasługuje na osobną uwagę: klucze obce są w SQLite domyślnie wyłączone. Jeśli ich nie włączysz, błędne odwołania wchodzą po cichu, a potem wybuchają, gdy w końcu włączysz egzekwowanie. Ustawiaj tę pragmę w każdym połączeniu:

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

Wywołano BEGIN, gdy transakcja była już otwarta. SQLite nie pozwala na zagnieżdżone transakcje, ale pozwala na zagnieżdżone savepointy, które dają ten sam efekt:

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;       -- albo: ROLLBACK TO inner_work;

COMMIT;

SELECT * FROM users;

Jeśli transakcjami zarządza twój ORM lub framework, prawdopodobnie kazano mu rozpocząć transakcję dwa razy. Sprawdź, czy autocommit jest włączony i czy pula połączeń nie używa ponownie połączenia, które ma już otwartą transakcję.

disk I/O error (SQLITE_IOERR)

System operacyjny odrzucił odczyt lub zapis. Pełny dysk, czkawka sieciowego systemu plików albo plik usunięty spod nóg SQLite. Pierwsze, co warto sprawdzić, to df -h. Drugie: czy baza nie leży na czymś niestabilnym, jak NFS albo folder synchronizowany z chmurą. SQLite zakłada lokalny system plików POSIX z działającym fsync. Jeśli nie możesz jej przenieść, pogódź się z większym ryzykiem uszkodzenia.

syntax error near "..."

Parser SQLite mówi, który token go zmylił. Poprawka zwykle leży trzy linie przed miejscem wskazanym przez błąd: brakujący przecinek, identyfikator bez cudzysłowów kolidujący ze słowem kluczowym albo tekst z apostrofami, które trzeba zapisać podwójnie ('it''s', a nie 'it's').

-- Słowa zastrzeżone jako nazwy kolumn wymagają cudzysłowów:
CREATE TABLE events (
    id INTEGER PRIMARY KEY,
    "order" INTEGER,
    "from" TEXT
);

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

Do danych od użytkownika używaj wiązania parametrów (symboli ?) zamiast budowania SQL przez sklejanie ciągów. Unikniesz w ten sposób całej kategorii błędów składni i jednocześnie SQL injection.

Lista kontrolna diagnostyki

Gdy coś psuje się na produkcji, ta sekwencja obejmuje większość przypadków w mniej niż minutę:

-- Gdzie jestem?
PRAGMA database_list;

-- Czy plik jest zdrowy?
PRAGMA integrity_check;

-- W jakim trybie jest dziennik?
PRAGMA journal_mode;

-- Czy klucze obce są egzekwowane?
PRAGMA foreign_keys;

-- Jak długo zapisujący czekają przed SQLITE_BUSY?
PRAGMA busy_timeout;

Pięć pragm, pięć odpowiedzi. Razem z kodem błędu z nieudanego zapytania wiesz, do której kategorii należy problem i którą stronę dokumentacji otworzyć jako następną.

Podsumowanie kursu

To już cała wycieczka. Za tobą droga od CREATE TABLE przez złączenia, indeksy, transakcje, tryb WAL i kopie zapasowe aż do awarii, które pojawiają się, gdy SQLite zderza się z prawdziwym światem. Wzorce się powtarzają: krótkie transakcje, włączone klucze obce, tryb WAL, regularne kopie zapasowe i zdrowy szacunek dla PRAGMA integrity_check. Trzymaj się tych nawyków, a SQLite będzie po cichu działać latami.