Introducción a la CLI de Databricks para Lakebase

Esta guía le ayuda a empezar a trabajar con la CLI de Databricks para administrar los proyectos, ramas y procesos de Lakebase (puntos de conexión). Aprenderá a crear un proyecto de trabajo en tan solo unos pocos comandos.

Para obtener una referencia de comandos completa y todas las opciones disponibles, consulte Comandos postgres de la CLI de Databricks.

Prerrequisitos

  • CLI de Databricks: instale la CLI de Databricks. Consulte Instalación de la CLI de Databricks.
  • Acceso al área de trabajo: debe tener acceso a un área de trabajo de Azure Databricks donde reside el recurso de Lakebase.

Autenticación con Azure Databricks

Antes de ejecutar los comandos de la CLI, autentíquese con el área de trabajo de Azure Databricks:

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

Reemplace por https://your-workspace.cloud.databricks.com la dirección URL real del área de trabajo. Este comando abre una ventana del explorador para que se autentique con su cuenta de Azure Databricks mediante OAuth.

Nota:

Si tiene varios perfiles, use la --profile marca para especificar cuál usar: databricks postgres <command> --profile my-profile. Para ver los perfiles configurados, ejecute databricks auth profiles.

Para más opciones de autenticación, consulte Autenticación de Databricks.

Obtención de ayuda sobre los comandos

La CLI proporciona ayuda integrada para todos los comandos. Use --help para ver los comandos y las opciones disponibles.

Obtenga información general sobre todos los comandos de Postgres:

databricks postgres --help

El comando muestra todos los comandos disponibles, marcas globales e información sobre las convenciones de nomenclatura de recursos.

Obtenga ayuda detallada para un comando específico:

databricks postgres create-project --help

Esto muestra el propósito del comando, los parámetros obligatorios y opcionales, los ejemplos de uso y las marcas disponibles.

Inicio rápido: Creación del primer proyecto

Sigue estos pasos para crear un proyecto con una rama y un endpoint de computación:

1. Crear un proyecto

Cree un proyecto de Lakebase:

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

Este comando crea un proyecto y espera a que se complete. El identificador del proyecto (my-project) se convierte en parte del nombre del recurso: projects/my-project. El proyecto se crea con una rama predeterminada para producción y un punto de procesamiento de lectura y escritura, ambos con identificadores generados automáticamente.

Opcionalmente, exporte el identificador del proyecto como una variable para usarlo en los comandos siguientes:

export PROJECT_ID="my-project"

2. Obtención del identificador de rama

Enumere las ramas del proyecto para buscar el identificador de rama predeterminado:

databricks postgres list-branches projects/$PROJECT_ID

Esto devuelve información sobre todas las ramas del proyecto. Busque la rama que tenga "default": true en su estado. Anote el identificador de rama del name campo (por ejemplo, production para la rama predeterminada).

Opcionalmente, exporte el identificador de rama como una variable para su uso en comandos posteriores:

export BRANCH_ID="production"

Reemplace production con su identificador de rama real de la salida de la lista.

3. Obtención del identificador del punto de conexión

Enumere los puntos de conexión de la rama. La rama predeterminada incluye automáticamente un punto de conexión de lectura y escritura:

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

Anote el identificador de punto de conexión del name campo (por ejemplo, primary para el punto de conexión de lectura y escritura predeterminado). Opcionalmente, expórtelo como una variable:

export ENDPOINT_ID="primary"

Reemplace primary con su identificador de rama real de la salida de la lista.

4. Generación de credenciales de base de datos

Genere credenciales para conectarse a la base de datos:

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

El comando devuelve un token de OAuth que puede usar con clientes de PostgreSQL como psql para acceder a los datos mediante la identidad de Databricks. Para obtener instrucciones paso a paso sobre cómo conectarse con psql, consulte Conexión con psql. Para obtener más información sobre la expiración y la autenticación de tokens, consulte Autenticación.

Administrar proyectos

Enumerar proyectos

Enumerar todos los proyectos del área de trabajo:

databricks postgres list-projects

El comando devuelve el nombre, el nombre para mostrar, el estado actual y las marcas de tiempo de cada proyecto.

Obtener detalles del proyecto

Obtenga información detallada sobre un proyecto:

databricks postgres get-project projects/$PROJECT_ID

El comando devuelve el nombre para mostrar del proyecto, la versión de PostgreSQL, el propietario, el período de retención del historial, los límites de tamaño de rama, el tamaño de almacenamiento y las marcas de tiempo.

Administración de ramas

Obtener detalles de la rama

Obtenga información detallada sobre una rama:

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

El comando devuelve el estado actual de la rama, el estado de protección, el tamaño lógico, los detalles de la rama de origen (si procede) y las marcas de tiempo.

Crea una rama de funcionalidad

Cree una nueva rama basada en una rama existente para probar los cambios. Al especificar un source_branch, la nueva rama tendrá el mismo esquema y datos que la rama de origen en el momento de la creación. Reemplace los identificadores de proyecto y rama por los valores reales:

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

Nota:

Al crear una rama, debe especificar una directiva de expiración. Use no_expiry: true para crear una rama permanente.

Para usar variables del shell dentro de la especificación JSON (como $PROJECT_ID o $BRANCH_ID), use comillas dobles para el valor --json y escape las comillas internas.

Lakebase crea automáticamente la rama de funcionalidad con un endpoint primario de computación de lectura y escritura. Después de finalizar el desarrollo y las pruebas en la rama de características, puede eliminarlo:

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

Nota:

Los comandos delete se completan de inmediato, pero la eliminación real puede tardar tiempo en completarse. Para comprobar la eliminación, ejecute el comando get resource correspondiente, que devuelve un error después de que el recurso se elimine por completo.

Actualizar la protección de una rama

Actualice un recurso mediante el patrón de máscara de actualización. La máscara de actualización especifica qué campos se van a actualizar:

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

En este ejemplo se establece spec.is_protected en true, lo que hace que la rama está protegida. La máscara de actualización (spec.is_protected) indica a la API qué campo actualizar. El comando devuelve el recurso actualizado que muestra el nuevo valor y una marca de tiempo actualizada update_time .

Administración de recursos informáticos

Obtener detalles de cómputo

Obtenga información detallada sobre un endpoint:

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

El comando devuelve el tipo de punto de conexión, la configuración de escalado automático, el estado actual, el host de conexión, el tiempo de espera de suspensión y las marcas de tiempo.

Escalado con réplicas de lectura

Agregue réplicas de lectura para gestionar el incremento de tráfico de lectura. En el ejemplo siguiente se agrega una réplica de lectura a la rama de producción predeterminada:

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

Puede crear varias réplicas de lectura con diferentes identificadores de punto de conexión (read-replica-1, read-replica-2, etc.) para distribuir cargas de trabajo de lectura.

Actualización de los límites de escalado automático

Para actualizar varios campos, use una lista separada por comas:

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

Configuración de la escala en cero

Para configurar la escala a cero, incluya spec.suspension en la máscara de actualización. Establezca suspend_timeout_duration (60s–604800s) para definir el tiempo de espera de inactividad o no_suspension: true para deshabilitarlo. No configure ninguna. La configuración no_suspension: false no es válida y devuelve un error. De forma predeterminada, la production rama tiene la escala a cero habilitada con un tiempo de espera de 24 horas.

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

Administración de roles

Use la CLI para crear y administrar roles de Postgres para el acceso a la base de datos dentro de una rama. Para obtener instrucciones detalladas sobre los tipos de roles y la autenticación, consulte Creación de roles de Postgres.

Crear un rol

Cree un rol basado en contraseña:

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

Cree un rol de OAuth vinculado a una identidad de 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>"}}'

Enumerar y obtener roles

Enumerar todos los roles de una rama:

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

Obtenga detalles sobre un rol específico:

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

La respuesta incluye el nombre de recurso de rol generado por el sistema (por ejemplo, rol-xxxx-xxxxxxxxxx) necesario para las llamadas de actualización y eliminación.

Actualización de un rol

Actualice un rol mediante el patrón de máscara de actualización. Pase la máscara de actualización como segundo argumento posicional.

Al actualizar spec.attributes, debe proporcionar los tres campos de atributo: la API reemplaza al objeto de atributos completo:

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

Eliminación de un rol

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

Si el rol posee objetos de base de datos, use --reassign-owned-to para transferir la propiedad antes de la eliminación:

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

Administración de tablas sincronizadas

Las tablas sincronizadas replican los datos del catálogo de Unity en la base de datos de Lakebase para lecturas operativas de baja latencia. Usa create-synced-table con un ID de {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
    }
  }'

El identificador de tabla sincronizado se convierte en el nombre de entidad del catálogo de Unity e identifica la tabla Postgres. Obtenga el estado y elimine una tabla sincronizada con el mismo formato de identificador:

# 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 y create-catalog son operaciones de larga duración. De forma predeterminada, la CLI espera la finalización. Use --no-wait para devolver inmediatamente o --timeout para establecer una duración de espera personalizada. Consulte Operaciones de ejecución prolongada.

Para obtener instrucciones detalladas sobre los modos de sincronización, la asignación de tipos de datos y el planeamiento de la capacidad, consulte Serve lakehouse data with synced tables (Servir datos de Lakehouse con tablas sincronizadas).

Descripción de los conceptos clave

Operaciones de larga duración

Los comandos create, update y delete son operaciones de ejecución prolongada. De forma predeterminada, la CLI espera a que se complete la operación. Use --no-wait para retornar inmediatamente y comprobar el estado por separado.

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

Sondee el estado de la operación:

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

Asignación de nombres de recursos

Lakebase usa nombres de recursos jerárquicos:

  • Proyectos: projects/{project_id}. Especifique el identificador del proyecto al crear un proyecto.
  • Ramas: projects/{project_id}/branches/{branch_id}. Al crear una rama, especifique el identificador de rama.
  • Puntos de conexión: projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}. Especifique el identificador de punto de conexión (como primary o read-replica-1) al crear un punto de conexión.

Los identificadores deben tener entre 1 y 63 caracteres, empezar con una letra minúscula y contener solo letras minúsculas, números y guiones.

Actualizar máscaras

Los comandos de actualización requieren una máscara de actualización que especifica los campos que se van a modificar. La máscara es una ruta de acceso de campo como spec.display_name o, en el caso de varios campos, una lista separada por comas.

La --json carga contiene los nuevos valores de esos campos. Solo se modifican los campos enumerados en la máscara de actualización.

Recursos adicionales

  • Last updated on