Databricks Driver for SQLTools en Visual Studio Code
Importante
Esta característica está en versión preliminar pública.
Databricks Driver for SQLTools le permite usar la extensión SQLTools en Visual Studio Code para navegar por objetos SQL y ejecutar consultas SQL en áreas de trabajo remotas de Azure Databricks.
Antes de empezar
Para poder usar Databricks Driver for SQLTools, el área de trabajo de Azure Databricks y la máquina de desarrollo local deben cumplir los siguientes requisitos.
Requisitos del área de trabajo
Debe tener al menos un área de trabajo de Azure Databricks disponible, y el área de trabajo debe cumplir los siguientes requisitos:
El área de trabajo debe contener al menos un almacén de Databricks SQL.
Nota:
Los clústeres de Azure Databricks no son compatibles con Databricks Driver for SQLTools.
En el caso de las áreas de trabajo habilitadas para Unity Catalog, el área de trabajo debe contener al menos un catálogo, con al menos un esquema (denominado formalmente una base de datos) dentro de ese catálogo.
En el caso de las áreas de trabajo que no están habilitadas para Unity Catalog, el área de trabajo debe contener al menos un esquema (anteriormente denominado base de datos).
Requisitos de la máquina de desarrollo local
En la máquina de desarrollo local, debe tener instalado lo siguiente:
- Visual Studio Code versión 1.70 o posterior. Para ver la versión instalada, haga clic en Código > Acerca de Visual Studio Code en el menú de administración de Linux o macOS y Ayuda > Acerca de en Windows. Para descargar, instalar y configurar Visual Studio Code, consulte Configuración de Visual Studio Code.
- La extensión SQLTools para Visual Studio Code.
- La extensión Databricks Driver for SQLTools para Visual Studio Code.
Para instalar la extensión SQLTools, vaya a SQLTools y haga clic en Instalar, o bien:
En Visual Studio Code, haga clic en Ver > Extensiones en el menú principal.
En el cuadro Buscar extensiones en Marketplace, escriba
SQLTools
.Haga clic en la entrada SQLTools de Matheus Teixeira.
Nota:
Puede haber varias entradas de SQLTools en la lista. Asegúrese de hacer clic en la entrada de Matheus Teixeira.
Haga clic en Instalar.
Para instalar la extensión Databricks Driver for SQLTools, vaya a Databricks Driver for SQLTools y haga clic en Instalar, o:
- En Visual Studio Code, haga clic en Ver > Extensiones en el menú principal.
- En el cuadro Buscar extensiones en Marketplace, escriba
Databricks Driver for SQLTools
. - Haga clic en la entrada Databricks Driver for SQLTools.
- Haga clic en Instalar.
Autenticación
Debe configurar la autenticación para Databricks Driver for SQLTools, como se indica a continuación.
Databricks Driver for SQLTools admite los siguientes tipos de autenticación de Azure Databricks:
- Autenticación de token de acceso personal de Azure Databricks
- autenticación de máquina a máquina (M2M) de OAuth de Azure Databricks
- autenticación de usuario a máquina (U2M) de Azure Databricks OAuth
- Autenticación de la CLI de Azure
Nota:
Databricks Driver for SQLTools no admite los tokens de Microsoft Entra ID.
Autenticación de token de acceso personal de Azure Databricks
Para usar Databricks Driver for SQLTools con la autenticación de token de acceso personal de Azure Databricks, debe tener un token de acceso personal de Azure Databricks. Para crear un token de acceso personal, haga lo siguiente:
- En el área de trabajo de Azure Databricks, haga clic en el nombre de usuario de Azure Databricks de la barra superior y, a continuación, seleccione Configuración en la lista desplegable.
- Haga clic en Desarrollador.
- Junto a Tokens de acceso, haga clic en Administrar.
- Haga clic en Generate new token (Generar nuevo token).
- (Opcional) Escriba un comentario que le ayude a identificar este token en el futuro y cambie la duración predeterminada del token de 90 días. Para crear un token sin duración (no recomendado), deje el cuadro Duración (días) vacío (en blanco).
- Haga clic en Generar.
- Copie el token mostrado en una ubicación segura y, a continuación, haga clic en Listo.
Nota:
Asegúrese de guardar el token copiado en una ubicación segura. No comparta el token copiado con otros usuarios. Si pierde el token copiado, no podrá volver a generar ese mismo token. Debe repetir el procedimiento para crear un nuevo token. Si pierde el token copiado o cree que el token se ha visto comprometido, Databricks recomienda eliminar inmediatamente ese token del área de trabajo haciendo clic en el icono de papelera (Revocar) situado junto al token en la página Tokens de acceso.
Si no puede crear o usar tokens en el área de trabajo, puede deberse a que el administrador del área de trabajo tiene tokens deshabilitados o no le ha concedido permiso para crear o usar tokens. Consulte el administrador del área de trabajo o lo siguiente:
autenticación de máquina a máquina (M2M) de OAuth de Azure Databricks
Puede usar la autenticación de máquina a máquina (M2M) de Azure Databricks OAuth para autenticarse con Databricks Driver for SQLTools, como se indica a continuación:
Nota:
La autenticación de OAuth M2M de Azure Databricks está disponible en Databricks Driver for SQLTools versiones 0.4.2 y posteriores.
- Complete los pasos de configuración para la autenticación de OAuth M2M. Consulte autenticación de máquina a máquina (M2M) de OAuth.
- Cree un perfil de configuración de Azure Databricks con las opciones de configuración de autenticación de OAuth M2M. Vea la sección “Configuración” de autenticación de máquina a máquina (M2M) de OAuth.
- Instale y abra la extensión de Databricks para Visual Studio Code en el equipo de desarrollo local.
- En la extensión de Databricks para Visual Studio Code, haga clic en el botón Configurar del panel Configuración. Si no se muestra el botón Configurar, haga clic en el icono de engranaje (Configurar área de trabajo) en su lugar.
- En la paleta de comandos, para Host de Databricks, escriba la dirección URL de Azure Databricks por área de trabajo, por ejemplo,
https://adb-1234567890123456.7.azuredatabricks.net
, y presione Entrar. - Seleccione la entrada del perfil de configuración que coincida con la que creó en el paso 2.
- Complete las instrucciones en pantalla del explorador web para terminar de autenticarse con su cuenta de Azure Databricks.
autenticación de usuario a máquina (U2M) de OAuth de Azure Databricks
Puede usar Azure Databricks autenticación de usuario a máquina (U2M) de OAuth para autenticarse con Databricks Driver for SQLTools, como se indica a continuación:
Nota:
La autenticación U2M de OAuth de Azure Databricks está disponible en Databricks Driver for SQLTools versiones 0.4.2 y posteriores.
- Instale y abra la extensión de Databricks para Visual Studio Code en el equipo de desarrollo local.
- En la extensión de Databricks para Visual Studio Code, haga clic en el botón Configurar del panel Configuración. Si no se muestra el botón Configurar, haga clic en el icono de engranaje (Configurar área de trabajo) en su lugar.
- En la Paleta de comandos, en Host de Databricks, escriba la dirección URL del área de trabajo de Azure Databricks, por ejemplo
https://adb-1234567890123456.7.azuredatabricks.net
. A continuación, presione Entrar. - Seleccione OAuth (usuario a máquina).
- Complete las instrucciones en pantalla del explorador web para terminar de autenticarse con su cuenta de Azure Databricks. Si se le solicita, permita el acceso
all-apis
.
Autenticación de la CLI de Azure
Puede usar la CLI de Azure para autenticarse con Databricks Driver for SQLTools, como se indica a continuación:
Nota:
La autenticación con la CLI de Azure se encuentra en un estado de característica experimental . Esta característica está disponible en Databricks Driver for SQLTools, versiones 0.4.2 y posteriores.
- Instale la CLI de Azure en la máquina de desarrollo local, si aún no lo ha hecho.
- Instale y abra la extensión de Databricks para Visual Studio Code en el equipo de desarrollo local.
- En la extensión de Databricks para Visual Studio Code, haga clic en el botón Configurar del panel Configuración. Si no se muestra el botón Configurar, haga clic en el icono de engranaje (Configurar área de trabajo) en su lugar.
- En la Paleta de comandos, en Host de Databricks, escriba la dirección URL del área de trabajo de Azure Databricks, por ejemplo
https://adb-1234567890123456.7.azuredatabricks.net
. A continuación, presione Entrar. - Seleccione CLI de Azure.
- Siga las indicaciones en la pantalla para finalizar la autenticación con la CLI de Azure.
Conexión a un esquema
- En Visual Studio Code, en la barra lateral, haga clic en el icono de SQLTools.
- En la vista SQLTools, si es la primera vez que usa la extensión SQLTools, haga clic en Agregar nueva conexión en el panel Conexiones. De lo contrario, haga clic en el icono Agregar nueva conexión en la barra de título del panel.
- En la pestaña Configuración de SQLTools, en el paso Seleccionar un controlador de base de datos, haga clic en el icono Databricks.
- En el paso Configuración de conexión, escriba la siguiente información sobre el almacenamiento, el catálogo y el esquema:
En Nombre de la conexión, escriba un nombre único para la conexión.
(Opcional) En Grupo de conexiones, escriba el nombre de un grupo de conexiones existente para agregar la nueva conexión a ese grupo. O bien, escriba un nombre único para crear un nuevo grupo de conexiones con la nueva conexión. Los grupos de conexiones facilitan la búsqueda de conexiones en la extensión.
En Conectar mediante, seleccione una de las siguientes opciones:
- Para usar un token de acceso personal de Azure Databricks para la autenticación, seleccione Nombre de host y Token.
- En Databricks Driver for SQLTools versiones 0.4.2 y posteriores, para usar la autenticación de OAuth U2M o M2M o la CLI de Azure, seleccione extensión de VS Code (beta).
Si seleccionó Nombre de host y Token para Conectar con, en Host, escriba la configuración Nombre de host del servidor del almacén. Para obtener la configuración Nombre de host del servidor de un almacenamiento, consulte Obtener detalles de conexión para un recurso de proceso de Azure Databricks.
En Ruta de acceso, escriba la configuración de la ruta de acceso HTTP del almacenamiento o del clúster. Para obtener la Ruta de acceso HTTP de un almacenamiento, consulte Obtener detalles de conexión para un recurso de proceso de Azure Databricks.
Si seleccionó nombre de host y token para Connect mediante, escriba el valor del token de acceso personal de Azure Databricks en Token.
En Catálogo, escriba el nombre del catálogo.
Nota:
En el caso de las áreas de trabajo que no están habilitadas para Unity Catalog, puede dejar el Catálogo en blanco para usar el valor predeterminado de
hive_metastore
.En Esquema, escriba el nombre del esquema.
(Opcional) En Mostrar límite predeterminado de registros, deje el valor predeterminado
50
para que solo se muestren las 50 primeras filas de cada consulta, o escriba un límite diferente.
- Haga clic en Probar conexión.
- Una vez que la conexión se haya realizado correctamente, haga clic en Guardar conexión.
Cambio en la configuración de una conexión
Para realizar este procedimiento, se da por hecho que se ha conectado correctamente a, al menos, un almacén.
- Si la vista SQLTools no está visible, vaya a Visual Studio Code y, en la barra lateral, haga clic en el icono SQLTools.
- En el panel Conexiones, expanda el grupo de conexiones si ya hay uno para la conexión de destino.
- Haga clic con el botón derecho en la conexión y haga clic en Editar conexión.
- Cambie la configuración de destino.
- Haga clic en Probar conexión.
- Una vez que la conexión se haya realizado correctamente, haga clic en Guardar conexión.
Navegación por los objetos de un esquema
- En el panel Conexiones, expanda el grupo de conexiones si ya hay uno para la conexión de destino.
- Haga doble clic o expanda la conexión de destino del almacén.
- Expanda la base de datos de destino (esquema), si ya hay una para la conexión.
- Expanda Tablas o Vistas, si existen una o varias tablas o vistas para la base de datos (esquema).
- Expanda cualquier tabla o vista de destino para ver las columnas de la tabla o la vista.
Visualización de las filas o el esquema de una tabla o vista
Con las Tablas o Vistas expandidas en el panel Conexiones, realice una de las siguientes acciones:
- Para mostrar las filas de la tabla o vista, haga clic con el botón derecho en la tabla o vista y en Mostrar registros de la tabla o Mostrar registros de la vista.
- Para mostrar el esquema de la tabla o vista, haga clic con el botón derecho en la tabla o vista y en Describir tabla o Describir vista.
Generación de una consulta de inserción para una tabla
- Coloque el cursor en un editor existente en la ubicación donde desea agregar la consulta de inserción.
- Con las Tablas expandidas en el panel Conexiones, haga clic con el botón derecho en la tabla y en Generar consulta de inserción. La definición de la consulta de inserción se agrega en el punto de inserción del cursor.
Creación y ejecución de una consulta
Para realizar este procedimiento, se da por hecho que se ha conectado correctamente a, al menos, un almacén.
- En el panel Conexiones, expanda el grupo de conexiones si ya hay uno para la conexión de destino.
- Haga doble clic o expanda la conexión de destino del almacén.
- Con la conexión seleccionada, haga clic en Nuevo archivo SQL en la barra de título del panel Conexiones. Aparece una nueva pestaña del editor.
- Escriba la consulta SQL en el nuevo editor.
- Para ejecutar la consulta SQL, haga clic en Ejecutar en la conexión activa en el editor. Los resultados de la consulta se muestran en una nueva pestaña del editor.
Ejecución de una consulta existente
Para realizar este procedimiento, se da por hecho que se ha conectado correctamente a, al menos, un almacén.
- En el panel Conexiones, expanda el grupo de conexiones si ya hay uno para la conexión de destino.
- Haga doble clic o expanda la conexión de destino del almacén.
- Con la conexión seleccionada, abra cualquier archivo con la extensión de archivo de
.sql
, o seleccione cualquier grupo de instrucciones SQL continuas en cualquier editor que se haya abierto anteriormente. - Para ejecutar la consulta SQL desde un archivo
.sql
abierto, con el contenido del archivo.sql
visible en el editor, haga clic en Ejecutar en la conexión activa en el editor. Los resultados de la consulta se muestran en una nueva pestaña del editor. - Para ejecutar un grupo seleccionado de instrucciones SQL continuas en un editor que se haya abierto anteriormente, haga clic con el botón derecho en la selección y, después, haga clic en Ejecutar consulta seleccionada. Los resultados de la consulta se muestran en una nueva pestaña del editor.
Envío de registros de uso a Databricks
Si tiene problemas al usar Databricks Driver for SQLTools, puede enviar registros de uso e información relacionada al soporte técnico de Databricks haciendo lo siguiente:
- Instale la extensión de Databricks para Visual Studio Code en el equipo de desarrollo local.
- Active el registro comprobando la configuración de Registros: Habilitado o estableciendo
databricks.logs.enabled
entrue
, como se describe en Configuración de la extensión de Databricks para Visual Studio Code. Asegúrese de reiniciar Visual Studio Code después de activar el registro. - Intente reproducir el problema.
- En la Paleta de comandos (Ver > Paleta de comandos desde el menú principal), ejecute el comando Databricks: Open full logs (Databricks: Abrir registros completos).
- Envíe al soporte técnico de Databricks los archivos
Databricks Logs.log
,databricks-cli-logs.json
ysdk-and-extension-logs.json
que aparecen. - Copie también el contenido del Terminal (Ver > Terminal) en el contexto del problema y envíe este contenido al soporte técnico de Databricks.
La vista Salida (Ver > Salida, Registros de Databricks) muestra información truncada si la opción Registros: Habilitado está activada o databricks.logs.enabled
está establecida en true
. Para mostrar más información, cambie la siguiente configuración, como se describe en Configuración de la extensión de Databricks para Visual Studio Code:
- Registros: longitud máxima de la matriz o
databricks.logs.maxArrayLength
- Registros: longitud máxima del campo o
databricks.logs.maxFieldLength
- Registros: profundidad de truncamiento o
databricks.logs.truncationDepth