Бази даних в Afina#

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

Перш ніж почати#

База даних, або БД, - це структуроване сховище інформації.

Дані в ній зберігаються не хаотично, а в чіткій структурі, щоб їх було зручно:

• знаходити;
• додавати;
• оновлювати;
• видаляти;
• використовувати в автоматизації.

У контексті Afina в базі даних найчастіше зберігають:

• адреси гаманців;
• баланси;
• списки акаунтів або адрес;
• статуси обробки;
• лог або історію дій;
• технічні дані, які скрипт має читати або оновлювати.

У Afina база даних використовується як локальний файл .db.

Це зручно, тому що:

• не потрібне окреме серверне підключення;
• робота йде локально і швидко;
• база краще підходить для масового читання і запису;
• її зручно переносити, копіювати і використовувати в різних скриптах.

Базовий і основний формат у цьому сценарії - SQLite.

SQLite - це база даних, у якій усе зберігається в одному файлі. Приклади назв:

• database.db;
• wallet.db;
• accounts.db.

Головна перевага SQLite в тому, що для неї не потрібен окремий сервер. Саме тому вона добре підходить для локальної роботи в Afina.

Розділ «Бази даних» в Afina потрібен для повної базової роботи з БД. Тут можна:

• створити нове підключення до бази;
• підключити вже існуючий .db-файл;
• переглядати список баз;
• групувати бази по папках;
• відкривати базу для роботи з таблицями;
• створювати таблиці;
• додавати і редагувати записи;
• запускати SQL-запити;
• імпортувати і експортувати базу;
• працювати з таблицями всередині бази.

Створення та підключення бази#

1. Перейдіть у розділ Бази даних.

На скріншоті нижче показано розділ «Бази даних» у табличному режимі зі списком підключень.

2. Натисніть Додати базу даних, якщо хочете створити нову базу або підключити існуючу.

На наступному скріншоті показано кнопку «Додати базу даних» у розділі «Бази даних».

3. У полі «Назва підключення» введіть назву підключення.

4. Перевірте, що в полі «Тип бази даних» вибрано SQLite.

5. Натисніть Зберегти, якщо хочете створити нове підключення до локальної бази даних.

Після цього Afina створить нове підключення до локальної бази даних.

6. Увімкніть перемикач «Використати існуючий .db файл», якщо потрібно підключити вже готовий .db-файл.

7. Вкажіть шлях до потрібного .db-файлу.

8. Натисніть Зберегти, щоб підключити існуючу базу.

Після цього Afina почне працювати з уже готовою базою даних.

На цьому скріншоті показано вікно «Створити базу даних» із назвою підключення, типом SQLite і режимом для підключення існуючого .db-файлу.

Імпорт та експорт бази#

SQL dump - це резервна копія бази даних у SQL-форматі.

У такому файлі зберігаються:

• структура таблиць;
• SQL-команди для створення бази;
• записи, які є в таблицях.

SQL dump потрібен, щоб:

• відновити базу;
• передати її іншій людині;
• перенести на інший ПК;
• зберегти повну резервну копію перед змінами.

1. Наведіть курсор на потрібну базу даних, якщо хочете імпортувати SQL-файл у вже існуючу .db-базу.

2. Натисніть кнопку імпорту SQL-файлу.

3. Виберіть локальний SQL-файл.

Після цього SQL-файл буде імпортовано в існуючу базу даних.

На скріншоті нижче показано список баз даних з підсвіченою кнопкою імпорту SQL-файлу в рядку потрібної бази.

4. Наведіть курсор на потрібну базу даних, якщо хочете експортувати її поточний стан.

5. Натисніть Експорт бази даних.

6. Виберіть потрібний варіант експорту.

Найчастіше використовують SQL-експорт усієї бази.

На наступному скріншоті показано меню експорту бази даних з варіантами повного експорту, тільки схеми або тільки даних.

Повний SQL-експорт підходить для:

• резервного копіювання;
• перенесення бази;
• передачі іншому користувачу;
• відновлення бази в майбутньому.

Видалення та відкриття бази#

1. Знайдіть потрібну базу даних у таблиці.

2. Натисніть іконку ⋮ у картці або рядку бази даних.

3. Оберіть Видалити базу даних.

4. Натисніть Підтвердити.

Після цього базу даних буде переміщено в кошик баз даних.

На скріншоті нижче показано меню дій бази даних з пунктом «Видалити базу даних».

5. Натисніть Фільтри, якщо хочете відкрити кошик баз даних.

6. Увімкніть перемикач «Показати тільки видалені».

7. Позначте чекбоксом потрібну базу даних у списку видалених.

8. Оберіть Видалити без відновлення, якщо хочете остаточно видалити базу.

9. Натисніть Підтвердити.

На наступному скріншоті показано список видалених баз даних з дією «Видалити без відновлення».

10. Знайдіть потрібну базу в списку, якщо хочете відкрити її для роботи.

11. Відкрийте базу з таблиці або картки.

12. Перейдіть у робочу область.

Саме в робочій області ви вже працюєте з таблицями і записами.

На цьому скріншоті показано список баз даних з іконкою відкриття менеджера бази даних.

Таблиці та типи даних#

Таблиця - це набір рядків і колонок.

Саме таблиці зберігають усі дані бази.

Наприклад, окремими таблицями можна зберігати:

• гаманці;
• баланси;
• статуси;
• історію дій;
• допоміжні технічні дані.

Для базової роботи достатньо розуміти такі типи:

• INTEGER - цілі числа;
• REAL - дробові числа;
• TEXT - текстові значення;
• BLOB - двійкові дані;
• NULL - відсутність значення;
• NUMERIC - числовий або універсальний тип, якщо інтерфейс його підтримує.

Найважливіші обмеження:

• NOT NULL - значення обов'язкове;
• DEFAULT - значення за замовчуванням;
• UNIQUE - заборона дублів;
• PRIMARY KEY - унікальний ідентифікатор рядка;
• AUTOINCREMENT - автоматичне збільшення значення, якщо це поле id.

Прості практичні приклади:

• адресу гаманця часто роблять UNIQUE;
• поле status часто має DEFAULT 0;
• поле id зазвичай роблять PRIMARY KEY і AUTOINCREMENT.

Створення та зміна таблиць#

1. У лівій панелі «Таблиці» натисніть іконку +, якщо потрібно створити таблицю вручну.

2. У вікні «Створення таблиці» введіть назву таблиці.

3. Натисніть Додати поле.

4. Для кожного поля задайте назву.

5. Для кожного поля виберіть тип.

6. За потреби задайте додаткові властивості.

7. За потреби увімкніть перемикачі «Первинний ключ», «Не NULL», «Унікальне» та «Автоінкремент».

8. Натисніть Створити таблицю.

На скріншоті нижче показано вікно «Створення таблиці» з полями, типами та додатковими властивостями.

9. Натисніть іконку редагування в рядку таблиці, якщо потрібно змінити її структуру.

Через іконку редагування зазвичай можна:

• змінити назву таблиці;
• додати нові поля;
• видалити зайві поля;
• змінити властивості полів.

10. Натисніть іконку кошика в рядку таблиці, якщо потрібно видалити таблицю повністю.

На наступному скріншоті показано рядок таблиці з іконками додавання запису, редагування та видалення таблиці.

Додавання та редагування записів#

Є два основні способи додавання даних у таблицю.

Вручну через інтерфейс Цей варіант підходить, якщо записів небагато, треба швидко перевірити логіку або ви створюєте тестові дані.

1. Виберіть таблицю.

2. Натисніть іконку додавання запису.

3. Заповніть поля.

4. Натисніть Додати запис.

На скріншоті нижче показано вікно «Створення запису» для додавання нового рядка.

Через імпорт або вставку підготовлених даних Цей варіант підходить, якщо даних багато, вони вже є в Google Sheets або іншій таблиці, і потрібно швидко завантажити велику кількість записів.

5. Скопіюйте потрібні дані в Google Sheets у такому форматі, щоб поля відповідали полям у таблиці Afina.

6. Вставте дані через Ctrl+V в одне з полів.

7. Натисніть Зберегти.

На цьому скріншоті показано таблицю з новим рядком після вставки даних і кнопкою збереження змін.

8. Натисніть двічі лівою кнопкою миші на потрібне поле в гриді даних, якщо потрібно відредагувати запис.

9. Змініть значення так, як вам потрібно.

10. Скористайтеся пакетними діями, якщо у вас вибрано кілька рядків через чекбокс.

У такому режимі можуть бути доступні дії:

• зберегти зміни;
• скасувати зміни;
• видалити вибрані записи.

На наступному скріншоті показано грид даних з вибраним рядком і пакетними діями збереження, скасування та видалення.

SQL та робота у скрипті#

Окрім роботи через інтерфейс, у Afina можна працювати із SQL-напряму.

Це робиться через компонент Database у скрипті або через «Термінал запитів» у самій базі даних.

Для базової автоматизації достатньо знати 4 команди:

• SELECT - отримати дані;
• INSERT - додати запис;
• UPDATE - оновити запис;
• DELETE - видалити запис.

На практиці найчастіше використовуються:

• SELECT, щоб перевірити, чи запис існує;
• INSERT, щоб створити новий запис;
• UPDATE, щоб змінити вже наявні дані.

Підключення до бази краще виносити в окремий блок на початку скрипта.

Це важливо, тому що так:

• підключення задається один раз;
• далі воно використовується по всьому скрипту;
• при зміні бази не треба правити багато місць;
• логіка скрипта стає зрозумілішою.

1. Перейдіть на полотно скрипта.

2. У «Панелі компонентів» знайдіть компонент «База даних підключень».

3. Перетягніть його на полотно в початок логіки або в ту частину, де починається робота з базою.

4. У полі «Тип бази даних» виберіть SQLite.

5. У полі «Вибрати підключення» виберіть потрібну базу даних зі списку.

6. У полі *«Зберегти в » вкажіть назву змінної, у яку буде збережено підключення.

7. Натисніть Зберегти.

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

На скріншоті нижче показано компонент «База даних підключень» на полотні скрипта з вибраним типом SQLite і підключенням.

Компонент Database у скрипті зазвичай містить:

• вибір типу бази даних;
• вибір підключення;
• поле SQL-запиту;
• збереження результату в змінну.

Базова логіка така:

1. обираєте підключення;
2. задаєте SQL-запит;
3. виконуєте його;
4. зберігаєте результат у змінну;
5. використовуєте результат у наступних блоках.

На наступному скріншоті показано компонент «База даних» на полотні скрипта з підключенням SQLite, SQL-запитом і змінною для результату.

Запити в Afina можна створювати:

• вручну;
• через вбудований конструктор;
• через ChatGPT або вбудований GPT, якщо ви налаштували API ChatGPT в Afina.

Конструктор зручний для старту, бо допомагає без помилок зібрати:

• SELECT;
• INSERT;
• UPDATE;
• DELETE.

Тестування запитів і результатів#

1. Додайте на полотно компонент «База даних», якщо хочете протестувати SQL-запит окремо.

2. У полі «Тип бази даних» виберіть SQLite.

3. У полі «Вибрати підключення» виберіть потрібну базу даних.

4. У полі *«Запит » введіть SQL-запит, який хочете перевірити.

Для тесту найзручніше починати з простого SELECT, наприклад SELECT * FROM emails.

5. У полі *«Зберегти в » вкажіть назву змінної, у яку буде збережено результат, наприклад emails.

6. Натисніть кнопку тестування або виконання запиту в компоненті.

7. Перегляньте результат виконання запиту.

Якщо запит коректний, ви одразу побачите результат у вигляді масиву записів.

Це зручно, тому що можна:

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

На скріншоті нижче показано вікно «Тестовий запит» з SQL-запитом SELECT і кнопкою виконання.

На наступному скріншоті показано результат тестового SQL-запиту у вигляді масиву записів.

Результат SELECT у Afina зазвичай приходить як масив рядків.

Якщо ви зберегли результат у змінну emails, звернення до значень виглядає так:

• ${emails[0].email};
• ${emails[0].address};
• ${emails[0].balance}.

Тут:

• [0] - перший рядок результату;
• .email, .address, .balance - назви колонок.

Умову в IF краще будувати не по всьому масиву, а по конкретному полю.

Наприклад:

• чи існує ${emails[0].address};
• чи існує ${emails[0].balance}.

Саме так зазвичай вирішують:

• робити INSERT;
• чи робити UPDATE.

Результат#

Після виконання цих дій у вас буде повний базовий сценарій роботи з базами даних в Afina: ви зможете створити або підключити SQLite-базу, імпортувати чи експортувати її через SQL dump, створювати таблиці, додавати й редагувати записи, виконувати SQL-запити та використовувати результати в скриптах через окремий блок підключення і компонент Database.

Ознаки успішного результату

• ви розумієте, що таке база даних у контексті Afina;
• знаєте, чому Afina зручно працює з локальним .db-файлом;
• розумієте, що таке SQLite;
• можете створити нову базу;
• можете підключити існуючий .db-файл;
• розумієте, що таке SQL dump;
• можете створити таблицю вручну;
• можете додати запис;
• розумієте, як працюють SELECT, INSERT, UPDATE, DELETE;
• знаєте, як дістати значення з результату SELECT;
• розумієте, коли і навіщо використовувати SQL dump.

Якщо щось працює не так

• якщо результат SELECT є, але значення не дістається, звертайтеся до нього у форматі ${вашаЗмінна[0].назва_колонки};
• якщо в таблиці з'являються дублікати, додайте UNIQUE для критичних полів і перед INSERT перевіряйте запис через SELECT;
• якщо після зміни бази доводиться правити скрипт у кількох місцях, винесіть підключення в окремий блок або змінну;
• якщо не вдається створити таблицю, перевірте, що є назва таблиці і хоча б одне поле з назвою та типом;
• якщо імпорт або експорт працює некоректно, закрийте активні процеси, перевірте файл і повторіть операцію;
• якщо не видно потрібну базу в списку, очистіть поле пошуку, перевірте фільтри і натисніть оновлення списку.