Objetivos
Neste tutorial, apresentamos as etapas a seguir usando o driver JDBC do Spanner:
- 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 do 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 JDBC 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-jdbc.git
Altere para o diretório que contém o código de amostra do Spanner:
cd java-spanner-jdbc/samples/snippets
Criar uma instância
Quando você usa o Spanner pela primeira vez, é necessário criar uma instância, que é uma 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 um 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ê vai ver:
Creating instance...done.
Examinar arquivos de amostra
O repositório de amostras contém uma amostra que mostra como usar o Spanner com o JDBC.
Opom.xml
adiciona o driver JDBC do Spanner às dependências do projeto e configura o plug-in do Assembly para criar um arquivo JAR executável com a classe Java definida neste tutorial.
Crie a amostra no
diretório samples/snippets
:
mvn package -DskipTests
criar um banco de dados
Crie um banco de dados chamado example-db
na instância chamada test-instance
executando o seguinte comando na linha de comando.
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
createdatabase test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
createpgdatabase test-instance example-db
Você vai ver:
Created database [projects/my-project/instances/test-instance/databases/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 uma conexão JDBC
Antes de fazer leituras ou gravações, você deve criar umConnection
. Todas as suas interações com o Spanner precisam passar por um Connection
. O nome do banco de dados e outras propriedades são especificados no URL de conexão JDBC e no conjunto java.util.Properties
.
GoogleSQL
PostgreSQL
Para uma lista completa das propriedades compatíveis, consulte Propriedades do URL de conexão.
Cada Connection
usa recursos. Portanto, é recomendável fechar
as conexões quando elas não forem mais necessárias ou usar um pool para
reutilizar as conexões em todo o aplicativo.
Leia mais na referência do Javadoc Connection
.
Conectar o driver JDBC ao emulador
Você pode conectar o driver JDBC ao emulador do Spanner de duas maneiras:
- Defina a variável de ambiente
SPANNER_EMULATOR_HOST
: isso instrui o driver JDBC a se conectar ao emulador. A instância e o banco de dados do Spanner no URL de conexão JDBC precisam existir no emulador. - Adicione
autoConfigEmulator=true
ao URL de conexão: isso instrui o driver JDBC a se conectar ao emulador e a criar automaticamente a instância e o banco de dados do Spanner no URL de conexão JDBC, se não existirem.
Este exemplo mostra como usar a opção de URL de conexão
autoConfigEmulator=true
.
GoogleSQL
PostgreSQL
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 PreparedStatement.executeUpdate()
para executar uma instrução DML.
GoogleSQL
PostgreSQL
Execute a amostra com este comando:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writeusingdml test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writeusingdmlpg test-instance example-db
Você vai ver:
4 records inserted.
Gravar dados com um lote DML
Use os métodos PreparedStatement#addBatch()
e
PreparedStatement#executeBatch()
para executar várias instruções DML em
um lote.
GoogleSQL
PostgreSQL
Execute a amostra com este comando:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writeusingdmlbatch test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writeusingdmlbatchpg test-instance example-db
Você vai ver:
3 records inserted.
Gravar dados com mutações
Também é possível inserir dados usando mutações.
Grave 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 aplica atomicamente a diferentes linhas e tabelas em um banco de dados do Spanner.
O método 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 método newInsertOrUpdateBuilder
para construir uma mutação INSERT_OR_UPDATE
, que atualiza os valores da coluna
se a linha já existir.
write()
na interface CloudSpannerJdbcConnection
grava as mutações. Todas as mutações em um único lote são aplicadas atomicamente.
É possível desencapsular a interface CloudSpannerJdbcConnection
de um Connection
do JDBC do Spanner.
Este código mostra como gravar dados usando mutações:
GoogleSQL
PostgreSQL
Execute a amostra com este comando:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
write test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writepg test-instance example-db
Você vai ver:
Inserted 10 rows.
Consultar dados usando SQL
O Spanner é compatível com uma interface SQL para leitura de dados, que pode ser acessada na linha de comando usando a Google Cloud CLI ou programaticamente usando o driver JDBC do Spanner.
Na linha de comando
Execute a instrução SQL a seguir para ler os valores de todas as colunas da tabela Albums
:
GoogleSQL
gcloud spanner databases execute-sql example-db --instance=test-instance \
--sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'
PostgreSQL
gcloud spanner databases execute-sql example-db --instance=test-instance \
--sql='SELECT singer_id, album_id, album_title 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 o driver JDBC do Spanner
Além de executar uma instrução SQL na linha de comando, é possível emitir a mesma instrução SQL de maneira programática usando o driver JDBC do Spanner.
Os seguintes métodos e classes são usados para executar a consulta SQL:- O método
createStatement()
na interfaceConnection
: use-o para criar um novo objeto de instrução para executar uma instrução SQL. - O método
executeQuery(String)
da classeStatement
: use este método para executar uma consulta em um banco de dados. - Classe
Statement
: use-a para executar uma string SQL. - Classe
ResultSet
: use-a para acessar os dados retornados por uma instrução SQL.
Veja como emitir a consulta e acessar os dados:
GoogleSQL
PostgreSQL
Execute a amostra com este comando:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
query test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
querypg test-instance example-db
O seguinte resultado será exibido:
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 o aplicativo tiver uma consulta executada com frequência, será possível melhorar o desempenho dela parametrizando-a. A consulta paramétrica resultante pode ser armazenada em cache e reutilizada, o que reduz os custos de compilação. Para mais informações, acesse Usar parâmetros de consulta para acelerar as consultas executadas com frequência.
Veja um exemplo de como usar um parâmetro na cláusula WHERE
para
consultar registros que contêm um valor específico para LastName
.
Use um java.sql.PreparedStatement
para executar uma consulta com um parâmetro.
GoogleSQL
PostgreSQL
Execute a amostra com este comando:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
querywithparameter test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
querywithparameterpg test-instance example-db
O seguinte resultado será exibido:
12 Melissa Garcia
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 é compatível com atualizações de esquema para um banco de dados enquanto o banco de dados continua a disponibilizar o tráfego. As atualizações do esquema não exigem que o banco de dados fique off-line e não bloqueiam tabelas ou colunas inteiras. É possível continuar gravando dados no banco de dados durante a atualização do esquema. Leia mais sobre as atualizações de esquemas compatíveis e o desempenho das alterações de esquemas em Fazer atualizações de esquema.
Adicionar uma coluna
É possível adicionar uma coluna na linha de comando usando a Google Cloud CLI ou de maneira programática usando a biblioteca de cliente do Spanner para JDBC.
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 marketing_budget BIGINT'
Você vai ver:
Schema updating...done.
Usar o driver JDBC do Spanner
Use o métodoexecute(String)
da classe java.sql.Statement
para modificar o esquema:
GoogleSQL
PostgreSQL
Execute a amostra com este comando:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
addmarketingbudget test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
addmarketingbudgetpg test-instance example-db
Você vai ver:
Added MarketingBudget column.
Executar um lote DDL
É recomendável executar várias modificações de esquema em um lote. Use o método
addBatch(String)
de java.sql.Statement
para adicionar várias instruções DDL a um lote.
GoogleSQL
PostgreSQL
Execute a amostra com este comando:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
ddlbatch test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
ddlbatchpg test-instance example-db
Você vai ver:
Added Venues and Concerts tables.
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)
.
GoogleSQL
PostgreSQL
Execute a amostra com este comando:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
update test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
updatepg test-instance example-db
A resposta será parecida com esta:
Updated albums
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 esta consulta, execute o seguinte comando:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
querymarketingbudget test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
querymarketingbudgetpg test-instance example-db
Você vai 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.
Defina AutoCommit=false
para executar transações de leitura e gravação no JDBC.
GoogleSQL
PostgreSQL
Execute a amostra com este comando:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writewithtransactionusingdml test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
writewithtransactionusingdmlpg test-instance example-db
Tags de transação e de solicitação
Use tags de transação e tags de solicitação para resolver problemas de transações e consultas no Spanner. É possível definir tags de transação e tags de solicitação no JDBC com as variáveis de sessão TRANSACTION_TAG
e STATEMENT_TAG
.
GoogleSQL
PostgreSQL
Execute a amostra com este comando:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
tags test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
tagspg test-instance example-db
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.
Defina ReadOnly=true
e AutoCommit=false
em um java.sql.Connection
ou use
a instrução SQL SET TRANSACTION READ ONLY
para executar uma transação somente
leitura.
Veja a seguir como executar uma consulta e fazer uma leitura na mesma transação somente leitura.
GoogleSQL
PostgreSQL
Execute a amostra com este comando:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
readonlytransaction test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
readonlytransactionpg test-instance example-db
Você verá um resultado semelhante a este:
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
2 2 Forever Hold Your Peace
1 2 Go, Go, Go
2 1 Green
2 3 Terrified
1 1 Total Junk
Consultas particionadas e otimização de dados
A API partitionQuery
divide uma consulta em partes menores ou partições e usa várias máquinas para buscar as partições em paralelo. Cada partição é identificada por um
token de partição. A API PartitionQuery tem uma latência maior do que a API de consulta
padrão porque se destina apenas a operações em massa, como exportação ou
verificação de todo o banco de dados.
O Data Boost permite que você execute consultas de análise e exportações de dados com impacto quase zero nas cargas de trabalho atuais na instância provisionada do Spanner. O Data Boost só oferece suporte a consultas particionadas.
GoogleSQL
PostgreSQL
Execute a amostra com este comando:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
databoost test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
databoostpg test-instance example-db
Para mais informações sobre como executar consultas particionadas e usar o Data Boost com o driver JDBC, consulte:
- GoogleSQL: Data Boost e instruções de consulta particionadas
- PostgreSQL: Data Boost e instruções de consulta particionadas
DML particionada
A linguagem de manipulação de dados (DML, na sigla em inglês) particionada foi projetada para os seguintes tipos de atualizações e exclusões em massa:
- Limpeza periódica e coleta de lixo.
Preenchimento de novas colunas com valores padrão.
GoogleSQL
PostgreSQL
Execute a amostra com este comando:
GoogleSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
pdml test-instance example-db
PostgreSQL
java -jar target/jdbc-snippets/jdbc-samples.jar \
pdmlpg test-instance example-db
Para mais informações sobre AUTOCOMMIT_DML_MODE
, consulte:
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
- Saiba como Integrar o Spanner ao Spring Data JPA (dialeto GoogleSQL).
- Saiba como Integrar o Spanner com o Spring Data JPA (dialeto PostgreSQL).
- Saiba como Integrar o Spanner ao Hibernate ORM (dialeto GoogleSQL).
- Saiba como Integrar o Spanner ao Hibernate ORM (dialeto PostgreSQL).
- Saiba mais sobre os comandos de gerenciamento de sessão do JDBC (GoogleSQL).
- Saiba mais sobre os comandos de gerenciamento de sessão do JDBC (PostgreSQL).
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 nos serviços do Cloud usando bibliotecas de cliente.
Saiba mais sobre as práticas recomendadas de design de esquemas do Spanner.