Sobre a autenticação

Saiba como autenticar conexões de banco de dados com o Lakebase Postgres. Para obter instruções de conexão passo a passo, consulte Início Rápido.

Visão geral

O Lakebase dá suporte a dois métodos de autenticação, cada um projetado para diferentes casos de uso:

OAuth token authentication: usa identidades Azure Databricks com tokens OAuth limitados por tempo. Melhor para:

• Sessões interativas em que você pode atualizar tokens
• Fluxos de trabalho integrados ao ambiente de trabalho
• Aplicativos que podem implementar a rotação de token
• Quando você quiser que a autenticação seja gerenciada por Azure Databricks

Autenticação de senha nativa do Postgres: Usa funções postgres tradicionais com senhas. Melhor para:

• Aplicativos que não podem atualizar credenciais por hora
• Processos de execução longa
• Ferramentas que não dão suporte à rotação de token

Tempos limite de conexão

Todas as conexões de banco de dados estão sujeitas aos seguintes limites, independentemente do método de autenticação:

• Tempo limite ocioso de 24 horas: As conexões sem atividade por 24 horas são fechadas automaticamente.
• Vida máxima de conexão de 3 dias: Conexões que estão ativas há mais de 3 dias podem ser fechadas independentemente da atividade.

Projete seus aplicativos para lidar graciosamente com timeouts de conexão implementando lógica de nova tentativa de conexão com configurações de tempo limite adequadas.

Autenticação de token OAuth

A autenticação de token OAuth permite que você se conecte usando sua identidade de Azure Databricks. Você gera um token OAuth limitado por tempo e usa-o como senha ao se conectar ao Postgres.

A função OAuth do proprietário do projeto é criada automaticamente. Para habilitar a autenticação OAuth para outras identidades Azure Databricks, você deve criar suas funções postgres usando a extensão databricks_auth e o SQL. Consulte Criar uma função OAuth para uma identidade de banco de dados usando SQL.

Como funcionam os tokens OAuth

• Tempo de vida do token: Os tokens OAuth expiram após uma hora.
• Imposição de expiração: A expiração do token é imposta somente no logon. As conexões abertas permanecem ativas mesmo após a expiração do token.
• Atualização de token: Para sessões interativas, gere um novo token quando necessário. Para aplicativos com conexões de execução longa, implemente a rotação de token para atualizar automaticamente as credenciais.

Requisitos e limitações

• Função Postgres correspondente necessária: sua identidade Azure Databricks deve ter uma função Postgres correspondente. A função do proprietário do projeto é criada automaticamente. Para outras identidades Azure Databricks, crie suas funções usando a extensão databricks_auth.
• Escopo do workspace: os tokens OAuth têm escopo de workspace e devem pertencer ao mesmo workspace que possui o projeto. Não há suporte para autenticação de token entre workspaces.
• SSL necessário: a autenticação baseada em token requer conexões SSL. Todos os clientes devem ser configurados para usar SSL (normalmente sslmode=require).

Obter um token OAuth em um fluxo de usuário para computador

Se você for um proprietário de banco de dados, administrador ou sua identidade de Azure Databricks tiver uma função postgres correspondente para o banco de dados, você poderá obter um token OAuth da interface do usuário, da API do Databricks, da CLI ou de um dos SDKs do Databricks.

Para outros usuários de identidade do Azure Databricks, consulte Como autorizar o acesso de usuários ao Azure Databricks com OAuth para instruções de autorização no nível do espaço de trabalho, a fim de obter tokens OAuth.

interface do usuário

Ao usar clientes SQL como psql ou DBeaver, use a interface do usuário do Lakebase para gerar tokens:

1. Navegue até seu projeto no Aplicativo Lakebase.
2. Selecione a ramificação e a computação à qual você deseja se conectar.
3. Clique em Conectar e siga as instruções para gerar um token OAuth.

Consulte Conectar com uma função OAuth para obter instruções completas.

CLI

# Generate OAuth token for database connection (1-hour expiration)
databricks postgres generate-database-credential projects/my-project/branches/production/endpoints/my-compute --output json

Resposta:

{
  "token": "eyJraWQiOiI1NDdkNjFjNzQ2YTk3M2Q3M2ViNjM2YWRiMWY2Nz...",
  "expire_time": "2026-01-22T17:07:00Z"
}

Use o token valor como a senha ao se conectar ao banco de dados.

SDK do Python

Você pode gerar um token OAuth usando o SDK Databricks para Python.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

# Generate OAuth token for database connection (1-hour expiration)
credential = w.postgres.generate_database_credential(
    endpoint="projects/my-project/branches/production/endpoints/my-compute"
)

print(f"Token: {credential.token}")
print(f"Expires: {credential.expire_time}")

# Use the token to connect to Postgres
import psycopg2

conn = psycopg2.connect(
    host="ep-example.database.region.databricks.com",
    port=5432,
    database="databricks_postgres",
    user="your.email@company.com",
    password=credential.token,
    sslmode="require"
)

SDK do Java

Você pode gerar um token OAuth usando o SDK Databricks para Java.

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

WorkspaceClient w = new WorkspaceClient();

// Generate OAuth token for database connection (1-hour expiration)
DatabaseCredential credential = w.postgres().generateDatabaseCredential(
    new GenerateDatabaseCredentialRequest()
        .setEndpoint("projects/my-project/branches/production/endpoints/my-compute")
);

System.out.println("Token: " + credential.getToken());
System.out.println("Expires: " + credential.getExpireTime());

Obter um token OAuth em um fluxo de máquina para máquina

Para habilitar o acesso seguro e automatizado (máquina a máquina) ao banco de dados, você deve obter um token OAuth usando um princípio de serviço do Azure Databricks. Esse processo envolve a configuração do principal de serviço, a geração de credenciais e a emissão de tokens OAuth para autenticação.

1. Configure uma entidade de serviço com credenciais de duração indefinida. Para obter instruções, consulte Autorizar o acesso da entidade de serviço ao Azure Databricks com OAuth.
2. Novos tokens OAuth do Mint como a entidade de serviço.

CLI

# Generate OAuth token for database connection (1-hour expiration)
databricks postgres generate-database-credential projects/my-project/branches/production/endpoints/my-compute --output json

Resposta:

{
  "token": "eyJraWQiOiI1NDdkNjFjNzQ2YTk3M2Q3M2ViNjM2YWRiMWY2Nz...",
  "expire_time": "2026-01-22T17:07:00Z"
}

Use o token valor como a senha ao se conectar ao banco de dados.

SDK do Python

Você pode gerar um token OAuth usando o SDK Databricks para Python.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient(
    host="https://<YOUR WORKSPACE URL>/",
    client_id="<YOUR SERVICE PRINCIPAL ID>",
    client_secret="REDACTED"
)

# Generate OAuth token for database connection (1-hour expiration)
credential = w.postgres.generate_database_credential(
    endpoint="projects/my-project/branches/production/endpoints/my-compute"
)

print(f"Token: {credential.token}")
print(f"Expires: {credential.expire_time}")

SDK do Java

Você pode gerar um token OAuth usando o SDK Databricks para Java.

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

// Initialize with service principal credentials
DatabricksConfig config = new DatabricksConfig()
    .setHost("https://<YOUR WORKSPACE URL>/")
    .setClientId("<YOUR SERVICE PRINCIPAL ID>")
    .setClientSecret("REDACTED");

WorkspaceClient w = new WorkspaceClient(config);

// Generate OAuth token for database connection (1-hour expiration)
DatabaseCredential credential = w.postgres().generateDatabaseCredential(
    new GenerateDatabaseCredentialRequest()
        .setEndpoint("projects/my-project/branches/production/endpoints/my-compute")
);

System.out.println("Token: " + credential.getToken());
System.out.println("Expires: " + credential.getExpireTime());

Exemplos de rotação de token

Como os tokens OAuth expiram após uma hora, os aplicativos que mantêm conexões de banco de dados de execução longa devem implementar a rotação de token para atualizar as credenciais periodicamente. Os exemplos a seguir demonstram como girar automaticamente tokens no código do aplicativo.

Python: psycopg3

Este exemplo usa o pool de conexões do psycopg3 com uma classe de conexão personalizada que gera um token OAuth novo sempre que uma nova conexão é criada. Essa abordagem garante que cada conexão do pool sempre tenha um token válido e atual.

%pip install "psycopg[binary,pool]"

from databricks.sdk import WorkspaceClient

import psycopg
from psycopg_pool import ConnectionPool

w = WorkspaceClient()

class CustomConnection(psycopg.Connection):
    @classmethod
    def connect(cls, conninfo='', **kwargs):
        # Generate a fresh OAuth token for each new connection
        endpoint = "projects/<project-id>/branches/<branch-id>/endpoints/<endpoint-id>"
        credential = w.postgres.generate_database_credential(endpoint=endpoint)
        kwargs['password'] = credential.token
        return super().connect(conninfo, **kwargs)

# Configure connection parameters (get these from the Connect dialog in the Lakebase App)
username = "your.email@company.com"  # Your DB identity
host = "ep-example.database.region.databricks.com"  # Your compute endpoint hostname
port = 5432
database = "databricks_postgres"

# Create connection pool with custom connection class
pool = ConnectionPool(
    conninfo=f"dbname={database} user={username} host={host} sslmode=require",
    connection_class=CustomConnection,
    min_size=1,
    max_size=10,
    open=True
)

# Use the connection pool
with pool.connection() as conn:
    with conn.cursor() as cursor:
        cursor.execute("SELECT version()")
        for record in cursor:
            print(record)

Python: SQLAlchemy

Este exemplo usa o pool de conexões do SQLAlchemy com um ouvinte de eventos que atualiza automaticamente o token OAuth antes de expirar. O listener de eventos é acionado antes que cada nova conexão física seja criada a partir do pool e atualiza o token se ele estiver dentro de 2 minutos da expiração, garantindo que seu aplicativo sempre tenha um token válido sem intervenção manual.

%pip install sqlalchemy psycopg2-binary databricks-sdk

from databricks.sdk import WorkspaceClient
import time

from sqlalchemy import create_engine, text, event

w = WorkspaceClient()

# Configure connection parameters (get these from the Connect dialog in the Lakebase App)
endpoint = "projects/<project-id>/branches/<branch-id>/endpoints/<endpoint-id>"
username = "your.email@company.com"  # Your DB identity
host = "ep-example.database.region.databricks.com"  # Your compute endpoint hostname
port = 5432
database = "databricks_postgres"

# Create SQLAlchemy engine
connection_pool = create_engine(f"postgresql+psycopg2://{username}:@{host}:{port}/{database}?sslmode=require")

# Global variables for token management
postgres_password = None
token_expiry = 0.0  # Unix timestamp when the current token expires

@event.listens_for(connection_pool, "do_connect")
def provide_token(dialect, conn_rec, cargs, cparams):
    global postgres_password, token_expiry

    # Refresh token if None or expiring within 2 minutes
    if postgres_password is None or time.time() >= token_expiry - 120:
        print("Refreshing PostgreSQL OAuth token")
        credential = w.postgres.generate_database_credential(endpoint=endpoint)
        postgres_password = credential.token
        token_expiry = credential.expire_time.seconds

    cparams["password"] = postgres_password

# Use the connection pool
with connection_pool.connect() as conn:
    result = conn.execute(text("SELECT version()"))
    for row in result:
        print(f"Connected to PostgreSQL database. Version: {row}")

Autenticação de senha do Postgres

A autenticação de senha nativa do Postgres usa funções postgres tradicionais com senhas. Ao contrário dos tokens OAuth, essas senhas não expiram após uma hora, tornando-as adequadas para aplicativos que não podem lidar com a rotação de credenciais frequentes.

Quando usar senhas do Postgres

Use a autenticação de senha do Postgres quando:

• Seu aplicativo ou ferramenta não pode atualizar credenciais a cada hora
• Você tem processos de longa execução que precisam de credenciais estáveis
• Sua biblioteca de clientes não dá suporte à rotação de token OAuth
• Você precisa da autenticação de banco de dados tradicional para compatibilidade

Como funcionam as senhas do Postgres

• Tempo de vida da senha: as senhas não expiram automaticamente
• Sem integração com workspace: a autenticação é realizada pelo Postgres, e não pela autenticação de workspace do Azure Databricks
• Gerenciamento manual: as senhas devem ser giradas manualmente e distribuídas aos usuários
• Os tempos limite de conexão ainda se aplicam: embora as senhas não expirem, as conexões ainda estão sujeitas ao tempo limite ocioso de 24 horas e à vida máxima de conexão de 3 dias

Considerações de segurança

• Armazenamento de senhas: armazenar senhas com segurança usando variáveis de ambiente ou sistemas de gerenciamento de segredos
• SSL necessário: todas as conexões devem usar SSL (sslmode=require)

Próximas etapas

• Início Rápido: Conectar-se ao banco de dados
• Gerenciar funções do Postgres
• Gerenciar permissões
• Consultar seus dados