Verbinden einer benutzerdefinierten Databricks-App mit Lakebase

In diesem Lernprogramm erfahren Sie, wie Sie eine Databricks-App mit Lakebase Autoscaling mit automatischer Rotation von Anmeldeinformationen verbinden. Die App generiert neue Datenbankanmeldeinformationen aus Databricks, bevor sie ablaufen. Im Beispiel wird Flask verwendet, aber das Authentifizierungsmuster gilt für jedes Framework.

Funktionsweise

Databricks Apps authentifizieren sich bei Lakebase mithilfe von OAuth-Token, die nach einer Stunde ablaufen. Um dies zu behandeln, erstellen Sie eine Postgres-Rolle für den Dienstprinzipal Ihrer App und konfigurieren dann Ihre App so, dass automatisch frische Token generiert werden, wenn eine Verbindung mit der Datenbank hergestellt werden muss. Die App verwendet einen Verbindungspool. Der Pool erstellt nach Bedarf neue Verbindungen mit neuen Token, sodass Ihre App niemals abgelaufene Anmeldeinformationen verwendet.

Wenn Sie die App für Azure Databricks bereitstellen, wird sie als Dienstprinzipal ausgeführt und generiert Token für diese Identität. Wenn Sie lokal testen, wird die App als Ihr Azure Databricks Benutzerkonto ausgeführt und generiert Token für Sie. Beide verwenden denselben Tokendrehungscode. Nur der Authentifizierungskontext ändert sich.

Vorbemerkungen

Um die Schritte dieses Tutorials abzuschließen, benötigen Sie Folgendes:

• Zugriff auf einen Azure Databricks Arbeitsbereich mit aktivierter Lakebase Postgres-Autoscaling. Wenden Sie sich an Ihren Arbeitsbereichsadministrator, wenn Lakebase nicht im App-Switcher angezeigt wird.
• Berechtigung zum Erstellen von Apps
• Grundlegende Kenntnisse mit Python und SQL
• Databricks CLI installiert für die lokale Entwicklung
• Python 3.9 oder höher lokal installiert

Schritt 1: Erstellen Ihrer App und Datenbank

Erstellen Sie zunächst eine Databricks-App und ein Lakebase-Projekt. Die App erhält automatisch eine Dienstprinzipalidentität, die Sie für die Datenbankauthentifizierung verwenden.

Erstellen der App

Erstellen Sie eine neue Databricks-App mit der Vorlage "Flask Hello world ". Siehe Erstellen einer Databricks-App aus einer Vorlage.

Nachdem Sie die App erstellt haben, wechseln Sie zur Registerkarte " Umgebung " der App, und notieren Sie sich den DATABRICKS_CLIENT_ID Wert (UUID-Format wie 6b215d2b-f099-4bdb-900a-60837201ecec). Dies wird zum Postgres-Benutzernamen Ihrer App für die OAuth-Authentifizierung.

Erstellen der Datenbank

Erstellen Sie ein neues Lakebase Autoscaling-Projekt, um Ihre Datenbank bereitzustellen. Klicken Sie auf das Wählen Sie Lakebase Postgres aus und erstellen Sie dann ein neues Projekt mit einem Namen (z. B. my-app-db) und der Postgres-Version (übernehmen Sie die Standardversion Postgres 17). Vollständige Setupdetails finden Sie unter Erstellen eines Projekts.

Warten Sie, bis die Berechnung aktiv wird (ca. 1 Minute), bevor Sie fortfahren.

Schritt 2: Konfigurieren der Datenbankauthentifizierung und des Schemas

Erstellen Sie eine Postgres-Rolle für den Dienstprinzipal Ihrer App mit OAuth-Authentifizierung, und erstellen Sie dann eine Beispieltabelle mit Daten für ihre App, die angezeigt werden sollen.

Einrichten der OAuth-Authentifizierung

Öffnen Sie in Ihrem Lakebase-Projekt den SQL-Editor, und führen Sie diese Befehle aus. Die databricks_auth Erweiterung aktiviert die OAuth-Authentifizierung. Damit akzeptieren Ihre Postgres-Rollen Databricks-Token anstelle herkömmlicher Kennwörter:

-- Enable the Databricks authentication extension
CREATE EXTENSION IF NOT EXISTS databricks_auth;

-- Create a Postgres role for your app's service principal
-- Replace the UUID below with your DATABRICKS_CLIENT_ID from Step 1
SELECT databricks_create_role('<DATABRICKS_CLIENT_ID>', 'service_principal');

-- Grant necessary permissions (use the same DATABRICKS_CLIENT_ID)
GRANT CONNECT ON DATABASE databricks_postgres TO "<DATABRICKS_CLIENT_ID>";
GRANT CREATE, USAGE ON SCHEMA public TO "<DATABRICKS_CLIENT_ID>";

Ersetzen Sie <DATABRICKS_CLIENT_ID> durch den DATABRICKS_CLIENT_ID Wert Ihrer App. Der Dienstprinzipal kann sich jetzt mithilfe von OAuth-Token authentifizieren, die von Azure Databricks automatisch verwaltet werden. Ausführliche Informationen finden Sie unter Create an OAuth role for a Azure Databricks identity.

Datenbankschema erstellen

Erstellen Sie eine Beispieltabelle mit expliziten Berechtigungen für Ihren Dienstprinzipal (Dienstprinzipale erben keine Standardschemaberechtigungen):

-- Create a sample table
CREATE TABLE notes (
    id SERIAL PRIMARY KEY,
    content TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Grant permissions to your app's service principal (use your DATABRICKS_CLIENT_ID)
GRANT SELECT, INSERT, UPDATE, DELETE ON TABLE notes TO "<DATABRICKS_CLIENT_ID>";

-- Insert sample data
INSERT INTO notes (content) VALUES
   ('Welcome to Lakebase Autoscaling!'),
   ('This app connects to Postgres'),
   ('Data fetched from your database');

Ersetzen Sie den <DATABRICKS_CLIENT_ID> Wert durch ihren DATABRICKS_CLIENT_ID Wert.

Schritt 3: Erstellen und Konfigurieren Ihrer Anwendung

Laden Sie Ihre App-Dateien herunter, konfigurieren Sie die Datenbankverbindung mit der automatischen OAuth-Tokenrotation, und testen Sie lokal, bevor Sie sie bereitstellen.

Herunterladen und Konfigurieren von App-Dateien

Laden Sie Ihre App-Dateien aus dem Arbeitsbereich herunter, indem Sie den Exportbefehl aus dem Abschnitt " Dateien synchronisieren " der App kopieren:

databricks workspace export-dir /Workspace/Users/<your-email>/databricks_apps/<app-folder>/flask-hello-world-app .

Bearbeiten Sie app.yaml, um Datenbankverbindungsdetails hinzuzufügen. ** Rufen Sie Ihre Verbindungswerte aus dem Lakebase-Connect-Dialogfeld ab, indem Sie nur Parameter auswählen:

command: ['flask', '--app', 'app.py', 'run', '--host', '0.0.0.0', '--port', '8000']

env:
  - name: PGHOST
    value: '<your-endpoint-hostname>'
  - name: PGDATABASE
    value: 'databricks_postgres'
  - name: PGUSER
    value: '<DATABRICKS_CLIENT_ID>'
  - name: PGPORT
    value: '5432'
  - name: PGSSLMODE
    value: 'require'
  - name: ENDPOINT_NAME
    value: 'projects/<project-id>/branches/<branch-id>/endpoints/<endpoint-id>'

Ersetzen Sie die Platzhalter:

• <your-endpoint-hostname>: Kopieren Sie den PGHOST-Wert aus dem Connect-Modul (z. B. ep-xyz.database.us-west-2.dev.databricks.com).
• <DATABRICKS_CLIENT_ID>: Verwenden Sie DATABRICKS_CLIENT_ID aus Schritt 1
• projects/<project-id>/branches/<branch-id>/endpoints/<endpoint-id>: Wechseln Sie in der Lakebase-App zur Registerkarte Computes Ihres Zweigs, klicken Sie auf Get ID für Ihren Compute, und wählen Sie Ressourcennamen kopieren aus.

Implementieren der OAuth-Tokenrotation und Datenbankabfrage

Ersetzen Sie app.py durch diesen Code, der eine automatische OAuth-Tokenrotation und eine Datenbankabfrage hinzufügt, die die Notizen aus Schritt 2 abruft:

import os
from databricks.sdk import WorkspaceClient
import psycopg
from psycopg_pool import ConnectionPool
from flask import Flask

app = Flask(__name__)

# Initialize Databricks client for token generation
w = WorkspaceClient()

# Custom connection class that generates fresh OAuth tokens
class OAuthConnection(psycopg.Connection):
    @classmethod
    def connect(cls, conninfo='', **kwargs):
        # Generate a fresh OAuth token for each connection (tokens are workspace-scoped)
        endpoint_name = os.environ["ENDPOINT_NAME"]
        credential = w.postgres.generate_database_credential(endpoint=endpoint_name)
        kwargs['password'] = credential.token
        return super().connect(conninfo, **kwargs)

# Configure connection parameters
username = os.environ["PGUSER"]
host = os.environ["PGHOST"]
port = os.environ.get("PGPORT", "5432")
database = os.environ["PGDATABASE"]
sslmode = os.environ.get("PGSSLMODE", "require")

# Create connection pool with automatic token rotation
pool = ConnectionPool(
    conninfo=f"dbname={database} user={username} host={host} port={port} sslmode={sslmode}",
    connection_class=OAuthConnection,
    min_size=1,
    max_size=10,
    open=True
)

@app.route('/')
def hello_world():
    # Use connection from pool (automatically gets fresh token)
    with pool.connection() as conn:
        with conn.cursor() as cur:
            cur.execute("SELECT content, created_at FROM notes ORDER BY created_at DESC LIMIT 5")
            notes = cur.fetchall()

    # Display results
    notes_html = "<ul>" + "".join([f"<li>{note[0]} - {note[1]}</li>" for note in notes]) + "</ul>"
    return f'<h1>Hello from Lakebase!</h1><h2>Recent Notes:</h2>{notes_html}'

if __name__ == '__main__':
    app.run(host="0.0.0.0", port=8000)

Die drei wichtigsten Komponenten sind:

• WorkspaceClient: generiert neue Anmeldeinformationen mit dem SDK.
• OAuthConnection: eine benutzerdefinierte Verbindungsklasse, die eine neue Anmeldeinformation in jede Verbindung eingibt.
• ConnectionPool: verwaltet Verbindungen und ruft die benutzerdefinierte Klasse nach Bedarf auf.

Weitere Informationen zu Strategien zur Drehung von Anmeldeinformationen und zur Fehlerbehandlung finden Sie unter Tokendrehungsbeispiele.

Aktualisieren Sie requirements.txt, um die erforderlichen Pakete einzuschließen.

flask
psycopg[binary,pool]
databricks-sdk>=0.81.0

Version 0.81.0 oder höher enthält die generate_database_credential() Methode.

Lokales Testen

Testen Sie Ihre App lokal, um zu überprüfen, ob die Datenbankverbindung funktioniert, bevor Sie sie bereitstellen. Beim lokalen Testen wird die App als Ihr Azure Databricks-Benutzerkonto (nicht der Dienstprinzipal) ausgeführt. Ändern Sie daher PGUSER zu Ihrer E-Mail-Adresse in den folgenden Umgebungsvariablen.

Authentifizieren Sie sich bei Ihren Arbeitsbereichs- und Exportumgebungsvariablen:

databricks auth login

export PGHOST="<your-endpoint-hostname>"
export PGDATABASE="databricks_postgres"
export PGUSER="your.email@company.com"  # Use YOUR email for local testing, not the service principal
export PGPORT="5432"
export PGSSLMODE="require"
export ENDPOINT_NAME="<your-endpoint-name>"

Kopieren Sie die Werte aus Ihrem app.yaml, ersetzen Sie jedoch den Wert PGUSER (Dienstprinzipalclient-ID) durch Ihre Azure Databricks E-Mail-Adresse.

Installieren Sie Abhängigkeiten, und führen Sie die App aus:

pip3 install --upgrade -r requirements.txt
python3 app.py

Öffnen Sie http://localhost:8000 in Ihrem Browser. Sie sollten "Hallo von Lakebase!" zusammen mit Ihren drei Beispielnotizen sehen. Der Verbindungspool generiert automatisch neue OAuth-Token beim Erstellen neuer Verbindungen. Weitere Informationen finden Sie unter OAuth-Tokenauthentifizierung.

Schritt 4: Bereitstellen und Überprüfen

Synchronisieren Sie nach dem lokalen Testen Ihre Änderungen mit einem Arbeitsbereichsordner, und stellen Sie sie von diesem Speicherort aus bereit:

# Upload files to workspace
databricks sync . /Workspace/Users/<your-email>/my-lakebase-app

# Deploy from the uploaded location
databricks apps deploy <app-name> --source-code-path /Workspace/Users/<your-email>/my-lakebase-app

Ersetzen Sie <your-email> durch Ihre Azure Databricks E-Mail-Adresse und <app-name> durch Ihren App-Namen. Das --source-code-path-Flag weist die Bereitstellung an, hochgeladene Dateien anstelle des voreingestellten Speicherorts der App zu verwenden.

Warten Sie, bis die Bereitstellung abgeschlossen ist (2-3 Minuten), und greifen Sie dann auf Ihre App unter der bereitgestellten URL zu. Sie sollten "Hello from Lakebase!" mit Ihren Beispielnotizen sehen.

Siehe auch

• Beispiele für Token-Rotation
• Databricks-Apps