Начало работы с интерфейсом командной строки Databricks для Lakebase

Это важно

Автомасштабирование Lakebase находится в бета-версии в следующих регионах: eastus2, westeurope, westus.

Автомасштабирование Lakebase — это последняя версия Lakebase с автомасштабированием вычислений, масштабированием до нуля, ветвлением и мгновенным восстановлением. Сравнение функций с Lakebase Provisioned см. в разделе выбора между версиями.

Это руководство поможет вам приступить к работе с интерфейсом командной строки Databricks для управления проектами Lakebase, ветвями и вычислениями (конечными точками). Вы узнаете, как создать рабочий проект с помощью всего нескольких команд.

Для полного справочника по командам и всем доступным вариантам см. Databricks CLI postgres commands.

Предпосылки

Databricks CLI: установите интерфейс командной строки Databricks. См. раздел "Установка интерфейса командной строки Databricks".
Доступ к рабочей области. У вас должен быть доступ к рабочей области Azure Databricks, в которой находится ресурс Lakebase.

Проверка подлинности с помощью Databricks

Перед выполнением команд CLI выполните проверку подлинности в рабочей области Azure Databricks:

databricks auth login --host https://your-workspace.cloud.databricks.com

Замените https://your-workspace.cloud.databricks.com фактическим URL-адресом рабочей области. Эта команда открывает окно браузера для проверки подлинности с помощью учетной записи Azure Databricks с помощью OAuth.

Замечание

Если у вас несколько профилей, используйте --profile флаг, чтобы указать, какой из них следует использовать: databricks postgres <command> --profile my-profile Чтобы просмотреть настроенные профили, выполните команду databricks auth profiles.

Дополнительные варианты проверки подлинности см. в разделе "Проверка подлинности Databricks".

Получите справку по командам

Интерфейс командной строки предоставляет встроенную справку для всех команд. Используйте --help для просмотра доступных команд и параметров.

Получите обзор всех команд Postgres:

databricks postgres --help

При этом отображаются все доступные команды, глобальные флаги и сведения о соглашениях об именовании ресурсов.

Получите подробную справку по определенной команде:

databricks postgres create-project --help

Здесь показаны назначение команды, обязательные и необязательные параметры, примеры использования и доступные флаги.

Быстрый старт: Создание первого проекта

Выполните следующие действия, чтобы создать полный рабочий проект с ветвью и конечной точкой вычислений:

1. Создание проекта

Создайте проект Lakebase:

databricks postgres create-project my-project \
  --json '{
    "spec": {
      "display_name": "My Lakebase Project"
    }
  }'

Эта команда создает проект и ожидает завершения. Идентификатор проекта (my-project) становится частью имени ресурса: projects/my-project Проект создается с рабочей ветвью по умолчанию и конечной точкой вычислений для чтения и записи с автоматически созданными идентификаторами.

При необходимости экспортируйте идентификатор проекта в качестве переменной для использования в последующих командах:

export PROJECT_ID="my-project"

2. Получение идентификатора ветви

Выведите список ветвей в проекте, чтобы найти идентификатор ветви по умолчанию:

databricks postgres list-branches projects/$PROJECT_ID

Это возвращает сведения обо всех ветвях проекта. Найдите ветвь со статусом "default": true. Запишите идентификатор ветви из name поля (например, br-divine-sea-y2k942xa).

При необходимости экспортируйте идентификатор ветви в качестве переменной для использования в последующих командах:

export BRANCH_ID="br-divine-sea-y2k942xa"

Замените br-divine-sea-y2k942xa на фактический идентификатор вашей основной ветки из списка выходных данных.

3. Получение идентификатора конечной точки

Перечислите конечные точки в вашей ветви. Ветвь по умолчанию автоматически включает конечную точку чтения и записи:

databricks postgres list-endpoints projects/$PROJECT_ID/branches/$BRANCH_ID

Запишите идентификатор конечной точки из поля name. Он будет находиться в формате projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}. Извлеките идентификатор конечной точки (например, ep-plain-sunset-y2vc0zan) и при необходимости экспортируйте его в виде переменной:

export ENDPOINT_ID="ep-plain-sunset-y2vc0zan"

Замените ep-plain-sunset-y2vc0zan на фактический идентификатор конечной точки из списка, полученного из выходных данных.

4. Создание учетных данных базы данных

Создайте учетные данные для подключения к базе данных:

databricks postgres generate-database-credential \
  projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID

Команда возвращает маркер OAuth, который можно использовать с клиентами PostgreSQL, например psql для доступа к данным с помощью удостоверения Databricks. Пошаговые инструкции по подключению к psql см. в статье Connect with psql. Дополнительные сведения об истечении срока действия маркера и проверке подлинности см. в разделе "Проверка подлинности".

Управление ресурсами

Перечислить все проекты

Список всех проектов в рабочей области:

databricks postgres list-projects

При этом возвращаются сведения о каждом проекте, включая его имя, отображаемое имя, текущее состояние и метки времени создания и обновления.

Получение сведений о ресурсе

Получение подробных сведений о проекте:

databricks postgres get-project projects/$PROJECT_ID

Это возвращает подробную конфигурацию проекта, включая отображаемое имя, версию PostgreSQL, период хранения журнала, ограничения размера ветви, параметры конечной точки по умолчанию, размер хранилища и метки времени создания и обновления.

Получение подробных сведений о ветви:

databricks postgres get-branch projects/$PROJECT_ID/branches/$BRANCH_ID

При этом возвращаются подробные сведения о ветви, включая текущее состояние, состояние ветви по умолчанию, состояние защиты, логический размер, сведения о исходной ветви (если ветвь из другой ветви) и метки времени создания и обновления.

Получите подробные сведения о конечной точке:

databricks postgres get-endpoint projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID

Это возвращает подробную конфигурацию конечной точки, включая тип конечной точки (для чтения и записи или только для чтения), параметры автомасштабирования (минимальные и максимальные единицы вычислений), текущее состояние (ACTIVE, IDLE и т. д.), время ожидания приостановки, хост подключения и метки времени создания и обновления.

Обновление ресурсов

Обновите ресурс с помощью шаблона маски обновления. Маска обновления указывает, какие поля необходимо обновить:

databricks postgres update-branch \
  projects/$PROJECT_ID/branches/$BRANCH_ID \
  spec.is_protected \
  --json '{
    "spec": {
      "is_protected": true
    }
  }'

В этом примере задано значение spec.is_protectedtrue, что делает ветвь защищенной. Маска обновления (spec.is_protected) сообщает API, какое поле необходимо обновить. Команда возвращает обновленный ресурс с новым значением и обновленной update_time меткой времени.

Чтобы обновить несколько полей, используйте разделенный запятыми список:

databricks postgres update-endpoint \
  projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID \
  "spec.autoscaling_limit_min_cu,spec.autoscaling_limit_max_cu" \
  --json '{
    "spec": {
      "autoscaling_limit_min_cu": 1.0,
      "autoscaling_limit_max_cu": 8.0
    }
  }'

Распространенные рабочие процессы

Создание ветви компонентов из рабочей среды

Создайте новую ветвь на основе существующей ветви для тестирования изменений. При указании source_branch новая ветвь будет иметь ту же схему и данные, что и исходная ветвь на момент создания. Замените идентификаторы проекта и ветви фактическими значениями:

databricks postgres create-branch \
  projects/my-project \
  feature \
  --json '{
    "spec": {
      "source_branch": "projects/my-project/branches/br-divine-sea-y2k942xa",
      "no_expiry": true
    }
  }'

Замечание

При создании ветви необходимо указать политику окончания срока действия. Используйте no_expiry: true для создания постоянной ветви.

Чтобы использовать переменные оболочки внутри спецификации JSON (например $PROJECT_ID , или $BRANCH_ID), необходимо использовать двойные кавычки для --json значения и экранировать внутренние кавычки.

В ветви компонентов требуется конечная точка вычислений для чтения и записи, чтобы разрешить операции базы данных:

databricks postgres create-endpoint \
  projects/$PROJECT_ID/branches/feature \
  primary \
  --json '{
    "spec": {
      "endpoint_type": "ENDPOINT_TYPE_READ_WRITE",
      "autoscaling_limit_min_cu": 0.5,
      "autoscaling_limit_max_cu": 2.0
    }
  }'

После завершения разработки и тестирования в ветви компонентов его можно удалить:

databricks postgres delete-branch projects/$PROJECT_ID/branches/feature

Замечание

Удаление команд возвращается немедленно, но фактическое удаление может занять некоторое время. Чтобы проверить удаление, выполните соответствующую команду get resource, которая возвращает ошибку после полного удаления ресурса.

Масштабирование операций чтения с помощью реплик чтения

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

databricks postgres create-endpoint \
  projects/$PROJECT_ID/branches/$BRANCH_ID \
  read-replica-1 \
  --json '{
    "spec": {
      "endpoint_type": "ENDPOINT_TYPE_READ_ONLY",
      "autoscaling_limit_min_cu": 0.5,
      "autoscaling_limit_max_cu": 4.0
    }
  }'

Для распространения рабочих нагрузок чтения можно создать несколько реплик чтения с различными идентификаторами конечных точек (read-replica-1, read-replica-2и т. д.).

Понимание ключевых понятий

Длительные операции

Создание, обновление и удаление команд являются операциями длительного выполнения. По умолчанию интерфейс командной строки ожидает завершения операции. Используйте --no-wait для немедленного возврата и отдельной проверки состояния.

databricks postgres create-project $PROJECT_ID \
  --json '{"spec": {"display_name": "My Project"}}' \
  --no-wait

Опрос состояния операции:

databricks postgres get-operation projects/$PROJECT_ID/operations/operation-id

Именование ресурсов

Lakebase использует иерархические имена ресурсов:

Проекты: projects/{project_id}. При создании проекта укажите идентификатор проекта.
Ветви: projects/{project_id}/branches/{branch_id}. При создании ветви укажите идентификатор ветви.
Конечные точки: projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}. При создании конечной точки укажите идентификатор конечной точки (например primary , или read-replica-1).

Идентификаторы должны иметь длину 1–63 символов, начинаться с строчной буквы и содержать только строчные буквы, цифры и дефисы.

Обновление маски

Для команд обновления требуется маска обновления, указывающая, какие поля нужно изменить. Маска — это путь к полю, например spec.display_name или разделенный запятыми список для нескольких полей.

Нагрузка --json содержит новые значения для этих полей. Изменяются только поля, перечисленные в маске обновления.

Дальнейшие шаги

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-02-07

Поделиться через

Начало работы с интерфейсом командной строки Databricks для Lakebase

Предпосылки

Проверка подлинности с помощью Databricks

Получите справку по командам

Быстрый старт: Создание первого проекта

1. Создание проекта

2. Получение идентификатора ветви

3. Получение идентификатора конечной точки

4. Создание учетных данных базы данных

Управление ресурсами

Перечислить все проекты

Получение сведений о ресурсе

Обновление ресурсов

Распространенные рабочие процессы

Создание ветви компонентов из рабочей среды

Масштабирование операций чтения с помощью реплик чтения

Понимание ключевых понятий

Длительные операции

Именование ресурсов

Обновление маски

Дальнейшие шаги

Обратная связь

Дополнительные ресурсы