Comandos de administración de sesiones de JDBC (PostgreSQL)

El controlador JDBC de Spanner (Java Database Connectivity) es compatible con las declaraciones de administración de sesiones, que te permiten modificar el estado de tu conexión, ejecutar transacciones y ejecutar lotes de declaraciones de manera eficiente.

Los siguientes comandos se aplican a las bases de datos de dialecto de PostgreSQL.

Declaraciones de conexión

Las siguientes declaraciones realizan cambios o muestran propiedades de la conexión actual.

SPANNER.READONLY

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

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

Puedes cambiar el valor de esta propiedad solo mientras no haya una transacción activa.

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

-- The following two queries both use the read-only transaction.
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

SELECT Title
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 starts
-- a new read-only transaction.
COMMIT;

AUTOCOMMIT

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

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

Puedes cambiar el valor de esta propiedad solo cuando no haya una transacción activa.

Cuando AUTOCOMMIT se establece como "false", se inicia una transacción nueva automáticamente después de que ejecutas COMMIT o ROLLBACK. La primera sentencia que ejecutas empieza la transacción.

-- 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 = FALSE;

-- 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

Es un valor booleano que indica si la conexión reintenta de manera automática las transacciones anuladas. El valor predeterminado es true.

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

Puedes cambiar el valor de esta propiedad solo después de que se inicie una transacción (consulta BEGIN TRANSACTION) y antes de que se ejecute cualquier sentencia dentro de la transacción.

Cuando estableces SPANNER.RETRY_ABORTS_INTERNALLY como verdadero, la conexión mantiene una suma de verificación de todos los datos que la conexión muestra a la aplicación cliente. Se usa para volver a intentar la transacción si Spanner la aborta.

El valor predeterminado es true. Te recomendamos establecer este valor en false si tu aplicación ya reintenta transacciones anuladas.

SPANNER.AUTOCOMMIT_DML_MODE

Es una propiedad STRING que indica el modo de confirmación automática para las sentencias de lenguaje de manipulación de datos (DML).

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

Los siguientes son los valores posibles:

• En el modo TRANSACTIONAL, el controlador ejecuta las declaraciones DML como transacciones atómicas independientes. El controlador crea una nueva transacción, ejecuta la declaración DML y confirma la transacción cuando se ejecuta de manera correcta o revierte la transacción en caso de error.
• En el modo PARTITIONED_NON_ATOMIC, el controlador ejecuta declaraciones DML como declaraciones de actualización particionadas. Una declaración de actualización particionada puede ejecutarse como una serie de varias transacciones, cada una de las cuales cubre un subconjunto de las filas afectadas. La sentencia particionada proporciona una semántica debilitada a cambio de una mejor escalabilidad y rendimiento.

El valor predeterminado es TRANSACTIONAL.

-- 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

Es una propiedad de tipo STRING que indica el valor de tiempo de espera actual para las sentencias.

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. DEFAULT significa 0 segundos, lo que equivale a no tener tiempo de espera. Un número int8 sin unidades indica ms. Si se estableció un valor de tiempo de espera de la sentencia, las sentencias que tarden más que el valor de tiempo de espera especificado provocarán un error java.sql.SQLTimeoutException y invalidarán la transacción.

Las unidades de tiempo admitidas son las que se muestran a continuación:

• s: Segundos
• ms: Milésimas de segundo
• us: Microsegundos
• ns: Nanosegundos

El valor predeterminado es 0, lo que significa que no hay tiempo de espera.

Si se agota el tiempo de espera de una declaración durante una transacción, se invalida la transacción, todas las declaraciones posteriores de la transacción invalidada (excepto ROLLBACK) fallan y el controlador JDBC de Spanner arroja java.sql.SQLTimeoutException.

SPANNER.READ_ONLY_STALENESS

Es una propiedad de tipo STRING que indica la configuración de inactividad de solo lectura actual que Spanner usa para las consultas y transacciones 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 de inactividad de solo lectura se aplica a todas las transacciones posteriores de solo lectura y a todas las consultas en el modo AUTOCOMMIT.

El valor predeterminado es STRONG.

Las opciones de límite de marca de tiempo son las que se muestran a continuación:

• STRONG le indica a Spanner que realice una lectura sólida.
• MAX_STALENESS define el intervalo de tiempo que Spanner usa para realizar una lectura de inactividad limitada, en relación con now().
• MIN_READ_TIMESTAMP define el tiempo absoluto que Spanner usa para realizar una lectura de inactividad limitada.
• EXACT_STALENESS define el intervalo de tiempo que Spanner usa para realizar una lectura de inactividad exacta, en relación con now().
• READ_TIMESTAMP define un tiempo absoluto que Spanner usa para realizar una lectura de inactividad exacta.

Las marcas de tiempo deben usar el siguiente formato:

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

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

• s: Segundos
• ms: Milésimas de segundo
• us: Microsegundos
• ns: Nanosegundos

Puedes modificar el valor de esta propiedad solo mientras no haya una transacción activa.

-- 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 returns results that are up to
-- 10 seconds stale.
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Read-only staleness can also be applied to read-only transactions.
-- MAX_STALENESS is 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 FirstName, LastName
FROM Singers
ORDER BY LastName;

SELECT Title, SingerId
FROM Albums
ORDER BY Title;

COMMIT;

-- Set the read staleness to an exact timestamp.
SET SPANNER.READ_ONLY_STALENESS = 'READ_TIMESTAMP 2024-01-26T10:36:00Z';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

SPANNER.OPTIMIZER_VERSION

Es una propiedad de tipo STRING que indica la versión del optimizador. La versión es un número entero o "LATEST".

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

Establece la versión del optimizador que se usará para todas las siguientes instrucciones en la conexión. Si la versión del optimizador se establece en '' (la cadena vacía), Spanner usa la versión más reciente. Si no se establece una versión del optimizador, Spanner usa la versión del optimizador que se establece a nivel de la base de datos.

El valor predeterminado es ''.

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

SPANNER.OPTIMIZER_STATISTICS_PACKAGE

Es 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'|'' }

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

El valor predeterminado es ''.

-- 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 FirstName, LastName
FROM Singers
ORDER BY LastName;

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

SPANNER.RETURN_COMMIT_STATS

Es una propiedad de tipo BOOL que indica si se deben mostrar estadísticas para las transacciones en esta conexión. Para ver las estadísticas que se devuelven, ejecuta el comando SHOW SPANNER.COMMIT_RESPONSE.

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

El valor predeterminado es false.

-- 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

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

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

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

El valor predeterminado es 'NULL'.

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

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

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

Etiquetas

Las siguientes instrucciones administran las etiquetas de solicitudes y transacciones.

SPANNER.STATEMENT_TAG

Es una propiedad de tipo STRING que contiene la etiqueta de solicitud para la siguiente sentencia.

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

Establece la etiqueta de solicitud para que se ejecute la siguiente sentencia. Solo se puede configurar una etiqueta por sentencia. La etiqueta no abarca varias instrucciones; se debe configurar por instrucción. Para quitar una etiqueta de solicitud, configúrala en la cadena vacía ('').

El valor predeterminado es ''.

Puedes configurar etiquetas de transacción y de estado para el mismo estado.

También puedes usar una sugerencia de sentencia para agregar una etiqueta de sentencia:

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

Para obtener más información, consulta Cómo solucionar problemas con las etiquetas de solicitud y las etiquetas de transacción.

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

-- 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 TrackNumber, Title
FROM Tracks
WHERE AlbumId=1 AND SingerId=1
ORDER BY TrackNumber;

SPANNER.TRANSACTION_TAG

Es una propiedad de tipo STRING que contiene la etiqueta de transacción para la siguiente transacción.

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

Establece la etiqueta de transacción para que se ejecute la transacción actual. Solo se puede configurar una etiqueta por transacción. La etiqueta no abarca varias transacciones, sino que se debe configurar por transacción. Para quitar una etiqueta de transacción, debes configurarla en la cadena vacía (''). La etiqueta de transacción se debe configurar antes de que se ejecute cualquier sentencia en la transacción.

El valor predeterminado es ''.

Puedes configurar etiquetas de transacción y de estado para el mismo estado.

Para obtener más información, consulta Cómo solucionar problemas con las etiquetas de solicitud y las etiquetas de transacción.

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 FirstName, LastName
FROM Singers
ORDER BY LastName;

-- 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 de transacciones

Las siguientes declaraciones administran y confirman transacciones de Spanner.

NIVEL DE AISLAMIENTO DE TRANSACCIONES

SHOW [VARIABLE] TRANSACTION ISOLATION LEVEL

Muestra un conjunto de resultados con una fila y una columna de tipo STRING. El valor que se muestra siempre es serializable.

SPANNER.READ_TIMESTAMP

SHOW [VARIABLE] SPANNER.READ_TIMESTAMP

Muestra un conjunto de resultados con una fila y una columna de tipo TIMESTAMP que contienen la marca de tiempo de lectura de la transacción de solo lectura más reciente. Esta declaración muestra una marca de tiempo solo cuando una transacción de solo lectura aún está activa y ejecuta al menos una consulta, o inmediatamente después de que se confirma una transacción de solo lectura y antes de que comience una nueva transacción. De lo contrario, el resultado es NULL.

-- Execute a query in autocommit mode using the default read-only staleness
-- (strong).
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Show 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 FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Show 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 FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Show 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

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

-- 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

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

• COMMIT_TIMESTAMP (type=TIMESTAMP) indica cuándo se confirmó la transacción más reciente.
• MUTATION_COUNT (type=INT64) indica cuántas mutaciones se aplicaron 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 SPANNER.RETURN_COMMIT_STATS se configuró como true antes de confirmar la transacción.

-- 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 transacción nueva. Las palabras clave TRANSACTION y WORK son opcionales, equivalentes y no tienen efecto.

• Usa COMMIT o ROLLBACK para finalizar una transacción.
• Si habilitaste el modo AUTOCOMMIT, esta declaración quitará la conexión del modo AUTOCOMMIT de forma temporal. La conexión regresa al modo AUTOCOMMIT cuando finaliza la transacción.
• Si no se especifica READ ONLY o READ WRITE, el modo de transacción se determina según el modo de transacción predeterminado de la sesión. Este valor predeterminado se configura con el comando SET SESSION CHARACTERISTICS AS TRANSACTION o con la variable READONLY.

Puedes ejecutar esta declaración solo si no hay transacciones activas.

-- This starts a transaction using the current defaults of this connection.
-- The value of 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 READONLY to TRUE to use read-only transactions by default.
SET READONLY=TRUE;

-- This starts a read-only transaction.
BEGIN;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
COMMIT;

-- Add 'READ WRITE' or 'READ ONLY' to the 'BEGIN' command to
-- override the current default of the connection.
SET READONLY=FALSE;
BEGIN READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
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.

• Si se confirma una transacción de lectura y escritura, todas las actualizaciones de esta transacción serán visibles para otras transacciones y se liberarán todos los bloqueos de la transacción en Spanner.
• La confirmación de una transacción de solo lectura finaliza la transacción de solo lectura actual. Cualquier declaración posterior inicia una nueva transacción. No hay diferencia semántica entre COMMIT y ROLLBACK para una transacción de solo lectura.

Puedes ejecutar esta declaración solo mientras haya una transacción activa.

-- 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 the Spanner JDBC driver in order
-- to mark the end of the transaction.
BEGIN READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
COMMIT;

{ ABORT | ROLLBACK } [TRANSACTION | WORK]

{ ABORT | 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.

• Si realizas una ROLLBACK de una transacción de lectura y escritura, borras las mutaciones de búfer, reviertes la transacción en Spanner y liberas todos los bloqueos que tenía la transacción.
• Si realizas una ROLLBACK de una transacción de solo lectura, finalizas la transacción de solo lectura actual. Las declaraciones posteriores inician una nueva transacción. No hay diferencia semántica entre COMMIT y ROLLBACK para una transacción de solo lectura en una conexión.

Puedes ejecutar esta declaración solo mientras haya una transacción activa.

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

-- Read-only transactions also need to be either committed or rolled back in the
-- Spanner JDBC driver 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 FirstName, LastName
FROM Singers
ORDER BY LastName;
ROLLBACK;

SET TRANSACTION

SET TRANSACTION { READ ONLY | READ WRITE }

Establece el modo de transacción para la transacción actual.

Puedes ejecutar esta sentencia solo cuando AUTOCOMMIT sea false o si iniciaste una transacción con la ejecución de BEGIN [TRANSACTION | WORK] y aún no ejecutaste ninguna sentencia en la transacción.

Esta sentencia establece el modo de transacción solo para la transacción actual. Cuando la transacción se confirma o se revierte, la siguiente transacción usa el modo predeterminado para la conexión. (consulta SET SESSION CHARACTERISTICS).

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

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- 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;

DEFINE LAS CARACTERÍSTICAS DE LA SESIÓN

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

Establece el modo de transacción predeterminado para las transacciones de la sesión en READ ONLY o READ WRITE. Esta sentencia solo se permite cuando no hay una transacción activa.

El comando SET TRANSACTION puede anular este parámetro de configuración.

Declaraciones por lotes

Las siguientes declaraciones administran lotes de declaraciones de DDL y envían esos lotes a Spanner.

START BATCH DDL

START BATCH DDL

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

Puedes ejecutar esta declaración solo si no hay transacciones activas.

-- 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 (
  SingerId  BIGINT NOT NULL PRIMARY KEY,
  FirstName VARCHAR,
  LastName  VARCHAR
);

-- This statement is buffered locally until RUN BATCH is executed.
CREATE TABLE Albums (
  AlbumId  BIGINT NOT NULL PRIMARY KEY,
  Title    VARCHAR,
  SingerId BIGINT,
  CONSTRAINT fk_albums_singers FOREIGN KEY (SingerId) REFERENCES Singers (SingerId)
);

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

RUN BATCH

RUN BATCH

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

Si Spanner no puede ejecutar al menos una declaración de DDL, RUN BATCH muestra un error para la primera declaración de DDL que Spanner no puede ejecutar. De lo contrario, RUN BATCH se muestra de forma correcta.

ABORT BATCH

ABORT BATCH

Borra todas las declaraciones de DDL almacenadas en búfer en el lote de DDL actual y finaliza el lote.

Puedes ejecutar esta declaración solo cuando un lote de DDL está activo. Puedes usar ABORT BATCH sin importar si el lote tiene o no declaraciones de DDL almacenadas en búfer. Se abortarán todas las declaraciones de DDL anteriores en el lote.

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

-- The following statements are buffered locally.
CREATE TABLE Singers (
  SingerId  BIGINT NOT NULL PRIMARY KEY,
  FirstName VARCHAR,
  LastName  VARCHAR
);

-- This statement is buffered locally until RUN BATCH is executed.
CREATE TABLE Albums (
  AlbumId  BIGINT NOT NULL PRIMARY KEY,
  Title    VARCHAR,
  SingerId BIGINT,
  CONSTRAINT fk_albums_singers FOREIGN KEY (SingerId) REFERENCES Singers (SingerId)
);

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

START BATCH DML y RUN BATCH

Las siguientes sentencias agrupan las dos sentencias DML y las envían en una sola llamada al servidor. Un lote de DML se puede ejecutar como parte de una transacción o en el 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;

-- 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;

Data Boost y sentencias de consulta particionadas

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.

Puedes habilitar el aumento de datos en la conexión actual con la instrucción SET SPANNER.DATA_BOOST_ENABLED.

El controlador JDBC 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 siguientes secciones.

SPANNER.DATA_BOOST_ENABLED

Es una propiedad de tipo BOOL que indica si esta conexión debe usar Data Boost para las consultas particionadas. El valor predeterminado es false.

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

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

El valor predeterminado es false.

-- 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;

Para ver un ejemplo completo, consulta DataBoostExample de PostgreSQL.

SPANNER.AUTO_PARTITION_MODE

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

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

• Establece esta variable en true si deseas que la conexión use la consulta particionada para todas las consultas que se ejecuten.
• También establece SPANNER.DATA_BOOST_ENABLED en true si deseas que la conexión use Data Boost para todas las consultas.

El valor predeterminado es false.

SET SPANNER.AUTO_PARTITION_MODE = true
SET SPANNER.DATA_BOOST_ENABLED = true
SELECT FirstName, LastName FROM Singers
SELECT SingerId, Title FROM Albums

Para ver un ejemplo completo, consulta AutoPartitionModeExample de PostgreSQL.

EJECUTAR CONSULTA PARTICIONADA

RUN PARTITIONED QUERY <sql>

Ejecuta una consulta como una consulta particionada 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

El controlador JDBC particiona la consulta de forma interna y ejecuta particiones en paralelo. Los resultados se combinan en un conjunto de resultados y se devuelven a la aplicación. La cantidad de subprocesos de trabajador que ejecutan particiones se puede establecer con la variable SPANNER.MAX_PARTITIONED_PARALLELISM.

Para ver un ejemplo completo, consulta PostgreSQL RunPartitionedQueryExample.

PARTITION <SQL>

PARTITION <sql>

Crea una lista de particiones para ejecutar una consulta en Spanner y muestra una lista de tokens de partición. Cada token de partición se puede ejecutar en una conexión JDBC independiente en el mismo host o en otro con el comando RUN PARTITION 'partition-token'.

-- 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';

Para ver un ejemplo completo, consulta PartitionQueryExample de PostgreSQL.

RUN PARTITION 'partition-token'

RUN PARTITION 'partition-token'

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

Para ver un ejemplo completo, consulta PartitionQueryExample de PostgreSQL.

SPANNER.MAX_PARTITIONED_PARALLELISM

Es una propiedad de tipo int8 que indica la cantidad de subprocesos de trabajo que usa el controlador JDBC de Spanner para ejecutar particiones. Este valor se usa para lo siguiente:

• SPANNER.AUTO_PARTITION_MODE = true
• RUN PARTITIONED QUERY sql

SHOW [VARIABLE] SPANNER.MAX_PARTITIONED_PARALLELISM
SET SPANNER.MAX_PARTITIONED_PARALLELISM = <int8>

Establece la cantidad máxima de subprocesos de trabajo que puede usar el controlador JDBC de Spanner para ejecutar particiones. Si estableces este valor en 0, se le indica al controlador JDBC de Spanner que use la cantidad de núcleos de CPU en la máquina cliente como el máximo.

El valor predeterminado es 0.

Comandos de punto de guardado

Las siguientes instrucciones habilitan y desactivan los puntos de guardado emulados en las transacciones. Para crear un punto de guardado, llama al método java.sql.Connection#setSavepoint().

El controlador de JDBC de Spanner emula puntos de guardado para admitir frameworks que dependen de ellos para las transacciones anidadas. Para emular los puntos de guardado, se realiza un seguimiento de una suma de comprobación en ejecución para los resultados que devolvieron las instrucciones en la transacción. Cuando se revierte a un punto de guardado, el controlador JDBC de Spanner revierte la transacción y, luego, vuelve a intentarla hasta el punto en el que se estableció el punto de guardado. La suma de comprobación de la reintento se compara con la suma de comprobación de la transacción inicial para verificar que se hayan devuelto los mismos resultados.

SPANNER.SAVEPOINT_SUPPORT

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

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

• DISABLED: Todos los comandos de punto de guardado están inhabilitados y fallarán.
• FAIL_AFTER_ROLLBACK: Los comandos de punto de guardado están habilitados. Si se revierte a un punto de guardado, se revierte toda la transacción. La transacción falla si intentas usarla después de revertir 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 revertirá la transacción y se volverá a intentar el punto de guardado. Esta operación falla con un error AbortedDueToConcurrentModificationException si cambiaron los datos subyacentes que usó la transacción hasta el punto de guardado.

El valor predeterminado es FAIL_AFTER_ROLLBACK.

Puedes cambiar el valor de esta variable solo mientras no haya una transacción activa.

try (Connection connection =
    DriverManager.getConnection(
        String.format(
            "jdbc:cloudspanner:/projects/%s/instances/%s/databases/%s",
            "my-project", "my-instance", "my-database"))) {
  // Savepoints can only be used when AutoCommit=false.
  connection.setAutoCommit(false);

  // Disables setting a savepoint.
  connection.createStatement().execute("SET SPANNER.SAVEPOINT_SUPPORT='DISABLED'");
  // The following statement fails because savepoints have been disabled.
  connection.setSavepoint("my_savepoint1");

  // Enables setting a savepoint and releasing a savepoint.
  // Rolling back to a savepoint is disabled.
  connection.createStatement().execute("SET SPANNER.SAVEPOINT_SUPPORT='FAIL_AFTER_ROLLBACK'");
  Savepoint mySavepoint2 = connection.setSavepoint("my_savepoint2");
  connection.createStatement().execute("insert into my_table (id, value) values (1, 'One')");
  connection.releaseSavepoint(mySavepoint2);
  connection.commit();

  // Enables setting, releasing and rolling back to a savepoint.
  connection.createStatement().execute("SET SPANNER.SAVEPOINT_SUPPORT='ENABLED'");
  Savepoint mySavepoint3 = connection.setSavepoint("my_savepoint3");
  connection.createStatement().execute("insert into my_table (id, value) values (2, 'Two')");
  connection.rollback(mySavepoint3);
}

¿Qué sigue?

Obtén información para conectar JDBC a una base de datos de dialecto de PostgreSQL.