Enregistrer une base de données Lakebase dans Unity Catalog

L'enregistrement d'une base de données Lakebase dans Unity Catalog crée un catalogue en lecture seule qui représente votre base de données Postgres, permettant une gouvernance des données unifiée et une analytique inter-sources sur votre lakehouse et vos charges de travail transactionnelles.

Pourquoi s'inscrire dans Unity Catalog

L'enregistrement présente plusieurs avantages :

Gouvernance unifiée : Appliquez les contrôles de gouvernance d'Unity Catalog (autorisations, suivi de la lignée et journaux d'audit) à vos données Lakebase, à côté de vos données lakehouse.

Queries inter-sources : query les tables Unity Catalog et les bases de données Lakebase à partir d’une seule interface SQL, permettant une analytique combinant des données transactionnelles et analytiques.

Découverte centralisée : Trouvez et découvrez les bases de données, les schémas et les tables Lakebase via l’Explorateur de catalogues, aux côtés d’autres sources de données dans votre Workspace.

Workflows intégrés : utilisez les données Lakebase dans les tableaux de bord et les applications Databricks sans changer de contexte ni gérer de connexions distinctes.

Comment cela fonctionne

L'enregistrement crée un catalogue Unity Catalog en lecture seule qui reflète la structure de votre base de données Postgres, offrant un accès aux métadonnées de vos objets de base de données (schémas, tables, vues) via la couche de gouvernance de Unity Catalog.

Vous lancez l'enregistrement depuis Catalog Explorer plutôt que depuis l'interface Lakebase, qui s'intègre naturellement au flux de travail de création de catalogue d'Unity Catalog.

Après l'inscription :

• Votre base de données Lakebase apparaît comme un catalogue dans Unity Catalog.
• Les autorisations Unity Catalog contrôlent qui peut afficher et query la base de données
• Le catalogue reste en lecture seule — vous gérez la base de données réelle via Lakebase

Prérequis

• Un projet Lakebase existant avec au moins une base de données.
• CREATE CATALOG privilèges sur le metastore Unity Catalog
• Un SQL Warehouse **Serverless** pour interroger le catalogue enregistré. Les SQL Warehouses Pro et Classic ne sont pas pris en charge et renvoient une erreur d'autorisation.

important

Les catalogues Lakebase dans Unity Catalog nécessitent un SQL Warehouse **Serverless**. L'interrogation avec un SQL Warehouse Pro ou Classic renvoie une erreur PERMISSION_DENIED. Dans l'éditeur SQL, ouvrez le menu déroulant des warehouse et sélectionnez un warehouse Serverless avant d'exécuter une query.

Enregistrer une base de données

UI

1. Utilisez le sélecteur d'applications pour accéder à Analytique et IA .
2. Dans Catalog Explorer, cliquez sur le bouton plus et Créer un catalogue .
3. Saisissez un nom de catalogue (par exemple, lakebase_catalog).
4. Sélectionnez Lakebase Postgres comme type de catalogue, puis sélectionnez l'option Autoscaling .
5. Sélectionnez votre projet, votre Branch et votre base de données Postgres.
6. Cliquez sur Créer .

Le catalogue apparaît dans l’Explorateur de catalogues, où vous pouvez trouver des schémas, des tables et des vues, et les query à l’aide de SQL warehouses.

Python SDK

Python

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.postgres import Catalog, CatalogCatalogSpec

w = WorkspaceClient()

catalog = w.postgres.create_catalog(
    catalog=Catalog(spec=CatalogCatalogSpec(
        postgres_database="mydb",
        branch="projects/my-project/branches/production",
    )),
    catalog_id="my-catalog",
).wait()

print(f"Catalog registered: {catalog.name}")

Java SDK

Java

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.postgres.*;

WorkspaceClient w = new WorkspaceClient();

Catalog catalog = w.postgres().createCatalog(
    new CreateCatalogRequest()
        .setCatalogId("my-catalog")
        .setCatalog(new Catalog()
            .setSpec(new CatalogCatalogSpec()
                .setPostgresDatabase("mydb")
                .setBranch("projects/my-project/branches/production"))))
    .waitForCompletion();

System.out.println("Catalog registered: " + catalog.getName());

curl

Bash

curl -X POST "https://your-workspace.cloud.databricks.com/api/2.0/postgres/catalogs?catalog_id=my-catalog" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "postgres_database": "mydb",
      "branch": "projects/my-project/branches/production"
    }
  }'

Ceci renvoie une Opération de longue durée. Sonder le champ name renvoyé jusqu'à done: true. Consultez Opérations de longue durée. Pour la configuration de l'authentification, consultez Authentification.

Explorer les bases de données enregistrées

Après l’inscription, accédez à votre catalogue dans l’Explorateur de catalogues pour trouver les schémas, les tables et les vues. Cliquez sur une table pour afficher les détails du schéma, les exemples de données et les information de lignage.

Unity Catalog synchronise automatiquement les métadonnées de votre base de données Lakebase. Lorsque vous ajoutez ou modifiez des tables dans Lakebase, refresh la vue du catalogue pour voir les mises à jour.

Vérifier l'état de l'inscription

Pour récupérer les détails d'enregistrement actuels d'un catalogue par programmation :

Python SDK

Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

catalog = w.postgres.get_catalog("catalogs/my-catalog")
print(f"Database: {catalog.status.postgres_database}")
print(f"Branch: {catalog.status.branch}")

Java SDK

Java

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.postgres.Catalog;

WorkspaceClient w = new WorkspaceClient();

Catalog catalog = w.postgres().getCatalog("catalogs/my-catalog");
System.out.println("Database: " + catalog.getStatus().getPostgresDatabase());
System.out.println("Branch: " + catalog.getStatus().getBranch());

curl

Bash

curl "https://your-workspace.cloud.databricks.com/api/2.0/postgres/catalogs/my-catalog" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Query des bases de données enregistrées

Interroger les bases de données Lakebase enregistrées à l'aide de SQL Warehouse ou de tout outil qui se connecte à Unity Catalog :

SQL

-- Query a registered Lakebase database
SELECT * FROM chatbot_catalog.public.conversations
WHERE created_at >= current_date - INTERVAL 7 DAYS;

-- Join Lakebase and lakehouse data
SELECT
  c.conversation_id,
  c.user_id,
  c.agent_response,
  u.user_name,
  u.subscription_tier
FROM chatbot_catalog.public.conversations c
JOIN main.user_analytics.users u
  ON c.user_id = u.user_id;

Le catalogue en lecture seule garantit que les query ne modifient pas votre base de données Lakebase via Unity Catalog. Pour modifier les données, utilisez l’éditeur SQL Lakebase ou connectez-vous directement à votre base de données.

Autorisations et contrôle d'accès

Les autorisations Unity Catalog contrôlent l'accès aux bases de données Lakebase enregistrées :

• **Propriété du catalogue** : L'utilisateur qui enregistre la base de données devient le propriétaire du catalogue.
• Accès en lecture : accordez les USE CATALOG SELECT privilèges et pour permettre aux autres de query la base de données.
• Administrateur du métastore : Les administrateurs du métastore peuvent gérer tous les catalogues enregistrés

Pour accorder l'accès à une base de données enregistrée :

SQL

-- Grant read access to a group
GRANT USE CATALOG ON CATALOG chatbot_catalog TO `ai-engineering`;
GRANT SELECT ON CATALOG chatbot_catalog TO `ai-engineering`;

Les autorisations définies dans Unity Catalog contrôlent l'accès aux query via les SQL Warehouse. Les connexions directes à votre base de données Lakebase utilisent les rôles et les autorisations Postgres indépendamment.

Désenregistrer une base de données

La désinscription supprime le catalogue de Unity Catalog, mais n'affecte pas votre base de données Lakebase. La base de données reste accessible via Lakebase et les connexions Postgres directes.

UI

Sélectionnez le catalogue dans Catalog Explorer, cliquez sur , puis sélectionnez Delete .

Python SDK

Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

w.postgres.delete_catalog("catalogs/my-catalog").wait()

Java SDK

Java

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

w.postgres().deleteCatalog("catalogs/my-catalog").waitForCompletion();

curl

Bash

curl -X DELETE "https://your-workspace.cloud.databricks.com/api/2.0/postgres/catalogs/my-catalog" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

remarque

Si vous avez créé des tables synchronisées à partir de la base de données enregistrée, supprimez d'abord ces tables. Chaque table source ne peut être utilisée que pour créer 20 tables synchronisées, et les tables synchronisées en attente de suppression comptent pour cette limite.

Limitations

Accès en lecture seule : les catalogues enregistrés à partir des bases de données Lakebase sont en lecture seule. Vous ne pouvez pas modifier les données via les queries Unity Catalog.

**Serverless SQL Warehouse required** : vous ne pouvez query un catalogue Lakebase enregistré qu'en utilisant un Serverless SQL Warehouse. Les SQL Warehouses Pro et classiques ne prennent pas en charge cette fonctionnalité.

Base de données unique par catalogue : Chaque catalogue Unity Catalog représente une base de données Lakebase. Pour exposer plusieurs bases de données, enregistrez chacune séparément.

Synchronisation des métadonnées : Unity Catalog met en cache les métadonnées pour réduire les requêtes Postgres. Les nouveaux objets peuvent ne pas apparaître immédiatement. Cliquez sur pour Trigger un refresh complet.

L'enregistrement de base de données en branche n'est pas pris en charge : vous ne pouvez pas enregistrer une base de données en branche en tant que catalogue Unity Catalog distinct. Lorsque vous créez une Branch à partir d'une base de données déjà enregistrée dans Unity Catalog, la Branch hérite des métadonnées d'enregistrement du parent. Cela entraîne l'échec de l'enregistrement d'un nouveau catalogue.

Ressources supplémentaires

• Gérer les bases de données
• En savoir plus sur les Branch
• Interroger avec l'éditeur SQL