Objetivos
Este tutorial orienta você nas etapas a seguir usando a biblioteca de cliente do Cloud Spanner para PHP:
- Criar uma instância e um banco de dados do Cloud 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 Cloud Spanner, que é um componente faturável do Google Cloud. Para informações sobre o custo de utilização do Cloud 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.
Preparar o ambiente PHP local
Siga as etapas descritas em Contas de serviço para configurar uma conta de serviço como suas Application Default Credentials. Siga essas etapas para ter um arquivo de chave da conta de serviço (em JSON) e uma variável de ambiente
GOOGLE_APPLICATION_CREDENTIALS
que permitirão a autenticação na API Cloud Spanner.Instale os seguintes itens na sua máquina de desenvolvimento se ainda não estiverem instalados:
Clone o repositório do aplicativo de amostra na máquina local:
git clone https://github.com/GoogleCloudPlatform/php-docs-samples
Outra alternativa é fazer download da amostra como um arquivo zip e extraí-la.
Altere para o diretório que contém o código de amostra do Cloud Spanner:
cd php-docs-samples/spanner
Instale as dependências:
composer install
Isso instalará a biblioteca de cliente do Cloud Spanner para PHP, que pode ser adicionada a qualquer projeto pela execução de
composer require google/cloud-spanner
.
Crie uma instância
Ao usar o Cloud Spanner pela primeira vez, é necessário criar uma instância, que é uma alocação de recursos usados pelos bancos de dados do Cloud 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 Cloud 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. Saiba mais em 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 Contagem de nós.
Você verá:
Creating instance...done.
Analisar os arquivos de amostra
O repositório de amostras contém uma amostra que demonstra como usar o Cloud Spanner com PHP.
Confira as funções em src/create_database.php
e src/add_column.php
, que mostram como criar um banco de dados e modificar um esquema de banco de dados. Os dados usam o esquema de exemplo exibido na página Esquema e modelo de dados.
Crie um banco de dados
Crie um banco de dados chamado example-db
na instância denominada test-instance
executando o seguinte comando na linha de comando.
php spanner.php create-database test-instance example-db
Você verá:
Created database example-db on instance test-instance
Você acabou de criar um banco de dados do Cloud Spanner. Veja a seguir o código usado na criação do banco de dados.
O código também define duas tabelas, Singers
e Albums
, para um aplicativo básico de música. Essas tabelas são usadas em toda esta página. Caso ainda não tenha feito isso, confira o exemplo de esquema.
A próxima etapa é gravar dados no seu banco de dados.
Criar um cliente de banco de dados
Para fazer leituras e gravações, é preciso ter uma instância doGoogle\Cloud\Spanner\Database
.
Pense em um Database
como uma conexão de banco de dados: todas as suas interações com o Cloud Spanner precisam passar por um Database
. Normalmente, você cria um Database
quando seu aplicativo é iniciado, depois reutiliza esse Database
para ler, gravar e executar transações. Cada cliente usa recursos no Cloud Spanner.
Se você criar vários clientes no mesmo aplicativo, chame
Database::close
para limpar os recursos do cliente, incluindo as conexões de rede, assim que ele
não for mais necessário.
Leia mais na referência de Database
.
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 comando write-data-with-dml
.
php spanner.php write-data-with-dml test-instance example-db
Você verá:
Inserted 4 row(s).
Gravar dados com mutações
Também é possível inserir dados usando mutações.
Grave dados usando o método Database::insertBatch
(em inglês). insertBatch
adiciona novas linhas a uma tabela. Todas as inserções em um único lote são aplicadas atomicamente.
Este código mostra como gravar dados usando mutações:
Execute a amostra usando o comando insert-data
.
php spanner.php insert-data test-instance example-db
Você verá:
Inserted data.
Consultar dados usando SQL
O Cloud Spanner é compatível com uma interface SQL nativa para leitura de dados, que você pode acessar na linha de comando usando a CLI do Google Cloud ou de maneira programática usando a biblioteca de cliente do Cloud Spanner para PHP.
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
Com a biblioteca de cliente do Cloud Spanner para PHP
Além de executar uma instrução SQL na linha de comando, você pode emitir a mesma instrução SQL de maneira programática usando a biblioteca de cliente do Cloud Spanner para PHP.
UseDatabase::execute()
(em inglês) para executar a consulta SQL.
Veja como emitir a consulta e acessar os dados:
Execute a amostra usando o comando query-data
.
php spanner.php query-data test-instance example-db
Você verá o seguinte resultado:
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold Your Peace
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 3, AlbumTitle: Terrified
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
Seus resultados não serão exibidos necessariamente nessa ordem. Se precisar manter a ordem do resultado, use uma cláusula ORDER BY
, conforme documentado em Práticas recomendadas de SQL.
Consulta usando um parâmetro SQL
É possível incluir valores personalizados em instruções SQL usando tipos do SQL compatíveis.
Veja um exemplo de como usar @lastName
como um parâmetro na cláusula WHERE
para
consultar registros que contêm um valor específico para LastName
.
Execute a amostra usando o comando query-data-with-parameter.
php spanner.php query-data-with-parameter test-instance example-db
Você verá o resultado a seguir:
SingerId: 12, FirstName: Melissa, LastName: Garcia
Ler dados usando a API de leitura
Além da interface SQL, o Cloud Spanner também é compatível com uma interface de leitura.
Use Database::read()
para ler as 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 comando read-data
.
php spanner.php read-data test-instance example-db
Você verá uma saída como:
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold your Peace
SingerId: 2, AlbumId: 3, AlbumTitle: 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 Cloud Spanner é compatível com atualizações de esquema em um banco de dados enquanto esse banco continua a disponibilizar o tráfego. Para fazer atualizações no esquema, não é necessário desconectar o banco de dados, nem bloquear 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 Atualizações de esquema.
Adicionar uma coluna
É possível adicionar uma coluna na linha de comando usando a CLI do Google Cloud ou programaticamente usando a biblioteca de cliente do Cloud Spanner para PHP.
Na linha de comando
Use o seguinte comando ALTER TABLE
para adicionar a nova coluna à tabela:
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='ALTER TABLE Albums ADD COLUMN MarketingBudget INT64'
Você verá:
Schema updating...done.
Com a biblioteca de cliente do Cloud Spanner para PHP
Use Database::updateDdl
para modificar o esquema:
Execute a amostra usando o comando add-column
.
php spanner.php add-column test-instance example-db
Você verá:
Added the 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 comando update-data
.
php spanner.php update-data test-instance example-db
Você verá:
Updated data.
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:
Para executar essa consulta, execute a amostra usando o argumento query-data-with-new-column
.
php spanner.php query-data-with-new-column test-instance example-db
Você verá:
SingerId: 1, AlbumId: 1, MarketingBudget: 100000
SingerId: 1, AlbumId: 2, MarketingBudget: 0
SingerId: 2, AlbumId: 1, MarketingBudget: 0
SingerId: 2, AlbumId: 2, MarketingBudget: 500000
SingerId: 2, AlbumId: 3, MarketingBudget: 0
Atualizar dados
É possível atualizar dados usando DML em uma transação de leitura/gravação.
Use o método executeUpdate()
para executar uma instrução DML.
Execute a amostra usando o comando write-data-with-dml-transaction
.
php spanner.php write-data-with-dml-transaction test-instance example-db
Você verá:
Transaction complete.
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. Como outras atualizações de esquema, o Cloud Spanner é compatível com a adição de um índice enquanto o banco de dados continua a disponibilizar o tráfego. O Cloud Spanner preenche automaticamente o índice 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 o preenchimento de índices.
Depois que você adiciona um índice secundário, o Cloud 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 Cloud Spanner para PHP.
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.
Com a biblioteca de cliente do Cloud Spanner para PHP
Use Database::updateDdl
para adicionar um índice:
Execute a amostra usando o comando create-index
.
php spanner.php create-index 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 Cloud Spanner usa automaticamente um índice apropriado. Na interface de leitura, especifique o índice em sua solicitação.
Para usar o índice na interface de leitura, use o método Database::read
.
Execute a amostra usando o comando read-data-with-index
.
php spanner.php read-data-with-index test-instance example-db
Você verá:
AlbumId: 2, AlbumTitle: Forever Hold your Peace
AlbumId: 2, AlbumTitle: Go, Go, Go
AlbumId: 1, AlbumTitle: Green
AlbumId: 3, AlbumTitle: Terrified
AlbumId: 1, AlbumTitle: Total Junk
Adicionar um índice com uma cláusula STORING
Talvez você tenha percebido que o exemplo de leitura acima não incluiu a leitura da coluna MarketingBudget
. Isso ocorre porque a interface de leitura do Cloud Spanner não é compatível com a capacidade de fazer a junção de um índice a uma tabela de dados para pesquisar 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
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) STORING (MarketingBudget)'
A adição do índice pode levar alguns minutos. Depois da adição, você verá:
Schema updating...done.
Com a biblioteca de cliente do Cloud Spanner para PHP
UseDatabase::updateDdl
para adicionar um índice com uma cláusula STORING
:
Execute a amostra usando o comando create-storing-index
.
php spanner.php create-storing-index test-instance example-db
Você verá:
Added the 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 comando read-data-with-storing-index
.
php spanner.php read-data-with-storing-index test-instance example-db
Você verá uma saída como:
AlbumId: 2, AlbumTitle: Forever Hold your Peace, MarketingBudget: 300000
AlbumId: 2, AlbumTitle: Go, Go, Go, MarketingBudget: 0
AlbumId: 1, AlbumTitle: Green, MarketingBudget: 0
AlbumId: 3, AlbumTitle: Terrified, MarketingBudget: 0
AlbumId: 1, AlbumTitle: Total Junk, MarketingBudget: 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 Snapshot
para executar transações somente leitura. Use o método Database::snapshot
para obter um objeto Snapshot
.
Veja a seguir como executar uma consulta e fazer uma leitura na mesma transação somente leitura.
Execute a amostra usando o comando read-only-transaction
.
php spanner.php read-only-transaction test-instance example-db
Você verá uma saída como:
Results from first read:
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold Your Peace
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 3, AlbumTitle: Terrified
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
Results from second read:
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
SingerId: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold Your Peace
SingerId: 2, AlbumId: 3, AlbumTitle: 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
No Console do Cloud
Acesse a página Instâncias do Cloud 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
No Console do Cloud
Acesse a página Instâncias do Cloud 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
Acesse o Cloud Spanner em uma instância de máquina virtual: crie uma instância de máquina virtual com acesso ao seu banco de dados do Cloud Spanner.
Saiba mais sobre credenciais de autorização e autenticação em Primeiros passos da autenticação.
Saiba mais sobre os conceitos do Cloud Spanner.