Базы из CLI

Бета-версия

Базы данных — в бета-версии: всё, что здесь описано, работает, но интерфейс и отдельные возможности ещё меняются. Подробнее — на странице «Базы данных».

Команды layero db нужны, чтобы не уходить в браузер посреди работы и чтобы то же самое умел агент в CI. Всё, что они делают, видно и в панели: база, заведённая из терминала, сразу появляется в списке.

Войдите один раз — CLI откроет браузер:

npx layero@latest login

Команды

Команда	Что делает
`layero db list`	Базы организации: имя, слаг, состояние, размещение, версия Postgres, занятое место и срок оплаты
`layero db create <имя>`	Завести общую базу из тарифа. Строка подключения печатается один раз
`layero db connect <база>`	Подключить проект к базе: строка подключения приедет в переменные проекта
`layero db disconnect <база>`	Отключить проект от базы: переменная уйдёт со следующим деплоем
`layero db sql <база> "<SQL>"`	Выполнить запрос или скрипт

У каждой из этих команд есть флаг --org <слаг>. Базу можно указать именем, слагом или id — как удобнее.

Какая организация

Если организация у вас одна, CLI возьмёт её. Если их несколько — возьмёт личную. Командную организацию нужно указать явно:

npx layero@latest db list --org moya-komanda

Выбирать «первую попавшуюся» командную организацию CLI не станет: базы стоят денег и принадлежат разным командам. Список организаций — layero orgs list.

Список баз

npx layero@latest db list

CRM  crm  active  Shared  PG18  API  проектов: 2  0.01 ГБ из 0.50 ГБ
Аналитика  analitika  active  выделенный  PG17  без API  проектов: 1  0.09 ГБ из 40.00 ГБ
  1 750 ₽/мес · спишем 12 октября

В строке:

размещение — Shared для общей базы из тарифа, выделенный для выделенной базы;
API или без API — включён ли у базы Data API;
занятое место из квоты — для общей базы квоту задаёт тариф, для выделенной — её диск.

У платной базы под основной строкой — вторая, про деньги. Она меняется вместе с состоянием оплаты:

Строка	Что это значит
`спишем 12 октября`	всё в порядке, следующее списание в этот день
`оплачено по 12 октября`	база оплачена до этой даты, автопродления нет
`оплата не прошла, работает по 12 октября`	списать не вышло, база пока работает — проверьте способ оплаты
`доступ закрыт за неоплату, удалим 15 октября`	база остановлена, в этот день её удалят

Что стоит за каждым состоянием — на странице «Тарификация».

Завести базу

npx layero@latest db create crm

Команда ждёт, пока база поднимется (обычно около 20 секунд), и печатает строку подключения:

✓ база «crm» готова в организации valya

  postgresql://<роль>:<пароль>@db.layero.ru:5432/<база>?sslmode=verify-full

  Пароль показывается один раз — сохраните строку подключения.
  Ключи Data API для фронтенда: layero data env

Строка подключения печатается один раз

Второй раз CLI её не напечатает. Если строка потерялась, пароль можно посмотреть или сменить в панели: меню карточки базы → Подключить → «Показать пароль» или «Сбросить пароль». Смена пароля отключит всё, что подключено со старым, поэтому надёжнее сохранить вывод сразу.

Если за полторы минуты база не поднялась, команда не ждёт дальше и пишет: «база ещё готовится — строка подключения ниже заработает, как только она поднимется». Строку она печатает всё равно.

Что из терминала завести нельзя

Из CLI заводится только общая база из тарифа. На флаги --dedicated, --cpu и --ram команда отвечает отказом и ссылкой на мастер в панели:

выделенный инстанс из терминала не заказывается

У выделенной базы есть цена и заморозка денег на карте, а подтвердить сумму в терминале негде. В панели видны конфигурации, цена и дата следующего списания — там и заказывайте, см. «Как завести базу».

Флаг --gb тоже больше не работает. Объём общей базы задаёт тариф, у выделенной — диск конфигурации, и выбрать его числом при создании нельзя.

Подключить проект

Запустите из каталога проекта, связанного с Layero (layero link или первый layero deploy):

npx layero@latest db connect crm

Из другого каталога — укажите проект явно:

npx layero@latest db connect crm --project moy-sajt

У подключения два следствия:

Строка подключения приедет в переменные проекта — в LAYERO_DATABASE_URL, а у второй базы того же проекта — в LAYERO_DATABASE_URL_<СЛАГ>. Приложение увидит её со следующего деплоя.
Домены проекта станут разрешёнными для Data API этой базы. Если сайт ходит в базу из браузера и получает отказ по CORS — первым делом проверьте, подключён ли проект.

Проект получает в базе собственную роль. Что она может — в разделе «Что может приложение».

Отключить проект

npx layero@latest db disconnect crm

Роль проекта удаляется сразу, переменная уходит из окружения со следующим деплоем, домены проекта перестают быть разрешёнными для Data API. Таблицы и данные остаются в базе, другие проекты продолжают работать.

Выполнить SQL

Запрос пишется следом за именем базы:

npx layero@latest db sql crm "select count(*) from orders"

Скрипт из нескольких операторов выполняется одной транзакцией: упал один — откатываются все. Ответ приходит по каждому оператору, так что миграция из десяти операторов не выглядит как «ничего не выполнилось»:

npx layero@latest db sql crm "
  create table if not exists tags (id bigint generated always as identity primary key, name text not null);
  insert into tags (name) values ('новое'), ('важное');
  select * from tags;
"

Запрос выполняется от имени владельца базы — с теми же правами, что и SQL-редактор в панели. Границы тоже общие:

Что	Значение
Время одного запроса	30 секунд, дальше Postgres отменяет его сам
Строк в ответе	первые 500, остальные отрезаются с пометкой «усечено»
Длина одного значения	4 096 символов, дальше — многоточие
Операторов в скрипте	до 200
Длина запроса	до 20 000 символов

Для выгрузки данных, долгих миграций и всего, что упирается в эти границы, подключайтесь напрямую через psql или драйвер по строке подключения.

В CI и у агентов

В CI вход по браузеру невозможен — выпустите токен и передайте его в переменной LAYERO_TOKEN:

npx layero@latest token create ci

LAYERO_TOKEN=<токен> npx layero@latest db sql crm "select 1" --json

С флагом --json, а также когда вывод идёт не в терминал, CLI печатает события JSON-lines, по одному на строку:

Команда	Событие	Что в нём
`db list`	`databases`	`org` и массив `databases` — те же поля, что и в панели
`db create`	`database_created`	`org`, `name`, `connection_string` — единственный раз, когда строка приходит с паролем
`db connect`	`database_connected`	`org`, `database`, `project`
`db disconnect`	`database_disconnected`	`org`, `database`, `project`
`db sql`	`query_result`	`columns`, `rows`, `row_count`, `truncated`, `statements`

Отказы приходят событием error с кодом и готовым следующим шагом в next_action. Коды, которые встречаются у layero db:

Код	Когда
`org_unknown`	CLI не смог выбрать организацию сам — передайте `--org`
`database_unknown`	в организации нет базы с таким именем, слагом или id
`project_unknown`	непонятно, какой проект подключать — запустите из каталога проекта или передайте `--project`
`sql_missing`	`db sql` вызван без запроса
`gb_not_supported`	`db create --gb`: объём так не выбирается
`dedicated_needs_panel`	`db create --dedicated`, `--cpu` или `--ram`: выделенная база заказывается в панели

Полный список событий и кодов — JSON-события CLI.

Data API из терминала

Ключи, разрешённые сайты и уровни доступа Data API настраиваются командами layero data:

npx layero@latest data enable --db crm        # включить Data API
npx layero@latest data env                    # адрес и публичный ключ для фронтенда
npx layero@latest data methods --db crm       # таблицы и функции с уровнями доступа
npx layero@latest data grant entries --get visitor --db crm
npx layero@latest data keys issue --kind secret --db crm

Как устроены уровни доступа и ключи — в разделе Data API.

Команды​

Какая организация​

Список баз​

Завести базу​

Что из терминала завести нельзя​

Подключить проект​

Отключить проект​

Выполнить SQL​

В CI и у агентов​

Data API из терминала​