Créer des rôles Postgres

Lorsque vous créez un projet, Lakebase crée plusieurs rôles Postgres dans le projet :

• Un rôle Postgres pour l'identité Databricks du propriétaire du projet (par exemple, user@databricks.com), qui est propriétaire de la base de données databricks_postgres default.
• Un rôle administratif databricks_superuser

Ces deux rôles sont visibles dans l'onglet **Roles & Databases** lorsque vous ouvrez votre projet pour la première fois.

La base de données databricks_postgres est créée afin que vous puissiez vous connecter et essayer Lakebase immédiatement après la création du projet.

Plusieurs rôles gérés par le système sont également créés. Il s'agit de rôles internes utilisés par les services Databricks pour la gestion, le monitoring et les opérations de données.

remarque

Les rôles Postgres contrôlent l'accès à la base de données (qui peut interroger les données). Pour les autorisations de projet (qui peut gérer l'infrastructure), consultez Autorisations de projet. Pour un tutoriel sur la configuration des deux, consultez Tutoriel : Accorder l'accès au projet et à la base de données à un nouvel utilisateur.

Consultez Rôles précréés et Rôles système.

Créer des rôles Postgres

Lakebase prend en charge deux types de rôles Postgres pour l'accès aux bases de données :

• Rôles OAuth pour les identités Databricks : Créez-les en utilisant l'interface utilisateur Lakebase, l'extension databricks_auth avec SQL, ou le SDK Python et l'API REST. Permet aux identités Databricks (utilisateurs, Service Principal et groupes) de se connecter à l'aide de jetons OAuth.
• Rôles de mot de passe Postgres natifs : créez-les à l’aide de l’interface utilisateur Lakebase, de SQL ou du SDK Python et de l’API REST. Utilisez un nom de rôle valide avec l’authentification par mot de passe.

Pour obtenir des conseils sur le choix du type de rôle à utiliser, consultez la Vue d'ensemble de l'authentification. Chacun est conçu pour des cas d’utilisation différents.

Créer un rôle OAuth pour les identités Databricks

Pour permettre aux identités Databricks (utilisateurs, Service Principals ou groupes) de se connecter à l'aide de jetons OAuth, créez un rôle OAuth à l'aide de l'interface utilisateur Lakebase, de l'extension databricks_auth avec SQL, ou de l'API REST.

Pour obtenir des instructions détaillées sur l'obtention de jetons OAuth, consultez Obtenir un jeton OAuth dans un flux utilisateur-machine et Obtenir un jeton OAuth dans un flux machine-machine.

UI

1. Dans Rôles & Bases de données > Ajouter un rôle > tab OAuth, sélectionnez l'utilisateur, le Service Principal Databricks ou le groupe auquel accorder l'accès à la base de données.
2. Après avoir créé le rôle, accordez les privilèges de base de données appropriés. Apprenez comment : Gérer les autorisations

SQL

Prérequis :

• Vous devez disposer des autorisations CREATE et CREATE ROLE sur la base de données
• Vous devez être authentifié(e) en tant qu'identité Databricks avec un jeton OAuth valide
• Les sessions authentifiées Postgres natives ne peuvent pas créer de rôles OAuth.

1. Créez l'extension databricks_auth. Chaque base de données Postgres doit avoir sa propre extension.

   SQL

   CREATE EXTENSION IF NOT EXISTS databricks_auth;

2. Utilisez la fonction databricks_create_role pour créer un rôle Postgres pour l'identité Databricks :

   SQL

   SELECT databricks_create_role('identity_name', 'identity_type');

   Pour un utilisateur Databricks :

   SQL

   SELECT databricks_create_role('myuser@databricks.com', 'USER');

   Pour un Service Principal Databricks :

   SQL

   SELECT databricks_create_role('8c01cfb1-62c9-4a09-88a8-e195f4b01b08', 'SERVICE_PRINCIPAL');

   Pour un groupe Databricks :

   SQL

   SELECT databricks_create_role('My Group Name', 'GROUP');

   Le nom du groupe est sensible à la casse et doit correspondre exactement à son apparence dans votre Workspace Databricks. Lorsque vous créez un rôle Postgres pour un groupe, tout membre direct ou indirect (utilisateur ou Service Principal Databricks) de ce groupe Databricks peut s'authentifier auprès de Postgres en tant que rôle de groupe en utilisant son jeton OAuth individuel. Ce modèle d'autorisations au niveau du groupe vous permet de gérer les autorisations dans Postgres au lieu de maintenir les autorisations pour les utilisateurs individuels.

3. Accorder les autorisations de base de données au rôle nouvellement créé.

La fonction databricks_create_role() crée un rôle Postgres avec l’autorisation LOGIN uniquement. Après avoir créé le rôle, vous devez accorder les privilèges et autorisations de base de données appropriés sur les bases de données, schémas ou tables spécifiques auxquels l’utilisateur doit accéder. Apprenez comment : Gérer les autorisations

Python SDK

Définissez identity_type sur USER, SERVICE_PRINCIPAL ou GROUP. Définissez postgres_role sur l'adresse e-mail de l'identité, l'ID d'application (UUID) ou le nom d'affichage du groupe, respectivement. Cette valeur devient le nom du rôle Postgres et est ce que vous utilisez dans les chaînes de connexion et les instructions GRANT.

Python

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.postgres import Role, RoleIdentityType, RoleRoleSpec

w = WorkspaceClient()

operation = w.postgres.create_role(
    parent="projects/my-project/branches/production",
    role=Role(
        spec=RoleRoleSpec(
            identity_type=RoleIdentityType.USER,
            postgres_role="user@example.com"
        )
    )
)
role = operation.wait()
print(f"Created role: {role.name}")

Après avoir créé le rôle, accordez les privilèges de base de données appropriés. Apprenez comment : Gérer les autorisations

CLI

Définissez identity_type sur USER, SERVICE_PRINCIPAL ou GROUP. Définissez postgres_role sur l'adresse e-mail de l'identité, l'ID d'application (UUID) ou le nom d'affichage du groupe, respectivement. Cette valeur devient le nom du rôle Postgres et est ce que vous utilisez dans les chaînes de connexion et les instructions GRANT.

Pour un utilisateur Databricks :

Bash

databricks postgres create-role projects/my-project/branches/production \
  --role-id my-user-role \
  --json '{"spec": {"identity_type": "USER", "postgres_role": "user@example.com"}}'

Pour un Service Principal Databricks :

Bash

databricks postgres create-role projects/my-project/branches/production \
  --role-id my-sp-role \
  --json '{"spec": {"identity_type": "SERVICE_PRINCIPAL", "postgres_role": "8c01cfb1-62c9-4a09-88a8-e195f4b01b08"}}'

Pour un groupe Databricks :

Bash

databricks postgres create-role projects/my-project/branches/production \
  --role-id my-group-role \
  --json '{"spec": {"identity_type": "GROUP", "postgres_role": "My Group Name"}}'

La commande attend que l'opération se termine et renvoie le rôle créé. Utilisez --no-wait pour revenir immédiatement et interroger séparément avec databricks postgres get-operation.

Après avoir créé le rôle, accordez les privilèges de base de données appropriés. Apprenez comment : Gérer les autorisations

curl

Définissez identity_type sur USER, SERVICE_PRINCIPAL ou GROUP. Définissez postgres_role sur l'adresse e-mail de l'identité, l'ID d'application (UUID) ou le nom d'affichage du groupe, respectivement. Cette valeur devient le nom du rôle Postgres et est ce que vous utilisez dans les chaînes de connexion et les instructions GRANT.

Bash

curl -X POST "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/production/roles" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "identity_type": "USER",
      "postgres_role": "user@example.com"
    }
  }' | jq

L’endpoint renvoie une opération de longue durée. Interroger jusqu'à ce que done soit true, puis utilisez le champ name du rôle pour les appels d'API ultérieurs. Voir Opérations de longue durée.

Après avoir créé le rôle, accordez les privilèges de base de données appropriés. Apprenez comment : Gérer les autorisations

Authentification basée sur les groupes

Lorsque vous créez un rôle Postgres pour un groupe Databricks, vous activez l'authentification basée sur les groupes. Cela permet à tout membre du groupe Databricks de s'authentifier auprès de Postgres en utilisant le rôle du groupe, ce qui simplifie la gestion des autorisations.

Comment ça marche :

1. Créez un rôle Postgres pour un groupe Databricks.
2. Accorder les autorisations de base de données au rôle de groupe dans Postgres. Voir Gérer les autorisations.
3. Tout membre direct ou indirect (utilisateur ou Service Principal Databricks) du groupe Databricks peut se connecter à Postgres en utilisant son jeton OAuth individuel.
4. Lors de la connexion, le membre s'authentifie en tant que rôle de groupe et hérite de toutes les autorisations que vous avez accordées à ce rôle.

Flux d'authentification :

Lorsqu'un membre du groupe se connecte, il spécifie le nom du rôle Postgres du groupe comme nom d'utilisateur et son propre jeton OAuth comme mot de passe :

Bash

export PGPASSWORD='<OAuth token of a group member>'
export GROUP_ROLE_NAME='<pg-case-sensitive-group-role-name>'

psql -h $HOSTNAME -p 5432 -d databricks_postgres -U $GROUP_ROLE_NAME

Considérations importantes :

• Validation de l'adhésion au groupe : L'adhésion au groupe n'est validée qu'au moment de l'authentification. Si un membre est supprimé du groupe Databricks après avoir établi une connexion, la connexion reste active. Les nouvelles tentatives de connexion des membres supprimés sont rejetées.
• Portée du Workspace : Seuls les groupes attribués au même Workspace Databricks que le projet sont pris en charge pour l’authentification basée sur les groupes. Pour savoir comment attribuer des groupes à un Workspace, consultez Gérer les groupes.
• Sensibilité à la casse : Le nom du groupe utilisé dans databricks_create_role() doit correspondre exactement au nom du groupe tel qu'il apparaît dans votre workspace Databricks, y compris la casse.
• Gestion des autorisations : la gestion des autorisations au niveau du groupe dans Postgres est plus efficace que la gestion des autorisations d'utilisateurs individuels. Lorsque vous accordez des autorisations au rôle de groupe, tous les membres actuels et futurs du groupe héritent automatiquement de ces autorisations.
• Renommage d'identité : si l'e-mail d'un utilisateur ou le nom d'affichage d'un groupe change dans Databricks, l'authentification et les octrois de base de données existants sont interrompus. Supprimez l'ancien rôle, créez-en un nouveau avec le nom mis à jour, et mettez à jour les chaînes de connexion et les autorisations.

remarque

Les noms de rôle ne peuvent pas dépasser 63 caractères, et certains noms ne sont pas autorisés. En savoir plus : Gérer les rôles

Créer un rôle de mot de passe Postgres natif

Les connexions par mot de passe peuvent être désactivées au niveau du projet ou du compute. Voir Bloquer les connexions par mot de passe.

UI

1. Sous Rôles et bases de données > Ajouter un rôle > tab Mot de passe, saisissez un nom de rôle et attribuez éventuellement databricks_superuser ou des attributs système (CREATEDB, CREATEROLE, BYPASSRLS).
2. Copiez le mot de passe généré et fournissez-le en toute sécurité à l'utilisateur. Il n'est plus affiché.

SQL

SQL

CREATE ROLE role_name WITH LOGIN PASSWORD 'your_secure_password';

Le mot de passe doit comporter au moins 12 caractères, avec un mélange de caractères minuscules, majuscules, numériques et symboliques. Les mots de passe définis par l'utilisateur sont validés au moment de la création pour vérifier l'entropie de 60 bits.

Python SDK

Omettre identity_type pour créer un rôle de mot de passe. L'API renvoie un mot de passe généré dans la réponse.

Python

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.postgres import Role, RoleRoleSpec

w = WorkspaceClient()

operation = w.postgres.create_role(
    parent="projects/my-project/branches/production",
    role=Role(
        spec=RoleRoleSpec(
            postgres_role="my-app-role"
        )
    )
)
role = operation.wait()
print(f"Created role: {role.name}")

CLI

Omettre identity_type pour créer un rôle de mot de passe. L’API génère un mot de passe et le renvoie dans la réponse.

Bash

databricks postgres create-role projects/my-project/branches/production \
  --role-id my-app-role \
  --json '{"spec": {"postgres_role": "my-app-role"}}'

La commande attend que l'opération se termine. La réponse inclut le mot de passe généré — enregistrez-le en toute sécurité, car il ne sera plus affiché.

curl

Omettre identity_type pour créer un rôle de mot de passe. L'Endpoint renvoie une opération de longue durée. Sonder jusqu'à ce que done soit true.

Bash

curl -X POST "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/production/roles" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "postgres_role": "my-app-role"
    }
  }' | jq

remarque

Les rôles de mot de passe natifs de Postgres prennent en charge le gestionnaire de connexions intégré. Voir Utiliser le regroupement de connexions.

Afficher les rôles Postgres

UI

Pour afficher tous les rôles Postgres dans votre projet, accédez à l'onglet Rôles et Bases de données de votre Branch dans l'application Lakebase. Tous les rôles créés dans la branch, à l'exception des rôles système, sont répertoriés. La colonne Type d'authentification indique si chaque rôle utilise l'authentification OAuth ou par mot de passe.

PostgreSQL

Afficher tous les rôles avec la commande \du :

Vous pouvez afficher tous les rôles Postgres, y compris les rôles système, à l'aide de la méta-commande \du de n'importe quel client Postgres (tel que psql) ou de l'éditeur SQL de Lakebase :

SQL

\du
                                      List of roles
          Role name          |                         Attributes
-----------------------------+------------------------------------------------------------
 cloud_admin                 | Superuser, Create role, Create DB, Replication, Bypass RLS
 my.user@databricks.com      | Create role, Create DB, Bypass RLS
 databricks_control_plane    | Superuser
 databricks_gateway          |
 databricks_monitor          |
 databricks_reader_12345     | Create role, Create DB, Replication, Bypass RLS
 databricks_replicator       | Replication
 databricks_superuser        | Create role, Create DB, Cannot login, Bypass RLS
 databricks_writer_12345     | Create role, Create DB, Replication, Bypass RLS

Python SDK

Liste de tous les rôles :

Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

roles = w.postgres.list_roles(parent="projects/my-project/branches/production")
for role in roles:
    print(f"{role.status.postgres_role} ({role.status.identity_type or 'PASSWORD'}): {role.name}")

Obtenir un rôle spécifique :

Python

role = w.postgres.get_role(
    name="projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx"
)
print(role)

CLI

Liste de tous les rôles :

Bash

databricks postgres list-roles projects/my-project/branches/production

Obtenir un rôle spécifique :

Bash

databricks postgres get-role projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx

La sortie inclut le champ name (par exemple, rol-xxxx-xxxxxxxxxx) requis pour les appels de mise à jour et de suppression.

curl

Liste de tous les rôles :

Bash

curl -X GET "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/production/roles" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

Obtenir un rôle spécifique :

Bash

curl -X GET "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

La réponse inclut le champ name (par exemple, rol-xxxx-xxxxxxxxxx) requis pour les appels de mise à jour et de suppression.

Mettre à jour un rôle

Pour mettre à jour les attributs d’un rôle dans l’interface utilisateur, sélectionnez Modifier le rôle dans le menu des rôles de la tab Rôles et bases de données.

Utilisez l'API ou l'interface de ligne de commande (CLI) pour mettre à jour les rôles système ou les attributs d'un rôle. Seuls les champs spécifiés dans le masque de mise à jour changent.

remarque

Pour obtenir le nom de la ressource d'un rôle à utiliser dans les appels de mise à jour et de suppression, utilisez l'endpoint lister les rôles. Les noms de ressources de rôle utilisent un identifiant généré par le système (par exemple, rol-xxxx-xxxxxxxxxx), et non la valeur postgres_role fournie lors de la création.

CLI

Mettre à jour un rôle à l’aide du modèle de masque de mise à jour. Le masque de mise à jour est le deuxième argument positionnel après le nom de la ressource.

Lors de la mise à jour de spec.attributes, vous devez fournir les trois champs d'attribut (createdb, createrole, bypassrls) — l'API remplace l'intégralité de l'objet d'attributs :

Bash

databricks postgres update-role \
  projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx \
  "spec.attributes" \
  --json '{
    "spec": {
      "attributes": {"createdb": true, "createrole": false, "bypassrls": false}
    }
  }'

Pour également mettre à jour les rôles d'adhésion, ajoutez spec.membership_roles au masque de mise à jour :

Bash

databricks postgres update-role \
  projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx \
  "spec.membership_roles" \
  --json '{"spec": {"membership_roles": ["DATABRICKS_SUPERUSER"]}}'

Pour supprimer databricks_superuser, passez un tableau vide : "membership_roles": [].

curl

Bash

curl -X PATCH "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx?update_mask=spec.membership_roles%2Cspec.attributes.createdb" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx",
    "spec": {
      "membership_roles": ["DATABRICKS_SUPERUSER"],
      "attributes": { "createdb": true }
    }
  }' | jq

Pour supprimer databricks_superuser, passez un tableau vide : "membership_roles": [].

Supprimer un rôle Postgres

Vous pouvez supprimer les rôles basés sur l'identité Databricks et les rôles de mot de passe Postgres intégrés.

UI

1. Accédez à l'onglet Rôles et bases de données de votre Branch dans l'application Lakebase.

2. Cliquez sur le menu du rôle que vous souhaitez ignorer et sélectionnez **Ignorer**.

3. Dans la boîte de dialogue de confirmation, activez éventuellement Réattribuer les objets détenus .

   Un rôle Postgres ne peut pas être supprimé s'il possède des objets de base de données tels que des tables, des vues ou des schémas. Lorsque cette option est activée, un menu déroulant **Réattribuer les éléments détenus à** apparaît. Sélectionnez le rôle qui recevra la propriété des objets avant la suppression. Les objets qui ne peuvent pas être réattribués, tels que les autorisations accordées au rôle supprimé, sont supprimés automatiquement une fois la réattribution terminée. Lorsqu'elle est désactivée, la suppression échoue si le rôle possède des objets.

4. Cliquez sur Confirmer .

La suppression d'un rôle est permanente et ne peut pas être annulée.

PostgreSQL

Vous pouvez supprimer n'importe quel rôle Postgres à l'aide de commandes Postgres standard. Pour plus de détails, consultez la documentation PostgreSQL sur la suppression de rôles.

Supprimer un rôle :

SQL

DROP ROLE role_name;

Après la suppression d'un rôle basé sur l'identité Databricks, cette identité ne peut plus s'authentifier auprès de Postgres à l'aide de jetons OAuth tant qu'un nouveau rôle n'est pas créé.

CLI

Bash

databricks postgres delete-role \
  projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx

Si le rôle détient des objets de base de données, utilisez --reassign-owned-to pour transférer la propriété à un autre rôle avant la suppression :

Bash

databricks postgres delete-role \
  projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx \
  --reassign-owned-to projects/my-project/branches/production/roles/rol-yyyy-yyyyyyyyyy

Python SDK

Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

operation = w.postgres.delete_role(
    name="projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx"
)
operation.wait()

curl

Bash

curl -X DELETE "$WORKSPACE/api/2.0/postgres/projects/my-project/branches/production/roles/rol-xxxx-xxxxxxxxxx" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq

Rôles pré-créés

Une fois un projet créé, Databricks crée automatiquement des rôles Postgres pour l'administration du projet et la mise en route.

Rôle	Description	Privilèges hérités
<project_owner_role>	L'identité Databricks du créateur du projet (par exemple, my.user@databricks.com). Ce rôle est propriétaire de la base de données databricks_postgres default et peut se connecter et administrer le projet.	Membre de databricks_superuser
databricks_superuser	Un rôle administratif interne. Utilisé pour configurer et gérer l'accès à travers le projet. Ce rôle se voit accorder de vastes privilèges.	Hérite de pg_read_all_data, pg_write_all_data et pg_monitor.

Rôle	Description	Privilèges hérités
<project_owner_role>	L'identité Databricks du créateur du projet (par exemple, my.user@databricks.com). Ce rôle est propriétaire de la base de données databricks_postgres default et peut se connecter et administrer le projet.	Membre de databricks_superuser
databricks_superuser	Un rôle administratif interne. Utilisé pour configurer et gérer l'accès à travers le projet. Ce rôle se voit accorder de vastes privilèges.	Hérite de pg_read_all_data, pg_write_all_data et pg_monitor.

En savoir plus sur les capacités et les privilèges spécifiques de ces rôles : Capacités des rôles pré-créés

Rôles système créés par Databricks

Databricks crée les rôles système suivants requis pour les services internes. Vous pouvez afficher ces rôles en émettant une commande \du à partir de psql ou de l’ éditeur SQL Lakebase.

Rôle	Objectif
cloud_admin	Rôle de superutilisateur utilisé pour la gestion de l'infrastructure cloud
databricks_control_plane	Rôle de superutilisateur utilisé par les composants internes de Databricks pour les Opérations de gestion
databricks_monitor	Utilisé par les services internes de collecte de métriques
databricks_replicator	Utilisé pour les opérations de réplication de base de données
databricks_writer_<dbid>	Rôle par base de données utilisé pour créer et gérer des tables synchronisées
databricks_reader_<dbid>	Rôle par base de données utilisé pour lire les tables enregistrées dans Unity Catalog
databricks_gateway	Utilisé pour les connexions internes pour les services gérés de diffusion de données

Rôle	Objectif
cloud_admin	Rôle de superutilisateur utilisé pour la gestion de l'infrastructure cloud
databricks_control_plane	Rôle de superutilisateur utilisé par les composants internes de Databricks pour les Opérations de gestion
databricks_monitor	Utilisé par les services internes de collecte de métriques
databricks_replicator	Utilisé pour les opérations de réplication de base de données
databricks_writer_<dbid>	Rôle par base de données utilisé pour créer et gérer des tables synchronisées
databricks_reader_<dbid>	Rôle par base de données utilisé pour lire les tables enregistrées dans Unity Catalog
databricks_gateway	Utilisé pour les connexions internes pour les services gérés de diffusion de données

Pour savoir comment les rôles, les privilèges et les appartenances aux rôles fonctionnent dans Postgres, utilisez les ressources suivantes dans la documentation Postgres :

• Rôles de base de données
• Privilèges

Ressources supplémentaires

• Gérer les autorisations
• Connectez-vous à votre projet
• En savoir plus sur l'authentification