Начните с четырёх безопасных команд
sqlrs status --cache
sqlrs ls --all --cache-details
sqlrs alias check
sqlrs discoverОни показывают готовность контейнерного окружения, состояния, экземпляры и задания, проверяют alias-файлы и выводят рекомендации по проекту. Ни одна из этих команд не применяет миграции к базе.
Рабочая область не найдена
Выполняйте команду внутри нужного репозитория. Если .sqlrs/ ещё нет, перейдите в корень и запустите sqlrs init local --snapshot auto. Не используйте --force для вложенной рабочей области, пока не определите, каким проектам должны принадлежать пути и alias-файлы.
Движок или контейнерный runtime недоступен
Убедитесь, что Docker/Podman запущен и соответствует платформенной матрице. Выполните sqlrs status. Если принудительно выбран недоступный backend, верните автоматический выбор командой sqlrs config set snapshot.backend "auto" или временно используйте copy.
SQL-файл отклонён или не найден
Все входные файлы должны оставаться внутри рабочей области. Пути в прямой команде считаются от текущего каталога, а пути внутри alias — от каталога alias-файла. Проверьте включённые файлы и регистр имён на Linux.
Alias не найден
sqlrs alias ls --from cwd --depth recursive
sqlrs alias check test-dbСсылка на alias — точный логический путь от текущего каталога без суффикса файла. CLI не ищет совпадающее короткое имя по всему репозиторию. Prepare-рецепт заканчивается на .prep.s9s.yaml.
Liquibase не запускается
Проверьте доступность Liquibase на локальной машине и путь liquibase.exec в .sqlrs/config.yaml. Аргументы Liquibase должны идти после --; changelog и подключаемые им файлы — находиться внутри рабочей области.
Prepare не переиспользует ожидаемое состояние
sqlrs cache explain prepare test-db
sqlrs ls --states --cache-detailscache explain не выполняет prepare, не создаёт экземпляр и сообщает решение hit или miss. Для hit код причины равенexact_state_match, для miss — no_matching_state. Команда также выводит образ, нормализованные аргументы и хэши входных файлов, но пока не определяет, какое именно различие вызвало miss. Сравните эти поля вручную и не судите о кэше только по времени запуска.
Тесты не подключаются по DSN
Убедитесь, что процесс тестов действительно получает DATABASE_URL и не заменяет адрес и порт своими настройками. Проверьте DSN отдельным клиентом. Не передавайте свои-h/-p/-U/-d в run:psql: соединение внедряет sqlrs.
Diff падает на ref или файле
Запускайте команду внутри Git-репозитория, сначала разрешите оба ref через Git и проверьте, что основной -f или changelog существует в обеих ревизиях. Если проект использует символические ссылки, сначала попробуйте стандартный режим worktree, а не blob.
Когда открывать issue
Сначала сократите пример до одной рабочей области и команды. Добавьте версию из sqlrs --help, ОС, контейнерный runtime, безопасный фрагмент конфигурации и вывод с удалёнными DSN и секретами. Затем откройте issue в репозитории sqlrs.
В проекте есть рабочая область, один проверенный prepare-alias, короткая проверка базы, подключение основного набора тестов по DSN и Git-diff файлов миграций. Дальше добавляйте по одному сценарию и проверяйте поведение кэша явными командами.