Databricks JDBC Sürücüsü (OSS)

Makale
07/26/2024

Önemli

Databricks, veritabanı yönetim sistemlerine erişmek için endüstri standardı bir belirtim olan Java Veritabanı Bağlantısı (JDBC) aracılığıyla DataGrip, DBeaver ve SQL Workbench/J gibi araçları Azure Databricks'e bağlamanızı sağlayan bir açık kaynak yazılımı (OSS) JDBC sürücüsü sağlar.

Bu makalede Databricks JDBC Sürücüsünü (OSS) yükleme ve kullanma hakkında bilgi sağlanır. OSS Olmayan Databricks JDBC Sürücüsü hakkında bilgi için bkz . Databricks JDBC Sürücüsü.

Gereksinimler

Databricks JDBC Sürücüsünü (OSS) kullanmak için aşağıdaki gereksinimlerin karşılanması gerekir:

Java Çalışma Zamanı Ortamı (JRE) 11.0 veya üzeri. CI testi JRE 11, 17 ve 21'de desteklenir.
Databricks SQL 2024.30 veya üzeri

Sürücüyü yükleme

Databricks JDBC Sürücüsü (OSS), Maven Deposunda yayımlanır. En son sürüm 0.9.0-oss'dir.

Sürücüyü yüklemek için aşağıdakilerden herhangi birini yapabilirsiniz:

Maven projeleri için, Maven'a pom.xml belirtilen sürüme sahip JDBC sürücüsünü otomatik olarak indirmesini bildirmek için projenin dosyasına aşağıdaki bağımlılığı ekleyin:
```
<dependency>
  <groupId>com.databricks</groupId>
  <artifactId>databricks-jdbc</artifactId>
  <version>0.9.0-oss</version>
  <scope>runtime</scope>
</dependency>
```
Gradle projeleri için, Gradle'a belirtilen sürüme sahip JDBC sürücüsünü otomatik olarak indirmesini bildirmek için projenin derleme dosyasına aşağıdaki bağımlılığı ekleyin:
```
implementation 'com.databricks:databricks-jdbc:0.9.0-oss'
```

Diğer proje türlerinin bağımlılık söz dizimini görüntülemek ve Databricks JDBC Sürücüsünün (OSS) en son sürüm numarasını almak için Maven Deposu'na bakın.

Bağlantı URL'sini yapılandırma

JDBC sürücüsünü kullanarak Azure Databricks çalışma alanınıza bağlanmak için, Azure Databricks çalışma alanınızın sunucu ana bilgisayar adı, işlem kaynağı ayarları ve çalışma alanına bağlanmak için kimlik doğrulaması kimlik bilgileri gibi çeşitli bağlantı ayarlarını içeren bir JDBC bağlantı URL'si belirtmeniz gerekir.

JDBC bağlantı URL'sinde bu özelliklerin değerini ayarlayabilir, bunları DriverManager.getConnection yöntemine veya her ikisinin bir bileşimine geçirebilirsiniz. Belirli uygulamanızı, istemcinizi, SDK'nızı, API'nizi veya SQL aracınızı kullanarak en iyi şekilde bağlanmayı öğrenmek için sağlayıcının belgelerine bakın.

JDBC bağlantı URL'si aşağıdaki biçimde olmalıdır. Özellikler büyük/küçük harfe duyarlı değildir.

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

Alternatif olarak, sınıfını veya bileşimini java.util.Properties kullanarak ayarları belirtin:

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

Bağlantı URL'si öğeleri aşağıdaki tabloda açıklanmıştır. Kimlik doğrulama özellikleri de dahil olmak üzere ek özellikler hakkında bilgi için aşağıdaki bölümlere bakın. URL öğeleri ve özellikleri büyük/küçük harfe duyarlı değildir.

URL öğesi veya özelliği	Açıklama
`<server-hostname>`	Azure Databricks işlem kaynağının sunucu ana bilgisayar adı değeri.
`<port>`	Azure Databricks işlem kaynağının bağlantı noktası değeri. Varsayılan değer şudur: `443`.
`<schema>`	Şemanın adı. Alternatif olarak özelliğini ayarlayabilirsiniz `ConnSchema` . Bkz. Bağlantı özellikleri.
`httpPath`	Azure Databricks işlem kaynağının HTTP yolu değeri. Bağlayıcı, değeri bağlantı URL'sinde belirtilen konak ve bağlantı noktasına ekleyerek `httpPath` bağlanacak HTTP adresini oluşturur. Örneğin, HTTP adresine `http://localhost:10002/cliservice`bağlanmak için aşağıdaki bağlantı URL'sini kullanabilirsiniz: `jdbc:databricks://localhost:10002;AuthMech=3;httpPath=cliservice;UID=token;PWD=password123;`

Azure Databricks kümesinin JDBC bağlantı URL'sini almak için:

Azure Databricks çalışma alanınıza giriş yapın.
Kenar çubuğunda İşlem'e ve ardından hedef kümenin adına tıklayın.
Yapılandırma sekmesinde Gelişmiş seçenekler'i genişletin.
JDBC/ODBC sekmesine tıklayın.
JDBC bağlantı URL'si olarak kullanmak için JDBC URL'sini kopyalayın veya Sunucu ana bilgisayar adı, Bağlantı Noktası ve HTTP Yolu alanlarındaki değerlerden URL'yi yapın.

Databricks SQL ambarı için JDBC bağlantı URL'sini almak için:

Azure Databricks çalışma alanınıza giriş yapın.
Kenar çubuğunda SQL Ambarları'na ve ardından hedef ambarın adına tıklayın.
Bağlantı ayrıntıları sekmesine tıklayın.
JDBC bağlantı URL'si olarak kullanmak için JDBC URL'sini kopyalayın veya Sunucu ana bilgisayar adı, Bağlantı Noktası ve HTTP Yolu alanlarındaki değerlerden URL'yi yapın.

Sürücünün kimliğini doğrulama

Aşağıdaki kimlik doğrulama mekanizmalarından birini kullanarak JDBC sürücü bağlantısının kimliğini doğrulayabilirsiniz:

Azure Databricks kişisel erişim belirteci
OAuth makineden makineye (M2M) kimlik doğrulaması

Azure Databricks kişisel erişim belirteci

Azure Databricks kişisel erişim belirtecini kullanarak JDBC sürücü bağlantınızın kimliğini doğrulamak için JDBC bağlantı URL'nize veya java.util.Properties nesnenize aşağıdaki özellikleri ekleyin:

Özellik	Değer
`AuthMech`	`3`
`UID` veya `user`	dize olarak değeri `token`.
`PWD` veya `password`	Dize olarak Azure Databricks kişisel erişim belirteci değeriniz.

OAuth makineden makineye (M2M) kimlik doğrulaması

JDBC sürücüsü, Microsoft Entra ID hizmet sorumlusu için OAuth makineden makineye (M2M) kimlik doğrulamasını destekler. Bu, OAuth 2.0 istemci kimlik bilgileri kimlik doğrulaması olarak da bilinir.

OAuth M2M veya OAuth 2.0 istemci kimlik bilgileri kimlik doğrulamasını yapılandırmak için:

Microsoft Entra Id yönetilen hizmet sorumlusu oluşturun ve ardından bunu Azure Databricks hesaplarına ve çalışma alanlarına atayın. Ayrıntılar için bkz . Hizmet sorumlularını yönetme.

Önemli

Databricks JDBC Sürücüsü (OSS), OAuth M2M veya OAuth 2.0 istemci kimlik bilgileri kimlik doğrulaması için Azure Databricks OAuth gizli dizilerini destekler. Microsoft Entra Id gizli dizileri desteklenmez.
Hizmet sorumlusu için bir Azure Databricks OAuth gizli dizisi oluşturun. Bunu yapmak için bkz . OAuth M2M kimlik doğrulaması için erişim belirteçlerini el ile oluşturma ve kullanma.
Hizmet sorumlusuna kümenize veya ambarınıza erişim verin. Bkz. İşlem izinleri veya SQL ambarı yönetme.

Mevcut JDBC bağlantı URL'nize veya java.util.Properties nesnenize aşağıdaki özellikleri ekleyin:

Özellik	Değer
`AuthMech`	`11`
`Auth_Flow`	`1`
`OAuth2ClientID`	Hizmet sorumlusunun Uygulama (istemci) Kimliği değeri.
`OAuth2Secret`	Hizmet sorumlusunun Azure Databricks OAuth gizli dizisi. (Microsoft Entra ID gizli dizileri OAuth M2M veya OAuth 2.0 istemci kimlik bilgileri kimlik doğrulaması için desteklenmez.)

Bağlantı özellikleri

Aşağıdaki ek bağlantı özellikleri JDBC sürücüsü tarafından desteklenir. Özellikler büyük/küçük harfe duyarlı değildir.

Özellik	Varsayılan değer	Açıklama
`AuthMech`	Gerekli	Mekanizmanın `3` bir Azure Databricks kişisel erişim belirteci olduğunu ve `11` mekanizmanın OAuth 2.0 belirteçleri olduğunu belirten kimlik doğrulama mekanizması. Her mekanizma için ek özellikler gereklidir. Bkz . Sürücünün kimliğini doğrulama.
`Auth_Flow`	`0`	Sürücü bağlantısı için OAuth2 kimlik doğrulama akışı. Bu özellik ise `AuthMech` `11`gereklidir.
`SSL`	`1`	Bağlayıcının SSL özellikli bir yuva üzerinden Spark sunucusuyla iletişim kurup kurmadığı.
`ConnCatalog` veya `catalog`	`SPARK`	Kullanılacak varsayılan kataloğun adı.
`ConnSchema` veya `schema`	`default`	Kullanılacak varsayılan şemanın adı. Bu, URL'de kullanılacak şemanın adıyla değiştirilerek `<schema>` veya özelliği kullanılacak şemanın adına ayarlanarak `ConnSchema` belirtilebilir.
`ProxyAuth`	`0`	olarak ayarlanırsa`1`, sürücü ve `ProxyPwd`ile `ProxyUID` temsil edilen proxy kimlik doğrulaması kullanıcı ve parolasını kullanır.
`ProxyHost`	`null`	ayrıca olarak ayarlandığında `1`kullanılacak `UseProxy` ara sunucu konağı adını temsil eden bir dize.
`ProxyPort`	`null`	ayrıca olarak ayarlandığında `1`kullanılacak `UseProxy` ara sunucu bağlantı noktasının sayısını temsil eden bir tamsayı.
`ProxyUID`	`null`	ve olarak ayarlandığında `1`proxy kimlik doğrulaması `ProxyAuth` `UseProxy` için kullanılacak kullanıcı adını temsil eden bir dize.
`ProxyPwd`	`null`	ve `ProxyAuth` `UseProxy` olarak ayarlandığında `1`ara sunucu kimlik doğrulaması için kullanılacak parolayı temsil eden bir dize.
`UseProxy`	`0`	olarak ayarlanırsa `1`, sürücü sağlanan ara sunucu ayarlarını kullanır (örneğin: `ProxyAuth`, `ProxyHost`, `ProxyPort`, `ProxyPwd`ve `ProxyUID`).
`UseSystemProxy`	`0`	olarak ayarlanırsa `1`, sürücü sistem düzeyinde ayarlanmış ara sunucu ayarlarını kullanır. Bağlantı URL'sinde başka ara sunucu özellikleri ayarlanırsa, bu ek ara sunucu özellikleri sistem düzeyinde ayarlanmış olanları geçersiz kılar.
`UseCFProxy`	`0`	olarak ayarlanırsa `1`, sürücü sağlanırsa bulut getirme proxy ayarlarını kullanır, aksi takdirde normal ara sunucuyu kullanın.
`CFProxyAuth`	`0`	olarak ayarlanırsa`1`, sürücü ve `CFProxyPwd`ile `CFProxyUID` temsil edilen proxy kimlik doğrulaması kullanıcı ve parolasını kullanır.
`CFProxyHost`	`null`	ayrıca olarak ayarlandığında `1`kullanılacak `UseCFProxy` ara sunucu konağı adını temsil eden bir dize.
`CFProxyPort`	`null`	ayrıca olarak ayarlandığında `1`kullanılacak `UseCFProxy` ara sunucu bağlantı noktasının sayısını temsil eden bir tamsayı.
`CFProxyUID`	`null`	ve olarak ayarlandığında `1`proxy kimlik doğrulaması `CFProxyAuth` `UseCFProxy` için kullanılacak kullanıcı adını temsil eden bir dize.
`CFProxyPwd`	`null`	ve `CFProxyAuth` `UseCFProxy` olarak ayarlandığında `1`ara sunucu kimlik doğrulaması için kullanılacak parolayı temsil eden bir dize.
`AsyncExecPollInterval`	`200`	Zaman uyumsuz sorgu yürütme durumu için her yoklama arasındaki milisaniye cinsinden süre. Zaman uyumsuz, Spark'a karşı sorgu yürütmek için kullanılan RPC çağrısının zaman uyumsuz olduğu gerçeğini ifade eder. Bu, JDBC zaman uyumsuz işlemlerinin desteklendiği anlamına gelmez.
`UserAgentEntry`	`browser`	HTTP isteğine eklenecek Kullanıcı Aracısı girdisi. Bu değer aşağıdaki biçimdedir: `[ProductName]/[ProductVersion] [Comment]`

SQL yapılandırma özellikleri

Aşağıdaki SQL yapılandırma özellikleri JDBC sürücüsü tarafından desteklenir. Bunlar Yapılandırma parametreleri bölümünde de açıklanmıştır. Özellikler büyük/küçük harfe duyarlı değildir.

Özellik	Varsayılan değer	Açıklama
`ansi_mode`	`TRUE`	Belirli işlevler ve atama kuralları için katı ANSI SQL davranışının etkinleştirilip etkinleştirilmeyileceği.
`enable_photo`	`TRUE`	Photon vektörleştirilmiş sorgu altyapısının etkinleştirilip etkinleştirilmeyileceği.
`legacy_time_parser_policy`	`EXCEPTION`	Tarihleri ve zaman damgalarını ayrıştırmak ve biçimlendirmek için kullanılan yöntemler. Geçerli değerler: `EXCEPTION`, `LEGACY` ve `CORRECTED`.
`max_file_partition_bytes`	`128m`	Dosya tabanlı kaynaklardan okurken tek bir bölüme paketlenmesi gereken bayt sayısı üst sınırı. Bu ayar herhangi bir pozitif tamsayı olabilir ve isteğe bağlı olarak (bayt) veya `kb` (1024 bayt) `k` gibi `b` bir ölçü içerebilir.
`read_only_external_metastore`	`false`	Dış meta veri deposuna salt okunur olarak davranılıp değerlendirilmediğini denetler.
`statement_timeout`	`172800`	0 ile 172800 saniye arasında bir SQL deyimi zaman aşımı ayarlar.
`timezone`	`UTC`	Yerel saat dilimini ayarlayın. Biçimindeki `area/city`Bölge Kimlikleri, örneğin Amerika/Los_Angeles veya biçimdeki bölge uzaklıkları (+
`use_cached_result`	`true`	Databricks SQL'in mümkün olduğunca sonuçları önbelleğe alıp almadığı ve yeniden kullanıp kullanmadığı.

Günlüğe kaydetme özellikleri

Aşağıdaki günlük özellikleri JDBC sürücüsü tarafından desteklenir. Özellikler büyük/küçük harfe duyarlı değildir.

Özellik	Varsayılan değer	Açıklama
`LogLevel`	`4`	0 ile 6 arasında bir değer olan günlük düzeyi: * 0: Tüm günlükleri devre dışı bırakın. * 1: Bağlayıcının durdurulmasına neden olacak çok ciddi hata olaylarını günlüğe kaydeden ÖNEMLİ düzeyinde günlüğe kaydetmeyi etkinleştirin. * 2: Bağlayıcının çalışmaya devam edebilmesine izin verebilen hata olaylarını günlüğe kaydeden HATA düzeyinde günlüğe kaydetmeyi etkinleştirin. * 3: Eylem yapılmazsa hataya neden olabilecek olayları günlüğe kaydeden UYARI düzeyinde günlüğe kaydetmeyi etkinleştirin. * 4: Bağlayıcının ilerleme durumunu açıklayan genel bilgileri günlüğe kaydeden BİlGİ düzeyinde günlüğe kaydetmeyi etkinleştirin. * 5: Bağlayıcıda hata ayıklamak için yararlı olan ayrıntılı bilgileri günlüğe kaydeden HATA AYıKLAMA düzeyinde günlüğe kaydetmeyi etkinleştirin. * 6: Tüm bağlayıcı etkinliğini günlüğe kaydeden TRACE düzeyinde günlüğe kaydetmeyi etkinleştirin. Bağlayıcıda günlüğe kaydetmeyi etkinleştirmek veya devre dışı bırakmak ve günlük dosyalarına dahil edilen ayrıntı miktarını belirtmek için bu özelliği kullanın.
`LogPath`	`logs/application.log`	Günlük etkinleştirildiğinde bağlayıcının günlük dosyalarını dize olarak kaydettiği klasörün tam yolu. `LogPath` Değer geçersizse, bağlayıcı günlüğe kaydedilen bilgileri standart çıkış akışına (System.out) gönderir.

Örnek: JDBC sürücüsünü kullanarak sorgu çalıştırma

Aşağıdaki örnekte, Azure Databricks işlem kaynağı kullanarak Databricks SQL sorgusu çalıştırmak için JDBC sürücüsünün nasıl kullanılacağı gösterilmektedir.

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

Aracılığıyla paylaş