Когда проект начал расти я почувствовал, что очень сильно не хватает комментариев к схеме базы данных. В живом приложении появляются таинcтвенные таблицы, какие-то флаги, json-ны и прочие неведомые вещи, иногда хочется узнать, что они означают.

Конечно некоторые поля в моделях очевидны, в Student#name в принципе очевидно что хранится, но какое-нибудь Group#migrated_from_old_db2 (название вымышленое) нуждается в объяснении - кто, когда, зачем это мигрировал и что такое старая база (вторая).

Я завел файл doc/db.md, в котором описал все таблицы и колонки, которые были на тот момент и попросил коллег поддерживать его. Конечно никто поддерживать не стал. И не из вредности, а потому-что при программировании приходится и так помнить тысячу вещей. Документирование изменений схемы не входило в обязательные рутины работы.

Решил проблему просто - написал тест, который падает, если в файле doc/db.md нет описания для какой-нибудь колонки. Формат файла очень простой, он легко парсится и красиво выглядит в интерфейсе гитхаба:

# uchi.ru db schema

## schools

Школы.

| column | description |
|--:|--:|
| name | Название |
...

Все таблицы и колонки легко вытянуть с помощью AR::Base.connection.tables и AR::Base.connection.columns. Вуаля! Мержить пул реквест на красных тестах нельзя. Но тесты падают, если схема обновилась, а doc/db.md нет!

Теперь все базы данных у нас документированы, а файл doc/db.md в каждом репозитарии один из ключевых при изучении приложения с которым работаешь первый раз или давно не работал. Поддерживать такую документацию легко и естественно, в итоге она гораздо информативнее стандартного файла db/schema.rb.