Nesta página, descrevemos como gerenciar um banco de dados do Spanner, incluindo como criar, modificar e excluir um banco de dados. Para saber como atualizar um esquema de banco de dados, consulte Fazer atualizações de esquema.
Para praticar a criação de um banco de dados e o carregamento com dados de amostra, consulte o codelab Seu primeiro banco de dados.
criar um banco de dados
Os exemplos a seguir mostram como criar um banco de dados em uma instância atual.
Para bancos de dados de dialeto GoogleSQL, é possível definir o esquema do banco de dados no momento da criação dele ou após a criação. Para bancos de dados do dialeto PostgreSQL, você precisa definir o esquema após a criação.
Os esquemas são definidos usando a linguagem de definição de banco de dados, documentada para GoogleSQL e PostgreSQL. Consulte os links a seguir para mais informações sobre como criar e atualizar esquemas:
Depois de criar o banco de dados, é possível proteger os bancos de dados importantes para seus aplicativos e serviços ativando a proteção contra exclusão de bancos de dados. Para mais informações, consulte Evitar a exclusão acidental do banco de dados.
Console
Acesse a página Instâncias no console do Google Cloud.
Selecione a instância em que o banco de dados será criado.
Clique em Criar banco de dados.
Digite os seguintes valores:
- O nome de banco de dados a ser exibido no console do Google Cloud.
- O dialeto a ser usado para este banco de dados.
- Para bancos de dados de dialetos do GoogleSQL, é possível fornecer um conjunto de instruções DDL que definem seu esquema. Use os modelos DDL para preencher previamente elementos comuns. Se houver erros nas instruções de DDL, o console do Google Cloud retornará um erro quando você tentar criar o banco de dados.
- Se quiser, selecione uma chave de criptografia gerenciada pelo cliente para usar no banco de dados.
Clique em Criar para criar o banco de dados.
gcloud
Use o comando gcloud spanner databases create
.
gcloud spanner databases create DATABASE \
--instance=INSTANCE \
[--async] \
[--database-dialect=DATABASE_DIALECT] \
[--ddl=DDL] \
[--ddl-file=DDL_FILE] \
[--kms-key=KMS_KEY : --kms-keyring=KMS_KEYRING --kms-location=KMS_LOCATION --kms-project=KMS_PROJECT] \
[GCLOUD_WIDE_FLAG …]
As seguintes opções são obrigatórias:
DATABASE
- ID do banco de dados ou identificador totalmente qualificado para o
banco de dados. Se você especificar o identificador totalmente qualificado, a sinalização
--instance
poderá ser omitida. --instance=INSTANCE
- A instância do Spanner para o banco de dados.
As seguintes opções são opcionais:
--async
- Retorna imediatamente, sem aguardar a conclusão da operação em andamento.
--database-dialect=DATABASE_DIALECT
- O dialeto SQL do banco de dados do Spanner. Precisa ser
um destes:
POSTGRESQL
ouGOOGLE_STANDARD_SQL
. --ddl=DDL
- Instruções DDL (linguagem de definição de dados) separadas por ponto e vírgula a serem executadas
dentro do banco de dados recém-criado. Se houver um erro em qualquer
instrução, o banco de dados não será criado. Essa sinalização será ignorada se
--ddl_file
for definido. Incompatível com os bancos de dados de dialeto PostgreSQL. --ddl-file=DDL_FILE
- Caminho de um arquivo que contém instruções DDL (linguagem de definição de dados) separadas por ponto e vírgula a serem executadas no banco de dados recém-criado. Se houver um erro em alguma instrução, o banco de dados
não será criado. Se
--ddl_file
for definido,--ddl
será ignorado. Incompatível com os bancos de dados de dialeto PostgreSQL.
Se você estiver especificando uma chave do Cloud Key Management Service para usar ao criar o banco de dados, inclua as seguintes opções:
--kms-key=KMS_KEY
- ID da chave ou identificador totalmente qualificado para a chave.
Essa sinalização precisará ser especificada se qualquer um dos outros argumentos desse grupo for especificado. Os outros argumentos poderão ser omitidos se o identificador totalmente qualificado for fornecido.
--kms-keyring=KMS_KEYRING
- ID do keyring do Cloud KMS da chave.
--kms-location=KMS_LOCATION
- Local do Google Cloud para a chave.
--kms-project=KMS_PROJECT
- ID do projeto do Google Cloud para a chave.
Cliente (GoogleSQL)
C++
Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.
Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Go
Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.
Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Java
Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.
Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.
Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
PHP
Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.
Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.
Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Ruby
Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.
Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Atualizar esquema ou opções do banco de dados
É possível atualizar o esquema e as opções do banco de dados usando instruções DDL.
Por exemplo, para adicionar uma coluna a uma tabela, use a seguinte instrução DDL:
GoogleSQL
ALTER TABLE Songwriters ADD COLUMN Publisher STRING(10);
PostgreSQL
ALTER TABLE Songwriters ADD COLUMN Publisher VARCHAR(10);
Para atualizar a versão do otimizador de consultas, use a seguinte instrução DDL:
GoogleSQL
ALTER DATABASE Music SET OPTIONS(optimizer_version=null);
PostgreSQL
ALTER DATABASE DB-NAME SET spanner.optimizer_version TO DEFAULT;
Para mais informações sobre as opções aceitas, consulte a referência DDL ALTER DATABASE
para GoogleSQL ou PostgreSQL.
Para informações sobre atualizações de esquema, consulte Fazer atualizações de esquema.
Console
Acesse a página Instâncias no console do Google Cloud.
Selecione a instância que contém o banco de dados a ser alterado.
Selecione o banco de dados.
Clique em Spanner Studio.
Clique em
Nova guia ou use a guia do editor vazia. Em seguida, insira as instruções DDL a serem aplicadas.Clique em Executar para aplicar as atualizações. Se houver erros no DDL, o console do Google Cloud retornará um erro e o banco de dados não será alterado.
gcloud
Para alterar um banco de dados com a ferramenta de linha de comando gcloud
, use
gcloud spanner databases ddl update
.
gcloud spanner databases ddl update \ (DATABASE : --instance=INSTANCE) \ [--async] \ [--ddl=DDL] \ [--ddl-file=DDL_FILE] \
Consulte a
referência do gcloud
para
detalhes sobre as opções disponíveis.
Transmita as atualizações do banco de dados para o comando com a sinalização --ddl
ou
--ddl-file
. Se um arquivo DDL for especificado, a sinalização --ddl
será ignorada.
Consulte a referência DDL ALTER DATABASE
para GoogleSQL ou PostgreSQL para saber quais instruções DDL serão incluídas.
DDL
Consulte a referência DDL ALTER DATABASE
para GoogleSQL ou PostgreSQL para saber mais.
Verificar o progresso das operações de atualização do esquema
Console
No menu de navegação do Spanner, selecione a guia Operações. A página Operações mostra uma lista das operações em execução no momento.
Encontre a operação de esquema na lista. Se ainda estiver em execução, a barra de progresso na coluna Horário de término mostrará a porcentagem da operação concluída, conforme mostrado na imagem a seguir:
gcloud
Use gcloud spanner operations describe
para verificar o progresso de uma operação.
Consiga o ID da operação:
gcloud spanner operations list --instance=INSTANCE-NAME \ --database=DATABASE-NAME --type=DATABASE_UPDATE_DDL
Substitua:
- INSTANCE-NAME pelo nome da instância do Spanner.
- DATABASE-NAME pelo nome do banco de dados.
Execute
gcloud spanner operations describe
:gcloud spanner operations describe OPERATION_ID\ --instance=INSTANCE-NAME \ --database=DATABASE-NAME
Substitua:
- OPERATION-ID: o ID da operação que você quer verificar.
- INSTANCE-NAME: o nome da instância do Spanner.
- DATABASE-NAME: o nome do banco de dados do Spanner.
A seção
progress
na saída mostra a porcentagem de conclusão da operação. A resposta será semelhante a:done: true metadata: ... progress: - endTime: '2022-03-01T00:28:06.691403Z' progressPercent: 100 startTime: '2022-03-01T00:28:04.221401Z' - endTime: '2022-03-01T00:28:17.624588Z' startTime: '2022-03-01T00:28:06.691403Z' progressPercent: 100 ...
REST v1
Consiga o ID da operação:
gcloud spanner operations list --instance=INSTANCE-NAME \ --database=DATABASE-NAME --type=DATABASE_UPDATE_DDL
Substitua:
- INSTANCE-NAME pelo nome da instância do Spanner.
- DATABASE-NAME pelo nome do banco de dados.
Verificar o progresso da operação.
Antes de usar os dados da solicitação, faça as substituições a seguir:
- PROJECT-ID: o ID do projeto.
- INSTANCE-ID: o ID da instância
- DATABASE-ID: o ID do banco de dados.
- OPERATION-ID: o ID da operação.
Método HTTP e URL:
GET https://spanner.googleapis.com/v1/projects/PROJECT-ID/instances/INSTANCE-ID/databases/DATABASE-ID/operations/OPERATION-ID
Para enviar a solicitação, expanda uma destas opções:
Você receberá uma resposta JSON semelhante a esta:
{ ... "progress": [ { "progressPercent": 100, "startTime": "2023-05-27T00:52:27.366688Z", "endTime": "2023-05-27T00:52:30.184845Z" }, { "progressPercent": 100, "startTime": "2023-05-27T00:52:30.184845Z", "endTime": "2023-05-27T00:52:40.750959Z" } ], ... "done": true, "response": { "@type": "type.googleapis.com/google.protobuf.Empty" } }
Se a operação demorar muito, será possível cancelá-la. Para mais informações, consulte Cancelar uma operação de banco de dados de longa duração.
Excluir um banco de dados
A exclusão de um banco de dados remove permanentemente o banco de dados e todos os respectivos dados. A exclusão do banco de dados não pode ser desfeita. Se a proteção contra exclusão de banco de dados estiver ativada em um banco de dados, não será possível excluir esse banco de dados até que você desative a proteção contra exclusão.
Os backups atuais não são excluídos quando um banco de dados é excluído. Para mais informações, consulte Backup e restauração.
Console
Acesse a página Instâncias no console do Google Cloud.
Selecione a instância que contém o banco de dados a ser excluído.
Selecione o banco de dados.
Clique em Excluir banco de dados. Uma confirmação vai aparecer.
Digite o nome do banco de dados e clique em Excluir.
gcloud
Para excluir um banco de dados com a ferramenta de linha de comando gcloud
, use
gcloud spanner databases delete
.
gcloud spanner databases delete \ (DATABASE : --instance=INSTANCE)
As seguintes opções são obrigatórias:
DATABASE
- ID do banco de dados ou identificador totalmente qualificado para o banco de dados. Se o identificador totalmente qualificado for fornecido, a sinalização
--instance
precisará ser omitida. --instance=INSTANCE
- A instância do Spanner para o banco de dados.
Para mais detalhes, consulte a
referência do gcloud
.
DDL
A DDL não oferece suporte à sintaxe de exclusão do banco de dados.
A seguir
- Crie um banco de dados e carregue-o com dados de amostra.
- Saiba mais sobre a referência de DDL do GoogleSQL.
- Saiba mais sobre a referência da DDL do PostgreSQL.
- Saiba como fazer backup e restaurar um banco de dados.
- Saiba como evitar a exclusão acidental do banco de dados.
- Saiba como fazer atualizações de esquema.