Objetivos
En este instructivo, se explican los siguientes pasos con la biblioteca cliente de Spanner para Python:
- Crea una base de datos y una instancia de Spanner.
- Escribe, lee y ejecuta consultas de SQL sobre datos en 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 de SQL sobre datos.
- Recupera datos con una transacción de solo lectura.
Costos
En este instructivo, se usa Spanner, que es un componente facturable deGoogle Cloud. Para obtener información sobre el costo de usar Spanner, consulta Precios.
Antes de comenzar
Completa los pasos descritos en Configuración, que abarcan la creación y configuración de un proyecto de Google Cloud predeterminado, 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 el entorno local de Python
Sigue las instrucciones para configurar un entorno de desarrollo de Python.
Clona el repositorio de la app de muestra en tu máquina local:
git clone https://github.com/googleapis/python-spanner
De manera opcional, puedes descargar la muestra como un archivo ZIP y extraerla.
Ve al directorio que contiene el código de muestra de Spanner:
cd python-spanner/samples/samples
Crea un entorno aislado de Python e instala las dependencias:
virtualenv env source env/bin/activate pip install -r requirements.txt
Crea una instancia
Cuando usas Spanner por primera vez, 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.
Ejecuta el siguiente comando para crear una instancia de Spanner en la región us-central1
con 1 nodo:
gcloud spanner instances create test-instance --config=regional-us-central1 \
--description="Test Instance" --nodes=1
Ten en cuenta que esto crea una instancia con las siguientes características:
- ID de instancia:
test-instance
- Nombre visible:
Test Instance
- Configuración de la instancia:
regional-us-central1
(la configuración regional almacena datos en una región, mientras que la multirregional distribuye datos en varias regiones; Para obtener más información, consulta Acerca de las instancias. - Recuento de nodos: 1 (
node_count
corresponde a la cantidad de recursos de procesamiento y almacenamiento disponibles para las bases de datos de la instancia; Obtén más información en Nodos y unidades de procesamiento).
Deberías ver lo siguiente:
Creating instance...done.
Examina archivos de muestra
El repositorio de muestras contiene una muestra que indica cómo usar Spanner con Python.
Consulta el archivosnippets.py
, en el que se muestra cómo usar Spanner. El código es un instructivo sobre cómo crear y usar una base de datos nueva. Los datos utilizan el esquema de ejemplo de la página Esquema y modelo de datos.
Crea una base de datos
GoogleSQL
python snippets.py test-instance --database-id example-db create_database
PostgreSQL
python pg_snippets.py test-instance --database-id example-db create_database
Deberías ver lo siguiente:
Created database example-db on instance test-instance
GoogleSQL
PostgreSQL
El siguiente paso consiste en escribir datos en tu base de datos.
Crea un cliente de base de datos
Para realizar operaciones de lectura o escritura, debes crear unClient
. Un Client
es como una conexión a una base de datos, es decir, todas las interacciones con Spanner deben realizarse mediante un Client
. Por lo general, creas un Client
cuando se inicia la aplicación y, luego, vuelves a usar ese Client
para leer, escribir y ejecutar transacciones. En el siguiente código, se muestra cómo crear un cliente.
Obtén más información en la referencia de Client
.
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 execute_update()
para ejecutar una declaración DML.
Ejecuta la muestra con el argumento insert_with_dml
.
python snippets.py test-instance --database-id example-db insert_with_dml
Deberías ver lo siguiente:
4 record(s) inserted.
Escribe datos con mutaciones
También puedes insertar datos mediante mutaciones.
Escribirás datos con un objeto Batch
. Este objeto Batch
es un contenedor de operaciones de mutación. Una mutación representa una secuencia de inserciones, actualizaciones y eliminaciones que Spanner aplica de manera atómica a diferentes filas y tablas en una base de datos de Spanner.
El método insert()
de la clase Batch
permite agregar una o más mutaciones de inserción al lote. Se aplican atómicamente todas las mutaciones de un lote.
En este código, se muestra cómo escribir los datos mediante mutaciones:
Ejecuta la muestra con el argumento insert_data
.
python snippets.py test-instance --database-id example-db insert_data
Deberías ver lo siguiente:
Inserted data.
Consulta datos mediante SQL
Spanner admite una interfaz de SQL para leer datos, a la que puedes acceder desde la línea de comandos mediante Google Cloud CLI o de manera programática con la biblioteca cliente de Spanner para Python.
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
:
gcloud spanner databases execute-sql example-db --instance=test-instance \
--sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'
El resultado debería ser este:
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 la biblioteca cliente de Spanner para Python
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 la biblioteca cliente de Spanner para Python.
Usa el método execute_sql()
de un objeto Snapshot
para ejecutar la consulta de SQL. Para obtener un objeto Snapshot
, llama al método snapshot()
de la clase Database
en una instrucción with
.
Aquí se muestra cómo enviar la consulta y acceder a los datos:
Ejecuta la muestra con el argumento query_data
.
python snippets.py test-instance --database-id example-db query_data
Deberías ver el siguiente 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
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 puede almacenarse en caché y volverse a usar, lo que reduce los costos de compilación. Para obtener más información, consulta Usa parámetros de consulta para agilizar las consultas que se ejecutan con frecuencia.
Este es un ejemplo del uso de un parámetro en la cláusula WHERE
para consultar registros que contienen un valor específico de LastName
.
Ejecuta la muestra con el argumento query_data_with_parameter.
python snippets.py test-instance --database-id example-db query_data_with_parameter
Deberías ver el siguiente resultado:
SingerId: 12, FirstName: Melissa, LastName: Garcia
Lee datos con la API de lectura
Además de la interfaz de SQL de Spanner, Spanner también admite una interfaz de lectura.
Usa el método read()
de un objeto Snapshot
para leer las filas de la base de datos.
Para obtener un objeto Snapshot
, llama al método snapshot()
de la clase Database
en una instrucción with
.
Usa un objeto KeySet
para definir un grupo de claves y rangos de claves que se leerán.
Aquí te indicamos cómo leer los datos:
Ejecuta la muestra con el argumento read_data
.
python snippets.py test-instance --database-id example-db read_data
Deberías ver un resultado similar a este:
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
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 admitidas del esquema y el rendimiento de los cambios de esquema en Cómo realizar actualizaciones de esquema.
Agrega una columna
Puedes usar la línea de comandos para agregar una columna con la CLI de Google Cloud o de manera programática con la biblioteca cliente de Spanner para Python.
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 MarketingBudget BIGINT'
Deberías ver lo siguiente:
Schema updating...done.
Usa la biblioteca cliente de Spanner para Python
Usa el métodoupdate_ddl()
de la clase Database
para modificar el esquema:
Ejecuta la muestra con el argumento add_column
.
python snippets.py test-instance --database-id example-db add_column
Deberías ver lo siguiente:
Added the MarketingBudget column.
Escribe datos en la columna nueva
Con el siguiente código, se escriben datos en la columna nueva. Establece MarketingBudget
en 100000
para la fila marcada por Albums(1, 1)
y en 500000
para la fila marcada por Albums(2, 2)
.
Ejecuta la muestra con el argumento update_data
.
python snippets.py test-instance --database-id example-db update_data
También puedes ejecutar una consulta de SQL o una llamada de lectura para recuperar los valores que acabas de escribir.
Este es el código para ejecutar la consulta:
Para ejecutar esta consulta, ejecuta la muestra con el argumento query_data_with_new_column
.
python snippets.py test-instance --database-id example-db query_data_with_new_column
Deberías ver lo siguiente:
SingerId: 2, AlbumId: 2, MarketingBudget: 500000
SingerId: 1, AlbumId: 2, MarketingBudget: None
SingerId: 2, AlbumId: 1, MarketingBudget: None
SingerId: 2, AlbumId: 3, MarketingBudget: None
SingerId: 1, AlbumId: 1, MarketingBudget: 100000
Actualiza datos
Puedes actualizar los datos mediante DML en una transacción de lectura y escritura.
Usa el método execute_update()
para ejecutar una declaración DML.
Ejecuta la muestra con el argumento write_with_dml_transaction
.
python snippets.py test-instance --database-id example-db write_with_dml_transaction
Deberías ver lo siguiente:
Transferred 200000 from Album2's budget to Album1's
Usa un índice secundario
Supongamos que deseas recuperar todas las filas de Albums
que tienen valores AlbumTitle
en un rango determinado. Puedes leer todos los valores de la columna AlbumTitle
con una instrucción de SQL o una llamada de lectura y, luego, descartar las filas que no cumplan con los criterios. Sin embargo, analizar tablas enteras es costoso, especialmente si tienen muchas filas. En su lugar, crea un índice secundario en la tabla para acelerar la recuperación de filas cuando realizas búsquedas por columnas sin claves primarias.
Para agregar un índice secundario a una tabla existente, es necesario actualizar el esquema. Al igual que otras actualizaciones de esquema, Spanner admite que se agregue un índice mientras la base de datos continúa entregando tráfico. Spanner reabastece de manera automática el índice con tus datos existentes. Los reabastecimientos pueden tardar unos minutos en completarse, pero no es necesario que uses la base de datos sin conexión ni que evites escribir en la tabla indexada durante este proceso. Para obtener más detalles, consulta Cómo agregar un índice secundario.
Después de agregar un índice secundario, Spanner lo usa de forma automática 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 deseas usar.
Agrega un índice secundario
Puedes usar la línea de comandos para agregar un índice con la CLI de gcloud o hacerlo de manera programática con la biblioteca cliente de Spanner para Python.
En la línea de comandos
Usa el siguiente comando CREATE INDEX
para agregar 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.
Usa la biblioteca cliente de Spanner para Python
Usa el métodoupdate_ddl()
de la clase Database
para agregar un índice:
Ejecuta la muestra con el argumento add_index
.
python snippets.py test-instance --database-id example-db add_index
Agregar un índice puede tardar unos minutos. Después de agregar el índice, deberías ver lo siguiente:
Added the AlbumsByAlbumTitle index.
Leer con el índice
Para las consultas de SQL, Spanner usa automáticamente un índice adecuado. En la interfaz de lectura, debes especificar el índice en tu solicitud.
Para usar el índice en la interfaz de lectura, proporciona un argumento Index
al método read()
de un objeto Snapshot
. Para obtener un objeto Snapshot
, llama al método snapshot()
de la clase Database
en una instrucción with
.
Ejecuta la muestra con el argumento read_data_with_index
.
python snippets.py test-instance --database-id example-db read_data_with_index
Deberías ver lo siguiente:
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
Agrega un índice para las operaciones de lectura de solo índice
Quizás notaste 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 unir 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)
Agregar un índice puede tardar unos minutos. Después de agregar el índice, deberías ver lo siguiente:
Schema updating...done.
Usa la biblioteca cliente de Spanner para Python
Usa el métodoupdate_ddl()
de la clase Database
para agregar un índice con una cláusula STORING
:
Ejecuta la muestra con el argumento add_storing_index
.
python snippets.py test-instance --database-id example-db add_storing_index
Deberías ver lo siguiente:
Added the AlbumsByAlbumTitle2 index.
Ahora puedes ejecutar una operación de lectura que recupere todas las columnas AlbumId
, AlbumTitle
y MarketingBudget
del índice AlbumsByAlbumTitle2
:
Ejecuta la muestra con el argumento read_data_with_storing_index
.
python snippets.py test-instance --database-id example-db read_data_with_storing_index
Deberías ver un resultado similar a este:
AlbumId: 2, AlbumTitle: Forever Hold Your Peace, MarketingBudget: 300000
AlbumId: 2, AlbumTitle: Go, Go, Go, MarketingBudget: None
AlbumId: 1, AlbumTitle: Green, MarketingBudget: None
AlbumId: 3, AlbumTitle: Terrified, MarketingBudget: None
AlbumId: 1, AlbumTitle: Total Junk, MarketingBudget: 300000
Recupera datos mediante transacciones de solo lectura
Supongamos que quieres ejecutar más de una lectura en la misma marca de tiempo. Las transacciones de solo lectura utilizan un prefijo coherente del historial de confirmaciones de transacciones, por lo que la aplicación siempre obtiene datos coherentes.
Usa un objeto Snapshot
para ejecutar transacciones de solo lectura. Para obtener un objeto Snapshot
, llama al método snapshot()
de la clase Database
en una instrucción with
.
A continuación, se muestra cómo ejecutar una consulta y cómo realizar una lectura en la misma transacción de solo lectura:
Ejecuta la muestra con el argumento read_only_transaction
.
python snippets.py test-instance --database-id example-db read_only_transaction
Deberías ver un resultado similar a este:
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
Limpieza
Para evitar que se apliquen cargos adicionales a tu cuenta de Google Cloud por los recursos que se usaron en este instructivo, descarta la base de datos y borra 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 acceder a Spanner con una instancia de máquina virtual.
Obtén más información sobre las credenciales de autorización y autenticación en Autentícate en servicios de Cloud con bibliotecas cliente.
Obtén más información sobre las prácticas recomendadas de diseño de esquemas de Spanner.