Connecter une application Databricks personnalisée à Lakebase

Ce tutoriel vous montre comment connecter une application Databricks à la mise à l’échelle automatique Lakebase avec rotation automatique des informations d’identification. L’application génère de nouvelles informations d’identification de base de données à partir de Databricks avant leur expiration. L’exemple utilise Flask, mais le modèle d’authentification s’applique à n’importe quelle infrastructure.

Fonctionnement

Databricks Apps s’authentifie auprès de Lakebase à l’aide de jetons OAuth qui expirent après une heure. Pour gérer cela, vous créez un rôle Postgres pour le principal de service de votre application, puis configurez votre application pour générer automatiquement des jetons frais chaque fois qu’elle doit se connecter à la base de données. L’application utilise un pool de connexions. Le pool crée de nouvelles connexions avec des jetons frais si nécessaire, de sorte que votre application n’utilise jamais d’informations d’identification expirées.

Lorsque vous déployez l’application sur Azure Databricks, elle s’exécute en tant que principal de service et génère des jetons pour cette identité. Lorsque vous testez localement, l’application s’exécute en tant que compte d’utilisateur Azure Databricks et génère des jetons pour vous. Les deux utilisent le même code de rotation de jeton. Seul le contexte d’authentification change.

Avant de commencer

Pour suivre ce didacticiel, vous avez besoin des éléments suivants :

• Accès à un espace de travail Azure Databricks avec Lakebase Postgres en mode mise à l’échelle automatique activée. Contactez l’administrateur de votre espace de travail si vous ne voyez pas Lakebase dans le commutateur d’application.
• Autorisation de créer des applications
• Connaissance de base des Python et SQL
• Interface CLI Databricks installée pour le développement local
• Python 3.9 ou version ultérieure installée localement

Étape 1 : Créer votre application et votre base de données

Tout d’abord, créez une application Databricks et un projet Lakebase. L’application obtient automatiquement une identité de principal de service que vous utiliserez pour l’authentification de base de données.

Créer l’application

Créez une application Databricks à l’aide du modèle Flask Hello World . Consultez Créer une application Databricks à partir d’un modèle.

Après avoir créé l’application, accédez à l’onglet Environnement de l’application et notez la DATABRICKS_CLIENT_ID valeur (format UUID comme 6b215d2b-f099-4bdb-900a-60837201ecec). Cela devient le nom d’utilisateur Postgres de votre application pour l’authentification OAuth.

Créer la base de données

Créez un projet de mise à l’échelle automatique Lakebase pour héberger votre base de données. Cliquez sur d’application, sélectionnez Lakebase Postgres, puis créez un projet avec un nom (par exemple my-app-db) et une version Postgres (acceptez la version par défaut de Postgres 17). Pour plus d’informations sur la configuration, consultez Créer un projet.

Attendez que le calcul devienne actif (environ 1 minute) avant de continuer.

Étape 2 : Configurer l’authentification et le schéma de base de données

Créez un rôle Postgres pour le principal de service de votre application avec l’authentification OAuth, puis créez un exemple de table avec des données pour que votre application s’affiche.

Configurer l’authentification OAuth

Dans votre projet Lakebase, ouvrez l’Éditeur SQL et exécutez ces commandes. L’extension active l’authentification databricks_auth OAuth. Avec cela, vos rôles Postgres acceptent les jetons Databricks au lieu des mots de passe traditionnels :

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

Remplacez <DATABRICKS_CLIENT_ID> par la valeur de DATABRICKS_CLIENT_ID votre application. Le principal de service peut désormais s’authentifier à l’aide de jetons OAuth qui Azure Databricks gère automatiquement. Pour plus d’informations, consultez Créer un rôle OAuth pour une identité Azure Databricks.

Créer un schéma de base de données

Créez un exemple de table avec des autorisations explicites pour votre principal de service (les principaux de service n’héritent pas des autorisations de schéma par défaut) :

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

Remplacez <DATABRICKS_CLIENT_ID> par votre valeur DATABRICKS_CLIENT_ID.

Étape 3 : Générer et configurer votre application

Téléchargez vos fichiers d’application, configurez la connexion de base de données avec la rotation automatique des jetons OAuth et testez localement avant le déploiement.

Télécharger et configurer des fichiers d’application

Téléchargez vos fichiers d’application à partir de l’espace de travail en copiant la commande d’exportation à partir de la section Synchroniser les fichiers de l’application :

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

Modifiez app.yaml pour ajouter des détails de connexion de base de données. Obtenez vos valeurs de connexion à partir du modal Lakebase Connect en sélectionnant Paramètres uniquement :

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

Remplacez les espaces réservés :

• <your-endpoint-hostname>: copiez la valeur PGHOST à partir du modal Connect (par exemple, ep-xyz.database.us-west-2.dev.databricks.com)
• <DATABRICKS_CLIENT_ID>: Utilisez votre DATABRICKS_CLIENT_ID de l'étape 1
• projects/<project-id>/branches/<branch-id>/endpoints/<endpoint-id>: Dans l’application Lakebase, accédez à l’onglet Calculs de votre branche, cliquez sur Obtenir l’ID de votre calcul, puis sélectionnez Copier le nom de la ressource.

Implémenter la rotation des jetons OAuth et la requête de base de données

Remplacez app.py par ce code, ce qui ajoute la rotation automatique des jetons OAuth et une requête de base de données qui extrait les notes de l’étape 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)

Les trois composants clés sont les suivants :

• WorkspaceClient: génère des informations d’identification fraîches à l’aide du Kit de développement logiciel (SDK).
• OAuthConnection: classe de connexion personnalisée qui injecte une nouvelle information d’identification dans chaque connexion.
• ConnectionPool: gère les connexions et appelle la classe personnalisée en fonction des besoins.

Pour plus d'informations sur les stratégies de rotation des identifiants et la gestion des erreurs, consultez les exemples de rotation des jetons.

Mettez à jour requirements.txt pour inclure les packages requis :

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

La version 0.81.0 ou ultérieure inclut la generate_database_credential() méthode.

Tester localement

Testez votre application localement pour vérifier que la connexion de base de données fonctionne avant le déploiement. Lorsque vous effectuez des tests localement, l’application s’exécute en tant que compte d’utilisateur Azure Databricks (et non le principal du service), remplacez PGUSER par votre adresse e-mail dans les variables d’environnement ci-dessous.

Authentifiez-vous auprès de votre espace de travail et exportez des variables d’environnement :

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

Copiez les valeurs de votre app.yaml, mais remplacez la valeur PGUSER (ID client du principal de service) par votre adresse e-mail Azure Databricks.

Installez les dépendances et exécutez l’application :

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

Ouvrez http://localhost:8000 dans votre navigateur. Vous devriez voir « Bonjour de Lakebase ! » avec vos trois exemples de notes. Le pool de connexions génère automatiquement des jetons OAuth frais lors de la création de connexions. Pour plus d’informations, consultez l’authentification par jeton OAuth.

Étape 4 : Déployer et vérifier

Après avoir testé localement, synchronisez vos modifications dans un dossier d’espace de travail et déployez à partir de cet emplacement :

# 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

Remplacez <your-email> par votre adresse e-mail Azure Databricks et <app-name> par le nom de votre application. L’indicateur --source-code-path indique au déploiement d’utiliser vos fichiers chargés au lieu de l’emplacement par défaut de l’application.

Attendez que le déploiement se termine (2 à 3 minutes), puis accédez à votre application à l’URL fournie. Vous devriez voir « Hello from Lakebase ! » avec vos exemples de notes.

Voir aussi

• Exemples de rotation de jetons
• Databricks Apps