Conecte aplicativos externos ao Lakebase usando a API.

info

Beta

A partir de 15 de junho, o Lakebase está disponível em Beta no GCP. Consulte Disponibilidade regional para regiões compatíveis.

Este guia mostra como conectar aplicativos externos ao Lakebase usando chamadas diretas de API REST. Use esta 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

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>.cloud.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

Nota: A primeira conexão após o estado parado pode levar mais tempo, pois o Lakebase inicia o compute 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.

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.