Objetivos
En este tutorial se explican los siguientes pasos mediante la biblioteca de cliente de Spanner para Java:
- Crea una instancia y una base de datos de Spanner.
- Escribir, leer y ejecutar consultas SQL sobre datos en la base de datos.
- Actualizar el esquema de la base de datos.
- Actualizar datos mediante una transacción de lectura y escritura.
- Agregar un índice secundario a la base de datos.
- Usar el índice para leer los datos y ejecutar consultas SQL sobre ellos.
- Recuperar datos mediante una transacción de solo lectura.
Costes
En este tutorial se usa Spanner, que es un componente facturable deGoogle Cloud. Para obtener información sobre el coste de usar Spanner, consulta la página Precios.
Antes de empezar
Sigue los pasos que se describen en la sección Configuración, donde se explica cómo crear y definir un proyecto predeterminado Google Cloud , habilitar la facturación y la API Cloud Spanner, y configurar OAuth 2.0 para obtener las credenciales de autenticación que se usarán con la API Cloud Spanner.
En concreto, asegúrate de ejecutar gcloud auth
application-default login
para configurar tu entorno de desarrollo local con credenciales de autenticación.
Preparar el entorno de Java local
Instala los elementos indicados a continuación en la máquina de desarrollo si aún no están instalados:
Clona el repositorio de aplicaciones de muestra en la máquina local:
git clone https://github.com/googleapis/java-spanner.git
Cambia al directorio que contiene el código de ejemplo de Spanner:
cd java-spanner/samples/snippets
Genera el archivo JAR de ejemplo:
mvn clean package
Crear una instancia
La primera vez que uses Spanner, debes crear una instancia, que es una asignación de recursos que utilizan las bases de datos de Spanner. Cuando creas una instancia, tienes que elegir una configuración de instancia, que determina dónde se almacenan tus datos y la cantidad de nodos que se van a usar, lo que permite conocer la cantidad de recursos de almacenamiento y publicación de la instancia.
Consulta Crear una instancia para saber cómo crear una instancia de Spanner con cualquiera de los siguientes métodos. Puedes llamar a tu instancia test-instance
para usarla con otros temas de este documento que hagan referencia a una instancia llamada test-instance
.
- Google Cloud CLI
- La Google Cloud consola
- Una biblioteca de cliente (C++, C#, Go, Java, Node.js, PHP, Python o Ruby)
Consultar los archivos de muestra
El repositorio de ejemplos contiene un ejemplo que muestra cómo usar Spanner con Java.
Crear una base de datos
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
Deberías ver lo siguiente:
Created database [example-db]
GoogleSQL
PostgreSQL
El siguiente paso consiste en escribir datos en la base de datos.
Crear un cliente de base de datos
Para poder leer o escribir datos, debes crear unDatabaseClient
.
Puedes considerar un DatabaseClient
como una conexión de base de datos: todas tus interacciones con Spanner deben pasar por un DatabaseClient
. Normalmente, se crea un DatabaseClient
cuando se inicia la aplicación y, a continuación, se reutiliza ese DatabaseClient
para leer, escribir y ejecutar transacciones.
Cada cliente usa recursos en Spanner, por lo que es recomendable cerrar los clientes innecesarios llamando a close()
.
Consulta más información en la DatabaseClient
referencia de Javadoc.
Escribir datos con DML
Puedes insertar datos mediante el lenguaje de manipulación de datos (DML) en una transacción de lectura y escritura.
Utilizas el método executeUpdate()
para ejecutar una instrucción DML.
Ejecuta la muestra con el argumento writeusingdml
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
writeusingdml test-instance example-db
Deberías ver lo siguiente:
4 records inserted.
Escribir datos con mutaciones
También puedes insertar datos mediante mutaciones.
Puedes escribir datos con un objeto Mutation
.
Un objeto Mutation
es un contenedor de operaciones de mutación. Una Mutation
representa una secuencia de inserciones, actualizaciones y eliminaciones que Spanner
aplica de forma atómica a diferentes filas y tablas de una base de datos de Spanner.
El método newInsertBuilder()
de la clase Mutation
crea una mutación INSERT
, que inserta una fila nueva en una tabla. Si ya existe la fila, no se puede escribir. También puedes usar el método newInsertOrUpdateBuilder
para crear una mutación INSERT_OR_UPDATE
, que actualiza los valores de las columnas
si la fila ya existe.
write()
de la clase DatabaseClient
escribe las mutaciones. Todas las mutaciones de un solo lote se aplican de forma atómica.
En este código se muestra cómo escribir los datos mediante mutaciones:
Ejecuta la muestra con el argumento write
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
write test-instance example-db
Debería ver que el comando se ejecuta correctamente.
Consultar datos mediante SQL
Spanner admite una interfaz SQL para leer datos, a la que puedes acceder en la línea de comandos mediante la CLI de Google Cloud o de forma programática con la biblioteca de cliente de Spanner para Java.
En la línea de comandos
Ejecuta la siguiente instrucción SQL para leer los valores de todas las columnas de la tabla Albums
:
gcloud spanner databases execute-sql example-db --instance=test-instance \
--sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'
El resultado muestra lo siguiente:
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 la biblioteca de cliente de Spanner para Java
Además de ejecutar una instrucción SQL en la línea de comandos, puedes emitir la misma instrucción SQL de forma programática mediante la biblioteca de cliente de Spanner para Java.
Los siguientes métodos y clases sirven para ejecutar la consulta SQL:- El método
singleUse()
de la claseDatabaseClient
: úsalo para leer el valor de una o varias columnas de una o varias filas de una tabla de Spanner.singleUse()
devuelve un objetoReadContext
, que se usa para ejecutar una lectura o una instrucción SQL. - El método
executeQuery()
de la claseReadContext
: usa este método para ejecutar una consulta en una base de datos. - La clase
Statement
: úsala para crear una cadena de SQL. - La clase
ResultSet
se usa para acceder a los datos devueltos por una instrucción SQL o una llamada de lectura.
A continuación, se indica cómo emitir la consulta y acceder a los datos:
Ejecuta la muestra con el argumento query
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
query test-instance example-db
El resultado debe ser el siguiente:
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
Consultar usando un parámetro de SQL
Si tu aplicación tiene una consulta que se ejecuta con frecuencia, puedes mejorar su rendimiento parametrizándola. La consulta paramétrica resultante se puede almacenar en caché y reutilizar, lo que reduce los costes de compilación. Para obtener más información, consulta Usar parámetros de consulta para acelerar las consultas que se ejecutan con frecuencia.
Aquí tienes un ejemplo de cómo usar un parámetro en la cláusula WHERE
para consultar registros que contengan un valor específico de LastName
.
GoogleSQL
PostgreSQL
Ejecuta el ejemplo con el argumento queryWithParameter.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
querywithparameter test-instance example-db
El resultado debe ser el siguiente:
12 Melissa Garcia
Leer datos mediante la API de lectura
Además de la interfaz SQL de Spanner, Spanner también admite una interfaz de lectura.
Usa el métodoread()
de la clase ReadContext
para leer filas de la base de datos. Usa un objeto KeySet
para definir una colección de claves e intervalos de claves que se van a leer.
A continuación, mostramos cómo leer los datos:
Ejecuta la muestra con el argumento read
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
read test-instance example-db
El resultado que verás debe parecerse al siguiente:
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
Actualizar el esquema de la base de datos
Supongamos que quiere añadir una nueva columna llamada MarketingBudget
a la tabla Albums
. Para agregar una nueva columna a una tabla existente, es preciso actualizar el esquema de base de datos. Spanner admite actualizaciones de esquemas en una base de datos mientras esta sigue atendiendo tráfico. Para actualizar el esquema, no es necesario desconectar la base de datos y no se bloquean tablas ni columnas completas. Puedes seguir escribiendo datos en la base de datos durante la actualización del esquema. Consulta más información sobre las actualizaciones de esquemas y el rendimiento de los cambios de esquemas admitidos en el artículo Hacer actualizaciones de esquemas.
Añadir una columna
Puedes añadir una columna en la línea de comandos con la CLI de Google Cloud o de forma programática con la biblioteca de cliente de Spanner para Java.
En la línea de comandos
Usa el siguiente comando ALTER TABLE
para añadir la nueva columna a la tabla:
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'
Deberías ver lo siguiente:
Schema updating...done.
Usar la biblioteca de cliente de Spanner para Java
Usa el métodoupdateDatabaseDdl()
de la clase DatabaseAdminClient
para modificar el esquema:
GoogleSQL
PostgreSQL
Ejecuta la muestra con el argumento addmarketingbudget
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
addmarketingbudget test-instance example-db
Deberías ver lo siguiente:
Added MarketingBudget column.
Escribir datos en la nueva columna
El siguiente código sirve para escribir datos en la nueva columna. Define MarketingBudget
como 100000
en la fila con la clave Albums(1, 1)
y como 500000
en la fila con la clave Albums(2, 2)
.
Ejecuta la muestra con el argumento update
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
update test-instance example-db
También puedes ejecutar una consulta SQL o una llamada de lectura para recuperar los valores que acabas de escribir.
Aquí está el código para ejecutar la consulta:
GoogleSQL
PostgreSQL
Para ejecutar esta consulta, ejecuta la muestra con el argumento querymarketingbudget
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
querymarketingbudget test-instance example-db
Deberías ver lo siguiente:
1 1 100000
1 2 NULL
2 1 NULL
2 2 500000
2 3 NULL
Actualizar datos
Puedes actualizar datos mediante DML en una transacción de lectura y escritura.
Utiliza el método executeUpdate()
para ejecutar una instrucción DML.
GoogleSQL
PostgreSQL
Ejecuta la muestra con el argumento writewithtransactionusingdml
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
writewithtransactionusingdml test-instance example-db
Usar un índice secundario
Supongamos que quieres obtener todas las filas de Albums
que tengan valores de AlbumTitle
en un intervalo determinado. Podría leer todos los valores de la columna AlbumTitle
con una instrucción SQL o una llamada de lectura y, a continuación, descartar las filas que no cumplan los criterios, pero hacer este análisis de toda la tabla es caro, sobre todo en el caso de las tablas con muchas filas. En su lugar, puedes acelerar la recuperación de filas al buscar por columnas que no sean de clave principal creando un índice secundario en la tabla.
Para añadir un índice secundario a una tabla existente, es preciso actualizar el esquema. Al igual que otras actualizaciones de esquema, Spanner permite añadir un índice mientras la base de datos sigue sirviendo tráfico. Spanner rellena automáticamente el índice con los datos que ya tengas. Los rellenos pueden tardar unos minutos en completarse, pero no es necesario que pongas la base de datos sin conexión ni que evites escribir en la tabla indexada durante este proceso. Para obtener más información, consulta Añadir un índice secundario.
Después de añadir un índice secundario, Spanner lo usa automáticamente en las consultas de SQL que probablemente se ejecuten más rápido con el índice. Si usas la interfaz de lectura, debes especificar el índice que quieras usar.
Añadir un índice secundario
Puedes añadir un índice en la línea de comandos con la CLI de gcloud o de forma programática con la biblioteca de cliente de Spanner para Java.
En la línea de comandos
Usa el siguiente comando CREATE INDEX
para añadir un índice a la base de datos:
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)'
Deberías ver lo siguiente:
Schema updating...done.
Usar la biblioteca de cliente de Spanner para Java
Usa el métodoupdateDatabaseDdl()
de la clase DatabaseAdminClient
para añadir un índice:
Ejecuta la muestra con el argumento addindex
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
addindex test-instance example-db
Añadir un índice es un proceso que puede llevar unos minutos. Esto es lo que debes ver después de añadir el índice:
Added the AlbumsByAlbumTitle index.
Leer datos mediante el índice
En el caso de las consultas de SQL, Spanner usa automáticamente un índice adecuado. En la interfaz de lectura, debe especificar el índice en su solicitud.
Para usar el índice en la interfaz de lectura, utiliza el método readUsingIndex()
de la clase ReadContext
.
El siguiente código obtiene todas las columnas AlbumId
y AlbumTitle
del índice AlbumsByAlbumTitle
.
Ejecuta la muestra con el argumento readindex
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
readindex test-instance example-db
Deberías ver lo siguiente:
2 Forever Hold Your Peace
2 Go, Go, Go
1 Green
3 Terrified
1 Total Junk
Añadir un índice para lecturas solo de índice
Puede que hayas observado que en el ejemplo de lectura anterior no se incluye la lectura de la columna MarketingBudget
. Esto se debe a que la interfaz de lectura de Spanner no admite la posibilidad de combinar un índice con una tabla de datos para buscar valores que no estén almacenados en el índice.
Crea una definición alternativa de AlbumsByAlbumTitle
que almacene una copia de MarketingBudget
en el índice.
En la línea de comandos
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ñadir un índice es un proceso que puede llevar unos minutos. Esto es lo que debes ver después de añadir el índice:
Schema updating...done.
Usar la biblioteca de cliente de Spanner para Java
Usa el método updateDatabaseDdl()
de la clase DatabaseAdminClient
para añadir un índice con una cláusula STORING
para GoogleSQL y una cláusula INCLUDE
para PostgreSQL:
GoogleSQL
PostgreSQL
Ejecuta la muestra con el argumento addstoringindex
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
addstoringindex test-instance example-db
Añadir un índice es un proceso que puede llevar unos minutos. Esto es lo que debes ver después de añadir el índice:
Added AlbumsByAlbumTitle2 index
Ahora puedes ejecutar una lectura que obtenga todas las columnas AlbumId
, AlbumTitle
y MarketingBudget
del índice AlbumsByAlbumTitle2
:
Ejecuta la muestra con el argumento readstoringindex
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
readstoringindex test-instance example-db
El resultado que verás debe parecerse al siguiente:
2 Forever Hold Your Peace 300000
2 Go, Go, Go NULL
1 Green NULL
3 Terrified NULL
1 Total Junk 300000
Recuperar datos mediante transacciones de solo lectura
Supongamos que deseas ejecutar más de una lectura en la misma marca de tiempo. En las transacciones de solo lectura se observa un prefijo uniforme del historial de confirmación de transacción, por lo que la aplicación siempre obtiene datos uniformes.
Usa un objeto ReadOnlyTransaction
para ejecutar transacciones de solo lectura. Usa el método readOnlyTransaction()
de la clase DatabaseClient
para obtener un objeto ReadOnlyTransaction
.
A continuación, se muestra cómo ejecutar una consulta y realizar una lectura en la misma transacción de solo lectura:
Ejecuta la muestra con el argumento readonlytransaction
.
java -jar target/spanner-snippets/spanner-google-cloud-samples.jar \
readonlytransaction test-instance example-db
El resultado que verás debe parecerse al siguiente:
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
Limpieza
Para evitar que se apliquen cargos adicionales en tu cuenta de Facturación de Cloud por los recursos utilizados en este tutorial, elimina la base de datos y la instancia que has creado.
Eliminar la base de datos
Al eliminar una instancia, se eliminan automáticamente todas sus bases de datos. En este paso se muestra cómo eliminar una base de datos sin eliminar una instancia (se seguirían generando costes por la instancia).
En la línea de comandos
gcloud spanner databases delete example-db --instance=test-instance
Usar la Google Cloud consola
Ve a la página Instancias de Spanner de la Google Cloud consola.
Haz clic en la instancia.
Haz clic en la base de datos que quieras eliminar.
En la página sobre detalles de la base de datos, haz clic en Eliminar.
Confirma que deseas eliminar la base de datos y haz clic en Eliminar.
Eliminar la instancia
Al eliminar una instancia, se borran todas las bases de datos creadas en dicha instancia.
En la línea de comandos
gcloud spanner instances delete test-instance
Usar la Google Cloud consola
Ve a la página Instancias de Spanner de la Google Cloud consola.
Haz clic en tu instancia.
Haz clic en Eliminar.
Confirma que deseas eliminar la instancia y haz clic en Eliminar.
Siguientes pasos
- Prueba el módulo Spring Data para Spanner.
Consulta cómo acceder a Spanner con una instancia de máquina virtual.
Consulta información sobre las credenciales de autorización y autenticación en el artículo Autenticarse en servicios de Cloud mediante bibliotecas de cliente.
Consulta más información sobre las prácticas recomendadas para el diseño de esquemas de Spanner.