Microsoft JDBC-driver til Microsoft Fabric Data Engineering

JDBC (Java Database Connectivity) er en bredt anvendt standard, der gør det muligt for klientapplikationer at forbinde til og arbejde med data fra databaser og big data-platforme.

Microsoft JDBC Driver for Fabric Data Engineering lader dig forbinde, forespørge og administrere Spark-arbejdsbelastninger i Fabric med pålideligheden og enkelheden fra JDBC-standarden. Drevet af Fabric's Livy API'er leverer sikker og fleksibel Spark SQL-forbindelse til dine Java-applikationer og BI-værktøjer. Denne integration gør det muligt at indsende og køre Spark-kode direkte uden at skulle oprette separate notebook- eller Spark-jobdefinitionselementer. Driveren er kompatibel med populære JDBC-klienter som DbVisualizer og DBeaver samt BI-værktøjer, der understøtter JDBC-forbindelse, herunder Tableau.

Vigtige funktioner

• JDBC 4.2-kompatibel: Fuld implementering af JDBC 4.2-specifikationen
• Microsoft Entra ID-autentificering: Flere autentificeringsflows, herunder interaktiv, klientoplysninger og certifikatbaseret autentificering
• HikariCP-integration: Brug HikariCP til at administrere og genbruge JDBC-forbindelser til produktionsapplikationer
• Spark SQL Native Query Support: Direkte udførelse af Spark SQL-sætninger uden oversættelse
• Omfattende understøttelse af datatyper: Understøttelse af alle Spark SQL-datatyper inklusive komplekse typer (ARRAY, MAP, STRUCT)
• Asynkron resultatmængde forudhentning: Indlæsning af baggrundsdata for forbedret ydeevne
• Circuit Breaker-mønster: Beskyttelse mod kaskaderede fejl med automatisk genprøvning
• Auto-genforbindelse: Gennemsigtig sessionsgendannelse ved forbindelsesfejl
• Avanceret Retry-logik: Genprøv med eksponentiel backoff og sessionsgenopretning for forbedret modstandsdygtighed
• Proxy-understøttelse: HTTP- og SOCKS-proxykonfiguration til virksomhedsmiljøer

Forudsætninger

Før du bruger Microsoft JDBC Driver til Fabric Data Engineering, skal du sikre dig, at du har:

• Java Development Kit (JDK): Version 11 eller højere (Java 21 anbefales)
• Fabric Access: Adgang til et Fabric-arbejdsområde
• Microsoft Entra ID legitimationsoplysninger: Passende legitimationsoplysninger til autentificering
• Workspace og Lakehouse ID'er: GUID-identifikatorer for dit Fabric workspace og lakehouse

Download og installation

Microsoft JDBC Driver for Fabric Data Engineering version 1.0.0 understøtter Java 11, 17 og 21. Vi forbedrer løbende Java-forbindelsesunderstøttelsen og anbefaler, at du arbejder med den nyeste version af Microsoft JDBC-driveren.

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

1. Download enten zip- eller tar-filen fra linkene ovenfor.
2. Udpak den downloadede fil for at få adgang til driverens JAR-filer.
3. Vælg den JAR-fil, der matcher din JRE-version:
   • 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. Tilføj den valgte JAR-fil til din applikations classpath.
5. For JDBC-klienter konfigureres JDBC-driverklassen: com.microsoft.spark.livy.jdbc.LivyDriver

Eksempel på hurtigstart

Dette eksempel demonstrerer, hvordan man forbinder til Fabric og udfører en forespørgsel ved hjælp af Microsoft JDBC Driver for Fabric Data Engineering. Før du kører denne kode, skal du sikre dig, at du har opfyldt adgangskravene og installeret 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();
        }
    }
}

Forbindelsesstrengsformat

Grundlæggende forbindelsesstreng

Microsoft JDBC Driver for Fabric Data Engineering bruger følgende forbindelsesstreng-format:

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

Forbindelsesstrengskomponenter

Eksempel på forbindelsesstrenge

Grundlæggende forbindelse (interaktiv browserbaseret autentificering)

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

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

Godkendelse

Microsoft JDBC Driver for Fabric Data Engineering understøtter flere autentificeringsmetoder via Microsoft Entra ID (tidligere Azure Active Directory). Autentificering konfigureres ved hjælp af parameteren AuthFlow i forbindelsesstrengen.

Autentificeringsflows

Interaktiv browserautentificering

Bedst til: Udvikling og interaktive applikationer

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

Parametre:

• AuthFlow=1: Specificerer interaktiv browserautentificering
• AuthTenantID (valgfrit): Microsoft Entra lejer-ID
• AuthClientID (valgfrit): Applikations-ID (klient)

Adfærd:

• Åbner et browservindue til brugerautentificering
• Legitimationsoplysninger caches til efterfølgende forbindelser, indtil det er udløbet
• Velegnet til enkeltbrugerapplikationer

Klientlegitimation eller Service Principal-autentificering

Bedst til: Automatiserede tjenester og baggrundsjobs

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

Påkrævede parametre:

• AuthFlow=3: Angiver klientlegitimationsautentificering
• AuthClientID: Application (klient) ID fra Microsoft Entra ID
• AuthClientSecret: Klienthemmelighed fra Microsoft Entra ID
• AuthTenantID: Microsoft Entra lejer-ID

Bedste praksis:

• Lagre hemmeligheder sikkert (Azure Key Vault, miljøvariabler)
• Brug managed identities, når det er muligt
• Roterer hemmeligheder regelmæssigt

Certificate-Based Autentificering

Bedst til: Virksomhedsapplikationer, der kræver certifikatbaseret autentificering

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

Påkrævede parametre:

• AuthFlow=4: Specificerer certifikatbaseret autentificering
• AuthClientID: Applikations-ID (klient)
• AuthCertificatePath: Sti til PFX/PKCS12 certifikatfil
• AuthCertificatePassword: Certifikatadgangskode
• AuthTenantID: Microsoft Entra lejer-ID

Adgangstoktuifikation

Bedst til: Brugerdefinerede autentificeringsscenarier

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

Autentificeringscache

Driveren cacher automatisk autentificeringstokens for at forbedre ydeevnen:

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

Konfigurationsparametre

Påkrævede parametre

Disse parametre skal være til stede i hver forbindelsesstreng:

Valgfrie parametre

API-versionskonfiguration

Miljøkonfiguration

Spark-konfiguration

Konfiguration af sessionsressourcer

Konfigurer Spark-sessionsressourcer for optimal ydeevne:

Eksempel:

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

Brugerdefinerede Spark Session-egenskaber

Enhver parameter med præfikset spark. anvendes automatisk på Spark-sessionen:

Eksempler på gnistkonfigurationer:

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

Native Execution Engine (NEE):

spark.nee.enabled=true

Fuldstændigt 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-klientforbindelsesindstillinger

Konfigurer driverens HTTP-transportforbindelser for optimal netværksydelse. Disse indstillinger konfigurerer eller administrerer ikke JDBC-forbindelsespooling:

Eksempel:

HttpMaxTotalConnections=200;HttpMaxConnectionsPerRoute=100;HttpConnectionTimeoutInSeconds=60

Proxy-konfiguration

Konfigurer HTTP- og SOCKS-proxyindstillinger til virksomhedsmiljøer:

HTTP-proxy eksempel:

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

Konfiguration af logning

Eksempel:

LogLevel=DEBUG

Standardlogplacering:

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

Brugerdefineret logkonfiguration: Brug en custom log4j2.xml eller logback.xml fil på din classpath.

Anvendelseseksempler

Grundlæggende forbindelse

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

Udførelse af forespørgsler

Simpel forespørgsel

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

Forespørgsel 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);
        }
    }
}

Forespørgsel med grænse

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

Arbejde med resultatmængder

Navigering af resultatmængder

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 af store resultatsæt

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
}

Brug af forberedte udsagn

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

Batchoperationer

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

Forbindelsespooling med HikariCP

Konfigurér HikariCP med JDBC-URL'en, så den opretter forbindelser gennem LivyDriver. Opret én HikariCP-instans og genbrug den i applikationens levetid.

Maven-afhængighed

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

Konfigurér HikariCP med JDBC-URL'en

Konfigurer JDBC URL'en og driverklassen, så HikariCP opretter fysiske forbindelser gennem LivyDriver. At sætte driverklassen eksplicit er valgfrit, når JDBC-tjenesteudbyderens auto-discovery er tilgængelig:

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

Brug følgende vejledning, når du konfigurerer poolen:

For den komplette liste over HikariCP-konfigurationsmuligheder, se:

• HikariConfig API-reference
• HikariCP-konfigurationsmuligheder

Datatypekortlægning

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

Relateret indhold

• Apache Spark Runtimes i Fabric
• Stof Driftstid 1.3
• Hvad er Livy API til Data Engineering