Compartir vía

Introducción a la CLI de Databricks para Lakebase

Importante

El escalado automático de Lakebase está en Beta en las siguientes regiones: eastus2, westeurope, westus.

El escalado automático de Lakebase es la versión más reciente de Lakebase con proceso de escalado automático, escalado a cero, bifurcación y restauración instantánea. Para ver la comparación de características con Lakebase Provisioned, consulte Elección entre versiones.

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

Esto 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

Siga estos pasos para crear un proyecto completamente operativo con una rama y un punto de conexión de cómputo:

1. Crear un proyecto

Cree un nuevo 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, br-divine-sea-y2k942xa).

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

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

Reemplace br-divine-sea-y2k942xa con su identificador actual de la rama predeterminada de la lista resultante.

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 campo name. Tendrá el formato projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}. Extraiga el identificador de punto de conexión (por ejemplo, ) y, opcionalmente, ep-plain-sunset-y2vc0zanexpórtelo como una variable:

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

Reemplace ep-plain-sunset-y2vc0zan por su identificador real de punto de conexión 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.

Administración de los recursos

Enumerar todos los proyectos

Enumerar todos los proyectos del área de trabajo:

databricks postgres list-projects

Esto devuelve información sobre cada proyecto, incluido su nombre, nombre para mostrar, estado actual y marcas de tiempo de creación o actualización.

Obtención de detalles del recurso

Obtenga información detallada sobre un proyecto:

databricks postgres get-project projects/$PROJECT_ID

Esto devuelve una configuración detallada del proyecto, incluido el nombre para mostrar, la versión de PostgreSQL, el propietario, el período de retención del historial, los límites de tamaño de rama, la configuración de punto de conexión predeterminada, el tamaño de almacenamiento y las marcas de tiempo de creación y actualización.

Obtenga información detallada sobre una rama:

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

Esto devuelve información detallada de la rama, incluido el estado actual, el estado de rama predeterminado, el estado de protección, el tamaño lógico, los detalles de la rama de origen (si se ramifican desde otra rama) y las marcas de tiempo de creación y actualización.

Obtenga información detallada sobre un endpoint:

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

Esto devuelve una configuración detallada del punto de conexión, incluido el tipo de punto de conexión (lectura y escritura o solo lectura), la configuración de escalado automático (unidades de computación mínimas y máximas), el estado actual (ACTIVO, INACTIVO, etc.), el host de conexión, el tiempo de espera de suspensión, y las marcas de tiempo de creación y actualización.

Actualizar recursos

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 .

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

Flujos de trabajo comunes

Crear una rama de funcionalidad a partir de producción

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/br-divine-sea-y2k942xa",
      "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 de shell dentro de la especificación JSON (como $PROJECT_ID o $BRANCH_ID), tendría que usar comillas dobles para el valor de --json y escapar las comillas internas.

La rama de función necesita un punto de conexión de computación con acceso de lectura y escritura para permitir las operaciones de base de datos.

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

Después de completar 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 de borrado devuelven inmediatamente, 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 una vez que el recurso se elimina por completo.

Escalar lecturas con réplicas de lectura

Agregue réplicas de lectura para gestionar el incremento de tráfico de lectura. Este ejemplo muestra cómo agregar 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.

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.

Pasos siguientes

  • Last updated on