Objetivos
En este instructivo, se explican los siguientes pasos con el controlador JDBC de Spanner:
- Crear una instancia y una base de datos de Spanner
- Escribir, leer y ejecutar consultas en SQL en los datos de la base de datos
- Actualiza el esquema de la base de datos.
- Actualiza los datos mediante una transacción de lectura y escritura.
- Agrega un índice secundario a la base de datos.
- Usa el índice para leer y ejecutar consultas en SQL sobre los datos.
- Recupera datos con una transacción de solo lectura.
Costos
En este instructivo, se usa Spanner, que es un componente facturable de Google Cloud. Para obtener información sobre el costo de usar Spanner, consulta Precios.
Antes de comenzar
Completa los pasos que se describen en Configuración, que abarcan la creación y la configuración de un proyecto de Google Cloud predeterminado, la habilitación de la facturación, la habilitación de la API de Cloud Spanner y la configuración de OAuth 2.0 para obtener credenciales de autenticación para usar la API de Cloud Spanner.
En especial, asegúrate de ejecutar gcloud auth
application-default login para configurar tu entorno de desarrollo local con credenciales de autenticación.
Prepara tu entorno de JDBC local
Instala los siguientes componentes en tu máquina de desarrollo si aún no se instalaron:
Clona el repositorio de la app de muestra en tu máquina local:
git clone https://github.com/googleapis/java-spanner-jdbc.gitCambia al directorio que contiene el código de muestra de Spanner:
cd java-spanner-jdbc/samples/snippets
Crea una instancia
La primera vez que uses Spanner, debes crear una instancia, que es una asignación de recursos que usan las bases de datos de Spanner. Cuando creas una instancia, debes elegir una configuración de instancia, que determina dónde se almacenan tus datos y también la cantidad de nodos que se usarán, lo que, a su vez, determina la cantidad de recursos de entrega y almacenamiento de tu instancia.
Consulta Crea una instancia
para aprender a crear una instancia de Spanner con cualquiera de los
siguientes métodos. Puedes asignar el nombre test-instance a tu instancia para usarla con
otros temas de este documento que hagan referencia a una instancia llamada test-instance.
- Google Cloud CLI
- La consola de Google Cloud
- Una biblioteca cliente (C++, C#, Go, Java, Node.js, PHP, Python, Ruby o Rust)
Examina archivos de muestra
El repositorio de muestras contiene un ejemplo que muestra cómo usar Spanner con JDBC.
Elpom.xml agrega el controlador de JDBC de Spanner a las
dependencias del proyecto y configura el complemento de ensamblado para compilar un
archivo JAR ejecutable con la clase de Java definida en este instructivo.
Compila la muestra desde el
directorio samples/snippets:
mvn package -DskipTests
Crea una base de datos
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
Deberías ver lo siguiente:
Created database [projects/my-project/instances/test-instance/databases/example-db]
GoogleSQL
PostgreSQL
El siguiente paso consiste en escribir datos en tu base de datos.
Crea una conexión de JDBC
Para realizar operaciones de lectura o escritura, debes crear unConnection. Todas tus interacciones
con Spanner deben pasar por un Connection. El nombre de la base de datos y otras
propiedades se especifican en la URL de conexión de JDBC y en el
conjunto java.util.Properties.
GoogleSQL
PostgreSQL
Para obtener una lista completa de las propiedades compatibles, consulta Propiedades de la URL de conexión.
Cada Connection usa recursos, por lo que se recomienda cerrar las conexiones cuando ya no sean necesarias o usar un grupo de conexiones para reutilizarlas en toda la aplicación.
Obtén más información en la referencia de Javadoc de Connection.
Conecta el controlador de JDBC al emulador
Puedes conectar el controlador de JDBC al emulador de Spanner de dos maneras:
- Configura la variable de entorno
SPANNER_EMULATOR_HOST: Esto indica al controlador JDBC que se conecte al emulador. La instancia y la base de datos de Spanner en la URL de conexión de JDBC ya deben existir en el emulador. - Agrega
autoConfigEmulator=truea la URL de conexión: Esto indica al controlador de JDBC que se conecte al emulador y que cree automáticamente la instancia y la base de datos de Spanner en la URL de conexión de JDBC si no existen.
En este ejemplo, se muestra cómo usar la opción de URL de conexión autoConfigEmulator=true.
GoogleSQL
PostgreSQL
Escribe datos con DML
Puedes insertar datos mediante el lenguaje de manipulación de datos (DML) en una transacción de lectura y escritura.
Usa el método PreparedStatement.executeUpdate() para ejecutar una sentencia
DML.
GoogleSQL
PostgreSQL
Ejecuta la muestra con 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
Deberías ver lo siguiente:
4 records inserted.
Escribe datos con un lote de DML
Usa los métodosPreparedStatement#addBatch() y
PreparedStatement#executeBatch() para ejecutar varias sentencias DML en
un lote.
GoogleSQL
PostgreSQL
Ejecuta la muestra con 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
Deberías ver lo siguiente:
3 records inserted.
Escribe datos con mutaciones
También puedes insertar datos mediante mutaciones.
Puedes escribir datos con un objeto Mutation.
Este 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 en una base de datos de Spanner.
El método newInsertBuilder()
en la clase Mutation construye una mutación INSERT, que inserta una
fila nueva en una tabla. Si la fila ya existe, la escritura falla. Como alternativa,
puedes usar el método newInsertOrUpdateBuilder
para construir una mutación INSERT_OR_UPDATE, que actualiza los valores de las columnas
si la fila ya existe.
write() de la interfaz CloudSpannerJdbcConnection escribe las mutaciones. Todas
las mutaciones de un solo lote se aplican de forma atómica.
Puedes desenvolver la interfaz CloudSpannerJdbcConnection de un Connection de JDBC de Spanner.
En este código, se muestra cómo escribir los datos mediante mutaciones:
GoogleSQL
PostgreSQL
Ejecuta la muestra con 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
Deberías ver lo siguiente:
Inserted 10 rows.
Consulta datos mediante SQL
Spanner admite una interfaz de SQL para leer datos, a la que puedes acceder en la línea de comandos con Google Cloud CLI o de manera programática con el controlador de JDBC de Spanner.
En la línea de comandos
Ejecuta la siguiente instrucción de SQL para leer los valores de todas las columnas de la
tabla Albums:
GoogleSQL
gcloud spanner databases execute-sql example-db --instance=test-instance \
--sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'
Sintaxis de canalización de GoogleSQL
gcloud spanner databases execute-sql example-db --instance=test-instance \
--sql='FROM Albums |> SELECT SingerId, AlbumId, AlbumTitle'
PostgreSQL
gcloud spanner databases execute-sql example-db --instance=test-instance \
--sql='SELECT singer_id, album_id, album_title 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
Usa el controlador de JDBC de Spanner
Además de ejecutar una instrucción de SQL en la línea de comandos, puedes emitir la misma instrucción de SQL de manera programática con el controlador JDBC de Spanner.
Los siguientes métodos y clases se usan para ejecutar la consulta en SQL:- El método
createStatement()en la interfazConnection: úsalo para crear un objeto de sentencia nuevo para ejecutar una instrucción de SQL. - El método
executeQuery(String)de la claseStatement: usa este método para ejecutar una consulta en una base de datos. - La clase
Statement: Úsala para ejecutar una cadena de SQL. - La clase
ResultSet: Úsala para acceder a los datos que devuelve una instrucción de SQL.
Aquí se muestra cómo enviar la consulta y acceder a los datos:
GoogleSQL
PostgreSQL
Ejecuta la muestra con 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
Deberías ver el siguiente resultado:
1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified
Consulta mediante 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 costos de compilación. Para obtener más información, consulta Usa parámetros de consulta para acelerar las consultas que se ejecutan con frecuencia.
Este es un ejemplo de cómo usar un parámetro en la cláusula WHERE para consultar registros
que contienen un valor específico para LastName.
Usa un java.sql.PreparedStatement
para ejecutar una consulta con un parámetro.
GoogleSQL
PostgreSQL
Ejecuta la muestra con 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
Deberías ver el siguiente resultado:
12 Melissa Garcia
Actualiza el esquema de la base de datos
Supongamos que necesitas agregar una columna nueva llamada MarketingBudget a la tabla Albums. Para agregar una columna nueva a una tabla existente, es necesario actualizar el esquema de la base de datos. Spanner admite actualizaciones del esquema de una base de datos mientras esta sigue entregando tráfico. Las actualizaciones de esquema no requieren que la
base de datos esté sin conexión y no bloquean tablas ni columnas completas. Puedes continuar
escribiendo datos en la base de datos durante la actualización del esquema. Obtén más información sobre las actualizaciones de esquemas compatibles y el rendimiento de los cambios de esquemas en Realiza actualizaciones de esquemas.
Agrega una columna
Puedes agregar una columna en la línea de comandos con Google Cloud CLI o de manera programática con el controlador JDBC de Spanner.
En la línea de comandos
Usa el siguiente comando ALTER TABLE para agregar la columna nueva 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 marketing_budget BIGINT'
Deberías ver lo siguiente:
Schema updating...done.
Usa el controlador de JDBC de Spanner
Usa el métodoexecute(String)
de la clase java.sql.Statement para modificar el esquema:
GoogleSQL
PostgreSQL
Ejecuta la muestra con 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
Deberías ver lo siguiente:
Added MarketingBudget column.
Ejecuta un lote de DDL
Te recomendamos que ejecutes varias modificaciones de esquema en un solo lote. Usa
el
método
addBatch(String)
de java.sql.Statement para agregar varias declaraciones de DDL a un lote.
GoogleSQL
PostgreSQL
Ejecuta la muestra con 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
Deberías ver lo siguiente:
Added Venues and Concerts tables.
Escribe datos en la columna nueva
Con el siguiente código, se escriben datos en la columna nueva. Establece MarketingBudget en
100000 para la clave de fila Albums(1, 1) y en 500000 para la clave de fila
Albums(2, 2).
GoogleSQL
PostgreSQL
Ejecuta la muestra con 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
Deberías ver un resultado similar a este:
Updated albums
También puedes ejecutar una consulta en SQL o una llamada de lectura para recuperar los valores que acabas de escribir.
Este es el código para ejecutar la consulta:
GoogleSQL
PostgreSQL
Para ejecutar esta consulta, ejecuta el siguiente 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
El resultado muestra lo siguiente:
1 1 100000
1 2 null
2 1 null
2 2 500000
2 3 null
Actualiza datos
Puedes actualizar los datos mediante DML en una transacción de lectura y escritura.
Establece AutoCommit=false para ejecutar transacciones de lectura y escritura en JDBC.
GoogleSQL
PostgreSQL
Ejecuta la muestra con 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
Etiquetas de transacción y de solicitud
Usa etiquetas de transacciones y de solicitudes
para solucionar problemas de transacciones y consultas en Spanner. Puedes establecer
etiquetas de transacción y de solicitud en JDBC con las variables de sesión TRANSACTION_TAG
y STATEMENT_TAG.
GoogleSQL
PostgreSQL
Ejecuta la muestra con 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
Recupera datos mediante transacciones de solo lectura
Supongamos que quieres ejecutar más de una lectura en la misma marca de tiempo. En las transacciones de solo lectura, se observa un prefijo coherente del historial de confirmaciones de transacciones, por lo que la aplicación siempre obtiene datos coherentes.
Establece ReadOnly=true y AutoCommit=false en un java.sql.Connection, o usa
la instrucción de SQL SET TRANSACTION READ ONLY para ejecutar una transacción
de solo lectura.
A continuación, se muestra cómo ejecutar una consulta y cómo realizar una lectura en la misma transacción de solo lectura:
GoogleSQL
PostgreSQL
Ejecuta la muestra con 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
Deberías ver un resultado similar 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 y Data Boost
La API de partitionQuery
divide una consulta en partes más pequeñas, o particiones, y usa varias
máquinas para recuperar las particiones en paralelo. Cada partición se identifica con un
token de partición. La API de PartitionQuery tiene una latencia más alta que la API de consulta estándar, ya que solo está diseñada para operaciones masivas, como exportar o analizar toda la base de datos.
Data Boost te permite ejecutar consultas de estadísticas y exportaciones de datos con un impacto casi nulo en las cargas de trabajo existentes de la instancia de Spanner aprovisionada. Data Boost solo admite consultas particionadas.
GoogleSQL
PostgreSQL
Ejecuta la muestra con 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 obtener más información sobre cómo ejecutar consultas particionadas y usar Data Boost con el controlador JDBC, consulta los siguientes vínculos:
- GoogleSQL: Data Boost y sentencias de consulta particionadas
- PostgreSQL: Data Boost y sentencias de consulta particionadas
DML particionado
El lenguaje de manipulación de datos (DML) particionado está diseñado para los siguientes tipos de actualizaciones y eliminaciones masivas:
- Recolección de elementos no usados y limpieza periódicos.
- El restablecimiento de columnas nuevas con valores predeterminados.
PostgreSQL
Ejecuta la muestra con 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 obtener más información sobre AUTOCOMMIT_DML_MODE, consulta los siguientes vínculos:
Limpieza
Para evitar que se apliquen cargos adicionales a tu cuenta de Facturación de Cloud por los recursos que se usaron en este instructivo, borra la base de datos y la instancia que creaste.
Borra la base de datos
Si borras una instancia, se borrarán de forma automática todas las bases de datos que contiene. En este paso, se muestra cómo borrar una base de datos sin borrar una instancia (ten en cuenta que se seguirán generando cargos por la instancia).
En la línea de comandos
gcloud spanner databases delete example-db --instance=test-instance
Usa la consola de Google Cloud
Ve a la página Instancias de Spanner en la consola de Google Cloud .
Haz clic en la instancia.
Haz clic en la base de datos que deseas borrar.
En la página Detalles de la base de datos, haz clic en Borrar.
Confirma que deseas borrar la base de datos y haz clic en Borrar.
Borra la instancia
Si borras una instancia, se descartarán de forma automática todas las bases de datos creadas en ella.
En la línea de comandos
gcloud spanner instances delete test-instance
Usa la consola de Google Cloud
Ve a la página Instancias de Spanner en la consola de Google Cloud .
Haz clic en tu instancia.
Haz clic en Borrar.
Confirma que deseas borrar la instancia y haz clic en Borrar.
¿Qué sigue?
- Obtén información para integrar Spanner en Spring Data JPA (dialecto de GoogleSQL).
- Aprende a integrar Spanner con Spring Data JPA (dialecto de PostgreSQL).
- Obtén información para integrar Spanner con Hibernate ORM (dialecto de GoogleSQL).
- Aprende a integrar Spanner con Hibernate ORM (dialecto de PostgreSQL).
- Obtén más información sobre los comandos de administración de sesiones de JDBC (GoogleSQL).
- Obtén más información sobre los comandos de administración de sesiones de JDBC (PostgreSQL).
Obtén información para acceder a Spanner con una instancia de máquina virtual.
Obtén información sobre las credenciales de autorización y autenticación en Autentícate en los servicios de Cloud con bibliotecas cliente.
Obtén más información sobre las prácticas recomendadas para el diseño de esquemas de Spanner.