Microsoft JDBC-driver for Microsoft Fabric Data Engineering

JDBC (Java Database Connectivity) er en mye brukt standard som gjør det mulig for klientapplikasjoner å koble til og arbeide med data fra databaser og big data-plattformer.

Microsoft JDBC Driver for Fabric Data Engineering lar deg koble til, spørre og administrere Spark-arbeidsbelastninger i Fabric med påliteligheten og enkelheten til JDBC-standarden. Bygget på Fabric sine Livy-API-er, gir driveren sikker og fleksibel Spark SQL-tilkobling til dine Java-applikasjoner og BI-verktøy. Denne integrasjonen lar deg sende inn og kjøre Spark-kode direkte uten å måtte lage separate notatbok- eller Spark-jobbdefinisjonselementer. Driveren er kompatibel med populære JDBC-klienter som DbVisualizer og DBeaver, samt BI-verktøy som støtter JDBC-tilkobling, inkludert Tableau.

Viktige funksjoner

• JDBC 4.2-kompatibel: Full implementering av JDBC 4.2-spesifikasjonen
• Microsoft Entra ID-autentisering: Flere autentiseringsflyter inkludert interaktiv, klientlegitimasjon og sertifikatbasert autentisering
• HikariCP-integrasjon: Bruk HikariCP til å administrere og gjenbruke JDBC-tilkoblinger for produksjonsapplikasjoner
• Spark SQL Native Query Support: Direkte kjøring av Spark SQL-setninger uten oversettelse
• Omfattende støtte for datatyper: Støtte for alle Spark SQL-datatyper, inkludert komplekse typer (ARRAY, MAP, STRUCT)
• Asynkron resultatsett-prefetching: Bakgrunnsdatainnlasting for bedre ytelse
• Sikringsmønster: Beskyttelse mot kaskaderende feil med automatisk omprøving
• Auto-retilkobling: Transparent sesjonsgjenoppretting ved tilkoblingsfeil
• Avansert retry-logikk: Retry med eksponentiell backoff og sesjonsgjenoppretting for bedre motstandskraft
• Proxy-støtte: HTTP- og SOCKS-proxykonfigurasjon for bedriftsmiljøer

Forutsetning

Før du bruker Microsoft JDBC Driver for Fabric Data Engineering, sørg for at du har:

• Java Development Kit (JDK): Versjon 11 eller nyere (Java 21 anbefales)
• Fabric Access: Tilgang til et Fabric-arbeidsområde
• Microsoft Entra ID legitimasjon: Passende legitimasjon for autentisering
• Workspace- og Lakehouse-ID-er: GUID-identifikatorer for ditt Fabric workspace og lakehouse

Nedlasting og installasjon

Microsoft JDBC Driver for Fabric Data Engineering versjon 1.0.0 støtter Java 11, 17 og 21. Vi forbedrer kontinuerlig støtte for Java-tilkobling og anbefaler at du bruker den nyeste versjonen av Microsoft JDBC-driveren.

• Last ned Microsoft JDBC Driver for Fabric Data Engineering (zip)
• Last ned Microsoft JDBC Driver for Fabric Data Engineering (tar)

1. Last ned enten zip- eller tar-filen fra lenkene ovenfor.
2. Pakk ut den nedlastede filen for å få tilgang til driverens JAR-filer.
3. Velg JAR-filen som matcher din JRE-versjon:
   • For Java 11:ms-sparksql-jdbc-1.0.1.jre11.jar
   • For Java 17:ms-sparksql-jdbc-1.0.1.jre17.jar
   • For Java 21:ms-sparksql-jdbc-1.0.1.jre21.jar
4. Legg til den valgte JAR-filen i applikasjonens klassesti.
5. For JDBC-klienter, konfigurer JDBC-driverklassen: com.microsoft.spark.livy.jdbc.LivyDriver

Eksempel på Quick Start

Dette eksempelet demonstrerer hvordan man kobler til Fabric og kjører en spørring ved hjelp av Microsoft JDBC Driver for Fabric Data Engineering. Før du kjører denne koden, sørg for at du har fullført forutsetningene og installert driveren.

import java.sql.*;

public class QuickStartExample {
    public static void main(String[] args) {
        // Connection string with required parameters
        String url = "jdbc:fabricspark://api.fabric.microsoft.com;" +
                     "FabricWorkspaceID=<workspace-id>;" +
                     "FabricLakehouseID=<lakehouse-id>;" +
                     "AuthFlow=2;" +  // Azure CLI based authentication
                     "LogLevel=INFO";
        
        try (Connection conn = DriverManager.getConnection(url)) {
            // Execute a simple query
            try (Statement stmt = conn.createStatement();
                 ResultSet rs = stmt.executeQuery("SELECT 'Hello from Fabric!' as message")) {
                
                if (rs.next()) {
                    System.out.println(rs.getString("message"));
                }
            }
        } catch (SQLException e) {
            e.printStackTrace();
        }
    }
}

Tilkoblingsstrengformat

Grunnleggende tilkoblingsstreng

Microsoft JDBC Driver for Fabric Data Engineering bruker følgende tilkoblingsstreng-format:

jdbc:fabricspark://<hostname>[:<port>][;<parameter1>=<value1>;<parameter2>=<value2>;...]

Tilkoblingsstrengkomponenter

Eksempler på tilkoblingsstrenger

Grunnleggende tilkobling (interaktiv nettleserbasert autentisering)

jdbc:fabricspark://api.fabric.microsoft.com;FabricWorkspaceID=<workspace-id>;FabricLakehouseID=<lakehouse-id>;AuthFlow=1

Med Spark Resource Configuration

jdbc:fabricspark://api.fabric.microsoft.com;FabricWorkspaceID=<workspace-id>;FabricLakehouseID=<lakehouse-id>;DriverCores=4;DriverMemory=4g;ExecutorCores=4;ExecutorMemory=8g;NumExecutors=2;AuthFlow=2

Med Spark Session-egenskaper

jdbc:fabricspark://api.fabric.microsoft.com;FabricWorkspaceID=<workspace-id>;FabricLakehouseID=<lakehouse-id>;spark.sql.adaptive.enabled=true;spark.sql.shuffle.partitions=200;AuthFlow=2

Autentisering

Microsoft JDBC Driver for Fabric Data Engineering støtter flere autentiseringsmetoder gjennom Microsoft Entra ID (tidligere Azure Active Directory). Autentisering konfigureres ved å bruke parameteren AuthFlow i tilkoblingsstrengen.

Autentiseringsflyter

Interaktiv nettleserautentisering

Best for: Utvikling og interaktive applikasjoner

String url = "jdbc:fabricspark://api.fabric.microsoft.com;" +
             "FabricWorkspaceID=<workspace-id>;" +
             "FabricLakehouseID=<lakehouse-id>;" +
             "AuthFlow=1;" +  
             "AuthTenantID=<tenant-id>;" +  // Optional
             "LogLevel=INFO";

Connection conn = DriverManager.getConnection(url);

Parametere:

• AuthFlow=1: Spesifiserer interaktiv nettleserautentisering
• AuthTenantID (valgfritt): Microsoft Entra leietaker-ID
• AuthClientID (valgfritt): Applikasjons-ID (klient)

Oppførsel:

• Åpner et nettleservindu for brukerautentisering
• Legitimasjonen lagres for påfølgende tilkoblinger til den utløper
• Egnet for enkeltbrukerapplikasjoner

Klientlegitimasjon eller autentisering av tjenestehovedpersoner

Best for: Automatiserte tjenester og bakgrunnsjobber

String url = "jdbc:fabricspark://api.fabric.microsoft.com;" +
             "FabricWorkspaceID=<workspace-id>;" +
             "FabricLakehouseID=<lakehouse-id>;" +
             "AuthFlow=3;" +  
             "AuthClientID=<client-id>;" +
             "AuthClientSecret=<client-secret>;" +
             "AuthTenantID=<tenant-id>;" +
             "LogLevel=INFO";

Connection conn = DriverManager.getConnection(url);

Nødvendige parametere:

• AuthFlow=3: Spesifiserer autentisering av klientlegitimasjon
• AuthClientID: Applikasjons-(klient-)ID fra Microsoft Entra-ID
• AuthClientSecret: Klienthemmelighet fra Microsoft Entra-ID
• AuthTenantID: Microsoft Entra leietaker-ID

Beste praksis:

• Lagre hemmeligheter sikkert (Azure Key Vault, miljøvariabler)
• Bruk administrerte identiteter når det er mulig
• Roter hemmeligheter regelmessig

Certificate-Based Autentisering

Best for: Bedriftsapplikasjoner som krever sertifikatbasert autentisering

String url = "jdbc:fabricspark://api.fabric.microsoft.com;" +
             "FabricWorkspaceID=<workspace-id>;" +
             "FabricLakehouseID=<lakehouse-id>;" +
             "AuthFlow=4;" +  
             "AuthClientID=<client-id>;" +
             "AuthCertificatePath=/path/to/certificate.pfx;" +
             "AuthCertificatePassword=<certificate-password>;" +
             "AuthTenantID=<tenant-id>;" +
             "LogLevel=INFO";

Connection conn = DriverManager.getConnection(url);

Nødvendige parametere:

• AuthFlow=4: Spesifiserer sertifikatbasert autentisering
• AuthClientID: Applikasjons-ID (klient-ID)
• AuthCertificatePath: Vei til PFX/PKCS12-sertifikatfilen
• AuthCertificatePassword: Sertifikatpassord
• AuthTenantID: Microsoft Entra leietaker-ID

Autentisering av tilgangstoken

Best for: Tilpassede autentiseringsscenarier

// Acquire token through custom mechanism
String accessToken = acquireTokenFromCustomSource();

String url = "jdbc:fabricspark://api.fabric.microsoft.com;" +
             "FabricWorkspaceID=<workspace-id>;" +
             "FabricLakehouseID=<lakehouse-id>;" +
             "AuthFlow=5;" +  // Access token authentication
             "AuthAccessToken=" + accessToken + ";" +
             "LogLevel=INFO";

Connection conn = DriverManager.getConnection(url);

Autentiseringsbuffer

Driveren cacher automatisk autentiseringstokene for å forbedre ytelsen:

// Enable/disable caching (enabled by default)
String url = "jdbc:fabricspark://api.fabric.microsoft.com;" +
             "FabricWorkspaceID=<workspace-id>;" +
             "FabricLakehouseID=<lakehouse-id>;" +
             "AuthFlow=2;" +
             "AuthEnableCaching=true;" +  // Enable token caching
             "AuthCacheTTLMS=3600000";    // Cache TTL: 1 hour

Connection conn = DriverManager.getConnection(url);

Konfigurasjonsparametere

Obligatoriske parametere

Disse parameterne må være til stede i hver tilkoblingsstreng:

Valgfrie parametere

API-versjonskonfigurasjon

Miljøkonfigurasjon

Spark-konfigurasjon

Sesjonsressurskonfigurasjon

Konfigurer Spark-sesjonsressurser for optimal ytelse:

Eksempel:

DriverCores=4;DriverMemory=4g;ExecutorCores=4;ExecutorMemory=8g;NumExecutors=2

Egendefinerte Spark-sesjonsegenskaper

Enhver parameter med prefikset spark. brukes automatisk på Spark-økten:

Eksempler på Spark-konfigurasjoner:

spark.sql.adaptive.enabled=true
spark.sql.adaptive.coalescePartitions.enabled=true
spark.sql.shuffle.partitions=200
spark.sql.autoBroadcastJoinThreshold=10485760
spark.dynamicAllocation.enabled=true
spark.dynamicAllocation.minExecutors=1
spark.dynamicAllocation.maxExecutors=10
spark.executor.memoryOverhead=1g

Innebygd utførelsesmotor (NEE):

spark.nee.enabled=true

Fullstendig eksempel:

jdbc:fabricspark://api.fabric.microsoft.com;FabricWorkspaceID=<guid>;FabricLakehouseID=<guid>;DriverMemory=4g;ExecutorMemory=8g;NumExecutors=2;spark.sql.adaptive.enabled=true;spark.nee.enabled=true;AuthFlow=2

HTTP-klienttilkoblingsinnstillinger

Konfigurer driverens HTTP-transportforbindelser for optimal nettverksytelse. Disse innstillingene konfigurerer eller administrerer ikke JDBC-tilkoblingspooling:

Eksempel:

HttpMaxTotalConnections=200;HttpMaxConnectionsPerRoute=100;HttpConnectionTimeoutInSeconds=60

Proxy-konfigurasjon

Konfigurer HTTP- og SOCKS-proxyinnstillinger for bedriftsmiljøer:

Eksempel på HTTP-proxy:

UseProxy=true;ProxyTransport=http;ProxyHost=proxy.company.com;ProxyPort=8080;ProxyAuthEnabled=true;ProxyUsername=user;ProxyPassword=pass

SOCKS-proxy-eksempel:

UseProxy=true;ProxyTransport=tcp;ProxyHost=socks.company.com;ProxyPort=1080;ProxySocksVersion=5

Konfigurasjon av logging

Eksempel:

LogLevel=DEBUG

Standard loggplassering:

${user.home}/.microsoft/livy-jdbc-driver/driver.log

Egendefinert loggkonfigurasjon: Bruk en egendefinert log4j2.xml fil eller logback.xml fil på klassestien din.

Brukseksempler

Grunnleggende tilkobling

import java.sql.*;

public class BasicConnectionExample {
    public static void main(String[] args) {
        String url = "jdbc:fabricspark://api.fabric.microsoft.com;" +
                     "FabricWorkspaceID=<workspace-id>;" +
                     "FabricLakehouseID=<lakehouse-id>;" +
                     "AuthFlow=2";
        
        try (Connection conn = DriverManager.getConnection(url)) {
            System.out.println("Connected successfully!");
            System.out.println("Database: " + conn.getMetaData().getDatabaseProductName());
            System.out.println("Driver: " + conn.getMetaData().getDriverName());
            System.out.println("Driver Version: " + conn.getMetaData().getDriverVersion());
        } catch (SQLException e) {
            System.err.println("Connection failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Utførelse av forespørsler

Enkel spørring

public void executeSimpleQuery(Connection conn) throws SQLException {
    String sql = "SELECT current_timestamp() as now";
    
    try (Statement stmt = conn.createStatement();
         ResultSet rs = stmt.executeQuery(sql)) {
        
        if (rs.next()) {
            Timestamp now = rs.getTimestamp("now");
            System.out.println("Current timestamp: " + now);
        }
    }
}

Søk med filter

public void executeQueryWithFilter(Connection conn) throws SQLException {
    String sql = "SELECT * FROM sales WHERE amount > 1000 ORDER BY amount DESC";
    
    try (Statement stmt = conn.createStatement();
         ResultSet rs = stmt.executeQuery(sql)) {
        
        while (rs.next()) {
            int id = rs.getInt("id");
            double amount = rs.getDouble("amount");
            Date date = rs.getDate("sale_date");
            
            System.out.printf("ID: %d, Amount: %.2f, Date: %s%n", 
                            id, amount, date);
        }
    }
}

Søk med grense

public void executeQueryWithLimit(Connection conn) throws SQLException {
    String sql = "SELECT * FROM customers LIMIT 10";
    
    try (Statement stmt = conn.createStatement();
         ResultSet rs = stmt.executeQuery(sql)) {
        
        ResultSetMetaData metaData = rs.getMetaData();
        int columnCount = metaData.getColumnCount();
        
        // Print column names
        for (int i = 1; i <= columnCount; i++) {
            System.out.print(metaData.getColumnName(i) + "\t");
        }
        System.out.println();
        
        // Print rows
        while (rs.next()) {
            for (int i = 1; i <= columnCount; i++) {
                System.out.print(rs.getString(i) + "\t");
            }
            System.out.println();
        }
    }
}

Arbeid med resultatsett

Navigering av resultatsett

public void navigateResultSet(Connection conn) throws SQLException {
    String sql = "SELECT id, name, amount FROM orders";
    
    try (Statement stmt = conn.createStatement(
            ResultSet.TYPE_SCROLL_INSENSITIVE,
            ResultSet.CONCUR_READ_ONLY);
         ResultSet rs = stmt.executeQuery(sql)) {
        
        // Move to first row
        if (rs.first()) {
            System.out.println("First row: " + rs.getString("name"));
        }
        
        // Move to last row
        if (rs.last()) {
            System.out.println("Last row: " + rs.getString("name"));
            System.out.println("Total rows: " + rs.getRow());
        }
        
        // Move to specific row
        if (rs.absolute(5)) {
            System.out.println("Row 5: " + rs.getString("name"));
        }
    }
}

Behandling av store resultatsett

public void processLargeResultSet(Connection conn) throws SQLException {
    String sql = "SELECT * FROM large_table";
    
    try (Statement stmt = conn.createStatement()) {
        // Set fetch size for efficient memory usage
        stmt.setFetchSize(1000);
        
        try (ResultSet rs = stmt.executeQuery(sql)) {
            int rowCount = 0;
            while (rs.next()) {
                // Process row
                processRow(rs);
                rowCount++;
                
                if (rowCount % 10000 == 0) {
                    System.out.println("Processed " + rowCount + " rows");
                }
            }
            System.out.println("Total rows processed: " + rowCount);
        }
    }
}

private void processRow(ResultSet rs) throws SQLException {
    // Process individual row
}

Bruk av forberedte utsagn

public void usePreparedStatement(Connection conn) throws SQLException {
    String sql = "SELECT * FROM products WHERE category = ? AND price > ?";
    
    try (PreparedStatement pstmt = conn.prepareStatement(sql)) {
        // Set parameters
        pstmt.setString(1, "Electronics");
        pstmt.setDouble(2, 100.0);
        
        try (ResultSet rs = pstmt.executeQuery()) {
            while (rs.next()) {
                String name = rs.getString("name");
                double price = rs.getDouble("price");
                System.out.printf("Product: %s, Price: $%.2f%n", name, price);
            }
        }
    }
}

Batchoperasjoner

public void executeBatchInsert(Connection conn) throws SQLException {
    String sql = "INSERT INTO logs (timestamp, level, message) VALUES (?, ?, ?)";
    
    try (PreparedStatement pstmt = conn.prepareStatement(sql)) {
        conn.setAutoCommit(false);  // Disable auto-commit for batch
        
        // Add multiple statements to batch
        for (int i = 0; i < 1000; i++) {
            pstmt.setTimestamp(1, new Timestamp(System.currentTimeMillis()));
            pstmt.setString(2, "INFO");
            pstmt.setString(3, "Log message " + i);
            pstmt.addBatch();
            
            // Execute batch every 100 statements
            if (i % 100 == 0) {
                pstmt.executeBatch();
                pstmt.clearBatch();
            }
        }
        
        // Execute remaining statements
        pstmt.executeBatch();
        conn.commit();
        
        System.out.println("Batch insert completed successfully");
    } catch (SQLException e) {
        conn.rollback();
        throw e;
    } finally {
        conn.setAutoCommit(true);
    }
}

Tilkoblingspooling med HikariCP

Konfigurer HikariCP med JDBC-URL-en slik at den oppretter forbindelser gjennom LivyDriver. Lag én HikariCP-instans og gjenbruk den gjennom applikasjonens levetid.

Maven-avhengighet

<dependency>
    <groupId>com.zaxxer</groupId>
    <artifactId>HikariCP</artifactId>
    <version>5.0.1</version>
</dependency>

Konfigurer HikariCP med JDBC-URL-en

Konfigurer JDBC-URL-en og driverklassen slik at HikariCP oppretter fysiske forbindelser gjennom LivyDriver. Å sette driver-klassen eksplisitt er valgfritt når JDBC-tjenesteleverandørens auto-discovery er tilgjengelig:

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;

public final class DriverConnectionPoolExample {
    public static HikariDataSource createPool(String url) {
        HikariConfig config = new HikariConfig();
        config.setDriverClassName("com.microsoft.spark.livy.jdbc.LivyDriver");
        config.setJdbcUrl(url);

        // Keep pool sizes small: each classic-mode physical connection owns a Livy session.
        config.setMaximumPoolSize(2);
        config.setMinimumIdle(0);
        config.setConnectionTimeout(900000);     // Wait up to 15 minutes to borrow a connection
        config.setInitializationFailTimeout(-1); // Skip startup validation; connect on demand
        config.setIdleTimeout(600000);           // 10 minutes
        config.setMaxLifetime(1800000);          // 30 minutes
        config.setPoolName("FabricSparkDriverPool");

        return new HikariDataSource(config);
    }

    public static void main(String[] args) throws SQLException {
        String url = "jdbc:fabricspark://api.fabric.microsoft.com;" +
                     "FabricWorkspaceID=<workspace-id>;" +
                     "FabricLakehouseID=<lakehouse-id>;" +
                     "AuthFlow=AZURE_CLI;" +            // Uses the DefaultAzureCredential chain
                     "LivySessionTimeoutSeconds=600";  // Poll up to 10 minutes for session readiness

        // Reuse this pool for the application lifetime; main closes it at process exit.
        try (HikariDataSource pool = createPool(url);
             Connection conn = pool.getConnection();
             Statement stmt = conn.createStatement();
             ResultSet rs = stmt.executeQuery("SELECT 'Pooled LivyDriver connection!' as message")) {

            if (rs.next()) {
                System.out.println(rs.getString("message"));
            }
        }
    }
}

Bruk følgende veiledning når du konfigurerer poolen:

For den komplette listen over HikariCP-konfigurasjonsalternativer, se:

• HikariConfig API-referanse
• HikariCP-konfigurasjonsalternativer

Datatypekartlegging

Driveren tilordner Spark SQL-datatyper til JDBC SQL-typer og Java-typer:

Relatert innhold

• Apache Spark Runtimes i Stoff
• Stoff Kjøretid 1.3
• Hva er Livy API for Data Engineering