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

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

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

Предпосылки

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

Проверка подлинности с помощью Azure 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 поля (например, production для ветви по умолчанию).

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

export BRANCH_ID="production"

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

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

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

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

Обратите внимание на идентификатор конечной name точки из поля (например, primary для конечной точки чтения и записи по умолчанию). При необходимости экспортируйте его в виде переменной:

export ENDPOINT_ID="primary"

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

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

Команда возвращает текущее состояние ветви, состояние защиты, логический размер, сведения о исходной ветви (если применимо), а также метки времени.

Создайте ветку функциональности

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

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

Замечание

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

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

Lakebase автоматически создает ветвь функций с первичной конечной точкой вычислений для чтения и записи. После завершения разработки и тестирования в ветви компонентов его можно удалить:

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

Замечание

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

Обновление защиты ветви

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

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 get-endpoint projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID

Команда возвращает тип конечной точки, параметры автомасштабирования, текущее состояние, узел подключения, время ожидания приостановки и метки времени.

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

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

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и т. д.).

Обновление ограничений автомасштабирования

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

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
    }
  }'

Настройка масштабирования до нуля

Чтобы настроить масштабирование до нуля, включите spec.suspension в маску обновления. Установите suspend_timeout_duration (60s–604800s), чтобы определить время ожидания бездействия или no_suspension: true отключить его. Не задавайте их оба. Параметр no_suspension: false недопустим и возвращает ошибку. По умолчанию для ветки production включено масштабирование до нуля с тайм-аутом 24 часа.

# Disable scale to zero (compute stays active indefinitely)
databricks postgres update-endpoint \
  projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID \
  spec.suspension \
  --json '{
    "spec": {
      "no_suspension": true
    }
  }'

# Enable scale to zero with a 5-minute inactivity timeout (60s–604800s)
databricks postgres update-endpoint \
  projects/$PROJECT_ID/branches/$BRANCH_ID/endpoints/$ENDPOINT_ID \
  spec.suspension \
  --json '{
    "spec": {
      "suspend_timeout_duration": "300s"
    }
  }'

Управление ролями

Используйте интерфейс командной строки для создания ролей Postgres и управления ими для доступа к базе данных в ветви. Подробные рекомендации по типам ролей и проверке подлинности см. в статье "Создание ролей Postgres".

Создание роли

Создайте роль на основе паролей:

databricks postgres create-role projects/$PROJECT_ID/branches/$BRANCH_ID \
  --role-id my-app-role \
  --json '{"spec": {"postgres_role": "my-app-role"}}'

Создайте роль OAuth, привязанную к удостоверению Azure Databricks:

# For a user:
databricks postgres create-role projects/$PROJECT_ID/branches/$BRANCH_ID \
  --role-id my-user-role \
  --json '{"spec": {"identity_type": "USER", "postgres_role": "user@example.com"}}'

# For a service principal:
databricks postgres create-role projects/$PROJECT_ID/branches/$BRANCH_ID \
  --role-id my-sp-role \
  --json '{"spec": {"identity_type": "SERVICE_PRINCIPAL", "postgres_role": "<sp-client-id>"}}'

Перечисление и получение ролей

Список всех ролей в ветке

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

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

databricks postgres get-role projects/$PROJECT_ID/branches/$BRANCH_ID/roles/$ROLE_ID

Ответ включает имя ресурса роли, созданного системой (например, rol-xxxx-xxxxxxxxxx), необходимое для вызовов обновления и удаления.

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

Обновите роль, используя шаблон маски обновления. Передайте маску обновления в качестве второго позиционного аргумента.

При обновлении spec.attributesнеобходимо предоставить все три поля атрибутов— API заменяет весь объект атрибутов:

databricks postgres update-role \
  projects/$PROJECT_ID/branches/$BRANCH_ID/roles/$ROLE_ID \
  "spec.attributes" \
  --json '{"spec": {"attributes": {"createdb": true, "createrole": false, "bypassrls": false}}}'

Удаление роли

databricks postgres delete-role projects/$PROJECT_ID/branches/$BRANCH_ID/roles/$ROLE_ID

Если роль владеет объектами базы данных, используйте --reassign-owned-to для передачи владения перед удалением:

databricks postgres delete-role \
  projects/$PROJECT_ID/branches/$BRANCH_ID/roles/$ROLE_ID \
  --reassign-owned-to projects/$PROJECT_ID/branches/$BRANCH_ID/roles/$OTHER_ROLE_ID

Управление синхронизированными таблицами

Синхронизированные таблицы реплицируют данные каталога Unity в базу данных Lakebase для операций чтения с низкой задержкой. Используйте create-synced-table с идентификатором {catalog}.{schema}.{table} :

databricks postgres create-synced-table my-catalog.sales.orders \
  --json '{
    "spec": {
      "source_table_full_name": "main.sales.orders",
      "branch": "projects/my-project/branches/production",
      "primary_key_columns": ["order_id"],
      "scheduling_policy": "SNAPSHOT",
      "postgres_database": "databricks_postgres",
      "create_database_objects_if_missing": true
    }
  }'

Идентификатор синхронизированной таблицы становится именем сущности каталога Unity и определяет таблицу Postgres. Получить статус и удалить синхронизированную таблицу в том же формате идентификатора:

# Check status
databricks postgres get-synced-table "synced_tables/my-catalog.sales.orders"

# Delete
databricks postgres delete-synced-table "synced_tables/my-catalog.sales.orders"

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

Подробные рекомендации по режимам синхронизации, сопоставлению типов данных и планированию емкости см. в разделе "Обслуживание данных Lakehouse с синхронизированными таблицами".

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

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

Создание, обновление и удаление команд являются операциями длительного выполнения. По умолчанию интерфейс командной строки ожидает завершения операции. Используйте --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-09-11