Esercitazione: Collegare un'app Databricks a Lakebase Autoscaling

Importante

La scalabilità automatica di Lakebase si trova in Beta nelle aree seguenti: eastus2, westeurope, westus.

Lakebase Autoscaling è la versione più recente di Lakebase con calcolo autoscalante, riduzione a zero, ramificazione e ripristino istantaneo. Per il confronto delle funzionalità con Lakebase Provisioned, vedere scegliere tra le versioni.

Questa esercitazione illustra come connettere un'app Databricks alla scalabilità automatica di Lakebase con rotazione automatica delle credenziali. L'app genera credenziali di database nuove da Databricks prima della scadenza. L'esempio usa Flask, ma il modello di autenticazione si applica a qualsiasi framework.

Come funziona

Databricks Apps esegue l'autenticazione a Lakebase usando token OAuth che scadono dopo un'ora. Per gestirlo, creare un ruolo Postgres per l'entità servizio dell'app, quindi configurare l'app per generare automaticamente token aggiornati ogni volta che deve connettersi al database. Ciò avviene tramite un modello di pool di connessioni: il pool crea nuove connessioni con token aggiornati in base alle esigenze, quindi l'app non usa mai le credenziali scadute.

Quando si implementa l'app in Databricks, viene eseguita come principal del servizio e genera token per tale identità. Quando si esegue il test in locale, l'app viene eseguita come account utente di Databricks e genera automaticamente i token. Entrambi usano lo stesso codice di rotazione del token: solo il contesto di autenticazione cambia.

Prima di iniziare

Per completare questa esercitazione, è necessario:

Accesso a un'area di lavoro di Databricks con la scalabilità automatica di Lakebase Postgres abilitata (contattare l'amministratore dell'area di lavoro se Lakebase non viene visualizzato nel commutatore dell'app)
Autorizzazione per la creazione di app Databricks
Conoscenza di base di Python e SQL
CLI di Databricks installata per lo sviluppo locale
Python 3.9 o versione successiva installata in locale

Passaggio 1: Creare l'app e il database

Creare prima di tutto un'app Databricks e un progetto Lakebase. L'app ottiene automaticamente un'identità dell'entità servizio che verrà usata per l'autenticazione del database.

Creare l'app

Creare una nuova app Databricks usando il modello Flask Hello World (+ Nuova > app nell'area di lavoro). Per istruzioni dettagliate, vedere Creare un'app Databricks.

Dopo l'installazione, passare alla scheda Ambiente dell'app e prendere nota del DATABRICKS_CLIENT_ID valore (formato UUID come 6b215d2b-f099-4bdb-900a-60837201ecec). Questo diventa il nome utente Postgres dell'app per l'autenticazione OAuth.

Annotazioni

Non distribuire ancora l'app. Prima di tutto si configurerà la connessione al database.

Creare il database

Creare un nuovo progetto di scalabilità automatica lakebase per ospitare il database. Fare clic sull'icona App. Le app nell'angolo in alto a destra selezionare Lakebase, quindi creare un nuovo progetto con il nome desiderato ( ad esempio my-app-db) e la versione di Postgres (accettare il valore predefinito postgres 17). Per informazioni dettagliate sull'installazione, vedere Creare un progetto.

Attendere che il calcolo diventi attivo (circa 1 minuto) prima di procedere.

Passaggio 2: Configurare l'autenticazione e lo schema del database

Creare un ruolo Postgres per l'entità servizio dell'app con l'autenticazione OAuth, quindi creare una tabella di esempio con i dati che verranno visualizzati dall'app.

Configurare l'autenticazione OAuth

Nel progetto Lakebase aprire l'editor SQL ed eseguire questi comandi. L'estensione databricks_auth abilita l'autenticazione OAuth, consentendo ai ruoli postgres di accettare i token di Databricks anziché le password tradizionali:

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

Sostituire <DATABRICKS_CLIENT_ID> con il valore dell'app DATABRICKS_CLIENT_ID . L'entità servizio può ora eseguire l'autenticazione usando token OAuth gestiti automaticamente da Databricks. Per informazioni dettagliate, vedere Creare un ruolo OAuth per un'identità di Databricks.

Creare uno schema di database

Creare una tabella di esempio con autorizzazioni esplicite per l'entità servizio (le entità servizio non ereditano le autorizzazioni dello schema predefinite):

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

Sostituire <DATABRICKS_CLIENT_ID> con il DATABRICKS_CLIENT_ID valore.

Passaggio 3: Compilare e configurare l'applicazione

Scaricare i file dell'app, configurare la connessione al database con rotazione automatica dei token OAuth e testare localmente prima della distribuzione.

Scaricare e configurare i file dell'app

Scaricare i file dell'app dall'area di lavoro copiando il comando di esportazione dalla sezione Sincronizza i file dell'app:

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

Modificare app.yaml per aggiungere i dettagli della connessione al database. Ottenere i valori di connessione da Lakebase Connect modale selezionando Solo parametri:

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

Sostituire i segnaposto:

<your-endpoint-hostname>: copiare il valore PGHOST dalla finestra di dialogo Connect (ad esempio, ep-xyz.database.us-west-2.dev.databricks.com)
<DATABRICKS_CLIENT_ID>: usa il tuo DATABRICKS_CLIENT_ID dal passaggio 1
projects/<project-id>/branches/<branch-id>/endpoints/<endpoint-id>: eseguire databricks postgres list-endpoints e copiare il valore del name campo (formato: projects/<uuid>/branches/<uuid>/endpoints/<id>)

Implementare la rotazione dei token OAuth e delle query al database

Sostituire app.py con questo codice. In questo modo vengono implementate due modifiche chiave: rotazione automatica dei token OAuth per l'autenticazione e una query di database che recupera e visualizza le note create nel passaggio 2:

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)

Questo codice implementa la rotazione automatica delle credenziali del database usando tre componenti chiave:

WorkspaceClient: genera credenziali di database nuove tramite Databricks SDK
Classe OAuthConnection: classe di connessione personalizzata che inserisce una nuova credenziale in ogni nuova connessione
ConnectionPool: gestisce le connessioni di database e chiama la classe di connessione personalizzata durante la creazione di connessioni

Questo modello garantisce che l'app abbia sempre credenziali di database valide. Per una spiegazione dettagliata del funzionamento della rotazione delle credenziali, delle diverse strategie di rotazione e della gestione degli errori, vedere Rotazione dei token in Lakebase.

Aggiornare requirements.txt per includere i pacchetti necessari:

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

La versione minima dell'SDK (0.81.0) garantisce che il metodo sia disponibile per la generate_database_credential() generazione di token OAuth.

Esegui test localmente

Testare l'app in locale per verificare il funzionamento della connessione al database prima della distribuzione. Quando si testa localmente, l'app viene eseguita come il tuo account utente di Databricks (non come principale del servizio), quindi è necessario sostituire PGUSER con il tuo indirizzo di posta elettronica nelle variabili di ambiente seguenti.

Eseguire l'autenticazione nell'area di lavoro ed esportare le variabili di ambiente:

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

Copia i valori da app.yaml, ma sostituisci il valore PGUSER (ID client dell'entità servizio) con il tuo indirizzo email Databricks.

Installare le dipendenze ed eseguire l'app:

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

Aprire http://localhost:8000 nel browser. Verrà visualizzato "Hello from Lakebase!" con le tre note di esempio. Il pool di connessioni genera automaticamente nuovi token OAuth durante la creazione di nuove connessioni. Per altri dettagli, vedere Autenticazione in Lakebase.

Output dell'app locale che mostra

Passaggio 4: Distribuire e verificare

Dopo aver testato in locale, sincronizza le modifiche in una cartella dell'area di lavoro ed effettuare il deployment da tale percorso.

# 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

Sostituire <your-email> con l'indirizzo di posta elettronica di Databricks e <app-name> con il nome dell'app. Il --source-code-path flag indica alla distribuzione di usare i file caricati anziché il percorso predefinito dell'app.

Attendere il completamento della distribuzione (2-3 minuti), quindi accedere all'app all'URL specificato. Dovresti vedere "Ciao da Lakebase!" con le tue note di esempio.

Vedere anche

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-02-07