Pilote JDBC Databricks (OSS)

Article
11/16/2024

Important

Ce pilote est en préversion publique, et n’est pas encore disponible open source.

Databricks fournit un pilote JDBC OSS (Open Source Software) qui vous permet de connecter des outils tels que DataGrip, DBeaver et SQL Workbench/J à Azure Databricks via Java Database Connectivity (JDBC), une spécification conforme aux normes du secteur d’activité pour accéder des systèmes de gestion de base de données.

Ce pilote a implémenté les API JDBC, et fournit des fonctionnalités de base, notamment OAuth, Cloud Fetch et des fonctionnalités telles que l’ingestion de volume Unity Catalog. Il exécute le mode de requête natif et prend en charge la requête paramétrisée native, et peut s’exécuter à l’aide des API d’exécution d’instructions, qui fournissent la fonctionnalité de rétention des résultats de requête bénéfique, ou Thrift.

Cet article fournit des informations sur l’installation et l’utilisation du pilote JDBC Databricks (OSS). Si vous souhaitez obtenir plus d’informations sur le pilote JDBC Databricks non-OSS, consultez Pilote JDBC Databricks.

Spécifications

Pour utiliser le pilote JDBC Databricks (OSS), les exigences suivantes doivent être satisfaites :

Nécessite Java Runtime Environment (JRE) 11.0 ou version ultérieure. Les tests CI sont pris en charge sur JRE 11, 17 et 21.

Remarque

Suite à une modification de JDK 16 qui a provoqué un problème de compatibilité avec la bibliothèque Apache Arrow utilisée par le pilote JDBC, les erreurs d’exécution peuvent se produire lors de l’utilisation du pilote JDBC avec JDK 16 ou version ultérieure. Pour éviter ces erreurs, redémarrez votre application ou pilote à l’aide de l’option de commande JVM suivante :

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

Installer le pilote

Le pilote JDBC Databricks (OSS) est publié dans le référentiel Maven. La dernière version est 0.9.6-oss.

Pour installer le pilote, vous pouvez effectuer l’une des opérations suivantes :

Pour les projets Maven, ajoutez la dépendance suivante au fichier pom.xml du projet pour indiquer à Maven de télécharger automatiquement le pilote JDBC avec la version spécifiée :
```
<dependency>
  <groupId>com.databricks</groupId>
  <artifactId>databricks-jdbc</artifactId>
  <version>0.9.6-oss</version>
  <scope>runtime</scope>
</dependency>
```
Pour les projets Gradle, ajoutez la dépendance suivante au fichier de build du projet pour indiquer à Gradle de télécharger automatiquement le pilote JDBC avec la version spécifiée :
```
implementation 'com.databricks:databricks-jdbc:0.9.6-oss'
```

Pour afficher la syntaxe de dépendance pour d’autres types de projets et obtenir le numéro de version le plus récent du pilote JDBC Databricks (OSS), consultez le référentiel Maven.

Configurer l’URL de connexion

Pour vous connecter à votre espace de travail Azure Databricks à l’aide du pilote JDBC, vous devez spécifier une URL de connexion JDBC qui inclut différents paramètres de connexion tels que le nom d’hôte du serveur de votre espace de travail Azure Databricks, les paramètres de ressources de calcul et les informations d’identification d’authentification pour se connecter à l’espace de travail.

Vous pouvez définir la valeur de ces propriétés sur l’URL de connexion JDBC, les définir et les transmettre à la méthode DriverManager.getConnection, ou une combinaison des deux. Consultez la documentation du fournisseur pour savoir comment vous connecter au mieux à l’aide de votre application, client, SDK, API ou outil SQL spécifique.

L’URL de connexion JDBC doit avoir le format suivant. Les propriétés ne respectent pas la casse.

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

Vous pouvez également spécifier les paramètres à l’aide de la classe java.util.Properties ou d’une combinaison :

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");

Les éléments de l’URL de connexion sont décrits dans le tableau suivant. Pour plus d’informations sur les propriétés supplémentaires, notamment les propriétés d’authentification, consultez les sections ci-dessous. Les éléments et propriétés d’URL ne respectent pas la casse.

Élément ou propriété d’URL	Description
`<server-hostname>`	Valeur du nom d’hôte du serveur de la ressource de calcul Azure Databricks.
`<port>`	Valeur du port de la ressource de calcul Azure Databricks. La valeur par défaut est `443`.
`<schema>`	Nom du schéma. En guise d'alternative, vous pouvez définir la propriété `ConnSchema`. Voir Propriétés de connexion.
`httpPath`	Valeur du chemin d’accès HTTP de la ressource de calcul Azure Databricks. Le connecteur forme l’adresse HTTP à laquelle se connecter en ajoutant la valeur `httpPath` à l’hôte et au port spécifiés dans l’URL de connexion. Par exemple, pour vous connecter à l’adresse HTTP `http://localhost:10002/cliservice`, vous devez utiliser l’URL de connexion suivante : `jdbc:databricks://localhost:10002;httpPath=cliservice`

Pour obtenir l’URL de connexion JDBC d’un cluster Azure Databricks :

Connectez-vous à votre espace de travail Azure Databricks.
Dans la barre latérale, cliquez sur Calcul, puis sur le nom du cluster cible.
Sous l’onglet Configuration, développez Options avancées.
Cliquez sur l’onglet JDBC/ODBC.
Copiez l’URL JDBC à utiliser comme URL de connexion JDBC, ou construisez l’URL à partir des valeurs indiquées dans les champs Nom d’hôte du serveur, Port et Chemin d’accès HTTP.

Pour obtenir l’URL de connexion JDBC d’un entrepôt Databricks SQL :

Connectez-vous à votre espace de travail Azure Databricks.
Dans la barre latérale, cliquez sur Entrepôts SQL, puis sur le nom de l’entrepôt cible.
Cliquez sur l’onglet Détails de la connexion.
Copiez l’URL JDBC à utiliser comme URL de connexion JDBC, ou construisez l’URL à partir des valeurs indiquées dans les champs Nom d’hôte du serveur, Port et Chemin d’accès HTTP.

Authentifier le pilote

Vous pouvez authentifier la connexion du pilote JDBC à l’aide de l’un des mécanismes d’authentification suivants :

Authentification utilisateur à machine (U2M) OAuth (Recommandé)
Authentification OAuth machine à machine (M2M)
Jeton d’accès personnel Azure Databricks

Authentification utilisateur à machine (U2M) OAuth

Le pilote JDBC prend en charge l’authentification utilisateur à machine (U2M) OAuth pour la connexion et le consentement humains en temps réel afin d’authentifier le compte d’utilisateur Databricks cible. Elle est également appelée authentification basée sur un navigateur OAuth.

Azure Databricks a créé l’ID client OAuth databricks-sql-jdbc pour les clients. Il s’agit également de l’ID client OAuth par défaut utilisé dans le pilote JDBC. Pour configurer l’authentification U2M OAuth, ajoutez simplement les propriétés suivantes à votre URL de connexion JDBC ou objet java.util.Properties existant :

Propriété	Valeur
`AuthMech`	`11`
`Auth_Flow`	`2`

Authentification OAuth machine à machine (M2M)

Le pilote JDBC prend en charge l’authentification de machine à machine (M2M) OAuth à l’aide d’un principal de service Azure Databricks. Elle est également appelée authentification des informations d’identification du client OAuth 2.0. Consultez Authentifier l’accès à Azure Databricks avec un principal de service à l’aide d’OAuth (OAuth M2M).

Pour configurer l’authentification des informations d’identification du client OAuth M2M ou OAuth 2.0 :

Créez un principal de service géré Microsoft Entra ID, puis affectez-le aux comptes et aux espaces de travail Azure Databricks. Pour plus de détails, consultez Gérer les principaux de service.

Important

Le pilote JDBC Databricks (OSS) prend en charge les secrets OAuth Azure Databricks pour l’authentification des informations d’identification du client OAuth 2.0 ou OAuth M2M. Les secrets Microsoft Entra ID ne sont pas pris en charge.
Créez un secret OAuth Azure Databricks pour le principal de service. Pour cela, consultez Générer et utiliser manuellement des jetons d’accès pour l’authentification M2M OAuth.
Accordez au principal de service l’accès à votre cluster ou entrepôt. Consultez Autorisations de calcul ou Gérer un entrepôt SQL.

Ajoutez les propriétés suivantes à votre URL de connexion JDBC ou objet java.util.Properties existant :

Propriété	Valeur
`AuthMech`	`11`
`Auth_Flow`	`1`
`OAuth2ClientID`	La valeur d’ID d’application (client) du principal de service.
`OAuth2Secret`	Secret OAuth Azure Databricks du principal de service. (Les secrets Microsoft Entra ID ne sont pas pris en charge pour l’authentification des informations d’identification de client OAuth M2M ou OAuth 2.0.)

Jeton d’accès personnel Azure Databricks

Pour authentifier votre connexion de pilote JDBC à l’aide d’un jeton d’accès personnel Azure Databricks, ajoutez les propriétés suivantes à votre URL de connexion JDBC ou objet java.util.Properties :

Propriété	Valeur
`AuthMech`	`3`
`user`	Valeur `token`, sous forme de chaîne.
`PWD` ou `password`	Valeur de votre jeton d’accès personnel Azure Databricks, sous forme de chaîne.

Propriétés de connexion

Les propriétés de connexion supplémentaires suivantes sont prises en charge par le pilote JDBC. Les propriétés ne respectent pas la casse.

Propriété	Valeur par défaut	Description
`AuthMech`	Obligatoire	Le mécanisme d’authentification, où `3` spécifie le mécanisme, est un jeton d’accès personnel Azure Databricks, et `11` spécifie que le mécanisme fait appel à des jetons OAuth 2.0. Des propriétés supplémentaires sont requises pour chaque mécanisme. Consultez Authentifier le pilote.
`Auth_Flow`	`0`	Flux d’authentification OAuth2 pour la connexion du pilote. Cette propriété est requise si `AuthMech` est `11`.
`SSL`	`1`	Indique si le connecteur communique avec le serveur Spark via un socket compatible SSL.
`ConnCatalog` ou `catalog`	`SPARK`	Nom du catalogue par défaut à utiliser.
`ConnSchema` ou `schema`	`default`	Nom du schéma par défaut à utiliser. Cela peut être spécifié en remplaçant `<schema>` dans l’URL par le nom du schéma à utiliser, ou en définissant la propriété `ConnSchema` sur le nom du schéma à utiliser.
`ProxyAuth`	`0`	Si la valeur est `1`, le pilote utilise l’utilisateur et le mot de passe d’authentification proxy, représentés par `ProxyUID` et `ProxyPwd`.
`ProxyHost`	`null`	Chaîne qui représente le nom de l’hôte proxy à utiliser lorsque `UseProxy` est également définie sur `1`.
`ProxyPort`	`null`	Entier qui représente le numéro du port proxy à utiliser quand `UseProxy` est également définie sur `1`.
`ProxyUID`	`null`	Chaîne qui représente le nom d’utilisateur à utiliser pour l’authentification proxy quand `ProxyAuth` et `UseProxy` sont également définies sur `1`.
`ProxyPwd`	`null`	Chaîne qui représente le mot de passe à utiliser pour l’authentification proxy quand `ProxyAuth` et `UseProxy` sont également définies sur `1`.
`UseProxy`	`0`	Si la valeur est `1`, le pilote utilise les paramètres de proxy fournis (par exemple : `ProxyAuth`, `ProxyHost`, `ProxyPort`, `ProxyPwd` et `ProxyUID`).
`UseSystemProxy`	`0`	Si la valeur est `1`, le pilote utilise les paramètres de proxy qui ont été définis au niveau du système. Si des propriétés de proxy supplémentaires sont définies dans l’URL de connexion, elles remplacent celles qui ont été définies au niveau du système.
`UseCFProxy`	`0`	Si la valeur est `1`, le pilote utilise les paramètres de proxy d’extraction cloud s’ils sont fournis ; autrement, il utilise le proxy standard.
`CFProxyAuth`	`0`	Si la valeur est `1`, le pilote utilise l’utilisateur et le mot de passe d’authentification proxy, représentés par `CFProxyUID` et `CFProxyPwd`.
`CFProxyHost`	`null`	Chaîne qui représente le nom de l’hôte proxy à utiliser lorsque `UseCFProxy` est également définie sur `1`.
`CFProxyPort`	`null`	Entier qui représente le numéro du port proxy à utiliser quand `UseCFProxy` est également définie sur `1`.
`CFProxyUID`	`null`	Chaîne qui représente le nom d’utilisateur à utiliser pour l’authentification proxy quand `CFProxyAuth` et `UseCFProxy` sont également définies sur `1`.
`CFProxyPwd`	`null`	Chaîne qui représente le mot de passe à utiliser pour l’authentification proxy quand `CFProxyAuth` et `UseCFProxy` sont également définies sur `1`.
`AsyncExecPollInterval`	`200`	Temps en millisecondes entre chaque sondage pour l’état d’exécution de requête asynchrone. L’option asynchrone fait référence au fait que l’appel RPC utilisé pour exécuter une requête sur Spark est asynchrone. Cela ne signifie pas que les opérations asynchrones JDBC sont prises en charge.
`UserAgentEntry`	`browser`	Entrée User-Agent à inclure dans la requête HTTP. Cette valeur est au format suivant : `[ProductName]/[ProductVersion] [Comment]`
`UseThriftClient`	`0`	Indique si le pilote JDBC doit utiliser le client Thrift pour se connecter à un cluster à usage général. La valeur par défaut fonctionne pour les entrepôts SQL.

Propriétés de configuration SQL

Les propriétés de configuration SQL suivantes sont prises en charge par le pilote JDBC. Elles sont également décrites dans Paramètres de configuration. Les propriétés ne respectent pas la casse.

Propriété	Valeur par défaut	Description
`ansi_mode`	`TRUE`	Indique s’il faut activer un comportement ANSI SQL strict pour certaines fonctions et règles de cast.
`enable_photo`	`TRUE`	Indique s’il faut activer le moteur de requête vectorisée Photon.
`legacy_time_parser_policy`	`EXCEPTION`	Méthodes utilisées pour analyser et mettre en forme les dates et les horodatages. Les valeurs valides sont `EXCEPTION`, `LEGACY` et `CORRECTED`.
`max_file_partition_bytes`	`128m`	Le nombre maximal d’octets à empaqueter dans une même partition lors de la lecture de sources basées sur des fichiers. Le paramètre peut être un entier positif, et éventuellement inclure une mesure telle que `b` (octets), `k` ou `kb` (1024 octets).
`read_only_external_metastore`	`false`	Contrôle si un metastore externe est traité comme étant en lecture seule.
`statement_timeout`	`172800`	Définit un délai d’expiration d’instruction SQL compris entre 0 et 172 800 secondes.
`timezone`	`UTC`	Définissez le fuseau horaire local. ID de région au format `area/city`, tel que Amérique/Los_Angeles, ou décalages de zone au format (+\|-)HH, (+\|-)HH:mm ou (+\|-)HH:mm:ss, par exemple -08, +01:00 ou -13:33:33. En outre, `UTC` est pris en charge comme alias pour +00:00
`use_cached_result`	`true`	Indique si Databricks SQL met en cache et réutilise les résultats dans la mesure du possible.

Propriétés de journalisation

Les propriétés de journalisation suivantes sont prises en charge par le pilote JDBC. Les propriétés ne respectent pas la casse.

Propriété	Valeur par défaut	Description
`LogLevel`	`OFF`	Niveau de journalisation, qui est une valeur comprise entre 0 et 6 : - 0 : Désactiver toute journalisation. - 1 : Activer la journalisation au niveau FATAL, ce qui enregistre les événements d’erreur très graves qui entraînent l’abandon du connecteur. - 2 : Activer la journalisation au niveau ERREUR, ce qui enregistre les événements d’erreur susceptibles de permettre au connecteur de continuer à s’exécuter. - 3 : Activer la journalisation au niveau AVERTISSEMENT, ce qui enregistre les événements susceptibles d’entraîner une erreur si aucune action n’est effectuée. - 4 : Activer la journalisation au niveau INFO, ce qui enregistre des informations générales qui décrivent la progression du connecteur. - 5 : Activer la journalisation au niveau DÉBOGAGE, ce qui enregistre des informations détaillées utiles pour le débogage du connecteur. - 6 : Activer la journalisation au niveau TRACE, ce qui enregistre toutes les activités du connecteur. Utilisez cette propriété pour activer ou désactiver la journalisation dans le connecteur, et spécifier la quantité de détails inclus dans les fichiers journaux.
`LogPath`	Pour déterminer le chemin par défaut des journaux, le pilote utilise la valeur définie pour ces propriétés système, dans cet ordre de priorité : 1. `user.dir` 2. `java.io.tmpdir` 3. le répertoire actif, en d’autres termes `.`	Chemin d’accès complet au dossier dans lequel le connecteur enregistre les fichiers journaux lorsque la journalisation est activée, sous forme de chaîne. Pour vous assurer que l’URL de connexion est compatible avec toutes les applications JDBC, échappez les barres obliques inverses (`\`) dans votre chemin de fichier en tapant une autre barre oblique inverse. Si la `LogPath` valeur n’est pas valide, le connecteur envoie les informations journalisées au flux de sortie standard (System.out).
`LogFileSize`	Pas de montant maximal	Taille maximale autorisée du fichier journal, spécifiée en Mo
`LogFileCount`	Pas de montant maximal	Nombre maximal de fichiers journaux autorisés

Activez et configurez la journalisation

Le pilote JDBC prend en charge les frameworks SLF4J (Simple Logging Façade for Java) et java.util.logging (JUL ). Le pilote utilise l’infrastructure de journalisation JUL par défaut.

Pour activer et configurer la journalisation pour le pilote JDBC :

Activez l’infrastructure de journalisation que vous souhaitez utiliser :
- Pour la journalisation SLF4J, définissez la propriété -Dcom.databricks.jdbc.loggerImpl=SLF4JLOGGER système et fournissez l’implémentation de liaison SLF4J (compatible avec SLF4J version 2.0.13 et ultérieure) et le fichier de configuration correspondant dans le classpath.
- Pour la journalisation JUL, définissez la propriété -Dcom.databricks.jdbc.loggerImpl=JDKLOGGERsystème . Il s’agit de la valeur par défaut.
Définissez la LogLevel propriété sur le chaîne de connexion sur le niveau d’informations souhaité à inclure dans les fichiers journaux.
Définissez la LogPath propriété sur le chaîne de connexion sur le chemin d’accès complet au dossier dans lequel vous souhaitez enregistrer les fichiers journaux.

Par exemple, l’URL de connexion suivante active le niveau de journalisation 6 et enregistre les fichiers journaux dans le dossier C :temp :
```
jdbc: databricks://localhost:11000;LogLevel=6;LogPath=C:\\temp
```
Redémarrez votre application JDBC et reconnectez-vous au serveur pour appliquer les paramètres.

Exemple : Exécuter une requête à l’aide du pilote JDBC

L’exemple suivant montre comment utiliser le pilote JDBC pour exécuter une requête Databricks SQL à l’aide d’une ressource de calcul 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();
        }
    }
}

Partager via