Microsoft JDBC-drivrutin för Microsoft Fabric Data Engineering

JDBC (Java Database Connectivity) är en allmänt antagen standard som gör det möjligt för klientprogram att ansluta till och arbeta med data från databaser och stordataplattformar.

Microsoft JDBC Driver för Fabric Data Engineering låter dig koppla samman, fråga och hantera Spark-arbetsbelastningar i Fabric med samma tillförlitlighet och enkelhet som JDBC-standarden. Byggd på Fabric:s Livy-API:er erbjuder drivrutinen säker och flexibel Spark SQL-anslutning till dina Java-applikationer och BI-verktyg. Denna integration gör det möjligt att skicka in och köra Spark-kod direkt utan att behöva skapa separata notebook- eller Spark-jobbdefinitionsobjekt. Drivrutinen är kompatibel med populära JDBC-klienter som DbVisualizer och DBeaver, samt BI-verktyg som stöder JDBC-anslutning, inklusive Tableau.

Huvudfunktioner    

• JDBC 4.2-kompatibel: Fullständig implementering av JDBC 4.2-specifikation
• Microsoft Entra-ID-autentisering: Flera autentiseringsflöden, inklusive interaktiva klientautentiseringsuppgifter och certifikatbaserad autentisering
• HikariCP-integration: Använd HikariCP för att hantera och återanvända JDBC-anslutningar för produktionsapplikationer
• Stöd för Spark SQL Native Query: Direkt körning av Spark SQL-instruktioner utan översättning
• Omfattande stöd för datatyper: Stöd för alla Spark SQL-datatyper, inklusive komplexa typer (ARRAY, MAP, STRUCT)
• Asynkron förinläsning av resultatuppsättning: Inläsning av bakgrundsdata för bättre prestanda
• Kretsbrytarmönster: Skydd mot sammanhängande fel med automatiskt återförsök
• Automatisk återanslutning: Transparent sessionsåterställning vid anslutningsfel
• Avancerad logik för återförsök: Försök igen med exponentiell backoff och sessionsåterställning för bättre motståndskraft
• Proxystöd: HTTP- och SOCKS-proxykonfiguration för företagsmiljöer

Förutsättningar

Innan du använder Microsoft JDBC Driver för Fabric Data Engineering, se till att du har:

• Java Development Kit (JDK): Version 11 eller senare (Java 21 rekommenderas)
• Fabric Access: Tillgång till en arbetsyta för Fabric
• Microsoft Entra ID-autentiseringsuppgifter: Lämpliga uppgifter för autentisering
• Workspace- och Lakehouse-ID: GUID-identifierare för din Fabric-arbetsyta och lakehouse

Ladda ned och installera

Microsoft JDBC Driver for Fabric Data Engineering version 1.0.0 stöder Java 11, 17 och 21. Vi förbättrar kontinuerligt Java-anslutningssupporten och rekommenderar att du arbetar med den senaste versionen av Microsoft JDBC-drivrutinen.

• Ladda ner Microsoft JDBC Driver för Fabric Data Engineering (zip)
• Ladda ner Microsoft JDBC Driver för Fabric Data Engineering (tar)

1. Ladda ned zip- eller tar-filen från länkarna ovan.
2. Extrahera den nedladdade filen för att få åtkomst till drivrutins-JAR-filerna.
3. Välj DEN JAR-fil som matchar din JRE-version:
   • För Java 11: ms-sparksql-jdbc-1.0.1.jre11.jar
   • För Java 17: ms-sparksql-jdbc-1.0.1.jre17.jar
   • För Java 21: ms-sparksql-jdbc-1.0.1.jre21.jar
4. Lägg till den valda JAR-filen i programmets klassökväg.
5. För JDBC-klienter konfigurerar du JDBC-drivrutinsklassen: com.microsoft.spark.livy.jdbc.LivyDriver

Snabbstartsexempel

Detta exempel visar hur man ansluter till Fabric och kör en fråga med Microsoft JDBC Driver for Fabric Data Engineering. Innan du kör den här koden kontrollerar du att du har slutfört förutsättningarna och installerat drivrutinen.

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

Format för anslutningssträng

Grundläggande anslutningssträng

Microsoft JDBC Driver for Fabric Data Engineering använder följande reťazec pripojenia-format:

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

Komponenter för anslutningssträngar

Exempel på anslutningssträngar

Grundläggande anslutning (interaktiv webbläsarbaserad autentisering)

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

Med Spark-resurskonfiguration

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 Egenskaper för Spark-sessioner

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

Authentication

Microsoft JDBC Driver for Fabric Data Engineering stöder flera autentiseringsmetoder via Microsoft Entra ID (tidigare Azure Active Directory). Autentisering konfigureras med hjälp av parametern AuthFlow i anslutningssträngen.

Autentiseringsflöden

Interaktiv webbläsarautentisering

Bäst för: Utveckling och interaktiva program

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: Anger interaktiv webbläsarautentisering
• AuthTenantID (valfritt): Microsoft Entra tenant-ID
• AuthClientID (valfritt): Program-ID (klient)-ID

Uppförande:

• Öppnar ett webbläsarfönster för användarautentisering
• Autentiseringsuppgifter cachelagras för efterföljande anslutningar tills de har upphört att gälla
• Lämplig för enanvändarprogram

Klientautentiseringsuppgifter eller tjänstehuvudkontoautentisering

Bäst för: Automatiserade tjänster och bakgrundsjobb

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

Obligatoriska parametrar:

• AuthFlow=3: Anger autentiseringsuppgifter för klienten
• AuthClientID: Program-ID (klient) från Microsoft Entra-ID
• AuthClientSecret: Klienthemlighet från Microsoft Entra-ID
• AuthTenantID: Microsoft Entra klientorganisations-ID

Metodtips:

• Lagra hemligheter på ett säkert sätt (Azure Key Vault, miljövariabler)
• Använda hanterade identiteter när det är möjligt
• Rotera hemligheter regelbundet

Certifikatbaserad autentisering

Bäst för: Företagsprogram som kräver certifikatbaserad 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);

Obligatoriska parametrar:

• AuthFlow=4: Anger certifikatbaserad autentisering
• AuthClientID: Program-ID (klient)-ID
• AuthCertificatePath: Sökväg till PFX/PKCS12-certifikatfilen
• AuthCertificatePassword: Certifikatlösenord
• AuthTenantID: Microsoft Entra klientorganisations-ID

Åtkomsttokenautentisering

Bäst för: Scenarier för anpassad autentisering

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

Cachelagring av autentisering

Drivrutinen cachelagrar automatiskt autentiseringstoken för att förbättra prestandan:

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

Konfigurationsparametrar

Obligatoriska parametrar

Dessa parametrar måste finnas i varje anslutningssträng:

Valfria parametrar

Konfiguration av API-version

Miljökonfiguration

Spark-konfiguration

Sessionsresurskonfiguration

Konfigurera Spark-sessionsresurser för optimala prestanda:

Example:

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

Egenskaper för anpassad Spark-session

Alla parametrar med prefixet spark. tillämpas automatiskt på Spark-sessionen:

Exempel på Spark-konfigurationer:

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

Inbyggd exekveringsmotor (NEE):

spark.nee.enabled=true

Fullständigt exempel:

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-klientanslutningsinställningar

Konfigurera drivrutinens HTTP-transportanslutningar för optimal nätverksprestanda. Dessa inställningar konfigurerar eller hanterar inte JDBC:s anslutningspoolning:

Example:

HttpMaxTotalConnections=200;HttpMaxConnectionsPerRoute=100;HttpConnectionTimeoutInSeconds=60

Proxykonfiguration

Konfigurera HTTP- och SOCKS-proxyinställningar för företagsmiljöer:

HTTP-proxyexempel:

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

EXEMPEL på SOCKS-proxy:

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

Loggningskonfiguration

Example:

LogLevel=DEBUG

Standardloggplats:

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

Anpassad loggkonfiguration: Använd en anpassad log4j2.xml fil eller logback.xml fil på din klasssökväg.

Användningsexempel

Grundläggande anslutning

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öra frågor

Enkel fråga

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

Fråga 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);
        }
    }
}

Fråga med gräns

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

Arbeta med resultatuppsättningar

Navigera i resultatuppsättningar

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

Bearbeta stora resultatuppsättningar

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
}

Använda förberedda satser

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

Batch-åtgärder

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

Anslutningspoolning med HikariCP

Konfigurera HikariCP med JDBC-URL:en så att den skapar anslutningar genom LivyDriver. Skapa en HikariCP-instans och återanvänd den under applikationens livslängd.

Maven-beroende

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

Konfigurera HikariCP med JDBC-URL:en

Konfigurera JDBC-URL:en och drivrutinsklassen så att HikariCP skapar fysiska anslutningar genom LivyDriver. Att uttryckligen ange drivrutinsklassen är valfritt när automatisk identifiering av JDBC-tjänstleverantörer stöds:

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

Använd följande vägledning när du konfigurerar poolen:

För den kompletta listan över HikariCP-konfigurationsalternativ, se:

• HikariConfig API-referens
• HikariCP-konfigurationsalternativ

Datatypsmappning

Drivrutinen mappar Spark SQL-datatyper till JDBC SQL-typer och Java-typer:

Relaterat innehåll

• Apache Spark Runtimes på plattformen
• Fabric-körmiljö 1.3
• Vad är Livy API för datateknik