Objetivos
Con este tutorial, te explicaremos cómo llevar a cabo estos pasos con la biblioteca cliente de Cloud Spanner para Ruby:
- Crear una instancia y una base de datos de Cloud Spanner.
- Escribir, leer y ejecutar consultas SQL sobre datos de la base de datos.
- Actualizar el esquema de la base de datos.
- Actualizar datos mediante una transacción de lectura y escritura.
- Añadir 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.
Precios
En este tutorial se usa Cloud Spanner, que es un componente facturable de Google Cloud Platform. Si quieres obtener información sobre el coste de usar Cloud Spanner, consulta el apartado de precios.
Antes de empezar
-
Completa los pasos descritos en la sección de configuración, en los que se explica cómo crear y configurar un proyecto predeterminado de Google Cloud Platform en el que se han habilitado la facturación y la API Cloud Spanner y se ha configurado OAuth 2.0 con el fin de obtener credenciales de autenticación para usar la API Cloud Spanner.
En concreto, asegúrate de que ejecutasgcloud auth application-default login
para configurar el entorno de desarrollo local con credenciales de autenticación. -
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/GoogleCloudPlatform/ruby-docs-samples.git
También puedes descargar la muestra como un archivo en formato zip y extraerla.
-
Cambia al directorio que contiene el código de ejemplo de Cloud Spanner:
cd ruby-docs-samples/spanner/
-
Instala las dependencias:
bundle install
-
Establece la variable de entorno GOOGLE_CLOUD_PROJECT en el ID de tu proyecto de Google Cloud Platform:
export GOOGLE_CLOUD_PROJECT=[MY_PROJECT_ID]
Crear una instancia
Cuando uses Cloud Spanner por primera vez, debes crear una instancia, que es una asignación de recursos usada por las bases de datos de Cloud Spanner. Cuando creas una instancia, eliges una configuración de instancia, que determina dónde se almacenan los datos, así como la cantidad de nodos que se usarán, lo que a su vez determina la cantidad de recursos de almacenamiento y de servicio de la instancia.
Ejecuta el siguiente comando para crear una instancia de Cloud Spanner en la región us-central1
con un nodo:
gcloud spanner instances create test-instance --config=regional-us-central1 \
--description="Test Instance" --nodes=1
Ten en cuenta que de este modo se crea una instancia con las siguientes características:
- ID de instancia
test-instance
- Nombre visible
Test Instance
- Configuración de instancia
regional-us-central1
(las configuraciones regionales almacenan datos en una región, mientras que las configuraciones de varias regiones distribuyen datos entre varias regiones; más información en el apartado sobre instancias) - Recuento de nodo de 1 (
node_count
corresponde a la cantidad de recursos de almacenamiento y servicio disponibles para las bases de datos de la instancia; más información en el apartado sobre recuento de nodos)
Deberías ver lo siguiente:
Creating instance...done.
Consultar los archivos de muestra
El repositorio de muestras contiene una en la que se explica cómo usar Cloud Spanner con Ruby.
Echa un vistazo al archivospanner_samples.rb
, que muestra cómo usar Cloud Spanner. El código muestra cómo crear y usar una nueva base de datos. Los datos usan el esquema de ejemplo que se muestra en la página sobre el esquema y el modelo de datos.
Crear una base de datos
Crea una base de datos llamada "example-db
" en la instancia que se denomina "test-instance
". Para ello, ejecuta este método en la línea de comandos:
bundle exec ruby spanner_samples.rb create_database test-instance example-db
Deberías ver lo siguiente:
Created database example-db on instance test-instance
Acabas de crear una base de datos de Cloud Spanner. Este es el código que ha creado la base de datos.
El código también define dos tablas, Singers
y Albums
, con las que se crea una aplicación de música básica. Estas tablas se usan en esta página. Echa un vistazo al esquema de ejemplo si aún no lo has hecho.
El siguiente paso consiste en escribir datos en la base de datos.
Crear un cliente de base de datos
Antes de que puedas leer o escribir, debes crear unClient
. Un Client
es algo así como una conexión de base de datos: todas las interacciones con Cloud Spanner deben pasar por un Client
. Por lo general, creas un Client
cuando se inicia la aplicación; después, reutilizas ese Client
para leer, escribir y ejecutar transacciones. El siguiente código muestra cómo crear un cliente.
Obtén más información en la referencia de Client
.
Escribir datos
Escribe datos mediante un objeto Client
. El método Client#commit
crea y confirma una transacción para escrituras que se ejecutan atómicamente en un único punto lógico en el tiempo en las columnas, filas y tablas de una base de datos.
Con este código se muestra cómo escribir los datos:
(Si deseas obtener más detalles sobre los datos, consulta el esquema de ejemplo sobre tablas Singers
y Albums
).
Ejecuta la muestra mediante el argumento insert_data
:
bundle exec ruby spanner_samples.rb insert_data test-instance example-db
Deberías ver lo siguiente:
Inserted data
Consultar datos mediante SQL
Cloud Spanner es compatible con una interfaz SQL nativa de lectura de datos, a la que se puede acceder desde la línea de comandos mediante la herramienta de línea de comandos gcloud
o mediante programación, a través de la biblioteca cliente de Cloud Spanner para Ruby.
En la línea de comandos
Ejecuta esta declaració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'
Deberías ver el siguiente resultado:
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 cliente de Cloud Spanner para Ruby
Además de ejecutar una declaración SQL en la línea de comandos, puedes emitir la misma declaración SQL mediante programación si utilizas la biblioteca cliente de Cloud Spanner para Ruby.
El método Client#execute
sirve para ejecutar la consulta SQL. Puedes usar un símbolo :ColumnName
de Ruby para acceder a los datos de una columna específica desde una fila.
A continuación, se indica cómo emitir la consulta y acceder a los datos:
Ejecuta la muestra mediante el argumento query_data
:
bundle exec ruby spanner_samples.rb query_data 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
Leer datos mediante la API de lectura
Además de con la interfaz SQL de Cloud Spanner, Cloud Spanner también es compatible con una interfaz de lectura.
El método Client#read
de la clase Client
sirve para leer las filas de la base de datos.
A continuación, mostramos cómo leer los datos:
Ejecuta la muestra mediante el argumento read_data
:
bundle exec ruby spanner_samples.rb read_data 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 necesitas añadir una nueva columna llamada MarketingBudget
a la tabla Albums
. Si deseas añadir una nueva columna a una tabla, es preciso actualizar el esquema de base de datos. Cloud Spanner es compatible con actualizaciones de esquema de bases de datos mientras que dicha base de datos sigue atendiendo el tráfico. No hace falta que la base de datos esté desconectada y no se bloquean tablas ni columnas enteras durante la actualización de un esquema; puedes continuar escribiendo datos en la base de datos durante ese periodo. Obtén más información sobre las actualizaciones de esquema compatibles y el rendimiento de cambio de esquema en el apartado sobre actualización de esquemas.
Añadir una columna
Puedes añadir una columna en la línea de comandos mediante la herramienta de línea de comandos gcloud
o a través de la biblioteca cliente de Cloud Spanner para Ruby.
En la línea de comandos
El siguiente comando ALTER TABLE
sirve para añadir la nueva columna a la tabla:
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='ALTER TABLE Albums ADD COLUMN MarketingBudget INT64'
Deberías ver lo siguiente:
DDL updating...done.
Usar la biblioteca cliente de Cloud Spanner para Ruby
Usa el métodoDatabase#update
de la clase Database
para modificar el siguiente esquema:
Ejecuta la muestra mediante el argumento add_column
:
bundle exec ruby spanner_samples.rb add_column test-instance example-db
Deberías ver lo siguiente:
Added the MarketingBudget column
Escribir datos en la nueva columna
El siguiente código sirve para escribir datos en la nueva columna. Establece MarketingBudget
en 100000
en la fila marcada como Albums(1, 1)
, y 500000
en la fila marcada como Albums(2, 2)
.
Ejecuta la muestra mediante el argumento update_data
:
bundle exec ruby spanner_samples.rb update_data test-instance example-db
Deberías ver lo siguiente:
Updated data
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:
Si quieres ejecutar esta consulta, hazlo mediante la muestra con el argumento query_data_with_new_column
.
bundle exec ruby spanner_samples.rb query_data_with_new_column test-instance example-db
Deberías ver lo siguiente:
1 1 100000
1 2
2 1
2 2 500000
2 3
Actualizar datos mediante una transacción de lectura y escritura
Supongamos que las ventas de Albums(1, 1)
son más bajas de lo esperado. Por este motivo, deseas mover 200.000 USD del presupuesto de comercialización de Albums(2, 2)
a Albums(1, 1)
, pero solo si el presupuesto de Albums(2, 2)
es de, al menos, 300.000 USD.
Debido a que esta transacción puede escribir datos que difieren según los valores que se leen, tienes que usar una transacción de lectura y escritura para realizar las lecturas y escrituras de forma automática.
El método transaction
de la clase Client
sirve para ejecutar una transacción.
Este es el código para ejecutar la transacción:
Ejecuta la muestra mediante el argumento read_write_transaction
:
bundle exec ruby spanner_samples.rb read_write_transaction test-instance example-db
Deberías ver lo siguiente:
Transaction complete
Consulta los datos de nuevo:
bundle exec ruby spanner_samples.rb query_data_with_new_column test-instance example-db
Deberías ver lo siguiente:
1 1 300000
1 2
2 1
2 2 300000
2 3
Usar un índice secundario
Supongamos que quieres buscar todas las filas de Albums
que tengan valores de AlbumTitle
en un intervalo determinado. Puedes leer todos los valores de la columna AlbumTitle
mediante una declaración SQL o una lectura de llamada y descartar después las filas que no cumplan los criterios, pero realizar esta búsqueda completa en la tabla resulta caro, especialmente cuando se trata de tablas con muchas filas. En su lugar, puedes acelerar la recuperación de filas al buscar columnas de clave no principales mediante la creación de un índice secundario en la tabla.
Si se desea añadir un índice secundario a una tabla, es preciso actualizar el esquema. Cloud Spanner permite añadir un índice mientras la base de datos continúa atendiendo el tráfico, al igual que sucede con otras actualizaciones de esquema. Cloud Spanner rellena el índice con datos (un proceso que también se conoce como "reposición"). Las reposiciones pueden tardar unos minutos en completarse, pero no es necesario que desconectes la base de datos o evites escribir en algunas tablas o columnas durante este proceso. Si quieres obtener más detalles, consulta el apartado sobre reposiciones de índice.
Añadir un índice secundario
Puedes añadir un índice en la línea de comandos mediante la herramienta de línea de comandos de gcloud
o mediante programación a través de la biblioteca de cliente de Cloud Spanner para Ruby.
En la línea de comandos
Usa este 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:
DDL updating...done.
Usar la biblioteca cliente de Cloud Spanner para Ruby
Usa el método Database#update
de la clase Database
para añadir un índice:
Ejecuta la muestra mediante el argumento create_index
:
bundle exec ruby spanner_samples.rb create_index test-instance example-db
Añadir un índice es un proceso que puede llevar unos minutos. Después de añadir el índice, esto es lo que deberías ver:
Added the AlbumsByAlbumTitle index
Realizar consultas mediante el índice
Puedes realizar consultas mediante el nuevo índice en la línea de comandos o mediante la biblioteca cliente.
En la línea de comandos
Ejecuta una declaración SQL con la herramienta de línea de comandos gcloud
para buscar AlbumId
, AlbumTitle
y MarketingBudget
en Albums
mediante el índice AlbumsByAlbumTitle
con el intervalo de AlbumsTitle
en ["Aardvark", "Goo")
.
gcloud spanner databases execute-sql example-db --instance=test-instance --sql='SELECT AlbumId, AlbumTitle, MarketingBudget FROM Albums@{FORCE_INDEX=AlbumsByAlbumTitle} WHERE AlbumTitle >= "Aardvark" AND AlbumTitle < "Goo"'
Deberías ver el siguiente resultado:
AlbumId AlbumTitle MarketingBudget
2 Go, Go, Go
2 Forever Hold Your Peace 300000
Usar la biblioteca cliente de Cloud Spanner para Ruby
El código para usar el índice mediante programación es similar al código de consulta utilizado anteriormente.
Ejecuta la muestra mediante el argumento query_data_with_index
:
bundle exec ruby spanner_samples.rb query_data_with_index test-instance example-db
El resultado que verás debe parecerse al siguiente:
2 Go, Go, Go
2 Forever Hold Your Peace 300000
Si quieres obtener más detalles, consulta estas referencias:
- Directiva de índices SQL, que indica que una tabla debe leerse mediante un índice.
- Funciones y operadores de SQL.
Leer datos mediante el índice
Si quieres leer mediante el índice, proporciona un parámetro de index
para el método de read
de la clase Client
.
Ejecuta la muestra mediante el argumento read_data_with_index
:
bundle exec ruby spanner_samples.rb read_data_with_index 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 con una cláusula STORING
Puede que hayas notado que el ejemplo de lectura anterior no incluye la lectura de la columna MarketingBudget
. Esto se debe a que la interfaz de lectura de Cloud Spanner no admite la capacidad de unirse a un índice con una tabla de datos para buscar valores que no están almacenados en él.
Crea una definición alternativa de AlbumsByAlbumTitle
que almacene una copia de MarketingBudget
en el índice.
En la línea de comandos
gcloud spanner databases ddl update example-db --instance=test-instance \
--ddl='CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) STORING (MarketingBudget)'
Añadir un índice es un proceso que puede llevar unos minutos. Después de añadir el índice, esto es lo que deberías ver:
DDL updating...done.
Usar la biblioteca cliente de Cloud Spanner para Ruby
Usa el métodoDatabase#update
de la clase Database
para añadir un índice con una cláusula STORING
:
Ejecuta la muestra mediante el argumento create_storing_index
:
bundle exec ruby spanner_samples.rb create_storing_index test-instance example-db
Deberías ver lo siguiente:
Added the AlbumsByAlbumTitle2 index
Ahora puedes ejecutar una lectura que recopile las columnas AlbumId
, AlbumTitle
, y
MarketingBudget
del índice AlbumsByAlbumTitle2
:
Ejecuta la muestra mediante el argumento read_data_with_storing_index
:
bundle exec ruby spanner_samples.rb read_data_with_storing_index test-instance example-db
El resultado que verás debe parecerse al siguiente:
2 Forever Hold Your Peace 300000
2 Go, Go, Go
1 Green
3 Terrified
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 coherentes.
El objeto Snapshot
sirve para ejecutar transacciones de solo lectura. Usa el método snapshot
de la clase Client
para obtener un objeto Snapshot
.
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 mediante el argumento read_only_transaction
:
bundle exec ruby spanner_samples.rb read_only_transaction test-instance example-db
El resultado que verás debe parecerse al siguiente:
2 Forever Hold Your Peace 2
2 Go, Go, Go 1
1 Green 2
3 Terrified 2
1 Total Junk 1
1 Total Junk 1
2 Go, Go, Go 1
1 Green 2
2 Forever Hold Your Peace 2
3 Terrified 2
Limpieza
Si quieres evitar que se generen más costes en la cuenta de Google Cloud Platform debido a los recursos usados en este tutorial, elimina la base de datos y la instancia que creaste.
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
Mediante la consola de GCP
- Visita la página sobre las instancias de Cloud Spanner en la consola de Google Cloud Platform.
Ir a la página de instancias de Cloud Spanner - 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
Mediante la consola de GCP
- Visita la página sobre las instancias de Cloud Spanner en la consola de Google Cloud Platform.
Ir a la página de instancias de Cloud Spanner - Haz clic en la instancia.
- Haz clic en Eliminar.
- Confirma que deseas eliminar la instancia y haz clic en Eliminar.
Siguientes pasos
- Acceder a Cloud Spanner en una instancia de máquina virtual: crea una instancia de máquina virtual con acceso a la base de datos de Cloud Spanner
- Más información sobre las credenciales de autorización y autenticación en el apartado de introducción a la autenticación
- Más información sobre conceptos de Cloud Spanner