Підтримка PostgreSQL¶

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

Вбудований PostgreSQL — повноцінний PostgreSQL 18, який їде разом із BamDude і яким BamDude керує сам. Не треба ставити сервер і не треба писати рядок підключення.
Власний PostgreSQL — зовнішній сервер, який ви вже тримаєте; задається URL-ом.

Одна змінна, DATABASE_URL, обирає між трьома станами:

`DATABASE_URL`	Бекенд
порожньо / не задано	SQLite (за замовчуванням)
`embedded`	вбудований PostgreSQL 18
`postgresql+asyncpg://…`	зовнішній сервер PostgreSQL

Будь-що інше застосунок відхилить одразу на старті зі зрозумілим повідомленням, тож помилка в написанні впаде відразу, а не пізніше помилкою підключення.

Що коли обирати¶

Ситуація	Рекомендація
Один користувач, 1–5 принтерів	SQLite
Невелика ферма, < 10 принтерів	SQLite
Завантажена ферма, 10+ принтерів	PostgreSQL
40+ принтерів	PostgreSQL — вважайте обов'язковим
Багато одночасних API-клієнтів	PostgreSQL
Хочеться PostgreSQL, але без адміністрування сервера	`embedded`
PostgreSQL уже є, хай BamDude ним користується	зовнішній URL
Найпростіше з можливого	SQLite

Для BamDude вбудований і зовнішній сервери — це той самий PostgreSQL; різниця лише в тому, хто його запускає й зупиняє.

Приблизно від 40 принтерів переходьте на PostgreSQL

SQLite дозволяє рівно одного писача за раз, а його кеш сторінок — per-connection, тож кожне з'єднання в завантаженому пулі приходить холодним. Ні перше, ні друге не лікується налаштуваннями: на такому масштабі писач стає чергою, у якій стоїть усе інше. Перехід — це одна змінна й перезапуск, імпорт відбудеться сам, тож робіть це до того, як ферма доросте до проблеми, а не після. embedded — найменше роботи на нативній установці: сервер не треба ні ставити, ні адмініструвати. У Docker він недоступний — там беріть окремий контейнер, описаний нижче.

Вбудований PostgreSQL (`embedded`)¶

Задайте одну змінну:

DATABASE_URL=embedded

Це все. На наступному старті BamDude:

один раз ініціалізує кластер PostgreSQL 18 у DATA_DIR/postgres/18,
підніме його на 127.0.0.1 з паролем, який згенерує собі сам,
імпортує наявний bamdude.db, якщо він є (див. Перехід із SQLite нижче),
і чисто зупинить його, коли BamDude завершує роботу.

Бінарники беруться з нашого відкритого пакета embedded-postgres (PostgreSQL 18 + pgvector + pg_stat_statements), зібраного як wheel під Linux (x86_64, aarch64, armv7l), macOS і Windows; він приходить автоматично разом із Python-залежностями BamDude. Качати вручну нічого не треба.

Де лежать його файли¶

Файл	Призначення
`DATA_DIR/postgres/18/`	кластер бази (каталог версіонований мажором PostgreSQL)
`DATA_DIR/postgres/password`	згенерований пароль (права 0600)
`DATA_DIR/postgres/port`	порт, на якому він піднявся (лише коли порт не запінено)

Як підключитися сторонніми інструментами¶

За замовчуванням сервер бере вільний порт і запам'ятовує його у DATA_DIR/postgres/port. Щоб мати відомий порт для psql, DBeaver, pgAdmin, Grafana тощо — запіньте його:

DATABASE_URL=embedded
EMBEDDED_PG_PORT=6432

Далі, наприклад:

psql -h 127.0.0.1 -p 6432 -U bamdude -d bamdude
# пароль: вміст файлу DATA_DIR/postgres/password

Сервер слухає лише 127.0.0.1 — у мережу він не виставлений.

Один мажор PostgreSQL, зафіксований

Вбудований сервер — це PostgreSQL 18, і BamDude відмовиться відкривати кластер, створений іншим мажором. Майбутній перехід на новий мажор вийде окремим релізом із явним кроком міграції, тож оновлення ніколи не перепише каталог даних мовчки.

Вибір бекенду в інсталяторах¶

Тепер кожен інсталятор питає, який бекенд вам потрібен, а оновлення лишає той, яким ви вже користуєтесь.

Linux / macOS (install.sh)Windows (інсталятор .exe)Docker (docker-install.sh)

В інтерактиві питає SQLite / вбудований / зовнішній. Без інтерактиву:

./install.sh --db embedded --yes
./install.sh --db external --database-url "postgresql+asyncpg://user:pass@host:5432/bamdude" --yes

З вбудованим сервером юніт служби отримує довше й акуратніше вікно зупинки (systemd TimeoutStopSec=90 + KillMode=mixed), щоб контрольна точка завжди встигала завершитись.

У майстрі з'явилася сторінка Database з чотирма варіантами:

SQLite (за замовчуванням),
вбудований PostgreSQL як окрема служба Windows — реєструє службу BamDudePostgres, яка стартує перед BamDude (найнадійніше),
вбудований PostgreSQL під керуванням BamDude — одна служба, найпростіше,
зовнішній PostgreSQL — ввести URL.

Деінсталяція питає (за замовчуванням Ні), чи видаляти також усі дані, і коректно знімає службу PostgreSQL.

Питає SQLite / окремий контейнер PostgreSQL / зовнішній URL і сам пише .env. Вбудований сервер тут навмисно не пропонується — див. розділ про Docker нижче.

Використання зовнішнього сервера¶

Вкажіть DATABASE_URL на свій сервер. Драйвер має бути postgresql+asyncpg, і база вже повинна існувати — BamDude створює таблиці, а не базу.

DATABASE_URL=postgresql+asyncpg://bamdude:[email protected]:5432/bamdude

Складова	Значення
Драйвер	`postgresql+asyncpg` (обов'язково)
Користувач / пароль	ваші облікові дані
Хост	адреса сервера
Порт	типово `5432`
База	має існувати заздалегідь

Створюйте базу з локаллю UTF-8

Пошук без урахування регістру (ILIKE) і ранжування повнотекстового пошуку залежать від LC_CTYPE бази. База, створена з локаллю C або POSIX, зводить регістр лише для ASCII, тож «Лампа» не знайдеться за запитом ЛАМПА. Створюйте її з локаллю UTF-8 — наприклад CREATE DATABASE bamdude ENCODING 'UTF8' LOCALE 'en_US.utf8' TEMPLATE template0; (або LOCALE_PROVIDER builtin LOCALE 'C.UTF-8' на PostgreSQL 17+). BamDude перевіряє це на старті: на базі з локаллю C він зводить регістр через юнікодне порівняння (PostgreSQL 17+ або збірка з ICU), вимикає ранжування повнотекстового пошуку і пише про це в лог; сервер, де такого порівняння немає, шукає лише зі зведенням ASCII і пише в лог попередження з тим, як це виправити. Вбудований сервер BamDude створює правильно сам.

PostgreSQL у Docker¶

Вбудований сервер — не варіант для Docker

DATABASE_URL=embedded працює на нативній установці (служба Linux, інсталятор Windows), але не в контейнері. Образ BamDude працює від root, а initdb під root запускатися відмовляється — це правило самого PostgreSQL, не обмеження BamDude. Якщо все ж виставити його в контейнері, той помре на першому старті з initdb: cannot be run as root, тому docker-install.sh цей варіант не пропонує.

У Docker PostgreSQL — це один із двох варіантів нижче.

Окремий контейнер PostgreSQL¶

Скористайтесь штатним override docker-compose.postgres.yml:

# .env
COMPOSE_FILE=docker-compose.yml:docker-compose.postgres.yml
POSTGRES_PASSWORD=change-me
DATABASE_URL=postgresql+asyncpg://bamdude:[email protected]:5433/bamdude

Host-мережа й адреса бази

Штатний compose запускає BamDude із network_mode: host (щоб працював пошук принтерів), а контейнер у host-мережі не бачить інший контейнер за іменем сервісу Compose. Тому на Linux override публікує PostgreSQL на 127.0.0.1:5433, і DATABASE_URL вказує саме туди; на Docker Desktop (macOS/Windows), де host-режим знімається, потрібне ім'я сервісу @postgres:5432. docker-install.sh сам пише правильний варіант під вашу платформу.

Перехід із SQLite¶

Перемикання на будь-який PostgreSQL (вбудований чи зовнішній) виконує міграцію за вас, один раз.

Задайте DATABASE_URL (embedded або URL) і перезапустіть BamDude.
BamDude бачить порожній PostgreSQL поруч із наявним bamdude.db.
Він переносить усі дані зі SQLite у PostgreSQL.
Перейменовує bamdude.db → bamdude.db.migrated.

Ручних кроків не потрібно

Переїжджають усі таблиці, налаштування, архіви, шпулі, черги й облікові записи. Конвертація типів (SQLite 0/1 → boolean, рядки дат → timestamps), послідовності автоінкременту й повнотекстовий індекс обробляються автоматично.

Що НЕ переноситься¶

Віртуальні таблиці FTS5 (їх замінює tsvector у PostgreSQL)
Файли WAL/SHM (специфічні для SQLite)
Внутрішній облік міграцій (створюється наново)

Повернення на SQLite

Приберіть DATABASE_URL (або лишіть порожнім) і перезапустіть. Ваші початкові дані нікуди не зникли — вони у bamdude.db.migrated, перейменуйте назад у bamdude.db.

Резервні копії й відновлення¶

Резервні копії завжди у переносному форматі SQLite, хай яким є бекенд:

копію з PostgreSQL можна відновити на SQLite і навпаки,
це один файл, який легко переглянути,
жодної залежності від pg_dump.

Створення й відновлення — у Налаштування → Резервні копії. При створенні BamDude вивантажує всі таблиці у тимчасовий файл SQLite і пакує його разом з архівами та іншими даними в ZIP; при відновленні — імпортує цей SQLite назад у активний бекенд із конвертацією типів.

Щоб зробити рідний дамп зовнішнього PostgreSQL, користуйтесь pg_dump напряму — вебінтерфейс завжди віддає переносний формат.

Повнотекстовий пошук¶

API пошуку поводиться однаково; відрізняється лише рушій під ним:

Можливість	SQLite	PostgreSQL
Рушій	віртуальна таблиця FTS5	`tsvector` + індекс GIN
Синтаксис запиту	`MATCH` із шаблонами	`to_tsquery` з пошуком за префіксом
Ваги	без ваг	A (назва) > B (ім'я файлу, теги) > C (дизайнер, філамент) > D (нотатки)

Ранжування потребує бази, яка сама зводить регістр юнікоду (локаль UTF-8). На базі з локаллю C, де є юнікодне сортування, BamDude шукає через ILIKE із цим сортуванням (без ранжування); а та, де сортування немає зовсім, зберігає індекс і ранжує — але зводить лише ASCII. Див. примітку про локаль вище.

Пул підключень¶

Параметр	SQLite	PostgreSQL
Розмір пулу	20	20
Максимальне переповнення	200	80
Pre-ping / recycle	—	увімкнено / 1800 с

Великі ферми можуть підняти ці значення змінними DB_POOL_SIZE, DB_MAX_OVERFLOW, DB_POOL_TIMEOUT, DB_POOL_RECYCLE і DB_POOL_USE_LIFO. Якщо користуєтесь зовнішнім PostgreSQL, переконайтесь, що його власний max_connections із запасом перевищує (pool_size + max_overflow) × кількість воркерів — вбудований сервер налаштований із щедрим max_connections саме для цього.

Повільні міграції на першому старті¶

Деякі міграції повільні незалежно від бекенду, бо вузьке місце — читання 3MF з диска, а не запис у базу. Наприклад, m022 (0.4.1) читає один конфігураційний файл усередині кожного наявного 3MF; бібліотека на тисячі файлів може провести там кілька хвилин, перш ніж підніметься API — однаково і на PostgreSQL, і на SQLite. Якщо здається, що старт завис, шукайте в журналі рядки m022 … progress.

Перевірити, чи все з нею гаразд¶

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

Що показує	На що дивитись
СУБД, версія і режим	`SQLite`, вбудований PostgreSQL, який запускає BamDude, вбудований як служба Windows, або зовнішній сервер. Варто глянути першим: інсталяція, яка мала переїхати на PostgreSQL і не переїхала, чесно про це скаже.
Розмір на диску	Справжня цифра на обох бекендах. (Картка «База даних» вище дивиться на файл `bamdude.db`, тож на PostgreSQL показує 0.)
Пул з'єднань	Зайнято проти розміру пулу, плюс перевищення. Постійне перевищення означає, що пул замалий для ферми — підніміть `DB_POOL_SIZE`.
Влучань у кеш (PostgreSQL)	Нижче ~90% на прогрітому сервері означає, що він читає з диска більше, ніж мав би: зазвичай це `shared_buffers` або запит, що читає значно більше рядків, ніж потрібно.
Взаємні блокування (PostgreSQL)	Має бути 0. Будь-що інше варто повідомити.
Режим журналу і розмір WAL (SQLite)	Режим журналу має бути `wal`. WAL, який лише росте, означає, що контрольні точки не завершуються.
Найповільніші запити	Текст запиту, скільки разів виконувався і скільки часу забрав сумарно.

Звідки береться список найповільніших¶

PostgreSQL — з власного pg_stat_statements сервера. Вбудований сервер вмикає його сам. ⚠️ Якщо вбудований PostgreSQL працює як служба Windows, BamDude не пише конфігурацію того сервера, тож розширення може бути встановлене, але не підвантажене — тоді картка так і напише замість того, щоб показати порожню таблицю.
SQLite — такого подання немає, тож список береться з власних вимірювань BamDude і потребує увімкненого журналу повільних запитів у Налаштуваннях → Загальні (див. Усунення неполадок → Що саме гальмує). Поки він вимкнений, картка про це каже.

Показник, який BamDude не зміг прочитати, не вигадується: він пропускається і називається внизу картки, тож одна недоступна цифра ніколи не гасить решту.

Prometheus

Ті самі числа експортуються як метрики bamdude_db_* — інформація про СУБД, розмір, пул, і залежно від бекенда або влучання в кеш, з'єднання та взаємні блокування, або байти WAL і вільні сторінки.

Що варто знати¶

Зовнішня база має існувати заздалегідь

Для зовнішнього сервера створіть базу самі — BamDude створює лише таблиці. Вбудованому серверу нічого з цього не потрібно, він створює все сам.

Тримайте рядок підключення подалі від чужих очей

У продакшені краще файл .env з обмеженими правами (або Docker secrets), ніж звичайна змінна середовища. Вбудований сервер узагалі не кладе пароль у ваш .env — він тримає його у DATA_DIR/postgres/password.