Microsoft JDBC-stuurprogramma voor Microsoft Fabric Data Engineering

JDBC (Java Database Connectivity) is een veelgebruikte standaard waarmee clienttoepassingen verbinding kunnen maken met en kunnen werken met gegevens uit databases en big data-platforms.

De Microsoft JDBC Driver for Fabric Data Engineering stelt je in staat om Spark-workloads in Fabric te verbinden, te bevragen en te beheren met de betrouwbaarheid en eenvoud van de JDBC-standaard. Gebouwd op Fabric's Livy-API's biedt de driver veilige en flexibele Spark SQL-connectiviteit naar je Java-applicaties en BI-tools. Deze integratie stelt je in staat om Spark-code direct in te dienen en uit te voeren zonder aparte notebook- of Spark-taakdefinitie-items te hoeven maken. Het stuurprogramma is compatibel met populaire JDBC-clients, zoals DbVisualizer en DBeaver, evenals BI-hulpprogramma's die ondersteuning bieden voor JDBC-connectiviteit, waaronder Tableau.

Belangrijke functies

• JDBC 4.2 Compatibel: volledige implementatie van JDBC 4.2-specificatie
• Microsoft Entra ID-verificatie: meerdere verificatiestromen, waaronder interactieve, clientreferenties en verificatie op basis van certificaten
• HikariCP-integratie: Gebruik HikariCP om JDBC-verbindingen te beheren en opnieuw te gebruiken voor productieapplicaties
• Ondersteuning voor systeemeigen Spark SQL-query's: directe uitvoering van Spark SQL-instructies zonder vertaling
• Uitgebreide ondersteuning voor gegevenstypen: ondersteuning voor alle Spark SQL-gegevenstypen, waaronder complexe typen (ARRAY, MAP, STRUCT)
• Asynchrone resultatenset prefetching: achtergrondgegevens laden voor verbeterde prestaties
• Circuit Breaker-patroon: beveiliging tegen cascaderende fouten met automatische pogingen
• Automatisch opnieuw verbinding maken: Transparant sessieherstel bij verbindingsfouten
• Geavanceerde logica voor opnieuw proberen: Opnieuw proberen met exponentieel uitstel en sessieherstel voor verbeterde tolerantie
• Proxyondersteuning: HTTP- en SOCKS-proxyconfiguratie voor bedrijfsomgevingen

Vereiste voorwaarden

Voordat je de Microsoft JDBC Driver for Fabric Data Engineering gebruikt, zorg ervoor dat je:

• Java Development Kit (JDK): versie 11 of hoger (Java 21 aanbevolen)
• Fabric Access: Toegang tot een Fabric werkruimte
• Microsoft Entra ID referenties: juiste referenties voor verificatie
• Werkruimte- en Lakehouse-id's: GUID-id's voor uw Fabric-werkruimte en Lakehouse

Downloaden en installeren

Microsoft JDBC Driver for Fabric Data Engineering versie 1.0.0 ondersteunt Java 11, 17 en 21. We verbeteren voortdurend ondersteuning voor Java-connectiviteit en raden u aan met de nieuwste versie van het Microsoft JDBC-stuurprogramma te werken.

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

1. Download het zip- of tar-bestand via de bovenstaande koppelingen.
2. Pak het gedownloade bestand uit om toegang te krijgen tot de JAR-bestanden van het stuurprogramma.
3. Selecteer het JAR-bestand dat overeenkomt met uw JRE-versie:
   • Voor Java 11: ms-sparksql-jdbc-1.0.1.jre11.jar
   • Voor Java 17: ms-sparksql-jdbc-1.0.1.jre17.jar
   • Voor Java 21: ms-sparksql-jdbc-1.0.1.jre21.jar
4. Voeg het geselecteerde JAR-bestand toe aan het klassepad van uw toepassing.
5. Voor JDBC-clients configureert u de JDBC-stuurprogrammaklasse: com.microsoft.spark.livy.jdbc.LivyDriver

Snelstartvoorbeeld

Dit voorbeeld laat zien hoe je verbinding maakt met Fabric en een query uitvoert met de Microsoft JDBC Driver for Fabric Data Engineering. Voordat u deze code uitvoert, moet u ervoor zorgen dat u de vereisten hebt voltooid en het stuurprogramma hebt geïnstalleerd.

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

Formaat van verbindingsstring

Basisverbindingsreeks

De Microsoft JDBC Driver for Fabric Data Engineering gebruikt het volgende verbindingsreeks-formaat:

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

Componenten van de connection string

Voorbeeld van verbindingsreeksen

Basisverbinding (verificatie op basis van interactieve browser)

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

Met Spark-resourceconfiguratie

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

Met eigenschappen van Spark-sessie

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

Authenticatie

De Microsoft JDBC Driver for Fabric Data Engineering ondersteunt meerdere authenticatiemethoden via Microsoft Entra ID (voorheen Azure Active Directory). Verificatie wordt geconfigureerd met behulp van de AuthFlow parameter in de verbindingsreeks.

Verificatiestromen

Interactieve browserverificatie

Geschikt voor: Ontwikkeling en interactieve toepassingen

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

Parameters:

• AuthFlow=1: Specificeert interactieve browserverificatie
• AuthTenantID (optioneel): Microsoft Entra tenant-ID
• AuthClientID (optioneel): Toepassing (client) ID

Gedrag:

• Hiermee opent u een browservenster voor gebruikersverificatie
• Referenties worden opgeslagen in de cache voor volgende verbindingen totdat deze verlopen is
• Geschikt voor toepassingen met één gebruiker

Client- of Servicegebruikerauthenticatie

Geschikt voor: Geautomatiseerde services en achtergrondtaken

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

Vereiste parameters:

• AuthFlow=3: Hiermee specificeert u client-credentials-authenticatie
• AuthClientID: Toepassings-ID (client) van Microsoft Entra ID
• AuthClientSecret: Clientgeheim van Microsoft Entra-id
• AuthTenantID: Microsoft Entra-tenant-id

Best practices:

• Geheimen veilig opslaan (Azure Key Vault, omgevingsvariabelen)
• Beheerde identiteiten gebruiken indien mogelijk
• Geheimen regelmatig roteren

Certificate-Based Authenticatie

Geschikt voor: Bedrijfstoepassingen waarvoor verificatie op basis van certificaten is vereist

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

Vereiste parameters:

• AuthFlow=4: Hiermee geeft u verificatie op basis van certificaten op
• AuthClientID: Applicatie-ID (client)
• AuthCertificatePath: Pad naar PFX-/PKCS12-certificaatbestand
• AuthCertificatePassword: Certificaatwachtwoord
• AuthTenantID: Microsoft Entra-tenant-id

Verificatie van toegangstokens

Geschikt voor: Scenario's voor aangepaste verificatie

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

Verificatiecaching

Het stuurprogramma slaat verificatietokens automatisch in de cache op om de prestaties te verbeteren:

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

Configuratieparameters

Vereiste parameters

Deze parameters moeten aanwezig zijn in elke verbindingsreeks:

Optionele parameters

API-versieconfiguratie

Omgevingsconfiguratie

Spark-configuratie

Configuratie van sessieresource

Spark-sessiebronnen configureren voor optimale prestaties:

Example:

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

Eigenschappen van aangepaste Spark-sessie

Elke parameter met het voorvoegsel spark. wordt automatisch toegepast op de Spark-sessie:

Voorbeeld van Spark-configuraties:

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

Systeemeigen uitvoeringsengine (NEE):

spark.nee.enabled=true

Volledig voorbeeld:

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-clientverbindingsinstellingen

Configureer de HTTP-transportverbindingen van de driver voor optimale netwerkprestaties. Deze instellingen configureren of beheren de JDBC-verbindingspooling niet:

Example:

HttpMaxTotalConnections=200;HttpMaxConnectionsPerRoute=100;HttpConnectionTimeoutInSeconds=60

Proxyconfiguratie

HTTP- en SOCKS-proxyinstellingen configureren voor bedrijfsomgevingen:

Voorbeeld van HTTP-proxy:

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

Voorbeeld van SOCKS-proxy:

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

Configuratie van logboekregistratie

Example:

LogLevel=DEBUG

Standaardlocatie van logboek:

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

Aangepaste logboekconfiguratie: Gebruik een aangepast log4j2.xml bestand of logback.xml bestand in uw klaspad.

Gebruiksvoorbeelden

Basisverbinding

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

Queries uitvoeren

Eenvoudige query

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

Query met 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);
        }
    }
}

Query met limiet

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

Werken met resultatensets

Navigeren in resultatensets

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

Grote resultatensets verwerken

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
}

Voorbereide instructies gebruiken

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

Batchverwerkingen

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

Verbindingspooling met HikariCP

Configureer HikariCP met de JDBC-URL zodat het verbindingen maakt via LivyDriver. Maak één HikariCP-instantie aan en hergebruik deze gedurende de levensduur van de applicatie.

Maven-afhankelijkheid

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

Configureer HikariCP met de JDBC-URL

Configureer de JDBC-URL en driverklasse zodat HikariCP fysieke verbindingen maakt via LivyDriver. Het expliciet instellen van de driverklasse is optioneel wanneer automatische ontdekking van JDBC-serviceproviders beschikbaar is:

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

Gebruik de volgende richtlijnen bij het configureren van de pool:

Voor de volledige lijst van HikariCP-configuratieopties, zie:

• HikariConfig API-referentie
• HikariCP-configuratieopties

Gegevenstypemapping

Het stuurprogramma wijst Spark SQL-gegevenstypen toe aan JDBC SQL-typen en Java-typen:

Verwante inhoud

• Apache Spark Runtimes in Fabric
• Fabric Runtime 1.3
• Wat is de Livy-API voor Data Engineering?