Comandos de gestión de sesiones de PGAdapter

PGAdapter de Spanner admite instrucciones de gestión de sesiones, que te permiten modificar el estado y el comportamiento de tu conexión, ejecutar transacciones y ejecutar de forma eficiente lotes de instrucciones. Todas las instrucciones que se describen en este documento se pueden usar con cualquier cliente o controlador que se conecte a PGAdapter.

Para obtener más información, consulta la lista completa de controladores y ORMs de PostgreSQL compatibles. Los siguientes comandos se aplican a las bases de datos con dialecto PostgreSQL.

Para obtener más información sobre el uso de PGAdapter, consulta el artículo Iniciar PGAdapter.

Instrucciones de conexión

Las siguientes instrucciones modifican o muestran las propiedades de la conexión actual.

SPANNER.READONLY

Valor booleano que indica si la conexión está en modo de solo lectura. El valor predeterminado es false.

SHOW [VARIABLE] SPANNER.READONLY
SET SPANNER.READONLY {TO|=} { true | false }

Solo puede cambiar el valor de esta propiedad si no hay ninguna transacción activa.

▶ Ejemplo: Transacción de solo lectura (haz clic para ampliar)
 En el siguiente ejemplo se muestra cómo usar esta propiedad para ejecutar transacciones de solo lectura en Spanner.

SET SPANNER.READONLY = TRUE;
-- This transaction is a read-only transaction.
BEGIN TRANSACTION;

-- The following two queries both use the read-only transaction.
SELECT first_name, last_name
FROM singers
ORDER BY last_name;

SELECT first_name, last_name
FROM albums
ORDER BY title;

-- This shows the read timestamp that was used for the two queries.
SHOW SPANNER.READ_TIMESTAMP;

-- This marks the end of the read-only transaction. The next statement will
-- start a new read-only transaction.
COMMIT;

AUTOCOMMIT

Valor booleano que indica si la conexión está en modo de confirmación automática. El valor predeterminado es true.

NOTE Normalmente, no es necesario modificar el valor de esta variable cuando se usa un controlador de PostgreSQL con PGAdapter. Estos controladores gestionan las transacciones automáticamente por ti ejecutando BEGIN y COMMIT cuando sea necesario. Puedes desactivar autocommit cuando uses herramientas de línea de comandos como psql para evitar que se confirmen automáticamente modificaciones de datos accidentales.

SHOW [VARIABLE] AUTOCOMMIT
SET AUTOCOMMIT {TO|=} { true | false }

Solo puede cambiar el valor de esta propiedad cuando no haya ninguna transacción activa.

Si AUTOCOMMIT tiene el valor false, se inicia automáticamente una nueva transacción después de ejecutar COMMIT o ROLLBACK. La primera instrucción que ejecutes inicia la transacción.

▶ Ejemplo: Autocomprobación (haz clic para ampliar)
 En el siguiente ejemplo se muestra cómo usar la propiedad autocommit.

-- The default value for AUTOCOMMIT is true.
SHOW AUTOCOMMIT;

-- This insert statement is automatically committed after it is executed, as
-- the connection is in autocommit mode.
INSERT INTO T (id, col_a, col_b) VALUES (1, 100, 1);

-- Turning off autocommit means that a new transaction is automatically started
-- when the next statement is executed.
SET AUTOCOMMIT = FALSE;
-- The following statement starts a new transaction.
INSERT INTO T (id, col_a, col_b) VALUES (2, 200, 2);

-- This statement uses the same transaction as the previous statement.
INSERT INTO T (id, col_a, col_b) VALUES (3, 300, 3);

-- Commit the current transaction with the two INSERT statements.
COMMIT;

-- Transactions can also be executed in autocommit mode by executing the BEGIN
-- statement.
SET AUTOCOMMIT = TRUE;

-- Execute a transaction while in autocommit mode.
BEGIN;
INSERT INTO T (id, col_a, col_b) VALUES (4, 400, 4);
INSERT INTO T (id, col_a, col_b) VALUES (5, 500, 5);
COMMIT;

SPANNER.RETRY_ABORTS_INTERNALLY

Valor booleano que indica si la conexión vuelve a intentar automáticamente las transacciones anuladas. El valor predeterminado es true.

SHOW [VARIABLE] SPANNER.RETRY_ABORTS_INTERNALLY
SET SPANNER.RETRY_ABORTS_INTERNALLY {TO|=} { true | false }

Solo puedes ejecutar este comando después de iniciar una transacción (consulta BEGIN [TRANSACTION | WORK]) y antes de ejecutar cualquier instrucción en la transacción.

Cuando habilita SPANNER.RETRY_ABORTS_INTERNALLY, la conexión mantiene una suma de comprobación de todos los datos que devuelve a la aplicación cliente. Se usa para volver a intentar la transacción si Spanner la cancela.

Este ajuste está habilitado de forma predeterminada. Te recomendamos que desactives este ajuste si tu aplicación ya vuelve a intentar las transacciones canceladas.

SPANNER.AUTOCOMMIT_DML_MODE

Una propiedad STRING que indica el modo de confirmación automática de las declaraciones del lenguaje de manipulación de datos (DML).

SHOW [VARIABLE] SPANNER.AUTOCOMMIT_DML_MODE
SET SPANNER.AUTOCOMMIT_DML_MODE {TO|=} { 'TRANSACTIONAL' | 'PARTITIONED_NON_ATOMIC' }

A continuación se especifican los posibles valores.

  • En el modo TRANSACTIONAL, el controlador ejecuta las instrucciones DML como transacciones atómicas independientes. El controlador crea una transacción, ejecuta la instrucción DML y confirma la transacción si se ejecuta correctamente o la revierte si se produce un error.
  • En el modo PARTITIONED_NON_ATOMIC, el controlador ejecuta las instrucciones DML como instrucciones de actualización particionadas. Una instrucción de actualización particionada se puede ejecutar como una serie de muchas transacciones, cada una de las cuales abarca un subconjunto de las filas afectadas. La instrucción de partición proporciona una semántica debilitada a cambio de una mejor escalabilidad y rendimiento.

El valor predeterminado es TRANSACTIONAL.

▶ Ejemplo: DML con particiones (haz clic para desplegar)
 En el siguiente ejemplo se muestra cómo ejecutar DML con particiones mediante PGAdapter.

-- Change autocommit DML mode to use Partitioned DML.
SET SPANNER.AUTOCOMMIT_DML_MODE = 'PARTITIONED_NON_ATOMIC';

-- Delete all singers that have been marked as inactive.
-- This statement is executed using Partitioned DML.
DELETE
FROM singers
WHERE active=false;

-- Change DML mode back to standard `TRANSACTIONAL`.
SET SPANNER.AUTOCOMMIT_DML_MODE = 'TRANSACTIONAL';

STATEMENT_TIMEOUT

Propiedad de tipo STRING que indica el valor de tiempo de espera actual de las instrucciones.

SHOW [VARIABLE] STATEMENT_TIMEOUT
SET STATEMENT_TIMEOUT {TO|=} { '<int8>{ s | ms | us | ns }' | <int8> | DEFAULT }

El valor int8 es un número entero seguido de un sufijo que indica la unidad de tiempo. El valor DEFAULT indica que no se ha definido ningún valor de tiempo de espera. Si se ha definido un valor de tiempo de espera de la instrucción, las instrucciones que tarden más que el valor de tiempo de espera especificado provocarán un error de tiempo de espera e invalidarán la transacción.

Las unidades de tiempo admitidas son:

  • s: segundos
  • ms: milisegundos
  • us: microsegundos
  • ns: nanosegundos

El valor de DEFAULT es 0 segundos, lo que significa que no hay tiempo de espera. Un número int8 sin unidades indica int8 ms. Por ejemplo, los dos comandos siguientes definen el tiempo de espera de la instrucción en 2 segundos.

SET STATEMENT_TIMEOUT TO 2000;
SET STATEMENT_TIMEOUT TO '2s';

Si se agota el tiempo de espera de una instrucción durante una transacción, la transacción se invalida y fallan todas las instrucciones posteriores de la transacción invalidada (excepto ROLLBACK).

READ_ONLY_STALENESS

Propiedad de tipo STRING que indica el valor de obsolescencia de solo lectura actual que usa Spanner para las transacciones y las consultas de solo lectura en el modo AUTOCOMMIT.

SHOW [VARIABLE] SPANNER.READ_ONLY_STALENESS
SET SPANNER.READ_ONLY_STALENESS {TO|=} staleness_type

staleness_type:

{ 'STRONG' 
  | 'MIN_READ_TIMESTAMP timestamp'
  | 'READ_TIMESTAMP timestamp'
  | 'MAX_STALENESS <int8>{ s | ms | us | ns }'
  | 'EXACT_STALENESS <int8>{ s | ms | us | ns }' }

El valor read-only staleness se aplica a todas las transacciones de solo lectura posteriores y a todas las consultas en modo AUTOCOMMIT.

El valor predeterminado es STRONG.

Las opciones de límite de marca de tiempo son las siguientes:

Las marcas de tiempo deben tener el siguiente formato:

YYYY-[M]M-[D]D [[H]H:[M]M:[S]S[.DDDDDD]][timezone]

Las unidades de tiempo admitidas para los valores MAX_STALENESS y EXACT_STALENESS son las siguientes:

  • s: segundos
  • ms: milisegundos
  • us: microsegundos
  • ns: nanosegundos

Solo puede modificar el valor de esta propiedad si no hay ninguna transacción activa.

▶ Ejemplo: Antigüedad de solo lectura (haz clic para desplegar)
 En el siguiente ejemplo se muestra cómo ejecutar consultas con un valor de obsolescencia personalizado con PGAdapter.

-- Set the read-only staleness to MAX_STALENESS 10 seconds.
SET SPANNER.READ_ONLY_STALENESS = 'MAX_STALENESS 10s';

-- Execute a query in auto-commit mode. This will return results that are up to
-- 10 seconds stale.
SELECT first_name, last_name
FROM singers
ORDER BY last_name;

-- Read-only staleness can also be applied to read-only transactions.
-- MAX_STALENESS is however only allowed for queries in autocommit mode.
-- Change the staleness to EXACT_STALENESS and start a read-only transaction.
SET SPANNER.READ_ONLY_STALENESS = 'EXACT_STALENESS 10s';
BEGIN;
SET TRANSACTION READ ONLY;

SELECT first_name, last_name
FROM singers
ORDER BY last_name;

SELECT title, singer_id
FROM albums
ORDER BY title;

COMMIT;

-- Read staleness can also be an exact timestamp.
SET SPANNER.READ_ONLY_STALENESS = 'READ_TIMESTAMP 2024-01-26T10:36:00Z';

SELECT first_name, last_name
FROM singers
ORDER BY last_name;

SPANNER.OPTIMIZER_VERSION

Una propiedad de tipo STRING que indica la versión del optimizador. La versión es numérica o LATEST.

SHOW [VARIABLE] SPANNER.OPTIMIZER_VERSION
SET SPANNER.OPTIMIZER_VERSION {TO|=} { 'version'|'LATEST'|'' }

Define la versión del optimizador que se va a usar en todas las instrucciones siguientes de la conexión. Si se asigna el valor '' (la cadena vacía) a la versión del optimizador, se indica que se debe usar la versión más reciente. Si no se ha definido ninguna versión del optimizador, Spanner usará la versión del optimizador que se haya definido en el nivel de la base de datos.

El valor predeterminado es ''.

▶ Ejemplo: Versión del optimizador (haz clic para ampliar)
 En el siguiente ejemplo se muestra cómo ejecutar consultas con una versión del optimizador específica con PGAdapter.

-- Set the optimizer version to 5 and execute a query.
SET SPANNER.OPTIMIZER_VERSION = '5';

SELECT first_name, last_name
FROM singers
ORDER BY last_name;

-- Execute the same query with the latest optimizer version.
SET SPANNER.OPTIMIZER_VERSION = 'LATEST';

SELECT first_name, last_name
FROM singers
ORDER BY last_name;

-- Revert back to using the default optimizer version that has been set for the
-- database.
SET SPANNER.OPTIMIZER_VERSION = '';

SELECT first_name, last_name
FROM singers
ORDER BY last_name;

SPANNER.OPTIMIZER_STATISTICS_PACKAGE

Una propiedad de tipo STRING que indica el paquete de estadísticas del optimizador actual que usa esta conexión.

SHOW [VARIABLE] SPANNER.OPTIMIZER_STATISTICS_PACKAGE
SET SPANNER.OPTIMIZER_STATISTICS_PACKAGE {TO|=} { 'package'|'' }

Define el paquete de estadísticas del optimizador que se va a usar en todas las instrucciones siguientes de la conexión. <package> debe ser un nombre de paquete válido. Si no se define ningún paquete de estadísticas del optimizador, Spanner usa el paquete de estadísticas del optimizador que se haya definido a nivel de base de datos.

El valor predeterminado es ''.

▶ Ejemplo: Paquete de estadísticas del optimizador (haz clic para ampliar)
 En el siguiente ejemplo se muestra cómo ejecutar consultas con un paquete de estadísticas del optimizador específico con PGAdapter.

-- Show the available optimizer statistics packages in this database.
SELECT * FROM INFORMATION_SCHEMA.SPANNER_STATISTICS;

-- Set the optimizer statistics package and execute a query.
SET SPANNER.OPTIMIZER_STATISTICS_PACKAGE = 'auto_20240124_06_47_29UTC';

SELECT first_name, last_name
FROM singers
ORDER BY last_name;

-- Execute the same query with the default optimizer statistics package.
SET SPANNER.OPTIMIZER_VERSION = '';

SELECT first_name, last_name
FROM singers
ORDER BY last_name;

SPANNER.RETURN_COMMIT_STATS

Propiedad de tipo BOOL que indica si se deben devolver estadísticas de las transacciones de esta conexión. Para ver las estadísticas devueltas, ejecuta el comando SHOW [VARIABLE] COMMIT_RESPONSE.

SHOW [VARIABLE] SPANNER.RETURN_COMMIT_STATS
SET SPANNER.RETURN_COMMIT_STATS {TO|=} { true | false }

El valor predeterminado es false.

▶ Ejemplo: estadísticas de confirmaciones (haz clic para desplegar)
 En el siguiente ejemplo se muestra cómo ver las estadísticas de confirmación de una transacción con PGAdapter.

-- Enable the returning of commit stats.
SET SPANNER.RETURN_COMMIT_STATS = true;

-- Execute a transaction.
BEGIN;
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1), (2, 200, 2), (3, 300, 3);
COMMIT;

-- View the commit response with the transaction statistics for the last
-- transaction that was committed.
SHOW SPANNER.COMMIT_RESPONSE;

SPANNER.RPC_PRIORITY

Propiedad de tipo STRING que indica la prioridad relativa de las solicitudes de Spanner. La prioridad actúa como una pista para el programador de Spanner y no garantiza el orden de ejecución.

SHOW [VARIABLE] SPANNER.RPC_PRIORITY
SET SPANNER.RPC_PRIORITY {TO|=} {'HIGH'|'MEDIUM'|'LOW'|'NULL'}

'NULL' significa que no se debe incluir ninguna pista en la solicitud.

El valor predeterminado es 'NULL'.

También puedes usar una sugerencia de instrucción para especificar la prioridad de la RPC:

/*@RPC_PRIORITY=PRIORITY_LOW*/ SELECT * FROM Albums

Para obtener más información, consulta Priority.

Extractos de transacciones

Las siguientes instrucciones gestionan y confirman las transacciones de Spanner.

NIVEL DE AISLAMIENTO DE TRANSACCIONES

SHOW [ VARIABLE ] TRANSACTION ISOLATION LEVEL

Devuelve un conjunto de resultados con una fila y una columna de tipo STRING. El valor devuelto siempre es serializable, ya que es el único nivel de aislamiento admitido para las bases de datos de Spanner con dialecto PostgreSQL.

SPANNER.READ_TIMESTAMP

SHOW [VARIABLE] SPANNER.READ_TIMESTAMP

Devuelve un conjunto de resultados con una fila y una columna de tipo TIMESTAMP que contiene la marca de tiempo de lectura de la transacción de solo lectura más reciente. Esta instrucción devuelve una marca de tiempo solo cuando una transacción de solo lectura sigue activa y ha ejecutado al menos una consulta, o inmediatamente después de que se haya confirmado una transacción de solo lectura y antes de que empiece una nueva transacción. De lo contrario, el resultado es NULL.

▶ Ejemplo: Leer marca de tiempo (haz clic para ampliar)
 En el siguiente ejemplo se muestra cómo ver la marca de tiempo de la última lectura de una operación de solo lectura con PGAdapter.

-- Execute a query in autocommit mode using the default read-only staleness
-- (strong).
SELECT first_name, last_name
FROM singers
ORDER BY last_name;

-- Shows the read timestamp that was used for the previous query.
SHOW SPANNER.READ_TIMESTAMP;

-- Set a non-deterministic read-only staleness and execute the same query.
SET SPANNER.READ_ONLY_STALENESS = 'MAX_STALENESS 20s';

SELECT first_name, last_name
FROM singers
ORDER BY last_name;

-- Shows the read timestamp that was used for the previous query. The timestamp
-- is determined by Spanner, and is guaranteed to be no less than 20
-- seconds stale.
SHOW SPANNER.READ_TIMESTAMP;

-- The read timestamp of a read-only transaction can also be retrieved.
SET SPANNER.READ_ONLY_STALENESS = 'STRONG';
BEGIN;
SET TRANSACTION READ ONLY;

SELECT first_name, last_name
FROM singers
ORDER BY last_name;

-- Shows the read timestamp of the current read-only transaction. All queries in
-- this transaction will use this read timestamp.
SHOW SPANNER.READ_TIMESTAMP;

SELECT title
FROM albums
ORDER BY title;

-- The read timestamp is the same as for the previous query, as all queries in
-- the same transaction use the same read timestamp.
SHOW SPANNER.READ_TIMESTAMP;

COMMIT;

SPANNER.COMMIT_TIMESTAMP

SHOW [VARIABLE] SPANNER.COMMIT_TIMESTAMP

Devuelve un conjunto de resultados con una fila y una columna de tipo TIMESTAMP que contiene la marca de tiempo de confirmación de la última transacción de lectura y escritura que Spanner ha confirmado. Esta instrucción devuelve una marca de tiempo solo cuando la ejecutas después de confirmar una transacción de lectura y escritura, y antes de ejecutar cualquier instrucción SELECT, DML o de cambio de esquema posterior. De lo contrario, el resultado es NULL.

▶ Ejemplo: Marca de tiempo de la confirmación (haz clic para ampliar)
 En el siguiente ejemplo se muestra cómo ver la marca de tiempo de la última confirmación de una operación de escritura con PGAdapter.

-- Execute a DML statement.
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1), (2, 200, 2), (3, 300, 3);

-- Show the timestamp that the statement was committed.
SHOW SPANNER.COMMIT_TIMESTAMP;

SPANNER.COMMIT_RESPONSE

SHOW [VARIABLE] SPANNER.COMMIT_RESPONSE

Devuelve un conjunto de resultados con una fila y dos columnas:

  • COMMIT_TIMESTAMP (type=TIMESTAMP): indica cuándo se completó la transacción más reciente.
  • MUTATION_COUNT (type=int8) Indica cuántas mutaciones se han aplicado en la transacción confirmada. Este valor siempre está vacío cuando se ejecuta en el emulador.

El recuento de mutaciones solo está disponible si SET RETURN_COMMIT_STATS se ha definido como true antes de confirmar la transacción.

▶ Ejemplo: respuesta de confirmación (haz clic para ampliar)
 En el siguiente ejemplo se muestra cómo ver la última respuesta de confirmación de una operación de escritura con PGAdapter.

-- Enable returning commit stats in addition to the commit timestamp.
SET SPANNER.RETURN_COMMIT_STATS = true;

-- Execute a DML statement.
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1), (2, 200, 2), (3, 300, 3);

-- Show the timestamp that the statement was committed.
SHOW SPANNER.COMMIT_RESPONSE;

{ START | BEGIN } [ TRANSACTION | WORK ]

{ START | BEGIN } [ TRANSACTION | WORK ] [{ READ ONLY | READ WRITE }]

Inicia una nueva transacción. Las palabras clave TRANSACTION y WORK son opcionales, equivalentes y no tienen ningún efecto.

  • Usa COMMIT o ROLLBACK para finalizar una transacción.
  • Si has habilitado el modo AUTOCOMMIT, esta instrucción desactiva temporalmente el modo AUTOCOMMIT. La conexión vuelve al modo AUTOCOMMIT cuando finaliza la transacción.
  • Si no se especifica READ ONLY o READ WRITE, el modo de transacción se determina mediante el modo de transacción predeterminado de la sesión. Este valor predeterminado se define mediante el comando SET SESSION CHARACTERISTICS AS TRANSACTION.

Solo puedes ejecutar esta instrucción si no hay ninguna transacción activa.

▶ Ejemplo: BEGIN TRANSACTION (haz clic para ampliar)
 En el siguiente ejemplo se muestra cómo iniciar diferentes tipos de transacciones con PGAdapter.

-- This starts a transaction using the current defaults of this connection.
-- The value of SPANNER.READONLY determines whether the transaction is a
-- read/write or a read-only transaction.

BEGIN;
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);
COMMIT;

-- Set SPANNER.READONLY to TRUE to use read-only transactions by default.
SET SPANNER.READONLY=TRUE;

-- This starts a read-only transaction.
BEGIN;
SELECT first_name, last_name
FROM singers
ORDER BY last_name;
COMMIT;

-- Use the 'READ WRITE' or 'READ ONLY' qualifier in the BEGIN statement to
-- override the current default of the connection.
SET SPANNER.READONLY=FALSE;
BEGIN READ ONLY;
SELECT first_name, last_name
FROM singers
ORDER BY last_name;
COMMIT;

COMMIT [TRANSACTION | WORK]

COMMIT [TRANSACTION | WORK]

Confirma la transacción actual. Las palabras clave TRANSACTION y WORK son opcionales y equivalentes, y no tienen ningún efecto.

  • Al confirmar una transacción de lectura y escritura, todas las actualizaciones de esta transacción se hacen visibles para otras transacciones y se liberan todos los bloqueos de la transacción en Spanner.
  • Al confirmar una transacción de solo lectura, se finaliza la transacción de solo lectura actual. Cualquier instrucción posterior inicia una nueva transacción. No hay diferencia semántica entre COMMIT y ROLLBACK en una transacción de solo lectura.

Solo puedes ejecutar esta instrucción mientras haya una transacción activa.

▶ Ejemplo: COMMIT TRANSACTION (haz clic para ampliar)
 En el siguiente ejemplo se muestra cómo confirmar una transacción con PGAdapter.

-- Execute a regular read/write transaction.
BEGIN;
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);
COMMIT;

-- Execute a read-only transaction. Read-only transactions also need to be
-- either committed or rolled back in PGAdapter in order to mark the
-- end of the transaction.
BEGIN READ ONLY;
SELECT first_name, last_name
FROM singers
ORDER BY last_name;
COMMIT;

ROLLBACK [TRANSACTION | WORK]

ROLLBACK [TRANSACTION | WORK]

Realiza una ROLLBACK de la transacción actual. Las palabras clave TRANSACTION y WORK son opcionales y equivalentes, y no tienen ningún efecto.

  • Al realizar una ROLLBACK de una transacción de lectura y escritura, se borran todas las mutaciones almacenadas en búfer, se revierte la transacción en Spanner y se liberan todos los bloqueos que tenía la transacción.
  • Al realizar una ROLLBACK de una transacción de solo lectura, se finaliza la transacción de solo lectura actual. Las instrucciones posteriores inician una nueva transacción. No hay ninguna diferencia semántica entre COMMIT y ROLLBACK en una transacción de solo lectura en una conexión.

Solo puedes ejecutar esta instrucción mientras haya una transacción activa.

▶ Ejemplo: ROLLBACK TRANSACTION (haz clic para ampliar)
 En el siguiente ejemplo se muestra cómo revertir una transacción con PGAdapter.

-- Use ROLLBACK to undo the effects of a transaction.
BEGIN;
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);
-- This will ensure that the insert statement is not persisted in the database.
ROLLBACK;

-- Read-only transactions also need to be either committed or rolled back in
-- PGAdapter in order to mark the end of the transaction. There is no
-- semantic difference between rolling back or committing a read-only
-- transaction.
BEGIN READ ONLY;
SELECT first_name, last_name
FROM singers
ORDER BY last_name;
ROLLBACK;

SET TRANSACTION

SET TRANSACTION { READ ONLY | READ WRITE }

Define el modo de transacción de la transacción actual.

Solo puedes ejecutar esta instrucción cuando AUTOCOMMIT es false o si has iniciado una transacción ejecutando BEGIN [TRANSACTION | WORK] y aún no has ejecutado ninguna instrucción en la transacción.

Esta instrucción solo define el modo de transacción de la transacción actual. Cuando se confirma o se revierte la transacción, la siguiente transacción usa el modo predeterminado para la conexión. Consulta SET SESSION CHARACTERISTICS.

▶ Ejemplo: SET TRANSACTION (haz clic para desplegar)
 En el siguiente ejemplo se muestra cómo definir las características de una transacción con PGAdapter.

-- Start a transaction and set the transaction mode to read-only.
BEGIN;
SET TRANSACTION READ ONLY;

SELECT first_name, last_name
FROM singers
ORDER BY last_name;

-- Commit the read-only transaction to mark the end of the transaction.
COMMIT;

-- Start a transaction and set the transaction mode to read/write.
BEGIN;
SET TRANSACTION READ WRITE;

INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);

COMMIT;

SET SESSION CHARACTERISTICS

SET SESSION CHARACTERISTICS AS TRANSACTION { READ ONLY | READ WRITE }

Define el modo de transacción predeterminado de las transacciones de la sesión como READ ONLY o READ WRITE. Esta instrucción solo se permite cuando no hay ninguna transacción activa.

El comando SET TRANSACTION puede anular este ajuste.

▶ Ejemplo: SET SESSION CHARACTERISTICS (Haz clic para desplegar)
 En el siguiente ejemplo se muestra cómo definir las características de la sesión con PGAdapter.

-- Set the default transaction mode to read-only.
SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY;

-- This will now start a read-only transaction.
BEGIN;
SELECT first_name, last_name
FROM singers
ORDER BY last_name;
COMMIT;

-- You can override the default transaction mode with the SET TRANSACTION
-- statement.
SET SESSION CHARACTERISTICS AS TRANSACTION READ WRITE;
BEGIN;
SET TRANSACTION READ ONLY;
SELECT first_name, last_name
FROM singers
ORDER BY last_name;
COMMIT;

SPANNER.STATEMENT_TAG

Propiedad de tipo STRING que contiene la etiqueta de solicitud de la siguiente instrucción.

SHOW [ VARIABLE ] SPANNER.STATEMENT_TAG
SET SPANNER.STATEMENT_TAG {TO|=} 'tag-name'

Define la etiqueta de solicitud de la siguiente instrucción que se va a ejecutar. Solo se puede definir una etiqueta por instrucción. La etiqueta no abarca varias instrucciones, sino que debe definirse por instrucción. Una etiqueta de solicitud se puede quitar asignándole la cadena vacía ('').

El valor predeterminado es ''.

Puede definir etiquetas de transacción y de extracto para el mismo extracto.

También puedes usar una sugerencia de declaración para añadir una etiqueta de declaración:

/*@STATEMENT_TAG='my-tag'*/ SELECT * FROM albums

Para obtener más información, consulta Solucionar problemas con etiquetas de solicitud y de transacción.

▶ Ejemplo: Etiquetas de declaración (haz clic para desplegar)
 En el siguiente ejemplo se muestra cómo definir etiquetas de instrucción con PGAdapter.

-- Set the statement tag that should be included with the next statement.
SET SPANNER.STATEMENT_TAG = 'tag1';
SELECT first_name, last_name
FROM singers
ORDER BY last_name;

-- The statement tag property is cleared after each statement execution.
SHOW SPANNER.STATEMENT_TAG;
-- Set another tag for the next statement.
SET SPANNER.STATEMENT_TAG = 'tag2';
SELECT title
FROM albums
ORDER BY title;

-- Set a statement tag with a query hint.
/*@STATEMENT_TAG='tag3'*/
SELECT track_number, title
FROM tracks
WHERE album_id=1 AND singer_id=1
ORDER BY track_number;

SPANNER.TRANSACTION_TAG

Propiedad de tipo STRING que contiene la etiqueta de transacción de la siguiente transacción.

SHOW [ VARIABLE ] SPANNER.TRANSACTION_TAG
SET SPANNER.TRANSACTION_TAG {TO|=} 'tag-name'

Define la etiqueta de transacción de la transacción actual que se va a ejecutar. Solo se puede definir una etiqueta por transacción. La etiqueta no abarca varias transacciones, sino que debe definirse para cada transacción. Para quitar una etiqueta de transacción, debe asignarle una cadena vacía (''). La etiqueta de transacción debe definirse antes de que se ejecute ninguna instrucción en la transacción.

El valor predeterminado es ''.

Puede definir etiquetas de transacción y de extracto para el mismo extracto.

Para obtener más información, consulta Solucionar problemas con etiquetas de solicitud y de transacción.

▶ Ejemplo: etiquetas de transacción (haz clic para ampliar)
 En el siguiente ejemplo se muestra cómo definir etiquetas de transacción con PGAdapter.

BEGIN;
-- Set the transaction tag for the current transaction.
SET SPANNER.TRANSACTION_TAG = 'transaction-tag-1';

-- Set the statement tag that should be included with the next statement.
-- The statement will include both the statement tag and the transaction tag.
SET SPANNER.STATEMENT_TAG = 'select-statement';
SELECT first_name, last_name
FROM singers
ORDER BY last_name;

-- The statement tag property is cleared after each statement execution.
SHOW SPANNER.STATEMENT_TAG;

-- Set another tag for the next statement.
SET SPANNER.STATEMENT_TAG = 'insert-statement';
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);

COMMIT;

-- The transaction tag property is cleared when the transaction finishes.
SHOW SPANNER.TRANSACTION_TAG;

Declaraciones por lotes

Las siguientes instrucciones gestionan lotes de instrucciones DDL y los envían a Spanner.

START BATCH DDL

START BATCH DDL

Inicia un lote de instrucciones DDL en la conexión. Todas las instrucciones posteriores durante el lote deben ser instrucciones DDL. Las instrucciones DDL se almacenan en búfer localmente y se envían a Spanner como un lote cuando ejecutas RUN BATCH. Ejecutar varias instrucciones DDL como un lote suele ser más rápido que ejecutar las instrucciones por separado.

Solo puedes ejecutar esta instrucción si no hay ninguna transacción activa.

▶ Ejemplo: lote de DDL (haz clic para desplegar)
 En el siguiente ejemplo se muestra cómo ejecutar un lote de DDL con PGAdapter.

-- Start a DDL batch. All following statements must be DDL statements.
START BATCH DDL;

-- This statement is buffered locally until RUN BATCH is executed.
CREATE TABLE singers (
  id bigint primary key,
  first_name varchar,
  last_name varchar
);

-- This statement is buffered locally until RUN BATCH is executed.
CREATE TABLE albums (
  id bigint primary key,
  title varchar,
  singer_id bigint,
  constraint fk_albums_singers foreign key (singer_id) references singers (id)
);

-- This runs the DDL statements as one batch.
RUN BATCH;

EJECUTAR BATCH

RUN BATCH

Envía a la base de datos todas las instrucciones DDL almacenadas en búfer del lote DDL actual, espera a que Spanner ejecute estas instrucciones y finaliza el lote DDL actual.

Si Spanner no puede ejecutar al menos una instrucción DDL, RUN BATCH devuelve un error para la primera instrucción DDL que Spanner no puede ejecutar. De lo contrario, RUN BATCH se devuelve correctamente.

ABORT BATCH

Borra todas las instrucciones DDL almacenadas en el búfer del lote DDL actual y finaliza el lote.

Solo puede ejecutar esta instrucción cuando haya un lote de DDL activo. Puedes usar ABORT BATCH independientemente de si el lote tiene o no instrucciones DDL almacenadas en búfer. Se anularán todas las instrucciones DDL anteriores del lote.

▶ Ejemplo: Abortar lote de DDL (haz clic para desplegar)
 En el siguiente ejemplo se muestra cómo abortar un lote de DDL con PGAdapter.

-- Start a DDL batch. All following statements must be DDL statements.
START BATCH DDL;

-- The following statements are buffered locally.
CREATE TABLE singers (
  id bigint primary key,
  first_name varchar,
  last_name varchar
);
CREATE TABLE albums (
  id bigint primary key,
  title varchar,
  singer_id bigint,
  constraint fk_albums_singers foreign key (singer_id) references singers (id)
);

-- This aborts the DDL batch and removes the DDL statements from the buffer.
ABORT BATCH;

START BATCH DML

Las siguientes instrucciones agrupan las dos instrucciones DML y las envían en una llamada al servidor. Un lote de DML se puede ejecutar como parte de una transacción o en modo de confirmación automática.

START BATCH DML;
INSERT INTO MYTABLE (ID, NAME) VALUES (1, 'ONE');
INSERT INTO MYTABLE (ID, NAME) VALUES (2, 'TWO');
RUN BATCH;

▶ Ejemplo: lote de DML (haz clic para ampliar)
 En el siguiente ejemplo se muestra cómo ejecutar un lote de DML con PGAdapter.

-- Start a DML batch. All following statements must be a DML statement.
START BATCH DML;

-- The following statements are buffered locally.
INSERT INTO MYTABLE (ID, NAME) VALUES (1, 'ONE');
INSERT INTO MYTABLE (ID, NAME) VALUES (2, 'TWO');

-- This sends the statements to Spanner.
RUN BATCH;

-- DML batches can also be part of a read/write transaction.
BEGIN;
-- Insert a row using a single statement.
INSERT INTO MYTABLE (ID, NAME) VALUES (3, 'THREE');

-- Insert two rows using a batch.
START BATCH DML;
INSERT INTO MYTABLE (ID, NAME) VALUES (4, 'FOUR');
INSERT INTO MYTABLE (ID, NAME) VALUES (5, 'FIVE');
RUN BATCH;

-- Rollback the current transaction. This rolls back both the single DML
-- statement and the DML batch.
ROLLBACK;

Comandos de estado guardado

Los puntos de guardado de PGAdapter se emulan. Al volver a un punto de guardado, se revierte toda la transacción y se vuelve a intentar hasta el punto en el que se estableció el punto de guardado. Esta operación fallará y se producirá un error AbortedDueToConcurrentModificationException si los datos subyacentes que ha usado la transacción hasta el punto de guardado han cambiado.

La creación y el lanzamiento de puntos de guardado siempre se realizan correctamente cuando la compatibilidad con puntos de guardado está habilitada.

Las siguientes instrucciones habilitan e inhabilitan los puntos de guardado emulados en las transacciones.

SPANNER.SAVEPOINT_SUPPORT

SHOW [VARIABLE] SPANNER.SAVEPOINT_SUPPORT
SET SPANNER.SAVEPOINT_SUPPORT = { 'DISABLED' | 'FAIL_AFTER_ROLLBACK' | 'ENABLED' }

Una propiedad de tipo STRING que indica la SAVEPOINT_SUPPORT configuración actual. Los valores posibles son:

  • DISABLED: todos los comandos de punto de guardado están inhabilitados y no funcionarán.
  • FAIL_AFTER_ROLLBACK: los comandos de punto de guardado están habilitados. Al restaurar un punto de guardado, se revierte toda la transacción. La operación falla si intentas usar la transacción después de volver a un punto de guardado.
  • ENABLED: todos los comandos de punto de guardado están habilitados. Si se revierte a un punto de guardado, se revierte la transacción y se vuelve a intentar hasta el punto de guardado. Esta operación falla y devuelve un error AbortedDueToConcurrentModificationException si los datos subyacentes que ha usado la transacción hasta el punto de guardado han cambiado.

El valor predeterminado es ENABLED.

Solo puedes ejecutar esta instrucción si no hay ninguna transacción activa.

SAVEPOINT nombre_punto_guardado

SAVEPOINT savepoint-name;

SAVEPOINT crea un nuevo punto de restauración en la transacción actual. Una transacción se puede revertir a un punto de guardado para deshacer todas las operaciones que se hayan ejecutado desde que se creó el punto de guardado.

▶ Ejemplo: Punto de guardado (haz clic para ampliar)
 En el siguiente ejemplo se muestra cómo guardar puntos con PGAdapter.

-- Start a transaction and execute an insert statement.
BEGIN;
INSERT INTO T (id, col_a, col_b) VALUES (1, 100, 1);

-- Set a savepoint and then execute another insert statement.
SAVEPOINT one_row_inserted;
INSERT INTO T (id, col_a, col_b) VALUES (2, 200, 2);

-- Roll back to the savepoint. This will undo all statements that have been
-- executed after the savepoint.
ROLLBACK TO one_row_inserted;

-- This only commits the first insert statement.
COMMIT;

ROLLBACK TO savepoint_name

ROLLBACK TO savepoint_name

Revierte la transacción actual al punto de guardado con el nombre especificado.

No se garantiza que la restauración a un punto de guardado se realice correctamente en todos los casos. Al volver a un punto de guardado, se revierte toda la transacción y se vuelve a intentar hasta el punto en el que se estableció el punto de guardado. Esta operación fallará con un AbortedDueToConcurrentModificationException si los datos subyacentes que ha usado la transacción hasta el punto de guardado han cambiado.

RELEASE [SAVEPOINT] savepoint_name

RELEASE savepoint_name

Quita el punto de restauración de la transacción actual. Ya no se puede usar para ejecutar una instrucción ROLLBACK TO savepoint_name.

Instrucciones preparadas

Las siguientes instrucciones crean y ejecutan instrucciones preparadas.

PREPARAR

PREPARE statement_name [(data_type, ...)] AS statement

Prepara una instrucción sobre esta conexión. La instrucción se analiza y valida por Spanner y se almacena en la memoria de PGAdapter.

▶ Ejemplo: Instrucciones preparadas (haz clic para ampliar)
 En el siguiente ejemplo se muestra cómo crear y ejecutar instrucciones preparadas con PGAdapter.

-- Create a prepared statement that can be used to insert a single row.
PREPARE insert_t AS INSERT INTO T (id, col_a, col_b) VALUES ($1, $2, $3);

-- The prepared statement can be used to insert rows both in autocommit, in a
-- transaction, and in DML batches.

-- Execute in autocommit.
EXECUTE insert_t (1, 100, 1);

-- Execute in transaction.
BEGIN;
EXECUTE insert_t (2, 200, 2);
EXECUTE insert_t (3, 300, 3);
COMMIT;

-- Execute in a DML batch.
START BATCH DML;
EXECUTE insert_t (4, 400, 4);
EXECUTE insert_t (5, 500, 5);
RUN BATCH;

-- Prepared statements can be removed with the DEALLOCATE command.
DEALLOCATE insert_t;

EXECUTE

EXECUTE statement_name [(value, ...)]

Ejecuta una instrucción que se ha creado en esta conexión con PREPARE.

▶ Ejemplo: Ejecutar (haz clic para desplegar)
 En el siguiente ejemplo se muestra cómo preparar y ejecutar instrucciones con PGAdapter.

-- Create a prepared statement.
PREPARE my_statement AS insert into my_table (id, value) values ($1, $2);

-- Execute the statement twice with different parameter values.
EXECUTE my_statement (1, 'One');
EXECUTE my_statement (2, 'Two');

DEALLOCATE

DEALLOCATE statement_name

Elimina una instrucción preparada de esta conexión.

Copiar

PGAdapter admite un subconjunto del comando COPY de PostgreSQL.

COPY table_name FROM STDIN

COPY table_name FROM STDIN [BINARY]

Copia datos de stdin en Spanner. Es más eficiente usar COPY para importar un conjunto de datos grande a Spanner que ejecutar instrucciones INSERT.

COPY se puede combinar con SPANNER.AUTOCOMMIT_DML_MODE para ejecutar una transacción no atómica. De esta forma, la transacción puede ejecutar más mutaciones que el límite de mutaciones de transacción estándar.

▶ Ejemplo: Copiar (haz clic para ampliar)
 En los siguientes ejemplos se muestra cómo copiar datos en Spanner y desde Spanner con PGAdapter.

create table numbers (number bigint not null primary key, name varchar);

Ejecuta una operación atómica COPY:

cat numbers.txt | psql -h /tmp -d test-db -c "copy numbers from stdin;"

Ejecuta una operación COPY no atómica:

cat numbers.txt | psql -h /tmp -d test-db \
  -c "set spanner.autocommit_dml_mode='partitioned_non_atomic'; copy numbers from stdin;"

Copia datos de PostgreSQL a Spanner:

psql -h localhost -p 5432 -d my-local-db \
  -c "copy (select i, to_char(i, 'fm000') from generate_series(1, 1000000) s(i)) to stdout binary" \
  | psql -h localhost -p 5433 -d my-spanner-db \
  -c "set spanner.autocommit_dml_mode='partitioned_non_atomic'; copy numbers from stdin binary;"

En este ejemplo se presupone que PostgreSQL se ejecuta en el puerto 5432 y PGAdapter en el puerto 5433.

Para ver más ejemplos, consulta PGAdapter - Compatibilidad con COPY.

COPY table_name TO STDOUT [BINARY]

COPY table_name TO STDOUT [BINARY]

Copia los datos de una tabla o de una consulta en stdout.

Acelerador de datos y sentencias de consulta con particiones

Data Boost te permite ejecutar consultas analíticas y exportaciones de datos con un impacto casi nulo en las cargas de trabajo de la instancia de Spanner aprovisionada. El aumento de datos solo se admite en las consultas particionadas.

Puedes habilitar Data Boost con la instrucción SET SPANNER.DATA_BOOST_ENABLED.

PGAdapter admite tres alternativas para ejecutar consultas particionadas:

  • SET SPANNER.AUTO_PARTITION_MODE = true
  • RUN PARTITIONED QUERY sql
  • PARTITION sql seguido de varios RUN PARTITION 'partition-token'

Cada uno de estos métodos se describe en las secciones siguientes.

SPANNER.DATA_BOOST_ENABLED

SHOW SPANNER.DATA_BOOST_ENABLED
SET SPANNER.DATA_BOOST_ENABLED {TO|=} { true | false }

Define si esta conexión debe usar Data Boost para las consultas particionadas.

El valor predeterminado es false.

▶ Ejemplo: Ejecutar una consulta con Data Boost (haga clic para ampliar)
 En el siguiente ejemplo se muestra cómo hacer una consulta con Data Boost y PGAdapter.

-- Enable Data Boost on this connection.
SET SPANNER.DATA_BOOST_ENABLED = true;

-- Execute a partitioned query. Data Boost is only used for partitioned queries.
RUN PARTITIONED QUERY SELECT FirstName, LastName FROM Singers;

SPANNER.AUTO_PARTITION_MODE

SHOW SPANNER.AUTO_PARTITION_MODE
SET SPANNER.AUTO_PARTITION_MODE {TO|=} { true | false}

Propiedad de tipo BOOL que indica si la conexión usa automáticamente consultas particionadas para todas las consultas que se ejecutan.

  • Asigna el valor true a esta variable si quieres que la conexión use consultas particionadas para todas las consultas que se ejecuten.
  • También puedes definir SPANNER.DATA_BOOST_ENABLED como true si quieres que la conexión use Data Boost para todas las consultas.

El valor predeterminado es false.

▶ Ejemplo: Ejecutar (haz clic para desplegar)
 En este ejemplo se ejecutan dos consultas con PGAdapter usando Data Boost.

SET SPANNER.AUTO_PARTITION_MODE = true
SET SPANNER.DATA_BOOST_ENABLED = true
SELECT first_name, last_name FROM singers
SELECT singer_id, title FROM albums

EJECUTAR CONSULTA PARTICIONADA

RUN PARTITIONED QUERY <sql>

Ejecuta una consulta como consulta con particiones en Spanner. Asegúrate de que SPANNER.DATA_BOOST_ENABLED esté configurado como true para ejecutar la consulta con Data Boost:

SET SPANNER.DATA_BOOST_ENABLED = true
RUN PARTITIONED QUERY SELECT FirstName, LastName FROM Singers

PGAdapter particiona internamente la consulta y ejecuta las particiones en paralelo. Los resultados se combinan en un conjunto de resultados y se devuelven a la aplicación. El número de hilos de trabajador que ejecutan particiones se puede definir con la variable SPANNER.MAX_PARTITIONED_PARALLELISM.

PARTITION <SQL>

PARTITION <sql>

Crea una lista de particiones para ejecutar una consulta en Spanner y devuelve una lista de tokens de partición. Cada token de partición se puede ejecutar en una conexión independiente en la misma instancia de PGAdapter o en otra mediante el comando RUN PARTITION 'partition-token'.

▶ Ejemplo: Consulta de partición (haz clic para desplegar)
 En el siguiente ejemplo se muestra cómo particionar una consulta y, a continuación, ejecutar cada partición por separado mediante PGAdapter.

-- Partition a query. This returns a list of partition tokens that can be
-- executed either on this connection or on any other connection to the same
-- database.
PARTITION SELECT FirstName, LastName FROM Singers;

-- Run the partitions that were returned from the previous statement.
RUN PARTITION 'partition-token-1';
RUN PARTITION 'partition-token-2';

EJECUTAR PARTICIÓN 'partition-token'

RUN PARTITION 'partition-token'

Ejecuta una partición de consulta que ha devuelto previamente el comando PARTITION. El comando se puede ejecutar en cualquier conexión que esté conectada a la misma base de datos que la base de datos que creó los tokens de partición.

SPANNER.MAX_PARTITIONED_PARALLELISM

Propiedad de tipo bigint que indica el número de subprocesos de trabajo que usa PGAdapter para ejecutar particiones. Este valor se usa para lo siguiente:

  • SPANNER.AUTO_PARTITION_MODE = true
  • RUN PARTITIONED QUERY sql
SHOW SPANNER.MAX_PARTITIONED_PARALLELISM
SET SPANNER.MAX_PARTITIONED_PARALLELISM {TO|=} <bigint>

Define el número máximo de hilos de trabajador que PGAdapter puede usar para ejecutar particiones. Si asignas el valor 0, PGAdapter usará el número de núcleos de CPU del equipo cliente como máximo.

El valor predeterminado es 0.

Siguientes pasos