Conecte aplicativos externos ao Lakebase usando a API.

info

O dimensionamento automático do Lakebase está disponível nas seguintes regiões: us-east-1, us-east-2, us-west-2, eu-central-1, eu-west-1, ap-south-1, ap-southeast-1, ap-southeast-2.

O Lakebase autoscale é a versão mais recente do Lakebase com recursos como autoscale compute, escala-to-zero, branching e instant restore. Para comparação de recursos com o provisionamento do Lakebase, veja escolhendo entre versões.

Este guia mostra como conectar aplicativos externos ao dimensionamento automático do Lakebase usando chamadas diretas API REST . Use essa abordagem quando um SDK do Databricks não estiver disponível para sua linguagem (Node.js, Ruby, PHP, Elixir, Rust, etc.).

Se a sua linguagem tiver suporte para SDK (Python, Java ou Go), use a opção "Conectar aplicativo externo ao Lakebase usando o SDK" para um gerenciamento de tokens mais simples.

Você realiza duas chamadas API para obter as credenciais do banco de dados com rotação de tokens OAuth . São fornecidos exemplos para curl e Node.js.

nota

Autenticação em duas etapas: Esta abordagem requer duas chamadas API para cada credencial de banco de dados: (1) troca do segredo da entidade de serviço pelos tokens OAuth workspace , (2) troca dos tokens OAuth pela credencial do banco de dados. Ambos os tokens expiram após 60 minutos. O SDK lida com a etapa 1 automaticamente.

Pré-requisitos

Você precisa da mesma configuração que a abordagem do SDK: entidade de serviço, função do Postgres e detalhes de conexão.

Pré-requisito	detalhe principal	Mais informações
Service principal	Segredo OAuth com tempo de vida máximo de 730 dias ; habilitar acesso ao espaço de trabalho . Anote o ID do cliente (UUID) para a função do Postgres e as variáveis de ambiente.	Criar service principal
Função do Postgres	Crie a função OAuth no Editor SQL do Lakebase: databricks_create_role('{client-id}', 'SERVICE_PRINCIPAL') e conceda CONNECT, USAGE, SELECT/INSERT/UPDATE/DELETE. Use o ID do cliente da etapa 1.	Criar função do Postgres
Detalhes da conexão	A partir do Lakebase Console Connect : nome do endpoint (projects/.../branches/.../endpoints/...), host , banco de dados (geralmente databricks_postgres).	Obtenha detalhes de conexão

Como funciona

A abordagem manual via API requer duas trocas de tokens:

Tempo de vida dos tokens:

• segredo de entidade de serviço: Até 730 dias (definido durante a criação)
• Tokens OAuth do espaço de trabalho: 60 minutos (o passo 1)
• Credencial de banco de dados: 60 minutos (o passo 2)

Escopo de tokens: As credenciais do banco de dados têm escopo workspace . Embora o parâmetro endpoint seja obrigatório, os tokens retornados podem acessar qualquer banco de dados ou projeto no workspace para o qual a entidade de serviço tenha permissões.

Conjunto de variáveis de ambiente

Defina estas variáveis de ambiente antes de executar seu aplicativo:

Bash

# Databricks workspace authentication
export DATABRICKS_HOST="https://your-workspace.databricks.com"
export DATABRICKS_CLIENT_ID="<service-principal-client-id>"
export DATABRICKS_CLIENT_SECRET="<your-oauth-secret>"

# Lakebase connection details (from prerequisites)
export ENDPOINT_NAME="projects/<project-id>/branches/<branch-id>/endpoints/<endpoint-id>"
export PGHOST="<endpoint-id>.database.<region>.databricks.com"
export PGDATABASE="databricks_postgres"
export PGUSER="<service-principal-client-id>"   # Same UUID as client ID
export PGPORT="5432"

Adicionar código de conexão

curl

Este exemplo mostra as chamadas brutas da API. Para aplicações de produção, implemente o armazenamento em cache de tokens e a lógica refresh .

Bash

# Step 1: Get workspace OAuth token
OAUTH_TOKEN=$(curl -s -X POST "${DATABRICKS_HOST}/oidc/v1/token" \
  -u "${DATABRICKS_CLIENT_ID}:${DATABRICKS_CLIENT_SECRET}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&scope=all-apis" \
  | jq -r '.access_token')

echo "Got workspace OAuth token (60-min lifetime)"

# Step 2: Get database credential
PG_TOKEN=$(curl -s -X POST "${DATABRICKS_HOST}/api/2.0/postgres/credentials" \
  -H "Authorization: Bearer ${OAUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"endpoint\": \"${ENDPOINT_NAME}\"}" \
  | jq -r '.token')

echo "Got database credential (60-min lifetime)"

# Step 3: Connect to Postgres
PGPASSWORD="${PG_TOKEN}" psql \
  -h "${PGHOST}" \
  -p "${PGPORT}" \
  -U "${PGUSER}" \
  -d "${PGDATABASE}" \
  -c "SELECT current_user, current_database()"

Node.js

Este exemplo utiliza node-postgres com uma função assíncrona de senha que lida com a busca e o armazenamento em cache de tokens.

JavaScript

import pg from 'pg';

// Step 1: Fetch workspace OAuth token
async function getWorkspaceToken(host, clientId, clientSecret) {
  const auth = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
  const response = await fetch(`${host}/oidc/v1/token`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: `Basic ${auth}`,
    },
    body: 'grant_type=client_credentials&scope=all-apis',
  });

  if (!response.ok) {
    throw new Error(`OAuth failed: ${response.status}`);
  }

  const data = await response.json();
  return {
    token: data.access_token,
    expires: Date.now() + data.expires_in * 1000,
  };
}

// Step 2: Fetch database credential
async function getPostgresCredential(host, workspaceToken, endpoint) {
  const response = await fetch(`${host}/api/2.0/postgres/credentials`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${workspaceToken}`,
    },
    body: JSON.stringify({ endpoint }),
  });

  if (!response.ok) {
    throw new Error(`Database credential failed: ${response.status}`);
  }

  const data = await response.json();
  return {
    token: data.token,
    expires: new Date(data.expire_time).getTime(),
  };
}

// Simple caching wrapper (production: use more sophisticated caching)
function cached(fetchFn) {
  let cache = null;
  return async (...args) => {
    const now = Date.now();
    if (!cache || now >= cache.expires - 5 * 60 * 1000) {
      // Refresh 5 min early
      const result = await fetchFn(...args);
      cache = result;
    }
    return cache.token;
  };
}

// Create connection pool with async password function
function createPool() {
  const host = process.env.DATABRICKS_HOST;
  const clientId = process.env.DATABRICKS_CLIENT_ID;
  const clientSecret = process.env.DATABRICKS_CLIENT_SECRET;
  const endpoint = process.env.ENDPOINT_NAME;

  const cachedWorkspaceToken = cached(() => getWorkspaceToken(host, clientId, clientSecret));
  const cachedPostgresToken = cached(async () => {
    const workspaceToken = await cachedWorkspaceToken();
    return getPostgresCredential(host, workspaceToken, endpoint);
  });

  return new pg.Pool({
    host: process.env.PGHOST,
    port: process.env.PGPORT,
    database: process.env.PGDATABASE,
    user: process.env.PGUSER,
    password: cachedPostgresToken, // Async function: () => Promise<string>
    ssl: { rejectUnauthorized: true },
    min: 1,
    max: 10,
    idleTimeoutMillis: 900000, // Example: 15 minutes
    connectionTimeoutMillis: 60000, // Example: 60 seconds
  });
}

// Use the pool
const pool = createPool();
const result = await pool.query('SELECT current_user, current_database()');
console.log('Connected as:', result.rows[0].current_user);

Dependências: pg (node-postgres)

Nota: Node-postgres (pg) aceita uma função assíncrona como senha. A função é chamada sempre que uma nova conexão é criada, garantindo tokens novos.

execução e verifique a conexão

curl

execute o script bash com variável de ambiente carregada:

Bash

export $(cat .env | xargs)
bash connect.sh

Resultado esperado:

Got workspace OAuth token (60-min lifetime)
Got database credential (60-min lifetime)
     current_user      | current_database
-----------------------+------------------
 c00f575e-d706-4f6b... | databricks_postgres

Se current_user corresponder ao seu ID de cliente da entidade de serviço, OAuth está funcionando corretamente.

Node.js

Instalar dependências:

Bash

npm install pg

execução:

Bash

node app.js

Resultado esperado:

Connected as: c00f575e-d706-4f6b-b62c-e7a14850571b

Observação: A primeira conexão após o Parado pode demorar mais, pois o dimensionamento automático do Lakebase inicia compute a partir do zero.

Solução de problemas

Erro	Consertar
"cliente inválido" ou "Autenticação de cliente ausente"	Verifique DATABRICKS_CLIENT_ID e DATABRICKS_CLIENT_SECRET estão corretos. Use autenticação básica (codificada em base64).
"API está desativada para usuários sem direito de acesso workspace ."	Habilite o "acesso ao espaço de trabalho" para a entidade de serviço (pré-requisitos).
"VALOR_DE_PARÂMETRO_INVÁLIDO" / "O campo 'endpoint' é obrigatório"	Certifique-se de que o parâmetro endpoint esteja incluído no corpo POST do passo 2 com formato projects/<id>/branches/<id>/endpoints/<id>.
"A função não existe" ou a autenticação falhou	Criar função OAuth via SQL (pré-requisitos).
"Conexão recusada" ou tempo limite excedido	A primeira conexão após a redução de escala para zero pode demorar mais. Implementar lógica de repetição.
Tokens expirados / "Falha na autenticação da senha"	tokens de espaço de trabalho e de banco de dados expiram após 60 minutos. Implemente o armazenamento em cache com verificações de expiração.