База даних
API ChurchApps використовує архітектуру окрема база даних для кожного модуля. Кожен із шести модулів даних має власну базу даних MySQL з незалежним пулом з'єднань. Це забезпечує чіткі межі даних і водночас дозволяє зберігати все в межах одного розгортання.
Перш ніж почати
- Встановіть MySQL 8.0+ -- див. Передумови
- Налаштуйте рядки підключення до бази даних у вашому файлі
.env-- див. Змінні середовища
Огляд архітектури
Api
├── membership_db ← Люди, групи, дозволи
├── attendance_db ← Служби, сесії, записи
├── content_db ← Сторінки, розділи, елементи
├── giving_db ← Пожертви, фонди, платежі
├── messaging_db ← Розмови, сповіщення
└── doing_db ← Завдання, плани, призначення
Ключові проєктні рішення
- Одна база даних на модуль -- Кожен модуль веде власну базу даних MySQL з окремим пулом з'єднань (яким керує
KyselyPool). Це забезпечує незалежність модулів і дозволяє незалежно змінювати схему. - Виняткове володіння -- Таблицями модуля читає і записує лише код самого цього модуля. Коли іншому модулю потрібні ці дані, він звертається до шлюзу модуля-власника, а не запитує таблиці напряму -- див. Міжмодульна взаємодія.
- Шаблон репозиторіїв без ORM -- Увесь доступ до даних відбувається через класи репозиторіїв, які будують типізовані SQL-запити за допомогою конструктора запитів Kysely для схеми модуля. Це дає повний контроль над продуктивністю запитів і поведінкою.
- Багатокористувацька архітектура з самого початку -- Кожен запит обмежується
churchId. Усі таблиці містять стовпецьchurchId, а шар репозиторіїв автоматично забезпечує ізоляцію між церквами.
Рядки підключення
Підключення до бази даних кожного модуля налаштовується у .env у стандартному форматі рядка підключення MySQL:
mysql://user:password@host:port/database
Наприклад, локальне середовище розробки може виглядати так:
Кожен модуль зчитує своє підключення зі змінної середовища з назвою <MODULE>_CONNECTION_STRING:
MEMBERSHIP_CONNECTION_STRING=mysql://root:password@localhost:3306/churchapps_membership
ATTENDANCE_CONNECTION_STRING=mysql://root:password@localhost:3306/churchapps_attendance
CONTENT_CONNECTION_STRING=mysql://root:password@localhost:3306/churchapps_content
GIVING_CONNECTION_STRING=mysql://root:password@localhost:3306/churchapps_giving
MESSAGING_CONNECTION_STRING=mysql://root:password@localhost:3306/churchapps_messaging
DOING_CONNECTION_STRING=mysql://root:password@localhost:3306/churchapps_doing
У продуктивному середовищі рядки підключення зберігаються в AWS SSM Parameter Store, і клас Environment зчитує їх під час запуску.
Скрипти схеми
Схеми таблиць визначено як міграції Kysely у каталозі tools/migrations/, упорядковані за модулями:
tools/migrations/
├── membership/
├── attendance/
├── content/
├── giving/
├── messaging/
└── doing/
Міграції визначають створення таблиць, індекси та зміни схеми. Каталог tools/dbScripts/ містить демонстраційні та початкові дані, які можна завантажити поверх схеми.
Ініціалізація бази даних
Ініціалізація всіх баз даних
npm run initdb
Ця команда створює всі шість баз даних і запускає міграції для кожної з них.
Ініціалізація однієї бази модуля
npm run initdb -- --module=membership
Працюючи з певним модулем, можна повторно ініціалізувати лише його базу даних, не торкаючись інших.
Шаблон доступу до даних
Репозиторії будують запити за допомогою конструктора запитів Kysely для типізованої схеми бази даних модуля, яку отримують через функцію getDb() модуля. Типовий метод репозиторію виглядає так:
public async loadAll(churchId: string) {
return getDb().selectFrom("people").selectAll()
.where("churchId", "=", churchId)
.execute();
}
Репозиторії отримують через RepoManager:
const repos = await RepoManager.getRepos<Repos>("membership");
const people = await repos.person.loadAll(churchId);
Завжди включайте churchId у свої запити, щоб зберігати ізоляцію між церквами. Ніколи не робіть запити між різними церквами, якщо для цього немає конкретної та авторизованої причини.
Міжмодульні посилання
Оскільки дані кожного модуля зберігаються в окремій базі даних, між межами модулів немає зовнішніх ключів чи SQL-з'єднань (JOIN). Запис, пов'язаний з даними іншого модуля, зберігає ідентифікатор цього запису -- наприклад, пожертва в базі giving містить personId особи з бази membership -- а будь-яке поєднання даних між модулями відбувається на рівні прикладного коду.
Саме це обмеження робить межі модулів реальними: кожна схема може змінюватися незалежно, базу даних модуля можна перенести на окремий сервер, а модуль навіть можна виділити в окремий сервіс без розплутування спільних таблиць чи міжбазових запитів.
Пов'язані статті
- Структура модуля -- Як контролери та репозиторії організовано всередині кожного модуля
- Локальне налаштування API -- Повна покрокова інструкція з налаштування