Controlador JDBC de Databricks (OSS)

Importante

Este controlador está en versión preliminar pública y aún no está disponible como código abierto.

Databricks proporciona un controlador JDBC de software de código abierto (OSS) que permite conectar herramientas como DataGrip, DBeaver, y SQL Workbench/J a Azure Databricks a través de Java Database Connectivity (JDBC), una especificación estándar del sector para acceder a los sistemas de administración de bases de datos.

Este controlador ha implementado las API de JDBC y proporciona otras funciones básicas como OAuth, Cloud Fetch y características como la ingesta de volúmenes de Unity Catalog. Ejecuta el modo de consulta nativa y admite la consulta parametrizada nativa y puede ejecutarse mediante las API de ejecución de instrucciones, que proporciona la característica de retención de resultados de consulta beneficiosa o Thrift.

En este artículo se proporciona información sobre cómo instalar y usar Databricks JDBC Driver (OSS). Para obtener información acerca del controlador JDBC que no es de OSS Databricks, consulte Controlador JDBC de Databricks.

Requisitos

Para usar Databricks JDBC Driver (OSS), se deben cumplir los siguientes requisitos:

• Java Runtime Environment (JRE) 11.0 o superior. Las pruebas de CI se admiten en JRE 11, 17 y 21.

Nota:

Como resultado de un cambio en JDK 16 que provocó un problema de compatibilidad con la biblioteca de Apache Arrow usada por el controlador JDBC, pueden producirse errores en tiempo de ejecución al usar el controlador JDBC con JDK 16 o superior. Para evitar estos errores, reinicie la aplicación o el controlador mediante la siguiente opción de comando de JVM:

--add-opens=java.base/java.nio=org.apache.arrow.memory.core ALL-UNNAMED

Instalar el controlador

El controlador Databricks JDBC (OSS) está publicado en el Repositorio Maven. La versión más reciente es 0.9.6-oss.

Para instalar el controlador, puede realizar cualquiera de las acciones siguientes:

• En el caso de los proyectos de Maven, agregue la siguiente dependencia al archivo pom.xml del proyecto para indicar a Maven que descargue automáticamente el controlador JDBC con la versión especificada:

  <dependency>
    <groupId>com.databricks</groupId>
    <artifactId>databricks-jdbc</artifactId>
    <version>0.9.6-oss</version>
    <scope>runtime</scope>
  </dependency>
  

• Para proyectos de Gradle, agregue la siguiente dependencia al archivo de compilación del proyecto para indicar a Gradle que descargue automáticamente el controlador JDBC con la versión especificada:

  implementation 'com.databricks:databricks-jdbc:0.9.6-oss'
  

Para ver la sintaxis de dependencia de otros tipos de proyecto y obtener el número de versión más reciente del controlador JDBC (OSS) de Databricks, consulte la Repositorio de Maven.

Configurar la dirección URL de conexión

Para conectarse al área de trabajo de Azure Databricks mediante el controlador JDBC, debe especificar una dirección URL de conexión JDBC que incluya varias opciones de conexión, como el nombre de host del servidor del área de trabajo de Azure Databricks, la configuración de recursos de proceso y las credenciales de autenticación para conectarse al área de trabajo.

Puede establecer el valor de estas propiedades en la dirección URL de conexión de JDBC, establecerlas y pasarlas al método DriverManager.getConnection, o una combinación de ambos. Consulte la documentación del proveedor para obtener la mejor manera de conectarse mediante la aplicación específica, el cliente, el SDK, la API o la herramienta SQL.

La dirección URL de conexión JDBC debe tener el formato siguiente. Las propiedades no distinguen mayúsculas de minúsculas.

jdbc:databricks://<server-hostname>:<port>/<schema>;[property1]=[value];[property2]=[value];...

Alternativamente, especifique los ajustes utilizando la clase java.util.Properties o una combinación:

String url = "jdbc:databricks://<server-hostname>:<port>/<schema>";
Properties properties = new java.util.Properties();
properties.put("<property1>", "<value1");
properties.put("<property2>", "<value2");
// ...
Connection conn = DriverManager.getConnection(url, properties);

String url = "jdbc:databricks://<server-hostname>:<port>/<schema>;[property1]=[value];[property2]=[value];";
Connection conn = DriverManager.getConnection(url, "token", "12345678901234667890abcdabcd");

Los elementos de la dirección URL de conexión se describen en la tabla siguiente. Para obtener información acerca de las propiedades adicionales, incluidas las propiedades de autenticación, consulte las secciones siguientes. Los elementos y propiedades de la dirección URL no distinguen mayúsculas de minúsculas.

Elemento o propiedad URL	Descripción
<server-hostname>	Valor del nombre de host del servidor del recurso informático Azure Databricks.
<port>	Valor de puerto del recurso de proceso de Azure Databricks. El valor predeterminado es 443.
<schema>	Nombre del esquema. Como alternativa, puede establecer la propiedad ConnSchema. Consulte Propiedades de conexión.
httpPath	Valor de la ruta HTTP del recurso informático Azure Databricks. El conector forma la dirección HTTP a la que conectarse anexando el valor httpPath al host y al puerto especificados en la dirección URL de conexión. Por ejemplo, para conectarse a la dirección HTTP http://localhost:10002/cliservice, usaría la siguiente dirección URL de conexión: jdbc:databricks://localhost:10002;httpPath=cliservice

Para obtener la URL de conexión JDBC para un clúster Azure Databricks:

1. Inicie sesión en su área de trabajo de Azure Databricks.
2. En la barra lateral, haga clic en Proceso, y a continuación, haga clic en el nombre del clúster de destino.
3. En la pestaña Configuración, expanda Opciones avanzadas.
4. Haga clic en la pestaña JDBC/ODBC.
5. Copie la dirección URL de JDBC para usarla como dirección URL de conexión de JDBC o construya la dirección URL a partir de valores en los campos Nombre de host del servidor, Puertoy Ruta de acceso HTTP.

Para obtener la URL de conexión JDBC de un almacén SQL de Databricks :

1. Inicie sesión en su área de trabajo de Azure Databricks.
2. En la barra lateral, haga clic en Almacenes SQL y, a continuación, en el nombre del almacén de destino.
3. Haga clic en la pestaña Detalles de conexión.
4. Copie la URL JDBC para utilizarla como URL de conexión JDBC, o construya la URL a partir de los valores de los campos Server hostname, Port, y HTTP Path.

Autenticación del controlador

Puede autenticar la conexión del controlador JDBC mediante uno de los siguientes mecanismos de autenticación:

• Autenticación de usuario a máquina (U2M) de OAuth (recomendado)
• autenticación de máquina a máquina (M2M) de OAuth
• Token de acceso personal de Azure Databricks

Autenticación de usuario a máquina (U2M) de OAuth

El driver JDBC admite la autenticación OAuth de usuario a máquina (U2M) para el inicio de sesión humano en tiempo real y el consentimiento para autenticar la cuenta de usuario de Databricks de destino. Esto también se conoce como autenticación OAuth basada en el explorador.

Azure Databricks ha creado el Id. de cliente de OAuth databricks-sql-jdbc para los clientes. También es el Id. de cliente de OAuth predeterminado que se usa en el driver JDBC. Para configurar la autenticación OAuth U2M, basta con agregar las siguientes propiedades a la dirección URL de conexión JDBC existente o el objeto java.util.Properties:

Propiedad	Valor
AuthMech	11
Auth_Flow	2

Autenticación de máquina a máquina (M2M) de OAuth

El driver JDBC admite la autenticación OAuth de máquina a máquina (M2M) mediante una entidad de servicio de Azure Databricks. Esto también se conoce como autenticación de credenciales de cliente de OAuth 2.0. Consulte Autenticación del acceso a Azure Databricks con una entidad de servicio mediante OAuth (OAuth M2M).

Para configurar la autenticación de credenciales de cliente de OAuth M2M o OAuth 2.0:

1. Cree una entidad de servicio administrada de Microsoft Entra ID y asígnela a las cuentas y áreas de trabajo de Azure Databricks. Para obtener más información, consulte Administración de entidades de servicio.

   Importante

   Databricks JDBC Driver (OSS) admite secretos de OAuth de Azure Databricks para la autenticación de credenciales de cliente de OAuth M2M o OAuth 2.0. No se admiten secretos de Microsoft Entra ID.

2. Cree un secreto de OAuth de Azure Databricks para la entidad de servicio. Para ello, consulte Generación manual y uso de tokens de acceso para la autenticación M2M de OAuth.

3. Proporcione a la entidad de servicio acceso al clúster o al almacenamiento. Vea Permisos de proceso o Administración de un almacén de SQL.

Agregue las siguientes propiedades a la dirección URL de conexión JDBC existente o el objeto java.util.Properties:

Propiedad	Valor
AuthMech	11
Auth_Flow	1
OAuth2ClientID	El valor del identificador de aplicación (cliente) de la entidad de servicio.
OAuth2Secret	El secreto de OAuth de la entidad de servicio de Azure Databricks. (Los secretos de Microsoft Entra ID no se admiten para la autenticación de credenciales de cliente de OAuth M2M o OAuth 2.0).

Token de acceso personal de Azure Databricks

Para autenticar su conexión de controlador JDBC mediante un token de acceso personal, Azure Databricks, agregue las siguientes propiedades a su dirección URL u objeto java.util.Properties de conexión JDBC:

Propiedad	Valor
AuthMech	3
user	El valor token, como una cadena.
PWD o password	El valor del token de acceso personal de Azure Databricks, como una cadena.

Propiedades de la conexión

El controlador JDBC admite las siguientes propiedades de conexión adicionales. Las propiedades no distinguen mayúsculas de minúsculas.

Propiedad	Valor predeterminado	Descripción
AuthMech	Obligatorio	El mecanismo de autenticación, donde 3 especifica que el mecanismo es un token de acceso personal de Azure Databricks y 11 especifica que el mecanismo es tokens de OAuth 2.0. Se requieren propiedades adicionales para cada mecanismo. Consulte Autenticación del controlador.
Auth_Flow	0	Flujo de autenticación de OAuth2 para la conexión del controlador. Esta propiedad es necesaria si AuthMech es 11.
SSL	1	Si el conector se comunica con el servidor Spark a través de un socket habilitado para SSL.
ConnCatalog o catalog	SPARK	Nombre del catálogo predeterminado que se vaya a usar.
ConnSchema o schema	default	Nombre del esquema predeterminado que se vaya a usar. Esto se puede especificar reemplazando <schema> en la dirección URL por el nombre del esquema que se va a usar o estableciendo la propiedad ConnSchema en el nombre del esquema que se va a usar.
ProxyAuth	0	Si se establece en 1, el controlador usa el usuario y la contraseña de autenticación de proxy, representados por ProxyUID y ProxyPwd.
ProxyHost	null	Cadena que representa el nombre del host proxy que se va a usar cuando UseProxy también se establece en 1.
ProxyPort	null	Entero que representa el número del puerto proxy que se va a usar cuando UseProxy también se establece en 1.
ProxyUID	null	Cadena que representa el nombre de usuario que se va a usar para la autenticación de proxy cuando ProxyAuth y UseProxy también se establecen en 1.
ProxyPwd	null	Cadena que representa la contraseña que se va a usar para la autenticación de proxy cuando ProxyAuth y UseProxy también se establecen en 1.
UseProxy	0	Si se establece en 1, el controlador usa la configuración de proxy proporcionada (por ejemplo: ProxyAuth, ProxyHost, ProxyPort, ProxyPwd, y ProxyUID).
UseSystemProxy	0	Si se establece en 1, el controlador usa la configuración de proxy que se ha establecido en el nivel del sistema. Si se establecen propiedades de proxy adicionales en la dirección URL de conexión, estas propiedades de proxy adicionales invalidan las que se han establecido en el nivel de sistema.
UseCFProxy	0	Si se establece en 1, el controlador usa la configuración del proxy de captura en la nube si se proporcionan; de lo contrario, use el proxy normal.
CFProxyAuth	0	Si se establece en 1, el controlador usa el usuario y la contraseña de autenticación de proxy, representados por CFProxyUID y CFProxyPwd.
CFProxyHost	null	Cadena que representa el nombre del host proxy que se va a usar cuando UseCFProxy también se establece en 1.
CFProxyPort	null	Entero que representa el número del puerto proxy que se va a usar cuando UseCFProxy también se establece en 1.
CFProxyUID	null	Cadena que representa el nombre de usuario que se va a usar para la autenticación de proxy cuando CFProxyAuth y UseCFProxy también se establecen en 1.
CFProxyPwd	null	Cadena que representa la contraseña que se va a usar para la autenticación de proxy cuando CFProxyAuth y UseCFProxy también se establecen en 1.
AsyncExecPollInterval	200	Tiempo en milisegundos entre cada sondeo para el estado de ejecución de la consulta asincrónica. Asincrónico hace referencia al hecho de que la llamada RPC utilizada para ejecutar una consulta en Spark es asincrónica. No significa que se admiten operaciones asincrónicas de JDBC.
UserAgentEntry	browser	La entrada User-Agent que se va a incluir en la solicitud HTTP. Este valor tiene el formato siguiente: [ProductName]/[ProductVersion] [Comment]
UseThriftClient	0	Si el driver JDBC debe usar el cliente Thrift para conectarse a un clúster de uso completo. El valor predeterminado funciona para los almacenes de SQL.

Propiedades de configuración de SQL

El controlador JDBC admite las siguientes propiedades de configuración de SQL. También se describen en Parámetros de configuración. Las propiedades no distinguen mayúsculas de minúsculas.

Propiedad	Valor predeterminado	Descripción
ansi_mode	TRUE	Si se habilita el comportamiento estricto de ANSI SQL para determinadas funciones y reglas de conversión.
enable_photo	TRUE	Indica si se va a habilitar el motor de consultas vectorizado Photon.
legacy_time_parser_policy	EXCEPTION	Los métodos usados para analizar y dar formato a fechas y marcas de tiempo. Los valores válidos son EXCEPTION, LEGACY y CORRECTED.
max_file_partition_bytes	128m	El número máximo de bytes a empaquetar en una sola partición cuando se lee de fuentes basadas en archivos. La configuración puede ser cualquier entero positivo y opcionalmente, incluir una medida como b (bytes), k o kb (1024 bytes).
read_only_external_metastore	false	Controla si un metastore externo se trata como de solo lectura.
statement_timeout	172800	Establece un tiempo de espera de instrucción SQL entre 0 y 172800 segundos.
timezone	UTC	Establezca la zona horaria local. Id. de región con el formato area/city, como America/Los_Angeles o desplazamientos de zona en el formato (+|-)HH, (+|-)HH:mm o (+|-)HH:mm:ss, por ejemplo -08, +01:00 o -13:33:33. Además, UTC se admite como alias para +00:00.
use_cached_result	true	Si Databricks SQL almacena en caché y reutiliza los resultados siempre que sea posible.

Propiedades de registro

El controlador JDBC admite las siguientes propiedades de registro. Las propiedades no distinguen mayúsculas de minúsculas.

Propiedad	Valor predeterminado	Descripción
LogLevel	OFF	El nivel de registro, que es un valor de 0 a 6: - 0: Deshabilitar todo el registro. - 1: Habilitar el registro en el nivel FATAL, que registra eventos de error muy graves que llevarán al conector a anular. - 2: Habilitar el registro en el nivel ERROR, que registra los eventos de error que aún podrían permitir que el conector siga funcionando. - 3: Habilitar el registro en el nivel ADVERTENCIA, que registra los eventos que podrían dar lugar a un error si no se realiza ninguna acción. - 4: Habilitar el registro en el nivel INFO, que registra información general que describe el progreso del conector. - 5: Habilitar el registro en el nivel DEBUG, que registra información detallada que resulta útil para depurar el conector. - 6: Habilitar el registro en el nivel SEGUIMIENTO, que registra toda la actividad del conector. Use esta propiedad para habilitar o deshabilitar el registro en el conector y especificar la cantidad de detalles incluidos en los archivos de registro.
LogPath	Para determinar la ruta de acceso predeterminada para los registros, el controlador usa el valor establecido para estas propiedades del sistema, en este orden de prioridad: 1. user.dir 2. java.io.tmpdir 3. El directorio actual, es decir, .	Ruta de acceso completa a la carpeta donde el conector guarda los archivos de registro cuando el registro está habilitado, como una cadena. Para asegurarse de que la dirección URL de conexión es compatible con todas las aplicaciones JDBC, escape las barras diagonales inversas (\) en la ruta de acceso del archivo escribiendo otra barra diagonal inversa. Si el LogPath valor no es válido, el conector envía la información registrada al flujo de salida estándar (System.out).
LogFileSize	Sin máximo	Tamaño máximo permitido del archivo de registro, especificado en MB
LogFileCount	Sin máximo	El número máximo de archivos de registro permitidos

Habilitación y configuración del registro

El controlador JDBC admite los marcos De fachada de registro simple para Java (SLF4J) y java.util.logging (JUL). El controlador usa el marco de registro jul de forma predeterminada.

Para habilitar y configurar el registro para el controlador JDBC:

1. Habilite el marco de registro que desea usar:

   • Para el registro de SLF4J, establezca la propiedad -Dcom.databricks.jdbc.loggerImpl=SLF4JLOGGER del sistema y proporcione la implementación de enlace SLF4J (compatible con la versión 2.0.13 y posteriores de SLF4J) y el archivo de configuración correspondiente en la ruta de clase.
   • Para el registro de JUL, establezca la propiedad -Dcom.databricks.jdbc.loggerImpl=JDKLOGGERdel sistema . Este es el valor predeterminado.

2. Establezca la LogLevel propiedad en el cadena de conexión en el nivel deseado de información que se va a incluir en los archivos de registro.

3. Establezca la LogPath propiedad en el cadena de conexión en la ruta de acceso completa a la carpeta donde desea guardar los archivos de registro.

   Por ejemplo, la siguiente dirección URL de conexión habilita el nivel de registro 6 y guarda los archivos de registro en la carpeta C:temp:

   jdbc: databricks://localhost:11000;LogLevel=6;LogPath=C:\\temp
   

4. Reinicie la aplicación JDBC y vuelva a conectarse al servidor para aplicar la configuración.

Ejemplo: Ejecución de una consulta mediante el controlador JDBC

En el ejemplo siguiente se muestra cómo usar el controlador JDBC para ejecutar una consulta SQL de Databricks mediante un recurso de proceso de Azure Databricks.

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.ResultSetMetaData;
import java.sql.Statement;
import java.util.Properties;

public class DatabricksJDBCExample {

    public static void main(String[] args) {

        Class.forName("com.databricks.client.jdbc.Driver");

        // Set JDBC URL properties
        String jdbcUrl = "jdbc:databricks://dbc-a1b2345c-d6e7.cloud.databricks.com:443";
        Properties connectionProperties = new Properties();
        connectionProperties.put("httpPath", "sql/protocolv1/o/123456780012345/0123-123450-z000pi22");
        connectionProperties.put("ssl", "1");

        // Set authentication properties (personal access token)
        connectionProperties.put("AuthMech", "3");
        connectionProperties.put("user", "token");
        connectionProperties.put("password", "12345678901234667890abcdabcd");

        // Set logging properties
        connectionProperties.put("logPath", "logs/myapplication.log");

        // Establish connection and execute query
        try (Connection connection = DriverManager.getConnection(jdbcUrl, connectionProperties);
             Statement statement = connection.createStatement();
             ResultSet resultSet = statement.executeQuery("SELECT * FROM samples.nyctaxi.trips")) {

            // Get metadata and column names
            ResultSetMetaData metaData = resultSet.getMetaData();
            String[] columns = new String[metaData.getColumnCount()];
            for (int i = 0; i < columns.length; i++) {
                columns[i] = metaData.getColumnName(i + 1);
            }

            // Process and print the result set
            while (resultSet.next()) {
                System.out.print("Row " + resultSet.getRow() + "=[");
                for (int i = 0; i < columns.length; i++) {
                    if (i != 0) {
                        System.out.print(", ");
                    }
                    System.out.print(columns[i] + "='" + resultSet.getObject(i + 1) + "'");
                }
                System.out.println("]");
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Recursos adicionales

• Integración de DataGrip con Azure Databricks

• Integración de DBeaver con Azure Databricks

• Conexión manual a SQL Workbench/J

• Conexión a Infoworks

• Conexión a Qlik Replicate

• Conexión a StreamSets

• Conexión a Syncsort

• Conexión a MicroStrategy