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 e o carregamento de um banco de dados 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 do dialeto GoogleSQL, você pode definir o esquema do banco de dados no momento da criação do banco de dados ou após a criação dele. Para bancos de dados do dialeto PostgreSQL, é preciso definir o esquema após a criação.
Os esquemas são definidos usando a linguagem de definição do banco de dados, que é documentada para o GoogleSQL e o PostgreSQL. Consulte os links a seguir para mais informações sobre como criar e atualizar esquemas:
Depois de criar o banco de dados, ative a proteção contra exclusão para proteger os bancos de dados importantes para seus aplicativos e serviços. Para mais informações, consulte Impedir 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:
- Um 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 do dialeto GoogleSQL, você tem a opção de fornecer um conjunto de instruções DDL que definam o esquema. Use os modelos de DDL para preencher previamente elementos comuns. Se houver erros nas instruções 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 do
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
- Retornar 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
,GOOGLE_STANDARD_SQL
. --ddl=DDL
- 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 qualquer
instrução, o banco de dados não será criado. Essa sinalização será ignorada se
--ddl_file
estiver definido. Incompatível com bancos de dados do 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 qualquer instrução, o banco de dados
não será criado. Se
--ddl_file
estiver definido,--ddl
será ignorado. Incompatível com bancos de dados do dialeto PostgreSQL.
Caso você especifique uma chave do Cloud Key Management Service para usar na criação do banco de dados, inclua as seguintes opções:
--kms-key=KMS_KEY
- ID da chave ou identificador totalmente qualificado dela.
Essa sinalização precisa ser especificada se algum dos outros argumentos nesse grupo também for. 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 da 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 para o 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 para o 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 para o 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 para o 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 para o 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 para o 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 para o 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 compatíveis, 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 na 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 as flags --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 ver as instruções DDL a serem incluídas.
DDL
Para mais detalhes, consulte a referência DDL ALTER DATABASE
do GoogleSQL ou do PostgreSQL.
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 do esquema na lista. Se ela ainda estiver em execução, a barra de progresso na coluna Horário de término vai 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 da operação concluída. 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. Não é possível desfazer a exclusão do banco de dados. Se a proteção contra exclusão de banco de dados estiver ativada em um banco de dados, não será possível excluí-lo 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 do banco de dados. Se o identificador totalmente qualificado for fornecido, a sinalização
--instance
deverá 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 de banco de dados.
A seguir
- Crie um banco de dados e carregue-o com dados de amostra.
- Saiba mais sobre a referência do Google SQL DDL.
- Saiba mais sobre a referência do PostgreSQL DDL.
- 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.