Навіщо база даних, якщо є текстовий файл

Ти опишеш на папері таблицю свого продукту — які в ній поля, які з них обов’язкові, який тип у кожного, — а потім створиш цю таблицю в базі даних однією командою CREATE TABLE. У базу ти додаси п’ять справжніх записів свого сервісу.

Після цього твоє API навчиться віддавати ці записи. Одна адреса API називається ендпоінт. Дані за нею передають у форматі JSON: це текст, у якому один об’єкт записаний у фігурних дужках парами «назва»: значення, а список об’єктів — у квадратних дужках через кому. За адресою на кшталт /u/<логін>/api/habits будь-хто з інтернету отримає такий текст із твоїми записами.

Наприкінці автоперевірка порахує записи в базі, порахує об’єкти у відповіді й порівняє два числа — вони мають збігтися.

Дані сервісу справді можна зберігати у звичайному текстовому файлі: один рядок — один запис, поля через кому. Для двадцяти рядків це працює, і для першої спроби так роблять. Проблеми починаються далі, і їх п’ять.

1. Пошук. Щоб знайти один запис, програма читає файл від початку до кінця й розбирає кожен рядок на частини. У файлі на 50 000 рядків із п’ятьма полями це чверть мільйона дій на кожен запит — і так щоразу, коли хтось відкриває сторінку.
2. Зміна одного запису. Замінити рядок посеред файлу неможливо, якщо новий рядок іншої довжини: доводиться переписувати весь файл. Якщо програма зупиниться посеред перезапису, від файлу лишиться половина.
3. Двоє одночасно. Через кілька занять твій сервіс буде відкритий для інших людей. Якщо два запити пишуть у файл в одну й ту саму секунду, частина одного рядка потрапляє всередину іншого, і прочитати такий файл уже не вдається.
4. Немає перевірок. У файл можна записати запис без назви, з датою «завтра ввечері» і з текстом там, де мало бути число. Ти помітиш це через місяць, коли рахуватимеш підсумки.
5. Питання до даних. «Скільки записів за минулий тиждень», «останні п’ять», «найдовший за часом» — у файлі кожне таке питання це окремий код на Python.

База даних — програма, яка зберігає дані у вигляді таблиць і відповідає на запити до них. На кожен із цих п’яти пунктів у бази є відповідь:

• для пошуку база тримає індекс (англійською index) — службовий список значень із номерами рядків, за яким потрібний рядок знаходиться без перегляду всіх інших;
• зміни вона робить транзакцією — це група дій, яка виконується або повністю, або ніяк. Якщо живлення зникне посеред запису, після ввімкнення база повернеться до стану, який був до транзакції;
• на час запису база ставить блокування: другий запит на запис не пише одночасно з першим, а чекає, поки той закінчить. Чекає він не безкінечно — у нашій заготовці межа очікування п’ять секунд, і якщо перший запис затягнувся довше, другий припиняє спроби й повертає помилку database is locked;
• правила для даних ти описуєш один раз під час створення таблиці, і далі база сама відмовляється приймати те, що їх порушує;
• питання до даних формулюють мовою запитів — одним рядком замість окремої функції.

Ми беремо SQLite — базу даних, яка тримає все в одному файлі на диску й не потребує окремої служби. Служба — це програма, яку операційна система запускає сама й тримає ввімкненою у фоні, поки працює сервер. Іншим базам даних така програма потрібна, SQLite обходиться без неї. Твоя база лежатиме у файлі ~/data/app.db. Саме через це її зручно копіювати й відновлювати: на занятті 11 ти робитимеш із неї резервні копії звичайною командою копіювання файлу.

Дані в базі лежать у таблицях. Розберемо три слова, які далі будуть у кожному реченні:

• таблиця — набір записів одного виду. Одна таблиця — один вид речей: звички, ігри, рослини;
• стовпець (його ще називають полем) — одна характеристика, яка є в кожного запису: назва, дата, кількість хвилин;
• рядок (він же запис) — один конкретний об’єкт з усіма його характеристиками.

Приклад, який ти бачив: журнал успішності. Стовпці там — прізвище, дата, оцінка. Рядок — одна виставлена оцінка. Кожен рядок має ті самі стовпці, що й решта; порожні клітинки бувають, а от «у цього учня є ще один стовпчик, якого нема в інших» — не буває. Це і є головна властивість таблиці.

Схема — повний перелік таблиць твого продукту, їхніх стовпців, типів і правил. Схему пишуть до того, як створювати таблиці: переробити її потім, коли в базі вже є дані, значно складніше.

Назву таблиці пиши в однині, латиницею, малими літерами: habit, game, plant. Латиниця тому, що ця назва потрапляє в кожен запит і в код програми. Однина тому, що один рядок — це одна звичка.

Одна з таблиць у тебе головна — та, записи якої показує список сервісу. Її назву ти запишеш у project.yaml: це файл-опис твого проєкту, у якому зібрані всі його назви й адреси, і такий файл називають маніфестом. Саме цю таблицю рахуватиме автоперевірка.

Первинний ключ (англійською primary key) — стовпець, значення якого не повторюється в таблиці й ніколи не буває порожнім. За ним база знаходить конкретний рядок, і за ним на цей рядок посилаються інші таблиці.

Найпростіший і найнадійніший варіант — окремий числовий стовпець id, який база заповнює сама:

id INTEGER PRIMARY KEY AUTOINCREMENT

Наступне число — 1, 2, 3 — база ставить сама вже через INTEGER PRIMARY KEY: тобі не треба ані передавати це значення, ані пам’ятати, яке було останнім. Слово AUTOINCREMENT додає до цього одне правило: номери видалених рядків більше не використовуються повторно. Без нього база може віддати новому рядку номер, який раніше належав видаленому.

Може виникнути думка взяти ключем назву — вона ж і так унікальна. Дві причини цього не робити: назви повторюються (у щоденнику звичок «Пробіжка» буде десятки разів, і це нормально), а ще назву іноді виправляють — після виправлення всі посилання на старе значення стають хибними. Номер id не змінюється ніколи.

Тепер про поля, які лишили незаповненими. NULL — окреме значення, яке означає «сюди нічого не записали». Воно не дорівнює нулю й не дорівнює порожньому рядку: нуль хвилин — це відомий факт, а NULL — відсутність факту.

NOT NULL — правило для стовпця: тут порожнього значення бути не може. Його ставлять на поля, без яких запис не має сенсу. У щоденнику звичок це назва й дата: запис без дати неможливо ані показати в списку, ані відфільтрувати. Якщо спробувати додати рядок без такого поля, база відмовить і поверне помилку NOT NULL constraint failed.

Поруч є ще два правила, які знадобляться далі:

• UNIQUE — значення в цьому стовпці не повторюється. Наприклад, електронна пошта в таблиці користувачів на занятті 07. Це не те саме, що первинний ключ: UNIQUE-стовпців у таблиці може бути кілька, а первинний ключ один;
• DEFAULT — значення, яке база підставить сама, якщо поле не передали. Наприклад, minutes INTEGER NOT NULL DEFAULT 0.

На кроці 2 практики ви з сусідом по парті поставите одне одному питання «а якщо два записи з однаковою назвою?» Правильна відповідь: нічого не станеться, вони різняться значенням id. Якщо ти зробив ключем назву — станеться помилка, і другий запис у базу не потрапить.

Тип даних — вид значення, яке лежить у стовпці. У SQLite їх небагато:

• INTEGER — ціле число: хвилини, кількість, оцінка, номер;
• REAL — число з дробовою частиною: вага, температура;
• TEXT — текст будь-якої довжини: назва, опис, дата;
• BLOB — двійкові дані, наприклад вміст картинки. Нам сьогодні не потрібен.

Тип обирають за тим, що ти збираєшся з цим значенням робити. Хвилини записують числом, бо з числами рахують суму й середнє. Якщо записати «18 хв» текстом, база не зможе їх додати: доведеться в Python відрізати два останні символи в кожному рядку.

Окремого типу для дати в SQLite немає. Через це дату записують текстом у певному форматі, і саме тут найчастіше помиляються. Формат такий: рік-місяць-день, чотиризначний рік і двозначні місяць та день, 2026-09-06. Причина проста: у такому записі порівняння тексту дає той самий результат, що й порівняння дат. Рядок "2026-09-06" більший за "2026-08-31" і як текст, і як дата, тому сортування й відбір за проміжком часу працюють без жодних перетворень.

Якщо писати 06.09.2026, база порівнюватиме спочатку день. У списку, впорядкованому за такою «датою», 06 вересня опиниться поруч із 06 березня, а відбір «за останній тиждень» доведеться писати самому в Python.

І ще одна особливість саме SQLite: вона не забороняє записати текст у стовпець, оголошений як INTEGER. Тип тут — це домовленість, яку тримає твій код. А ось правила NOT NULL, UNIQUE, PRIMARY KEY і CHECK база перевіряє по-справжньому й порушити їх не дасть. CHECK — умова, яку база перевіряє під час кожного запису, наприклад CHECK (minutes >= 0): від’ємної кількості хвилин після цього в таблиці не з’явиться.

SQL — мова запитів до бази. Нею ти кажеш, який результат тобі потрібен; як саме його дістати з файлу, база вирішує сама. Команди традиційно пишуть великими літерами — так їх видно серед назв стовпців; база великі й малі літери в ключових словах не розрізняє.

CREATE TABLE — створити таблицю

CREATE TABLE habit (
    id      INTEGER PRIMARY KEY AUTOINCREMENT,
    title   TEXT    NOT NULL,
    day     TEXT    NOT NULL,
    minutes INTEGER NOT NULL DEFAULT 0,
    note    TEXT
);

У дужках перелічені стовпці: назва, тип і правила. Стовпець note без NOT NULL — необов’язковий, його можна лишити порожнім.

INSERT — додати рядок

INSERT INTO habit (title, day, minutes) VALUES ('Пробіжка 2 км', '2026-09-01', 18);

Спочатку перелік стовпців, потім значення в тому самому порядку. Текст у одинарних лапках, числа без лапок. Стовпець id не вказуємо — база поставить його сама.

SELECT — дістати рядки

SELECT * FROM habit ORDER BY id DESC;
SELECT id, title, day FROM habit WHERE day >= '2026-09-01' ORDER BY day DESC;
SELECT id, title FROM habit ORDER BY id DESC LIMIT 10;
SELECT COUNT(*) FROM habit;

Що тут за що відповідає:

• SELECT * — усі стовпці; замість зірочки можна перелічити потрібні через кому;
• FROM habit — з якої таблиці;
• WHERE — умова відбору: у результат потраплять лише рядки, для яких вона істинна;
• ORDER BY day DESC — упорядкувати за стовпцем day, DESC означає від більшого до меншого;
• LIMIT 10 — віддати не більше десяти рядків. Корисна річ, але саме через неї найчастіше не збігаються числа в автоперевірці;
• COUNT(*) — рахує рядки. Результат — таблиця з одного рядка й одного стовпця.

DELETE — видалити рядки

DELETE FROM habit WHERE id = 7;

Без WHERE команда видаляє всі рядки таблиці й нічого не перепитує, тому умову пиши завжди.

Останнє про запити: значення в них ніколи не склеюють із текстом запиту через + або f-рядок. Замість значення ставлять знак питання, а саме значення передають окремим списком:

db.execute("INSERT INTO habit (title, day) VALUES (?, ?)", ("Пробіжка", "2026-09-01"))

Так база отримує текст запиту й дані окремо й ніколи не сприймає дані як команду. Що буває інакше, розберемо на занятті 08, коли перевірятимемо сервіси одне одного на слабкі місця в захисті.

Нагадування із заняття 02: ендпоінт — це адреса, за якою сервер щось конкретне відповідає. Сьогодні ти додаєш ендпоінт списку — третій після /api/ping і /api/about.

У теці ~/app уже лежить готовий файл db.py. Його редагувати не треба, але треба знати, що в ньому:

• connect() — відкриває файл бази. Шлях бере з project.yaml, тому в коді його ніде не пишуть руками;
• query(sql, params) — виконує SELECT і повертає список словників Python, по одному словнику на рядок. Словник — це набір пар «назва: значення»; значення дістають за назвою, наприклад row["title"]. Назвами тут стають назви стовпців;
• execute(sql, params) — виконує INSERT, UPDATE або DELETE і повертає id доданого рядка;
• DB_PATH — готовий шлях до файлу бази. Його зручно надрукувати, щоб побачити, з яким саме файлом працює твій код.

Підключити db.py до свого файлу можна двома способами, і сьогодні тобі трапляться обидва. Рядок import db підключає весь файл, і далі до всього в ньому звертаються через крапку: db.query(...), db.DB_PATH. Рядок from db import query підключає лише одну функцію, і тоді пишуть query(...) — без db і крапки. Перш ніж писати виклик, подивись, який із цих двох рядків стоїть на початку файлу, у якому ти працюєш.

Сам ендпоінт після цього займає три рядки:

@app.get("/api/habits")
def list_items():
    return query("SELECT * FROM habit ORDER BY id DESC")

Рядок, що починається зі знака @ й стоїть просто над функцією, називають декоратором: він прив’язує функцію до адреси. @app.get("/api/habits") читається так: «коли хтось запитає цю адресу методом GET, виклич функцію, написану нижче». GET — вид запиту, яким просять дані; саме такий запит робить браузер, коли ти відкриваєш адресу.

FastAPI — бібліотека, якою написаний твій main.py. Вона зіставляє адресу запиту з потрібною функцією й перетворює те, що функція повернула, на JSON. Наша функція повертає список словників, і у відповіді він стає масивом JSON: квадратні дужки, всередині об’єкти у фігурних дужках через кому.

[{"id": 5, "title": "Читання", "day": "2026-09-04", "minutes": 40, "note": ""},
 {"id": 4, "title": "Пробіжка 2 км", "day": "2026-09-03", "minutes": 17, "note": "дощ"}]

Звідси й береться критерій заняття: кількість об’єктів у цьому масиві дорівнює кількості рядків, які повернув SELECT. Якщо в запиті немає ані WHERE, ані LIMIT, вона дорівнює COUNT(*) усієї таблиці.

Дві речі, без яких критерій не зарахується. Перша: адресу свого ендпоінта треба записати в маніфест project.yaml. Це єдине місце, де вона зафіксована, і саме звідти її беруть і викладач, і скрипти перевірки — самі вони назв не вгадують.

Друга: твій сервіс тримає ввімкненим uvicorn — програма, яка приймає запити з мережі й передає їх функціям із main.py. Файл main.py вона читає один раз, під час запуску, тому після кожної зміни файлу службу треба перезапустити. Службами в Linux керує systemd — частина системи, яка запускає програми у фоні й стежить, щоб вони працювали; команди їй дають через systemctl:

systemctl --user restart club-api

І ще одне, що знадобиться вже в наступному питанні. Крім даних сервер повертає на кожен запит код відповіді — тризначне число, яким він каже, чим усе скінчилося. Сьогодні трапляться три: 200 — усе гаразд, відповідь у тілі; 404 — сервер не знає такої адреси; 500 — адреса є, але функція під час роботи завершилася з помилкою.

1. Довести базу до 25 записів. Скрипт рахує тільки кількість, але записи мають бути справжні: за минулий місяць, за свій список ігор, за свої рослини. Найзручніше дописувати їх у seed.py частинами: додав п’ять нових рядків у список — запустив — перевірив кількість командою з кроку 8. Якщо додав ті самі рядки вдруге, дивись розділ про дублікати.
2. Запит із власною умовою. Додай у check_db.py ще один SELECT, який відповідає на осмислене питання про твої дані: скільки хвилин загалом за тиждень (SUM(minutes)), або п’ять найдовших записів, або всі записи однієї категорії. Запиши поруч у коментарі, на яке питання відповідає запит.
3. Розділ «Дані» у README. Відкрий ~/app/README.md і додай розділ, у якому переліч свої стовпці: назва, тип, обов’язковий чи ні, що означає. Цей розділ читатиме людина, яка бачить проєкт уперше.
4. Перевірка з телефона. Вимкни Wi-Fi і відкрий на телефоні адресу свого списку: http://91.219.61.4/u/<логін>/api/…. Ти маєш побачити текст JSON зі своїми записами.
5. Коміт домашнього завдання. Коли допишеш записи, новий запит і розділ у README, збережи ці нові зміни в git тими самими чотирма командами, що й у кроці 15. Повідомлення коміта має описувати зміну, а не бути словом «update».

На початку наступного заняття буде питання «поясни рядок»: викладач покаже будь-який рядок із твого init_db.py або seed.py і попросить сказати, що він робить.

sqlite3.OperationalError: unable to open database file

Python не зміг ані відкрити, ані створити файл бази. Найчастіша причина — немає теки ~/data: шлях до бази складається з неї, але сама вона не створюється. Перевір і, якщо теки немає, створи:

ls -ld ~/data
mkdir -p ~/data

Після цього повтори крок 5. Друга можлива причина — у project.yaml у полі file написано не ім’я файлу, а шлях із похилими рисками. Там має стояти саме app.db.

sqlite3.OperationalError: no such table: habit

База відкрилася, але таблиці в ній немає. Перевір по черзі три речі. Перше: чи запускався init_db.py — виконай його ще раз, він безпечний для повторного запуску. Друге: чи збігаються назви — у CREATE TABLE, у запиті й у полі main_table має стояти те саме слово, великі й малі літери теж мають збігатися. Третє: чи не з’явилася друга база. Ця команда покаже всі файли баз у твоїй домашній теці:

find ~ -name "*.db" -not -path "*/venv/*" -ls

Правильний файл один — ~/data/app.db. Якщо знайшовся ще один файл бази, подивись у project.yaml поле file: там має бути тільки ім’я app.db, без тек і похилих рисок — решту шляху db.py додає сам. Виправ поле, видали зайвий файл і повтори крок 5.

Записів удвічі більше, ніж додавав

seed.py запустився двічі, і кожен рядок додався повторно. Подивись, що саме в базі:

cd ~/app && /opt/club/venv/bin/python -c 'import db
for r in db.query("SELECT id, day, title FROM habit ORDER BY id"):
    print(r)'

Дублікати — це рядки з більшими номерами. Якщо перші п’ять записів правильні, а решта зайва, видали все, що після п’ятого:

cd ~/app && /opt/club/venv/bin/python -c 'import db; db.execute("DELETE FROM habit WHERE id > 5")'

Команда DELETE без WHERE видаляє всю таблицю й нічого не перепитує, тому умову перечитай перед натисканням Enter.

Забув NOT NULL або первинний ключ

Додати NOT NULL до наявного стовпця однією командою SQLite не дає. Поки записів п’ять, найпростіше створити таблицю заново. Спочатку виправ опис у init_db.py, потім видали стару таблицю й запусти обидва файли ще раз:

cd ~/app
/opt/club/venv/bin/python -c 'import db; c = db.connect(); c.execute("DROP TABLE habit"); c.commit()'
/opt/club/venv/bin/python init_db.py
/opt/club/venv/bin/python seed.py

DROP TABLE видаляє таблицю разом з усіма записами без можливості скасувати. Роби це лише зараз, поки даних мало; коли записів набереться 25, так уже не вийде, і таблицю доведеться переносити копіюванням.

Ендпоінт відповідає 500

Код 500 означає, що запит дійшов до твоєї функції і вона завершилася з помилкою. Дивись журнал: journalctl --user -u club-api -n 30. Найчастіші причини сьогодні — помилка в назві таблиці всередині SELECT (див. перший пункт) і неправильна назва стовпця в ORDER BY. Текст помилки називає стовпець прямо. Наприклад, no such column: data — це типова описка: стовпець із датою зветься day, а в запиті набрано data.

attempt to write a readonly database

Файл бази є, але записувати в нього твоя програма не може. Перевір права — і на теку, і на файл:

ls -ld ~/data
ls -l ~/data/

Власником і теки, і файлу має бути твій логін. Право на запис потрібне на обидва: під час запису SQLite створює поруч із базою тимчасовий файл app.db-journal, тому дозволу тільки на app.db не вистачить. Якщо власник правильний, а помилка лишається, дай собі права:

chmod u+rwx ~/data
chmod u+rw ~/data/app.db

Якщо власник інший — сам ти цього не виправиш, скажи викладачеві.