Добавить схему БД, миграции и проект транзакционных границ

This commit is contained in:
2026-11-16 21:47:32 +00:00
parent 65003b6119
commit fd3eb67798
3 changed files with 80 additions and 0 deletions
+19
View File
@@ -0,0 +1,19 @@
# Схема и транзакционные границы
Проект схемы составлен перед реализацией SQL-адаптера. PostgreSQL — единый источник истины, включая сессии.
| Таблица | Ключи и ограничения | Индексы и назначение |
| --- | --- | --- |
| users | UUID PK, username UNIQUE, NOT NULL для имени/хеша/времени | UNIQUE username для регистрации и входа |
| chats | UUID PK, title NOT NULL | (created_at, id) для списка |
| chat_members | (chat_id, user_id) PK, два FK, position для порядка участников | (user_id, chat_id) для доступных чатов |
| messages | UUID PK, chat_id FK, sender_id FK, составной FK на членство | (chat_id, created_at, id) для истории |
| sessions | token_hash PK, user_id FK, expires_at NOT NULL | expiry для возможной очистки |
| app_settings | name PK, value NOT NULL | постоянный случайный ключ подписи курсоров |
| schema_migrations | version PK | только учёт применённых миграций |
Каждый метод записи репозитория — одна транзакция с COMMIT до HTTP-ответа. Создание чата: проверить существование всех пользователей, вставить чат и всех участников, COMMIT; ошибка откатывает всё. Регистрация защищена UNIQUE, конфликт возвращает 409. Сообщение вставляется после проверки членства; FK также не позволяет записать отправителя вне чата. Создание/отзыв сессии — отдельные транзакции. Сессия проверяется на каждом защищённом запросе по времени БД; рестарт не меняет expiry.
Миграции нумеруются в migrations/*.sql. Runner выполняет новые файлы и запись версии в одной транзакции под advisory lock. Повторный запуск не выполняет уже учтённую версию. Пароли — Argon2id; в sessions лежит SHA-256 случайного 256-битного токена, а не пароль. SHA-256 здесь служит индексом высокоэнтропийного токена и не заменяет password KDF.
Пагинация SQL keyset, LIMIT + 1; offset не используется. Курсор сохраняет область ресурса и подписан постоянным ключом из БД, поэтому продолжение работает после рестарта. Часы PostgreSQL задают created_at. Между страницами нет snapshot; поздно закоммиченная конкурентная запись с ключом до курсора может не попасть в уже начатый обход. Для неизменной истории гарантируется отсутствие повторов и пропусков.
+24
View File
@@ -0,0 +1,24 @@
"""Versioned, transactional migrations; safe to run again."""
from pathlib import Path
import secrets
from .config import Settings
from .database import Database
def migrate(database):
directory = Path(__file__).resolve().parents[1] / 'migrations'
with database.transaction() as conn:
conn.execute('SELECT pg_advisory_xact_lock(20260201)')
conn.execute('CREATE TABLE IF NOT EXISTS schema_migrations (version text PRIMARY KEY)')
versions = {r['version'] for r in conn.execute('SELECT version FROM schema_migrations')}
for path in sorted(directory.glob('*.sql')):
if path.name not in versions:
conn.execute(path.read_text(encoding='utf-8'))
conn.execute('INSERT INTO schema_migrations(version) VALUES (%s)', (path.name,))
conn.execute("INSERT INTO app_settings(name,value) VALUES ('cursor_key',%s) ON CONFLICT DO NOTHING",
(secrets.token_hex(32),))
if __name__ == '__main__':
migrate(Database(Settings.from_env().database_url))
print('Migrations applied successfully (already applied versions skipped).')
+37
View File
@@ -0,0 +1,37 @@
CREATE TABLE users (
id uuid PRIMARY KEY,
username text NOT NULL UNIQUE CHECK (username ~ '^[a-z0-9_]{3,32}$'),
display_name text NOT NULL CHECK (char_length(display_name) BETWEEN 1 AND 100),
password_hash text NOT NULL,
created_at timestamptz NOT NULL DEFAULT clock_timestamp()
);
CREATE TABLE chats (
id uuid PRIMARY KEY,
title text NOT NULL CHECK (char_length(title) BETWEEN 1 AND 100),
created_at timestamptz NOT NULL DEFAULT clock_timestamp()
);
CREATE INDEX chats_order_idx ON chats(created_at, id);
CREATE TABLE chat_members (
chat_id uuid NOT NULL REFERENCES chats(id) ON DELETE CASCADE,
user_id uuid NOT NULL REFERENCES users(id),
position integer NOT NULL CHECK (position >= 0),
PRIMARY KEY(chat_id, user_id),
UNIQUE(chat_id, position)
);
CREATE INDEX chat_members_user_idx ON chat_members(user_id, chat_id);
CREATE TABLE messages (
id uuid PRIMARY KEY,
chat_id uuid NOT NULL REFERENCES chats(id),
sender_id uuid NOT NULL REFERENCES users(id),
text text NOT NULL CHECK (char_length(text) BETWEEN 1 AND 4000),
created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
FOREIGN KEY(chat_id, sender_id) REFERENCES chat_members(chat_id, user_id)
);
CREATE INDEX messages_history_idx ON messages(chat_id, created_at, id);
CREATE TABLE sessions (
token_hash text PRIMARY KEY CHECK (char_length(token_hash) = 64),
user_id uuid NOT NULL REFERENCES users(id),
expires_at timestamptz NOT NULL
);
CREATE INDEX sessions_expiry_idx ON sessions(expires_at);
CREATE TABLE app_settings (name text PRIMARY KEY, value text NOT NULL);