Criar e gerenciar uma instância de banco de dados

info

O provisionamento Lakebase é a oferta original Lakebase que usa compute de provisionamento que você escala manualmente. Para regiões compatíveis, consulte Disponibilidade por região. Para obter a versão mais recente do Lakebase, com compute, redução de recursos a zero, ramificação e restauração instantânea, consulte a documentação sobre escalonamento automáticoLakebase.

Desde 12 de março de 2026, novas instâncias Lakebase são criadas como projetos de escalonamento automático. As instâncias de provisionamento existentes serão atualizadas automaticamente para escalonamento automático a partir de junho de 2026. Para obter detalhes, consulte Atualização para dimensionamento automático Lakebase.

Para começar a trabalhar com cargas de trabalho OLTP, crie uma instância de banco de dados de provisionamento do Lakebase usando a interface do usuário Databricks , uma chamada API , SDK Python ou CLI.

Criar uma instância de banco de dados

Crie uma instância de banco de dados com o padrão recomendado. Você precisa fornecer um nome de instância (somente de 1 a 63 caracteres, letras e hífens). Como criador, você é o proprietário do banco de dados com a função databricks_superuser.

A maioria dos usuários do site workspace pode criar instâncias de banco de dados pelo site default. Se você encontrar problemas de permissão, consulte permissões de instância de banco de dados.

UI

1. Clique Acesse os aplicativos no canto superior direito e selecione Lakebase Postgres .

2. Clique em provisionamento para abrir a página de instâncias de provisionamento .

3. Clique em Criar instância de banco de dados .

4. Configure sua instância:

   • Nome : Insira um nome para a instância do banco de dados (de 1 a 63 caracteres, somente letras e hífenes).
   • Capacidade : Selecione o tamanho compute (default: 2 CUs). Consulte o tamanho da instância.
   • Política de uso serverless : Selecione uma política de uso para atribuir o uso e o faturamento serverless (opcional). Consulte Políticas de uso serverless.

5. (Opcional) Expanda as Configurações Avançadas para configurar:

   • Criar a partir do pai : Cria um clone copy-on-write a partir de uma instância existente, incluindo dados até um ponto específico no tempo. Consulte Criar a partir do pai.
   • Habilitar HA : Habilite a alta disponibilidade com nós de failover, configure nós secundários legíveis e defina o número de nós de HA. Veja Alta disponibilidade.

6. Clique em Criar .

Python SDK

Python

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.database import DatabaseInstance

# Initialize the Workspace client
w = WorkspaceClient()

# Create a database instance
instance = w.database.create_database_instance(
    DatabaseInstance(
        name="my-database-instance",
        capacity="CU_1"
    )
)

print(f"Created database instance: {instance.name}")
print(f"Connection endpoint: {instance.read_write_dns}")

CLI

Bash

# Create a database instance
databricks database create-database-instance my-database-instance \
  --capacity CU_1

# Create with advanced options (using JSON for more complex parameters)
databricks database create-database-instance \
  --json '{
    "name": "my-database-instance",
    "capacity": "CU_2",
    "retention_window_in_days": 14
  }'

curl

Crie uma instância de banco de dados e especifique uma janela de retenção.

Bash

export PAT=<YOUR_PAT>
export INSTANCE_NAME="instance_name"

> curl -X POST --header "Authorization: Bearer ${DATABRICKS_TOKEN}" https://[your databricks workspace]/api/2.0/database/instances \
--data-binary @- << EOF
{
  "name": "$INSTANCE_NAME",
  "capacity": "CU_1",
  "retention_window_in_days": 14
}
EOF

Configurações avançadas

O senhor também pode configurar esses recursos durante a criação ou após a criação, editando sua instância:

Recurso	Descrição
política de uso de serverless	Selecione uma política de uso para a instância do seu banco de dados para atribuir o uso e o faturamento serverless a orçamentos específicos. Você também pode adicionar tags personalizadas.
Tamanho da instância	escala compute recurso para os requisitos de desempenho de sua carga de trabalho (padrão: 2 CU).
Janela de restauração	Defina a janela de retenção (2-35 dias, default 7 dias) para recuperação pontual.
Alta disponibilidade	Adicione nós de failover para garantir a continuidade dos negócios das cargas de trabalho de produção.
Criar a partir do pai	Crie um clone copy-on-write a partir de uma instância de banco de dados existente.

Parar ou começar uma instância

Para interromper ou iniciar uma instância de banco de dados, o senhor deve ter as permissões CAN MANAGE nela. Para parar ou começar uma instância, use a interface do usuário Databricks, a chamada API, Python SDK, ou CLI.

UI

1. Clique Acesse os aplicativos no canto superior direito e selecione Lakebase Postgres .
2. Clique em provisionamento para abrir a página de instâncias de provisionamento .
3. Clique na instância do banco de dados que o senhor deseja interromper ou começar.
4. Clique em Parar ou começar no canto superior direito da página.

Python SDK

Python

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.database import DatabaseInstance

# Initialize the Workspace client
w = WorkspaceClient()

# Stop a database instance
instance_name = "my-database-instance"
w.database.update_database_instance(
    name=instance_name,
    database_instance=DatabaseInstance(
        name=instance_name,
        stopped=True
    ),
    update_mask="*"
)
print(f"Stopped database instance: {instance_name}")

# Start a database instance
w.database.update_database_instance(
    name=instance_name,
    database_instance=DatabaseInstance(
        name=instance_name,
        stopped=False
    ),
    update_mask="*"
)
print(f"Started database instance: {instance_name}")

CLI

Bash

# Stop a database instance
databricks database update-database-instance my-database-instance '*' \
  --json '{
    "stopped": true
  }'

# Start a database instance
databricks database update-database-instance my-database-instance '*' \
  --json '{
    "stopped": false
  }'

curl

A seguinte chamada de API interrompe uma instância de banco de dados.

Bash

-X PATCH --header "Authorization: Bearer ${DATABRICKS_TOKEN}" https://$WORKSPACE/api/2.0/database/instances/$INSTANCE_NAME \
--data-binary @- << EOF
{
  "stopped": true
}
EOF

O seguinte API chama o senhor de começar uma instância de banco de dados.

Bash

curl -X PATCH --header "Authorization: Bearer ${DATABRICKS_TOKEN}" https://$WORKSPACE/api/2.0/database/instances/$INSTANCE_NAME \
--data-binary @- << EOF
{
  "stopped": false
}
EOF

Comportamento quando interrompido

Comportamento da instância do banco de dados

• Os dados são preservados.
• A instância não pode ser usada para operações de leitura ou gravação.
• As tabelas sincronizadas não servem para leituras.
• O pipeline declarativo (LDP) LakeFlow Spark não detecta instâncias paradas e pode retornar erros.
• Catálogos registrados em instâncias interrompidas não mostram detalhes do esquema na interface do usuário.

Limitações funcionais:

• Você não pode criar nem excluir DatabaseTables ou DatabaseCatalogs.
• Você pode excluir ou redimensionar uma instância interrompida. As mudanças de capacidade entram em vigor quando a instância é reiniciada.
• O senhor pode interromper o pipeline.

Comportamento ao começar

• A instância entra no estado STARTING e se torna AVAILABLE quando estiver pronta.

Limitações

• O LDP não detecta instâncias interrompidas e pode retornar erros.
• Catálogos registrados em instâncias interrompidas não mostram detalhes do esquema na interface do usuário.

Excluir uma instância

Tenha cuidado ao excluir a instância do banco de dados, pois isso excluirá todos os dados associados.

Você deve ter as permissões CAN MANAGE na instância do banco de dados. Se você não for o proprietário das tabelas ou catálogos, deverá reatribuir a propriedade para si mesmo. os administradores do espaço de trabalho podem excluir instâncias de banco de dados que não lhes pertencem.

A Databricks recomenda excluir todos os catálogos associados do Unity Catalog, tabelas sincronizadas e instâncias filhas antes de excluir a instância do banco de dados. Caso contrário, a tentativa de acessar view catálogos ou executar SQL consultas que fazem referência a eles resultará em erros.

UI

1. Clique Acesse os aplicativos no canto superior direito e selecione Lakebase Postgres .
2. Clique em provisionamento para abrir a página de instâncias de provisionamento .
3. Selecione a instância do banco de dados que você deseja excluir.
4. Selecione "Catálogos" na barra lateral do aplicativo Lakebae para view a lista completa de catálogos de banco de dados associados à instância do banco de dados.
5. Para cada catálogo de banco de dados, exclua todas as tabelas sincronizadas, inclusive as que estão localizadas em catálogos gerenciais e não estão registradas como catálogos de banco de dados.
6. Clique em > Excluir catálogo .

Python SDK

Python

from databricks.sdk import WorkspaceClient

# Initialize the Workspace client
w = WorkspaceClient()

# Delete a database instance
instance_name = "my-database-instance"
w.database.delete_database_instance(
    name=instance_name,
    purge=True  # Required to delete the instance
)
print(f"Deleted database instance: {instance_name}")

# Delete with force option (to delete child instances too)
w.database.delete_database_instance(
    name=instance_name,
    force=True,  # Delete child instances too
    purge=True
)

CLI

Bash

# Delete a database instance
databricks database delete-database-instance my-database-instance \
  --purge

# Delete with force option (to delete child instances too)
databricks database delete-database-instance my-database-instance \
  --json '{
    "force": true,
    "purge": true
  }'

curl

purge=true deve ser especificado para excluir uma instância de banco de dados.

Bash

curl -X DELETE --header "Authorization: Bearer ${DATABRICKS_TOKEN}" https://$WORKSPACE/api/2.0/database/instances/$INSTANCE_NAME?purge=true

Atualizar a política de uso serverless de uma instância de banco de dados.

As políticas de utilização de computação sem servidor consistem em tags que são aplicadas a qualquer atividade compute serverless realizada por um usuário atribuído à política. Ao associar uma política de uso serverless a uma instância de banco de dados, você pode atribuir custos de faturamento e uso a políticas específicas, facilitando o rastreamento, o gerenciamento e o controle dos gastos em recursos serverless .

Para atualizar a política de uso de uma instância de banco de dados usando a IU:

1. Clique Acesse os aplicativos no canto superior direito e selecione Lakebase Postgres .
2. Clique em provisionamento para abrir a página de instâncias de provisionamento .
3. Selecione a instância do banco de dados para a qual você deseja atualizar a política de cobrança.
4. Clique em Editar no canto superior direito.
5. Selecione uma política de utilização sem servidor .
6. Clique em Salvar .

capacidade da instância

Para redimensionar uma instância, você precisa ter permissões CAN MANAGE . O redimensionamento pode levar vários minutos e entra em vigor quando a instância é reiniciada.

Cada unidade de capacidade aloca cerca de 16 GB de RAM, juntamente com a CPU associada e recursos SSD locais. Antes de dimensionar, teste e otimize as consultas. O armazenamento escala automaticamente.

UI

1. Clique Acesse os aplicativos no canto superior direito e selecione Lakebase Postgres .
2. Clique em provisionamento para abrir a página de instâncias de provisionamento .
3. Selecione a instância do banco de dados que deseja redimensionar.
4. Clique em Editar no canto superior direito.
5. Utilize o menu suspenso Capacidade para selecionar o novo tamanho da instância.
6. Clique em Salvar .

curl

Bash

curl -X PATCH --header "Authorization: Bearer ${DATABRICKS_TOKEN}" https://$WORKSPACE/api/2.0/database/instances/$INSTANCE_NAME \
--data-binary @- << EOF
{
  "capacity": "CU_4"
}
EOF

Python SDK

Python

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.database import DatabaseInstance

w = WorkspaceClient()
instance_name = "my-database-instance"
w.database.update_database_instance(
    name=instance_name,
    database_instance=DatabaseInstance(name=instance_name, capacity="CU_4"),
    update_mask="*"
)

CLI

Bash

databricks database update-database-instance my-database-instance '*' --capacity CU_4

Monitorar uma instância de banco de dados

Acesse os detalhes na tab de monitoramento da página de detalhes da instância.

1. Clique Acesse os aplicativos no canto superior direito e selecione Lakebase Postgres .
2. Clique em provisionamento para abrir a página de instâncias de provisionamento .
3. Selecione a instância do banco de dados que deseja monitorar.
4. Selecione monitoramento na barra lateral do App Lakebase .

Use os seguintes critérios para analisar tendências de desempenho, identificar possíveis gargalos e avaliar se deve otimizar o uso do aplicativo ou aumentar a capacidade da sua instância:

• Transações por segundo: Mostra a taxa de transferência da transação confirmada. Utilize esta ferramenta para compreender os padrões de carga de trabalho e identificar os períodos de pico de transações. Se esse valor for consistentemente alto, considere otimizar o comportamento do cliente ou aumentar o tamanho da instância.

• Linhas por segundo: Exibe o número de linhas buscadas, retornadas, inseridas, atualizadas e excluídas. "Linhas buscadas" refere-se ao número de linhas retornadas aos clientes. O termo "linhas retornadas" refere-se ao número de linhas lidas pelas consultas. Ajuda a diagnosticar o tipo de carga de trabalho e seu impacto no sistema. Se o desempenho for limitado, considere adicionar índices ou otimizar os padrões de consulta.

• Conexões abertas: Exibe o número de conexões ativas abertas. As conexões consomem recursos da instância. Use isso para avaliar se o agrupamento de conexões do lado do cliente é necessário. Consulte os limites para o número máximo de conexões permitidas.

• Utilização do armazenamento: Indica o uso atual do armazenamento da instância. Se a utilização se aproximar dos limites de provisionamento Lakebase , remova dados ou índices desnecessários. Como alternativa, entre em contato com o suporte para solicitar um aumento de cota.

• Utilização da CPU (%): Mede a utilização da CPU pela instância do banco de dados. O uso elevado da CPU pode indicar uma carga de trabalho computacionalmente intensiva. Considere otimizações no lado da aplicação ou o aumento do tamanho da instância.

• Taxa de transferência de leitura de páginas (%): Reflete o quão próxima a instância está de sua capacidade de leitura de páginas, geralmente causada por falhas de cache. Se o valor for alto, reduza a carga de trabalho ou o conjunto de trabalho, adicione índices, armazene consultas em cache no lado do cliente ou otimize os dados.

• Taxa de acerto do cache de buffer (%): Indica a porcentagem de leituras atendidas a partir da memória. Cargas de trabalho de alto desempenho devem apresentar valores acima de 99%. Taxas baixas sugerem que a carga de trabalho excede a capacidade do cache ou poderia se beneficiar de otimizações.

• Taxa de acerto do cache SSD local (%): Monitora a porcentagem de leituras atendidas pelo cache SSD após uma falha no cache de buffer. Um valor baixo pode aumentar a taxa de transferência de leitura da página. Utilize otimizações semelhantes às do cache de buffer ou considere uma instância maior.

• Impasses por segundo: mede a frequência com que as transações encontram impasses. Esses problemas geralmente ocorrem quando várias transações acessam o mesmo recurso em ordem conflitante. Investigar e refatorar cargas de trabalho para evitar impasses.

Next os passos

• Disponibilize dados lakehouse com tabelas sincronizadas.
• Conecte-se e consulte sua instância de banco de dados.
• registro da instância do banco de dados em Unity Catalog.
• Permitir que outros usuários acessem a instância do banco de dados a partir do Databricks. Consulte a seção sobre gerenciamento de permissões e funções do Postgres.

Limitações e requisitos

As seções a seguir descrevem os limites e os requisitos de configuração para gerenciar instâncias de banco de dados.

• Um workspace permite um máximo de dez instâncias.
• Cada instância suporta até 1000 conexões simultâneas.
• O limite de tamanho lógico para todos os bancos de dados em uma instância é de 2 TB.
• As instâncias do banco de dados são limitadas a um único workspace.

Requisitos de nome de instância

• Deve ter de 1 a 63 caracteres.
• Deve começar com uma carta.
• Pode conter somente caracteres alfanuméricos e hífens.
• Não é possível incluir dois hífens consecutivos.