Propiedades de conexión compatibles

En este artículo se describen las propiedades de conexión compatibles con databricks JDBC Driver, versión 3 y posteriores.

Propiedades de autenticación y proxy

El controlador JDBC de Databricks admite las siguientes propiedades de autenticación y proxy. Las propiedades no distinguen mayúsculas de minúsculas.

Propiedad	Valor predeterminado	Descripción
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.
Auth_Flow	0	Flujo de autenticación de OAuth2 para la conexión del controlador. Esta propiedad es necesaria si AuthMech es 11.
Auth_JWT_Alg	RS256	Algoritmo para la autenticación JWT de clave privada. Los algoritmos admitidos son: RSA: RS256, RS384, RS512, PS256, PS384, PS512 y EC: ES256, ES384, ES512
Auth_JWT_Key_File	null	Ruta de acceso al archivo de clave privada (formato PEM) para la autenticación JWT.
Auth_JWT_Key_Passphrase	null	Frase de contraseña para descifrar una clave privada cifrada.
Auth_KID	null	Identificador de clave (KID) necesario para la autenticación JWT. Esto es obligatorio cuando se usa JWT de clave privada.
Auth_RefreshToken	null	Token de actualización de OAuth2 usado para recuperar un nuevo token de acceso.
Auth_Scope	all-apis	Ámbito de autenticación de los flujos de OAuth2.
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.
AzureTenantId	null	Identificador de inquilino de Azure para la autenticación específica de Azure.
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	Una cadena que representa el nombre del host proxy que se debe usar cuando UseCFProxy también está configurado en 1.
CFProxyPort	null	Un entero que representa el número del puerto proxy que se va a usar cuando UseCFProxy también esté configurado 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.
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.
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.
EnableOIDCDiscovery	1	Si se establece en 1, se usa la dirección URL de detección de OpenID Connect.
EnableTokenCache	1	Si se establece en 1, habilita el almacenamiento en caché de tokens de OAuth para mejorar el rendimiento.
GoogleCredentialsFile	null	Ruta de acceso al archivo de clave JSON para la autenticación de la cuenta de servicio de Google.
GoogleServiceAccount	null	Habilita la autenticación mediante una cuenta de servicio de Google.
OAuth2ClientId	null	Identificador de cliente de OAuth2 para la autenticación. De forma predeterminada, databricks-sql-jdbc se usa para AWS, GCP y Azure. Se requiere un identificador de cliente personalizado para las configuraciones avanzadas de OAuth.
OAuth2ConnAuthAuthorizeEndpoint	null	Dirección URL del punto de conexión de autorización que se usa en un flujo de OAuth2.
OAuth2ConnAuthTokenEndpoint	null	Dirección URL del punto de conexión del token para el flujo de OAuth2.
OAuth2RedirectUrlPort	8020	Puerto de dirección URL de redireccionamiento de OAuth2 para flujos de autenticación basados en explorador.
OIDCDiscoveryEndpoint	null	La dirección URL de detección de OpenID Connect para recuperar la configuración de OIDC.
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	Una cadena que representa el nombre del host proxy que se debe usar cuando UseProxy también está configurado en 1.
ProxyPort	null	Un entero que representa el número del puerto proxy que se va a usar cuando UseProxy también esté configurado 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.
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.
TokenCachePassPhrase	null	Frase de contraseña que se va a usar para el cifrado de caché de tokens U2M de OAuth.
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, usa el proxy normal.
UseJWTAssertion	false	Habilita la autenticación JWT de clave privada para casos de uso de M2M en los que la autenticación secreta de cliente está restringida.
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.

Propiedades de configuración del almacén de confianza SSL

Las siguientes propiedades de configuración del almacén de confianza SSL son compatibles con el controlador JDBC de Databricks. Las propiedades no distinguen mayúsculas de minúsculas.

Propiedad	Valor predeterminado	Descripción
AcceptUndeterminedRevocation	0	Si se establece en 1, acepta certificados con estado de revocación no predeterminado cuando está habilitada la comprobación de revocación de certificados.
AllowSelfSignedCerts	0	Si se establece en 1, el controlador permite conexiones a servidores con certificados SSL autofirmados.
CheckCertificateRevocation	0	Si se establece en 1, el controlador comprueba si se ha revocado el certificado SSL.
SSL	1	Si el conector se comunica con el servidor Spark a través de un socket habilitado para SSL.
SSLKeyStore	null	Ruta de acceso al archivo de almacén de claves SSL para la autenticación de certificados de cliente. De forma predeterminada, la autenticación TLS de solo servidor se realiza para que no se requiera un certificado de cliente.
SSLKeyStorePwd	null	Contraseña del archivo de almacén de claves SSL.
SSLKeyStoreType	JKS	Tipo del almacén de claves SSL. Los valores válidos son JKS, PKCS12, JCEKSDKS y PKCS11.
SSLTrustStore	null	Ruta de acceso al archivo de almacén de confianza para la validación de certificados SSL.
SSLTrustStorePassword	null	Contraseña del archivo de almacén de confianza, si está protegido con contraseña.
SSLTrustStoreType	JKS	Tipo del almacén de confianza, por ejemplo, JKS o PKCS12. Si no se especifica, el controlador usa el almacén de confianza de JKS de forma predeterminada. Los tipos válidos son JKS, PKCS12y BCFKS.
UseSystemTrustStore	0	Si se establece en 1, el controlador usa el almacén de confianza predeterminado del sistema para la comprobación del certificado SSL.

Tipos de almacén de confianza

El controlador JDBC admite los siguientes modos SSL y tipos de almacén de confianza.

Modo de certificado autofirmado

Para usar el modo de certificado autofirmado, establezca la propiedad AllowSelfSignedCerts=1 de conexión. Este modo usa un generador de sockets de confianza que acepta cualquier certificado.

Almacén de confianza personalizado

Para usar un almacén de confianza personalizado, especifique un archivo de almacén de confianza personalizado en la SSLTrustStore propiedad de conexión. Este almacén de confianza se carga directamente desde la ruta de acceso especificada y utiliza los certificados para la validación SSL. Puede estar en JKS, PKCS12 u otros formatos admitidos.

Debe especificar las siguientes propiedades de conexión adicionales:

• SSLTrustStore: ruta de acceso al archivo del repositorio de confianza
• SSLTrustStorePassword: contraseña para el almacén de confianza (si es necesario)
• SSLTrustStoreType: tipo de almacén de confianza (opcional, el valor predeterminado es JKS si no se especifica)

Almacén de confianza de propiedades del sistema Java

Para usar el almacén de confianza de propiedades del sistema, establezca UseSystemTrustStore=1 y asegúrese de que no especifique un almacén de confianza personalizado. En su lugar, especifique un almacén de confianza mediante la propiedad javax.net.ssl.trustStoredel sistema Java . Esta propiedad se establece en el nivel de JVM mediante la -D marca , por ejemplo:

java -Djavax.net.ssl.trustStore=/path/to/truststore.jks -Djavax.net.ssl.trustStorePassword=changeit ...

El controlador JDBC comprueba primero la propiedad javax.net.ssl.trustStoredel sistema Java . Si se establece, usa este archivo de almacén de confianza en lugar del valor predeterminado de JDK. Si no se establece ninguna propiedad del sistema, usa el almacén de confianza predeterminado de JDK (cacerts), que se localiza en $JAVA_HOME/lib/security/cacerts o en una ruta de acceso similar.

Almacén de confianza predeterminado de JDK (cacerts)

El JDK incluye un almacén de confianza integrado denominado cacerts que contiene certificados de entidades de certificación conocidas, lo que permite la comprobación de certificados emitidos por esas CA. Este almacén de confianza se encuentra normalmente en $JAVA_HOME/lib/security/cacerts con una contraseña predeterminada "changeit" o "changeme".

Para usar el almacén de confianza predeterminado de JDK, establezca UseSystemTrustStore=1 y asegúrese de que no especifique un almacén de confianza personalizado o un almacén de confianza de propiedades del sistema Java. Si también se especifica un almacén de confianza mediante la propiedad javax.net.ssl.trustStoredel sistema Java , se omite, lo que garantiza que el controlador solo usa certificados del almacén de confianza de JDK predeterminado.

Orden de prioridad del almacén de confianza

El controlador usa el siguiente orden de prioridad para determinar qué almacén de confianza se va a usar:

1. El almacén de confianza personalizado especificado en la propiedad de conexión SSLTrustStore
2. Almacén de confianza especificado en la propiedad javax.net.ssl.trustStore del sistema Java (cuando UseSystemTrustStore=1)
3. El almacén de confianza predeterminado de JDK (cacerts)

Recomendaciones de seguridad

Para mantener la conexión segura, Databricks recomienda lo siguiente:

• Para entornos de producción:

  • No use el modo de certificado autofirmado (AllowSelfSignedCerts=1).
  • Utilice certificados oficiales firmados por una CA.
  • Usa UseSystemTrustStore=1 a menos que necesites un repositorio de confianza personalizado.

• Para almacenes de confianza personalizados:

  • Use al conectarse a servidores con certificados que no están en el almacén de confianza predeterminado.
  • Asegúrese de que el almacén de confianza contiene la cadena de certificados completa.
  • Proteja los archivos del almacén de confianza con los permisos adecuados.

Propiedades de la estrategia de reintento

Las siguientes propiedades de estrategia de reintento son compatibles con databricks JDBC Driver (OSS). Las propiedades no distinguen mayúsculas de minúsculas.

Propiedad	Valor predeterminado	Descripción
RateLimitRetry	1	Si se establece en 1, habilita el reintento en errores de límite de velocidad.
RateLimitRetryTimeout	120	Tiempo de espera de reintento de límite de velocidad en segundos.
TemporarilyUnavailableRetry	1	Si se establece en 1, habilita el reintento en errores no disponibles temporalmente.
TemporarilyUnavailableRetryTimeout	900	Tiempo de espera de reintento para errores temporalmente no disponibles, en segundos.
VolumeOperationRetryableHttpCode	408,429,500,502,503,504	Lista separada por comas de códigos HTTP que se pueden reintentar para la ingesta de volúmenes de Unity Catalog.
VolumeOperationRetryTimeout	15	Tiempo de espera de reintento para solicitudes HTTP de ingesta de volúmenes del catálogo de Unity, en minutos.

Propiedades de administración de rendimiento y conexión

Las siguientes propiedades de administración de rendimiento y conexión son compatibles con Databricks JDBC Driver (OSS). Las propiedades no distinguen mayúsculas de minúsculas.

Propiedad	Valor predeterminado	Descripción
CloudFetchThreadPoolSize	16	Tamaño del grupo de subprocesos para las operaciones de obtención en la nube.
DefaultStringColumnLength	255	Número máximo de caracteres que se pueden contener en columnas STRING para los informes de metadatos.
HttpConnectionPoolSize	100	Tamaño máximo del grupo de conexiones HTTP.
IdleHttpConnectionExpiry	60	Tiempo de expiración de la conexión HTTP inactiva, en segundos.
RowsFetchedPerBlock	2000000	Número máximo de filas que devuelve una consulta a la vez. Esto solo se aplica a los resultados en línea.
SocketTimeout	900	Tiempo de espera del socket para las operaciones de red, en segundos.

Propiedades de configuración de SQL

Las siguientes propiedades de configuración de SQL son compatibles con el controlador JDBC de Databricks. 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_photon	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, LEGACYy 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).
query_tags	"" (cadena vacía)	Lista separada por comas de etiquetas clave-valor que se van a asociar a consultas SQL para el seguimiento y el análisis en system.query.history.
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.

Registro de propiedades

Las siguientes propiedades de registro son compatibles con el controlador JDBC de Databricks. Las propiedades no distinguen mayúsculas de minúsculas.

Propiedad	Valor predeterminado	Descripción
LogFileCount	10	El número máximo de archivos de registro permitidos
LogFileSize	10	Tamaño máximo permitido del archivo de registro, especificado en MB
LogLevel	OFF	El nivel de registro, que es un valor de 0 a 6: 0: Desactivar 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: Habilite el registro en el nivel ERROR, que registra eventos de error que podrían permitir que el conector continúe ejecutándose. 3: Habilite 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: Habilite 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: Habilite el registro en el nivel TRACE, 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: user.dir java.io.tmpdir 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).

Habilitación y configuración del registro

El controlador JDBC admite los frameworks Simple Logging Facade for 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=JDKLOGGER del sistema. Este es el valor predeterminado.

2. Establezca la propiedad LogLevel en la cadena de conexión al nivel deseado de información para incluir en los archivos de registro.

3. Establezca la propiedad LogPath de la 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.

Otras propiedades de las funcionalidades

Las siguientes propiedades habilitan las características del controlador JDBC de Databricks. Las propiedades no distinguen mayúsculas de minúsculas.

Propiedad	Valor predeterminado	Descripción
EnableArrow	1	Si se establece en 0, la serialización de flechas para los resultados está deshabilitada, lo que también deshabilita el comportamiento de Captura en la nube, ya que el formato de flecha es necesario para Cloud Fetch.
EnableComplexDatatypeSupport	0	Si se establece en 1, se habilita la compatibilidad con tipos de datos complejos (ARRAYs, STRUCTs, MAPs) como objetos java nativos en lugar de cadenas.
EnableDirectResults	1	Si se establece en 1, habilita los resultados directos para mejorar el rendimiento de las consultas.
EnableGeoSpatialSupport	0	Si se establece en 1, habilita la compatibilidad con tipos de datos geoespaciales (GEOMETRY y GEOGRAPHY) como objetos estructurados de Java. Requiere EnableComplexDatatypeSupport=1 y EnableArrow=1 (Arrow está habilitado de forma predeterminada). Cuando se deshabilita, las columnas geoespaciales se devuelven como STRING en formato EWKT. Consulte Funciones geoespaciales ST.
EnableSqlScripting	1 o true	Habilita la compatibilidad del scripting SQL para bloques de instrucciones compuestas (BEGIN...END) y llamadas a procedimientos almacenados. Disponible en la versión 1.0.10 del controlador y versiones posteriores con Databricks Runtime 16.3 y versiones posteriores. Los procedimientos almacenados requieren Databricks Runtime 17.0 y versiones posteriores y la versión 3.0.1 del controlador y posteriores. Utilice Statement o PreparedStatement para invocar procedimientos. CallableStatement no se admite. Para obtener sintaxis y ejemplos, consulte Scripting de SQL.
EnableMetricViewMetadata	0	Si se establece en 1, habilita las operaciones de metadatos mejoradas para las vistas de métricas. Consulte Trabaje con los metadatos de la vista de métricas mediante el controlador JDBC de Databricks.
EnableTelemetry	0	Si se establece en 1, la telemetría está habilitada. Consulte Telemetría.
EnableVolumeOperations	1o true	Propiedad de información de cliente para habilitar las operaciones de volumen en una secuencia. Consulte Administración de archivos en volúmenes con el controlador JDBC de Databricks. De forma predeterminada, esta propiedad también habilita la REMOVE operación sobre un volumen. Importante: Debe establecerlo como una propiedad de información de cliente. Proporcionarlo solo en la URL de conexión no habilita las operaciones de volumen para un flujo de datos.
MaxBatchSize	500	Tamaño máximo del lote para las operaciones por lotes y el procesamiento de datos.
QueryResultCompressionType	1	Los valores válidos son 0 (sin compresión) y 1 (para la compresión LZ4). El controlador invalida automáticamente a 0 (sin compresión) para los resultados en línea, independientemente de la configuración.
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	1	Si el controlador JDBC debe usar el cliente thrift o las API de ejecución de instrucciones.
VolumeOperationAllowedLocalPaths	``	Lista separada por comas de rutas de acceso locales permitidas para descargar y cargar archivos de ingesta de volúmenes de Unity Catalog. Las rutas de acceso también incluyen subdirectorios. Cuando no se especifica, esto vuelve al valor de StagingAllowedLocalPathsy, a continuación, a una cadena vacía que no especifica ninguna restricción. Consulte Administración de archivos mediante volúmenes. Importante: Si la configuración está en un entorno multiinquilino (como herramientas de BI o servicios para desarrolladores) y los usuarios controlan la dirección URL completa de JDBC, el servicio debe establecer esta propiedad en una ubicación de espacio aislado o en una ruta de acceso inexistente. Esto impide que los usuarios escriban archivos arbitraty e interfieran con la implementación interna del servicio.

Colección de telemetría

La telemetría permite a Databricks simplificar la depuración y proporcionar una solución de problemas oportuna mediante la recopilación de:

• Detalles del entorno de cliente (versión del controlador, tiempo de ejecución, detalles del sistema operativo)
• Configuraciones de conexión JDBC (excluye los datos de PII)
• Medidas de latencia de operación
• Formato de resultado de ejecución (JSON insertado, flecha, etc.)
• Tipos de operación (consulta de ejecución, consulta de metadatos, operaciones de volumen)
• Datos de clasificación de errores
• Recuentos de reintentos

Nota:

Databricks mantiene estándares de privacidad estrictos que garantizan que no se recopilan contenido de consulta, resultados ni información de identificación personal (PII).