База данных

Data.Rentgen использует реляционную базу данных для хранения сущностей происхождения данных и связей между ними.

В настоящее время Data.Rentgen поддерживает только PostgreSQL, поскольку полагается на партиционирование таблиц, полнотекстовый поиск и специфические функции агрегации.

Миграции

После запуска базы данных необходимо выполнить скрипт миграции. Если база данных пуста, он создаст все необходимые таблицы и индексы. Если база данных не пуста, будет выполнено обновление структуры базы данных.

Скрипт миграции — это тонкая обертка над Alembic cli, параметры и команды точно такие же.

Внимание

Другие контейнеры (consumer, server) должны быть остановлены во время выполнения миграций, чтобы предотвратить вмешательство.

Партиции

После выполнения миграций необходимо запустить [create-partitions-cli][DR-DB-doc-reference-database-create-partitions-cli], который создает партиции для некоторых таблиц в базе данных. По умолчанию он создает ежемесячные партиции для текущего и следующего месяца. Это можно изменить, переопределив аргументы команды.

Этот скрипт должен выполняться по расписанию, в зависимости от гранулярности партиций. Планирование можно выполнить, добавив специальную запись в crontab.

Настоятельно рекомендуется также добавить в cron скрипт очистки старых партиций cleanup-partitions-cli. Настройка планирования такая же, как и для создания партиций.

Аналитические представления

Вместе с миграциями создается несколько аналитических представлений. Они управляются через refresh-analytic-views-cli и должны выполняться по расписанию.

Заполнение данными

По умолчанию база данных создается без данных. Для заполнения базы данных примерами используйте db-seed-cli.

Требования

PostgreSQL 12 или выше. Рекомендуется использовать последнюю версию Postgres.

Установка и запуск

С Docker

Установите Docker
Установите docker-compose
Выполните следующую команду:
```
$ docker compose --profile analytics,cleanup,seed up -d
...
```
docker-compose загрузит образ PostgreSQL, создаст контейнер и том, а затем запустит контейнер. Точка входа образа создаст базу данных, если том пуст.

После этого запустится несколько одноразовых контейнеров:
- db-create-partitions создаст необходимые партиции в БД.
- db-cleanup-partitions очистит старые партиции.
- db-refresh-views обновит аналитические представления.
- db-seed заполнит базу данных примерами (необязательно, можно пропустить).
Параметры можно установить через файл .env или секцию environment в docker-compose.yml

docker-compose.yml

services: db: image: postgres:17 restart: unless-stopped env_file: .env.docker ports: - 5432:5432 volumes: - postgres_data:/var/lib/postgresql/data healthcheck: test: pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB start_period: 5s interval: 5s timeout: 5s retries: 3

db-migration: image: mtsrus/data-rentgen:${VERSION:-latest} command: | python -m data_rentgen.db.migrations upgrade head env_file: .env.docker depends_on: db: condition: service_healthy

db-create-partitions: image: mtsrus/data-rentgen:${VERSION:-latest} command: | python -m data_rentgen.db.scripts.create_partitions env_file: .env.docker depends_on: db-migration: condition: service_completed_successfully

db-refresh-views: image: mtsrus/data-rentgen:${VERSION:-latest} command: | python -m data_rentgen.db.scripts.refresh_analytic_views env_file: .env.docker depends_on: db-migration: condition: service_completed_successfully profiles: - analytics - all

db-cleanup-partitions: image: mtsrus/data-rentgen:${VERSION:-latest} command: | python -m data_rentgen.db.scripts.cleanup_partitions truncate --keep-after $(date --date='-1year' '+%Y-%m-%d') env_file: .env.docker depends_on: db-migration: condition: service_completed_successfully profiles: - cleanup - all

db-seed: image: mtsrus/data-rentgen:${VERSION:-latest} command: | python -m data_rentgen.db.scripts.seed env_file: .env.docker depends_on: db-migration: condition: service_completed_successfully profiles: - seed - all postgres_data: kafka_data:

.env.docker

Init Postgres database

POSTGRES_DB=data_rentgen POSTGRES_USER=data_rentgen POSTGRES_PASSWORD=changeme POSTGRES_INITDB_ARGS=--encoding=UTF-8 --lc-collate=C --lc-ctype=C DATA_RENTGEN__DATABASE__URL=postgresql+asyncpg://data_rentgen:changeme@db:5432/data_rentgen DATA_RENTGEN__LOGGING__PRESET=colored

See Backend -> Server -> Configuration documentation

DATA_RENTGEN__SERVER__DEBUG=false

See Backend -> Consumer -> Configuration documentation

DATA_RENTGEN__KAFKA__BOOTSTRAP_SERVERS=["broker:9092"] DATA_RENTGEN__KAFKA__SECURITY__TYPE=SCRAM-SHA-256 DATA_RENTGEN__KAFKA__SECURITY__USER=data_rentgen DATA_RENTGEN__KAFKA__SECURITY__PASSWORD=changeme DATA_RENTGEN__KAFKA__COMPRESSION=zstd

See Frontend -> UI

DATA_RENTGEN__UI__API_BROWSER_URL=http://localhost:8000

Session

DATA_RENTGEN__SERVER__SESSION__ENABLED=True DATA_RENTGEN__SERVER__SESSION__SECRET_KEY=session_secret_key

Keycloak Auth

DATA_RENTGEN__AUTH__KEYCLOAK__SERVER_URL=http://keycloak:8080 DATA_RENTGEN__AUTH__KEYCLOAK__REALM_NAME=create_realm_manually DATA_RENTGEN__AUTH__KEYCLOAK__CLIENT_ID=create_client_manually DATA_RENTGEN__AUTH__KEYCLOAK__CLIENT_SECRET=generated_by_keycloak DATA_RENTGEN__AUTH__KEYCLOAK__REDIRECT_URI=http://localhost:3000/auth-callback DATA_RENTGEN__AUTH__KEYCLOAK__SCOPE=email DATA_RENTGEN__AUTH__KEYCLOAK__VERIFY_SSL=False DATA_RENTGEN__AUTH__PROVIDER=data_rentgen.server.providers.auth.keycloak_provider.KeycloakAuthProvider

Dummy Auth

DATA_RENTGEN__AUTH__PROVIDER=data_rentgen.server.providers.auth.dummy_provider.DummyAuthProvider DATA_RENTGEN__AUTH__ACCESS_TOKEN__SECRET_KEY=access_key_secret

Personal Tokens

DATA_RENTGEN__AUTH__PERSONAL_TOKENS__ENABLED=True DATA_RENTGEN__AUTH__PERSONAL_TOKENS__SECRET_KEY=pat_secret

Cors

DATA_RENTGEN__SERVER__CORS__ENABLED=True DATA_RENTGEN__SERVER__CORS__ALLOW_ORIGINS=["http://localhost:3000"] DATA_RENTGEN__SERVER__CORS__ALLOW_CREDENTIALS=True DATA_RENTGEN__SERVER__CORS__ALLOW_METHODS=[""] DATA_RENTGEN__SERVER__CORS__ALLOW_HEADERS=[""] DATA_RENTGEN__SERVER__CORS__EXPOSE_HEADERS=["X-Request-ID","Location","Access-Control-Allow-Credentials"]

Добавьте скрипты в crontab:

$ crontab -e
...

0 0 * * * docker compose -f "/path/to/docker-compose.yml" start db-create-partitions db-refresh-views db-cleanup-partitions

Без Docker

Для установки PostgreSQL следуйте инструкции по установке.
Установите Python 3.10 или выше

Создайте виртуальное окружение

$ python -m venv /some/.venv
...
$ source /some/.venv/activate

Установите пакет data-rentgen со следующими дополнительными зависимостями:
```
$ pip install data-rentgen[postgres]
...
```
Настройте [подключение к базе данных][DR-DB-doc-reference-database-configuration] используя переменные окружения, например, создав файл .env:
/some/.env
```
$ export DATA_RENTGEN__DATABASE__URL=postgresql+asyncpg://data_rentgen:changeme@localhost:5432/data_rentgen
...
```
А затем прочитайте значения из этого файла:

console $ source /some/.env ...

Выполните миграции:

$ python -m data_rentgen.db.migrations upgrade head
...

Примечание

Эта команда должна выполняться после каждого обновления до новой версии Data.Rentgen.

Создайте партиции:

$ python -m data_rentgen.db.scripts.create_partitions
...

Создайте аналитические представления:
```
$ python -m data_rentgen.db.scripts.refresh_analytic_views
...
```
Заполните базу данных примерами данных (необязательно, можно пропустить):
```
$ python -m data_rentgen.db.scripts.seed
...
```

Добавьте скрипты в crontab:

$ crontab -e
...

# читаем настройки из файла .env и запускаем скрипт используя определенное venv со всеми необходимыми зависимостями
0 0 * * * /bin/bash -c "source /some/.env && /some/.venv/bin/python -m data_rentgen.db.scripts.create_partitions"
0 0 * * * /bin/bash -c "source /some/.env && /some/.venv/bin/python -m data_rentgen.db.scripts.cleanup_partitions truncate --keep-after $(date --date='-1year' '+%Y-%m-%d')"
0 0 * * * /bin/bash -c "source /some/.env && /some/.venv/bin/python -m data_rentgen.db.scripts.refresh_analytic_views"