Metadata-Version: 2.4
Name: dbspec
Version: 1.1.6
Summary: DBSpec: CLI/TUI for database design (Excel as DSL)
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: textual
Requires-Dist: rich
Requires-Dist: openpyxl
Requires-Dist: pydantic>=2.0.0
Requires-Dist: sqlalchemy>=2.0.16
Requires-Dist: alembic
Requires-Dist: psycopg[binary]
Requires-Dist: jinja2

# DBSpec

![DBSpec TUI Project screen](docs/assets/logo.png)


**Проектирование реляционных баз данных со скоростью продуктовой команды.**

DBSpec — CLI/TUI-инструмент для команд, которые моделируют данные в таблицах, но хотят инженерную воспроизводимость и контроль качества.
Он превращает привычный spreadsheet-процесс в проверяемый delivery pipeline:

- XLSX как удобная поверхность редактирования для аналитиков;
- JSONL (`.dbspec/data/*.jsonl`) как SSOT;
- CLI/TUI-операции для sync, validation, import, code generation и migrations.

## Why DBSpec

Проектирование БД часто ломается между бизнес-смыслом и техническими деталями:

- аналитики быстро работают в spreadsheets, но такие изменения сложно проверять и ревьюить;
- инженерам нужен структурированный источник данных для автоматизации, проверок и генерации кода;
- команды теряют время на перенос смысла схемы в SQL/models и поддержку синхронизации.

DBSpec решает это через единый operational flow: от spreadsheet-ввода до валидированных schema artifacts, пригодных для автоматизации.

## What You Get

- быструю итерацию схем без отказа от spreadsheet workflows;
- воспроизводимую синхронизацию XLSX и SSOT JSONL;
- встроенную validation для targets `ssot` и `db`;
- PostgreSQL import в SSOT;
- генерацию SQLAlchemy models из SSOT;
- управление Alembic migrations из CLI и TUI;
- установку CLI через npm package `@ai-devtools/dbspec`.

## Product Vision

DBSpec делает проектирование баз данных общим языком для analytics, backend и platform teams.
Вместо разрозненных инструментов он дает один source of truth и один workflow, понятный людям и исполняемый tooling.

## Quick Start

### 1. Установить CLI

```bash
npm i -g @ai-devtools/dbspec
```

После установки команда остается стабильной:

```bash
dbspec --help
```

### 2. Инициализировать проект

```bash
dbspec init
```

### 3. Сгенерировать XLSX template

```bash
dbspec xlsx --template
```

### 4. Синхронизировать и проверить SSOT

```bash
dbspec sync
dbspec validate --target=ssot
```

### 5. Сгенерировать models

```bash
dbspec gen models
```

## Local Development

Для разработки из исходников установите зависимости:

```bash
make install-deps
```

## Run CLI

```bash
dbspec --help
```

or

```bash
uv run python -m src --help
```

Полный command reference: `docs/cli.md`.

## Run TUI

```bash
dbspec tui
```

TUI включает project workflows для init/xlsx/sync/import/validate/codegen/logs/migrations.

Migrations user guide: `docs/tui-migrations.md`.

## Configuration

Локальная конфигурация: `.dbspec/config.toml`.

Подробнее:

- `docs/config.md` — все ключи и defaults;
- `docs/jsonl-format.md` — формат SSOT JSONL;
- `docs/xlsx-template-structure.md` — структура XLSX и template resources.

## Development and Quality

После изменений в коде запускайте:

```bash
make lint
make format
make test
```

Environment и tooling: `docs/development.md`.

## Distribution

Пользовательский канал установки DBSpec — npm root package:

```bash
npm i -g @ai-devtools/dbspec
```

Root package `@ai-devtools/dbspec` устанавливает команду `dbspec` и подтягивает matching platform package для поддерживаемой ОС/архитектуры. PyInstaller binary остается внутренним release artifact для сборки npm platform packages, но не является отдельным пользовательским install channel.

Для maintainer release flow:

```bash
make build-binary
make smoke-binary
make npm-trust-setup DRY_RUN=1
make npm-trust-setup
make release TAG=v0.1.0
```

Release process и maintainer checklist:

- `docs/process/release-process.md`;
- `docs/process/release-checklist.md`.

## Documentation Index

Главный индекс документации: `docs/README.md`.
