Objetivos
Neste tutorial, mostramos as seguintes etapas usando o Spanner biblioteca de cliente para Java:
- Criar uma instância e um banco de dados do Spanner.
- Gravar, ler e executar consultas SQL em dados contidos no banco de dados.
- Atualizar o esquema do banco de dados.
- Atualizar dados usando uma transação de leitura e gravação.
- Adicionar um índice secundário ao banco de dados.
- Usar o índice para ler e executar consultas SQL nos dados.
- Recuperar dados usando uma transação somente leitura.
Custos
Neste tutorial, usamos o Spanner, que é um componente faturável da Google Cloud. Para informações sobre o custo do uso do Spanner, consulte Preços.
Antes de começar
Conclua as etapas descritas em Configurar, que abrangem a criação e a configuração de um projeto padrão do Google Cloud, o faturamento, a API Cloud Spanner e a configuração do OAuth 2.0 para receber credenciais de autenticação para usar a API Cloud Spanner.
Especificamente, execute gcloud auth
application-default login
para configurar o ambiente de desenvolvimento local com credenciais de autenticação.
Prepare seu ambiente Java local
Instale os seguintes itens na sua máquina de desenvolvimento se ainda não estiverem instalados:
- Java 8 JDK (fazer o download).
- Maven 3 (fazer download).
Clone o repositório do app de amostra na máquina local:
git clone https://github.com/googleapis/java-spanner.git
Mude para o diretório que contém o exemplo de código do Spanner:
cd java-spanner/samples/snippets
Criar uma instância
Quando você usa o Spanner pela primeira vez, precisa criar uma instância, que é um alocação de recursos usados pelos bancos de dados do Spanner. Ao criar uma instância, escolha uma configuração que determine onde os dados serão armazenados e também o número de nós a serem usados. Isso determina a quantidade de recursos de exibição e armazenamento na instância.
Execute o seguinte comando para criar uma instância do Spanner na região
us-central1
com 1 nó:
gcloud spanner instances create test-instance --config=regional-us-central1 \
--description="Test Instance" --nodes=1
A instância criada tem as seguintes características:
- Código da instância:
test-instance
- Nome de exibição:
Test Instance
- Configuração da instância:
regional-us-central1
as configurações regionais armazenam dados em uma região, enquanto as configurações multirregionais distribuem dados em várias regiões. Para mais informações, consulte Sobre instâncias. - Um nó
node_count
corresponde à quantidade de recursos de exibição e armazenamento disponíveis aos bancos de dados na instância. Saiba mais em Nós e unidades de processamento.
Você verá:
Creating instance...done.
Consultar os arquivos de amostra
O repositório de amostras contém uma amostra que mostra como usar o Spanner com Java.
Criar um banco de dados
Crie um banco de dados com o nome example-db
na instância com o nome test-instance
ao
executando o seguinte na linha de comando:
GoogleSQL
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
createdatabase test-instance example-db
PostgreSQL
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
createpgdatabase test-instance example-db
Você verá:
Created database [example-db]
O código a seguir cria um banco de dados e duas tabelas no banco de dados.
GoogleSQL
PostgreSQL
O próximo passo é gravar dados no seu banco de dados.
Criar um cliente de banco de dados
Antes de fazer leituras ou gravações, você deve criar umDatabaseClient
.
Pense em uma DatabaseClient
como uma conexão de banco de dados: todas as suas
interações com o Spanner precisam passar por um DatabaseClient
. Normalmente, você cria um DatabaseClient
quando seu aplicativo é iniciado, então você reutiliza esse DatabaseClient
para ler, gravar e executar transações.
GoogleSQL
PostgreSQL
Como cada cliente usa recursos no Spanner, é recomendável fechar
desnecessários chamando close()
.
Leia mais na DatabaseClient
Referência do Javadoc.
Gravar dados com DML
É possível inserir dados usando a linguagem de manipulação de dados (DML, na sigla em inglês) em uma transação de leitura/gravação.
Use o método executeUpdate()
para executar uma instrução DML.
Execute a amostra usando o argumento writeusingdml
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
writeusingdml test-instance example-db
Você verá:
4 records inserted.
Gravar dados com mutações
Também é possível inserir dados usando mutações.
É possível gravar dados usando
um objeto Mutation
.
Um objeto Mutation
é um contêiner para operações de mutação. Um Mutation
representa uma sequência de inserções, atualizações e exclusões que o Spanner
são aplicados atomicamente em diferentes linhas e tabelas em um banco de dados do Spanner.
O newInsertBuilder()
na classe Mutation
constrói uma mutação INSERT
, que insere uma
nova linha em uma tabela. Se a linha já existir, a gravação falhará. Como alternativa,
use o newInsertOrUpdateBuilder
para construir uma mutação INSERT_OR_UPDATE
, que atualiza os valores da coluna
se a linha já existir.
write()
na classe DatabaseClient
grava as mutações. Todas as mutações em um único lote são aplicadas atomicamente.
Este código mostra como gravar dados usando mutações:
Execute a amostra usando o argumento write
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
write test-instance example-db
Você verá o comando executado com sucesso.
Consultar dados usando SQL
O Spanner dá suporte a uma interface SQL para leitura de dados, que pode acesso na linha de comando usando a Google Cloud CLI ou programaticamente usando biblioteca de cliente do Spanner para Java.
Na linha de comando
Execute a instrução SQL a seguir para ler os valores de todas as colunas da tabela Albums
:
gcloud spanner databases execute-sql example-db --instance=test-instance \
--sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'
O resultado será:
SingerId AlbumId AlbumTitle
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
Usar a biblioteca de cliente do Spanner para Java
Além de executar uma instrução SQL na linha de comando, você pode emitir o mesma instrução SQL usando a biblioteca de cliente do Spanner para Java.
Os seguintes métodos e classes são usados para executar a consulta SQL:- O
singleUse()
na classeDatabaseClient
: use-o para ler o valor de um ou mais colunas de uma ou mais linhas em uma tabela do Spanner. Devolução porsingleUse()
Um objetoReadContext
, que é usado para executar uma instrução de leitura ou SQL. - O método
executeQuery()
da classeReadContext
: use este método para executar uma consulta em um banco de dados. - A classe
Statement
: use para criar uma string SQL. - A classe
ResultSet
: use para acessar os dados retornados por uma instrução SQL ou chamada de leitura.
Veja como emitir a consulta e acessar os dados:
Execute a amostra usando o argumento query
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
query test-instance example-db
Você verá o resultado a seguir:
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
Consulta usando um parâmetro SQL
Se seu aplicativo tiver uma consulta executada com frequência, você poderá melhorar seu desempenho ao parametrizar-o. A consulta paramétrica resultante pode ser armazenada em cache e reutilizada, o que reduz os custos de compilação. Para mais informações, consulte Use parâmetros de consulta para acelerar as consultas executadas com frequência.
Aqui está um exemplo de como usar um parâmetro na cláusula WHERE
para
registros de consulta que contêm um valor específico para LastName
.
GoogleSQL
PostgreSQL
Execute a amostra usando o argumento queryWithParameter.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
querywithparameter test-instance example-db
Você verá o resultado a seguir:
12 Melissa Garcia
Ler dados usando a API de leitura
Além da interface SQL, o Spanner também dá suporte a uma interface de leitura automática.
Use o métodoread()
da classe ReadContext
para ler linhas do banco de dados. Use um objeto KeySet
para definir um conjunto de chaves e intervalos de chaves a serem lidos.
Veja como ler os dados:
Execute a amostra usando o argumento read
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
read test-instance example-db
Você verá uma saída como:
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
Atualizar o esquema do banco de dados
Suponha que você precise adicionar uma nova coluna denominada MarketingBudget
à tabela Albums
. Para isso, é necessário atualizar seu esquema de banco de dados. O Spanner dá suporte a atualizações de esquema em um banco de dados, enquanto
o banco de dados continua a disponibilizar o tráfego. As atualizações de esquema não exigem
banco de dados off-line e não bloqueiam tabelas ou colunas inteiras. você pode continuar
gravação de dados no banco de dados durante a atualização do esquema. Leia mais sobre os recursos
e o desempenho das alterações de esquema
Faça atualizações de esquema.
Adicionar uma coluna
É possível adicionar uma coluna na linha de comando usando a Google Cloud CLI ou programaticamente usando biblioteca de cliente do Spanner para Java.
Na linha de comando
Use o seguinte comando ALTER TABLE
para adicionar a nova coluna à tabela:
GoogleSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='ALTER TABLE Albums ADD COLUMN MarketingBudget INT64'
PostgreSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='ALTER TABLE Albums ADD COLUMN MarketingBudget BIGINT'
Você verá:
Schema updating...done.
Usar a biblioteca de cliente do Spanner para Java
Usar oupdateDatabaseDdl()
da classe DatabaseAdminClient
para modificar o esquema:
GoogleSQL
PostgreSQL
Execute a amostra usando o argumento addmarketingbudget
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
addmarketingbudget test-instance example-db
Você verá:
Added MarketingBudget column.
Gravar dados na nova coluna
O código a seguir grava dados na coluna nova. Ele define MarketingBudget
como 100000
para a linha indexada por Albums(1, 1)
e como 500000
para a linha indexada por Albums(2, 2)
.
Execute a amostra usando o argumento update
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
update test-instance example-db
Também é possível executar uma consulta SQL ou uma chamada de leitura para coletar os valores que você acabou de gravar.
Veja a seguir o código para executar a consulta:
GoogleSQL
PostgreSQL
Para executar essa consulta, execute a amostra usando o argumento querymarketingbudget
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
querymarketingbudget test-instance example-db
Você verá:
1 1 100000
1 2 NULL
2 1 NULL
2 2 500000
2 3 NULL
Atualizar dados
É possível atualizar dados usando DML em uma transação de leitura/gravação.
Você usa o executeUpdate()
para executar uma instrução DML.
GoogleSQL
PostgreSQL
Execute a amostra usando o argumento writewithtransactionusingdml
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
writewithtransactionusingdml test-instance example-db
Usar um índice secundário
Suponha que você queira buscar todas as linhas de Albums
que tenham valores AlbumTitle
em um determinado intervalo. É possível ler todos os valores da coluna AlbumTitle
usando uma instrução SQL ou uma chamada de leitura e descartar as linhas que não satisfazem os critérios, mas fazer essa verificação na tabela inteira é caro, especialmente para tabelas com muitas linhas. Em vez disso, acelere a recuperação de linhas ao pesquisar por colunas de chaves não primárias por meio da criação de um índice secundário na tabela.
Adicionar um índice secundário a uma tabela requer uma atualização de esquema. Gostei outras atualizações de esquema, o Spanner oferece suporte à adição de um índice enquanto o banco de dados continua a disponibilizar o tráfego. O Spanner preenche automaticamente o com seus dados atuais. Os preenchimentos podem levar alguns minutos para serem concluídos, mas você não precisa ficar off-line ou evitar gravar na tabela indexada durante esse processo. Para mais detalhes, consulte Adicione um índice secundário.
Depois que você adiciona um índice secundário, o Spanner o usa automaticamente para Consultas SQL que provavelmente serão executadas mais rapidamente com o índice. Se você usar a interface de leitura, deverá especificar o índice que quer usar.
Adicionar um índice secundário
É possível adicionar um índice na linha de comando usando a CLI gcloud ou programaticamente, usando a biblioteca de cliente do Spanner para Java.
Na linha de comando
Use o comando CREATE INDEX
a seguir para adicionar um índice ao banco de dados:
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)'
Você verá:
Schema updating...done.
Como usar a biblioteca de cliente do Spanner para Java
Usar oupdateDatabaseDdl()
da classe DatabaseAdminClient
para adicionar um índice:
Execute a amostra usando o argumento addindex
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
addindex test-instance example-db
A adição do índice pode levar alguns minutos. Depois da adição, você verá:
Added the AlbumsByAlbumTitle index.
Ler usando o índice
Para consultas SQL, o Spanner usa automaticamente um índice adequado. Na interface de leitura, especifique o índice em sua solicitação.
Para usar o índice na interface de leitura, use o método readUsingIndex()
da classe ReadContext
.
O código a seguir busca todas as colunas AlbumId
e AlbumTitle
do índice AlbumsByAlbumTitle
.
Execute a amostra usando o argumento readindex
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
readindex test-instance example-db
Você verá:
2 Forever Hold Your Peace
2 Go, Go, Go
1 Green
3 Terrified
1 Total Junk
Adicionar um índice para leituras somente de índice
Você deve ter notado que o exemplo de leitura anterior não inclui a leitura
na coluna MarketingBudget
. Isso ocorre porque a interface de leitura do Spanner
não oferece suporte à capacidade de mesclar um índice com uma tabela de dados para procurar valores
que não estão armazenados no índice.
Crie uma definição alternativa de AlbumsByAlbumTitle
que armazene uma cópia de MarketingBudget
no índice.
Na linha de comando
GoogleSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) STORING (MarketingBudget)
PostgreSQL
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) INCLUDE (MarketingBudget)
A adição do índice pode levar alguns minutos. Depois da adição, você verá:
Schema updating...done.
Como usar a biblioteca de cliente do Spanner para Java
Usar o updateDatabaseDdl()
método da classe DatabaseAdminClient
para adicionar um índice com um STORING
para GoogleSQL e INCLUDE
para PostgreSQL:
GoogleSQL
PostgreSQL
Execute a amostra usando o argumento addstoringindex
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
addstoringindex test-instance example-db
A adição do índice pode levar alguns minutos. Depois da adição, você verá:
Added AlbumsByAlbumTitle2 index
Agora é possível executar uma leitura que busque todas as colunas AlbumId
, AlbumTitle
e MarketingBudget
do índice AlbumsByAlbumTitle2
:
Execute a amostra usando o argumento readstoringindex
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
readstoringindex test-instance example-db
Você verá uma saída como:
2 Forever Hold Your Peace 300000
2 Go, Go, Go NULL
1 Green NULL
3 Terrified NULL
1 Total Junk 300000
Recuperar dados usando transações somente leitura
Suponha que você queira executar mais de uma leitura no mesmo carimbo de data/hora. As transações somente leitura observam um prefixo consistente do histórico de confirmações da transação. Portanto, o aplicativo sempre recebe dados consistentes.
Use um objeto ReadOnlyTransaction
para executar transações somente leitura. Use o método readOnlyTransaction()
da classe DatabaseClient
para obter um objeto ReadOnlyTransaction
.
Veja a seguir como executar uma consulta e fazer uma leitura na mesma transação somente leitura.
Execute a amostra usando o argumento readonlytransaction
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
readonlytransaction test-instance example-db
Você verá uma saída como:
2 2 Forever Hold Your Peace
1 2 Go, Go, Go
2 1 Green
2 3 Terrified
1 1 Total Junk
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
Limpeza
Para não gerar cobranças extras na sua conta do Google Cloud pelos recursos usados neste tutorial, suspenda o banco de dados e exclua a instância que você criou.
Excluir o banco de dados
Se você excluir uma instância, todos os bancos de dados nela serão excluídos automaticamente. Nesta etapa, mostramos como excluir um banco de dados sem remover a instância. Ainda pode haver cobrança em relação à instância.
Na linha de comando
gcloud spanner databases delete example-db --instance=test-instance
Use o console do Google Cloud
Acesse a página Instâncias do Spanner no console do Google Cloud.
Clique na instância.
Clique no banco de dados que você quer excluir.
Na página Detalhes do banco de dados, clique em Excluir.
Confirme se quer excluir o banco de dados e clique em Excluir.
Excluir a instância
A exclusão de uma instância descarta automaticamente todos os bancos de dados criados nela.
Na linha de comando
gcloud spanner instances delete test-instance
Use o console do Google Cloud
Acesse a página Instâncias do Spanner no console do Google Cloud.
Clique na sua instância.
Clique em Excluir.
Confirme se quer excluir a instância e clique em Excluir.
A seguir
- Teste o módulo Spring Data para o Spanner.
Saiba como acessar o Spanner com uma instância de máquina virtual.
Saiba mais sobre credenciais de autorização e autenticação em Autenticar para do Google Cloud usando bibliotecas de cliente.
Saiba mais sobre as práticas recomendadas de criação de esquemas do Spanner.