Pilote JDBC Databricks (OSS)

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.

Installer le pilote

Le pilote JDBC Databricks (OSS) est publié dans le référentiel Maven. La dernière version est 0.9.1-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.1-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.1-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.

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

1. Connectez-vous à votre espace de travail Azure Databricks.
2. Dans la barre latérale, cliquez sur Calcul, puis sur le nom du cluster cible.
3. Sous l’onglet Configuration, développez Options avancées.
4. Cliquez sur l’onglet JDBC/ODBC.
5. 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 :

1. Connectez-vous à votre espace de travail Azure Databricks.
2. Dans la barre latérale, cliquez sur Entrepôts SQL, puis sur le nom de l’entrepôt cible.
3. Cliquez sur l’onglet Détails de la connexion.
4. 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 :

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 :

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

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

3. 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 :

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

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();
        }
    }
}

Ressources supplémentaires

• Intégration de DataGrip à Azure Databricks

• Intégration de DBeaver à Azure Databricks

• Se connecter à SQL Workbench/J

• Se connecter à Infoworks

• Se connecter à Qlik Replicate

• Se connecter à StreamSets

• Se connecter à Syncsort

• Se connecter à MicroStrategy