Базы данных в 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;
• если после изменения базы приходится править скрипт в нескольких местах, вынесите подключение в отдельный блок или переменную;
• если не удается создать таблицу, проверьте, что есть название таблицы и хотя бы одно поле с названием и типом;
• если импорт или экспорт работает некорректно, закройте активные процессы, проверьте файл и повторите операцию;
• если не видно нужную базу в списке, очистите поле поиска, проверьте фильтры и нажмите обновление списка.