Spanner PGAdapter admite declaraciones de administración de sesiones, que te permiten modificar el estado y el comportamiento de tu conexión, ejecuta y ejecutar lotes de declaraciones de manera eficiente. Todas las afirmaciones que que se describen en este documento se pueden utilizar con cualquier cliente o controlador que se conecta a PGAdapter.
Para obtener más información, consulta una lista completa de los controladores y ORM de PostgreSQL compatibles. El siguientes comandos se aplican a las bases de datos del dialecto de PostgreSQL.
Para obtener más información sobre el uso de PGAdapter, consulta Cómo iniciar PGAdapter.
Declaraciones de conexión
Las siguientes declaraciones realizan cambios o muestran propiedades de la conexión actual.
SPANNER.READONLY
Un valor booleano que indica si la conexión está o no en modo de solo lectura. 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.
▶ Ejemplo: Transacción de solo lectura (haz clic para expandir)
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
Un valor booleano que indica si la conexión está o no en modo de confirmación automática. El valor predeterminado es true
.
NOTA: Por lo general, no es necesario modificar el valor de esta variable cuando
con un controlador PostgreSQL
con PGAdapter. Estos conductores
administrar las transacciones de forma automática mediante la ejecución de BEGIN
y COMMIT
cuando sea necesario. Puedes desactivar autocommit
cuando uses herramientas de línea de comandos, como
psql para evitar que se confirmen modificaciones accidentales de datos
automáticamente.
SHOW [VARIABLE] AUTOCOMMIT
SET AUTOCOMMIT {TO|=} { true | false }
Puedes cambiar el valor de esta propiedad solo cuando no haya ninguna actividad transacción.
Cuando AUTOCOMMIT
se establece como falso, se inicia automáticamente una nueva transacción
después de ejecutar COMMIT
o ROLLBACK
. La primera sentencia que ejecutas
empieza la transacción.
▶ Ejemplo: Confirmación automática (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
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 ejecutar este comando solo después de que se inicia una transacción (consulta BEGIN [TRANSACTION | WORK]
) y antes de que se ejecute cualquier sentencia dentro de la transacción.
Cuando habilitas SPANNER.RETRY_ABORTS_INTERNALLY
, la conexión mantiene una
de todos los datos que la conexión muestra a la aplicación cliente. Esta
para reintentar la transacción si Spanner la anula.
Esta configuración se habilita de forma predeterminada. Te recomendamos desactivar este parámetro de configuración en los siguientes casos: tu aplicación ya reintenta transacciones anuladas.
SPANNER.AUTOCOMMIT_DML_MODE
Una propiedad STRING
que indica el modo de confirmación automática para
Declaraciones 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
.
▶ Ejemplo: DML particionado (haz clic para expandir)
En el siguiente ejemplo, se muestra cómo ejecutar
DML particionada con 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
Una propiedad de tipo STRING
que indica el valor de tiempo de espera actual para las declaraciones.
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. Un valor de DEFAULT
indica que no se estableció un valor de tiempo de espera. Si una
tiempo de espera de la sentencia, las sentencias que tardan más que
un valor de tiempo de espera especificado causará un error de tiempo de espera e invalidará el
transacción.
Las unidades de tiempo admitidas son las que se muestran a continuación:
s
: Segundosms
: Milésimas de segundous
: Microsegundosns
: Nanosegundos
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 siguientes comandos establecen el tiempo de espera de la sentencia en 2 segundos.
SET STATEMENT_TIMEOUT TO 2000;
SET STATEMENT_TIMEOUT TO '2s';
El tiempo de espera de una declaración durante una transacción invalida la transacción,
las declaraciones posteriores en la transacción invalidada (excepto ROLLBACK
) fallan.
READ_ONLY_STALENESS
Una propiedad de tipo STRING
que indica la propiedad
configuración de inactividad de solo lectura que
Spanner usa para transacciones de solo lectura y consultas en 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 todos
para las transacciones de solo lectura posteriores y para todas las consultas en 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 connow()
.MIN_READ_TIMESTAMP
define el tiempo absoluto que Spanner usa para realizar lo siguiente: 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 connow()
.READ_TIMESTAMP
define el tiempo absoluto que Spanner usa para realizar una una lectura de inactividad exacta.
Las marcas de tiempo deben usar el siguiente formato:
YYYY-[M]M-[D]D [[H]H:[M]M:[S]S[.DDDDDD]][timezone]
Las unidades de tiempo admitidas para configurar los valores MAX_STALENESS
y EXACT_STALENESS
son:
s
: Segundosms
: Milésimas de segundous
: Microsegundosns
: Nanosegundos
Puedes modificar el valor de esta propiedad solo mientras no esté activa transacción.
▶ Ejemplo: Inactividad de solo lectura (haz clic para expandir)
En el siguiente ejemplo, se muestra cómo ejecutar consultas con una inactividad personalizada
de salida 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
ya sea un valor numérico o "LATEST
".
SHOW [VARIABLE] SPANNER.OPTIMIZER_VERSION
SET SPANNER.OPTIMIZER_VERSION {TO|=} { 'version'|'LATEST'|'' }
Establece la versión del optimizador que se utilizará para todas las siguientes sentencias en
la conexión. Si configuras la versión del optimizador en ''
(la cadena vacía), se indica que se debe usar la versión más reciente. Si no se establece ninguna versión del optimizador,
Spanner usa la versión del optimizador que se configura en la base de datos
a nivel de organización.
El valor predeterminado es ''
.
▶ Ejemplo: Versión del optimizador (haz clic para expandir)
En el siguiente ejemplo, se muestra cómo ejecutar consultas con una versión de 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 la propiedad
paquete de estadísticas del optimizador
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 siguientes instrucciones en la conexión. <package>
debe ser un nombre de paquete válido. Si no hay optimizador
de estadísticas, Spanner usa las estadísticas del optimizador
que se configura a nivel de la base de datos.
El valor predeterminado es ''
.
▶ Ejemplo: Paquete de estadísticas del optimizador (haz clic para expandir)
En el siguiente ejemplo, se muestra cómo ejecutar consultas usando un bucket
paquete de estadísticas del optimizador 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
Una propiedad de tipo BOOL
que indica si se deben mostrar estadísticas para
transacciones en esta conexión. Para ver las estadísticas mostradas, 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 confirmación (haz clic para expandir)
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
Una propiedad de tipo STRING
que indica la prioridad relativa para
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 {TO|=} {'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
.
Declaraciones de transacciones
Las siguientes declaraciones administran y confirman transacciones de Spanner.
NIVEL DE ISOLACIÓN DE LA TRANSACCIÓN
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
, ya que este es el único nivel de aislamiento compatible con las bases de datos de Spanner con dialecto PostgreSQL.
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
.
▶ Ejemplo: Marca de tiempo de lectura (haz clic para expandir)
En el siguiente ejemplo, se muestra cómo ver la última marca de tiempo de 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
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 Spanner
comprometida. 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
.
▶ Ejemplo: Marca de tiempo de confirmación (haz clic para expandir)
En el siguiente ejemplo, se muestra cómo ver la última marca de tiempo de 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
Muestra un conjunto de resultados con una fila y dos columnas:
COMMIT_TIMESTAMP
(tipo=TIMESTAMP
) Indica cuándo se se confirmó la transacción.MUTATION_COUNT
(type=int8
): Indica cuántas mutaciones se aplicaron en la transacción confirmada. Este valor siempre está vacío cuando se ejecuta en la emulador.
El recuento de mutaciones solo está disponible si SET RETURN_COMMIT_STATS
se configuró 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 para un
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 transacción nueva. Las palabras clave TRANSACTION
y WORK
son opcionales, equivalentes y no tienen efecto.
- Usa
COMMIT
oROLLBACK
para finalizar una transacción. - Si habilitaste el modo
AUTOCOMMIT
, esta declaración quitará la conexión del modoAUTOCOMMIT
de forma temporal. La conexión regresa al modoAUTOCOMMIT
cuando finaliza la transacción. - Si no se especifica
READ ONLY
oREAD WRITE
, el modo de transacción se determina según el modo de transacción predeterminado de la sesión. El valor predeterminado es se puede establecer con el comandoSET SESSION CHARACTERISTICS AS TRANSACTION
.
Puedes ejecutar esta declaración solo si no hay transacciones activas.
▶ Ejemplo: COMENZAR TRANSACCIÓN (haz clic para expandir)
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;
ENVIAR [TRANSACCIÓN | TRABAJO]
COMMIT [TRANSACTION | WORK]
Confirma la transacción actual. Las palabras clave TRANSACTION
y WORK
son
opcionales y equivalentes, y no tienen efecto.
- Cuando se confirma una transacción de lectura y escritura, se realizan todas las actualizaciones de esta transacción visible para otras transacciones y libera todos los bloqueos de la transacción 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
yROLLBACK
para una transacción de solo lectura.
Puedes ejecutar esta declaración solo mientras haya una transacción activa.
▶ Ejemplo: COMMIT TRANSACTION (haz clic para expandir)
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;
REVERSIÓN [TRANSACCIÓN | TRABAJO]
ROLLBACK [TRANSACTION | WORK]
Realiza una ROLLBACK
de la transacción actual. Las palabras clave TRANSACTION
y
Las WORK
son opcionales y equivalentes, y no tienen efecto.
- Realizar una
ROLLBACK
de una transacción de lectura y escritura borra cualquier búfer almacenado mutaciones, revierte la transacción en Spanner y libera bloquea la transacción que contiene. - 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 entreCOMMIT
yROLLBACK
para una transacción de solo lectura en una conexión.
Puedes ejecutar esta declaración solo mientras haya una transacción activa.
▶ Ejemplo: TRANSACCIÓN DE REVERSIÓN (haz clic para expandir)
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 }
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. Cuándo
la transacción se confirma o revierte, la siguiente transacción usa la configuración
modo para la conexión. (consulta SET SESSION CHARACTERISTICS
).
▶ Ejemplo: SET TRANSACTION (haz clic para expandir)
En el siguiente ejemplo, se muestra cómo establecer características de 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;
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 en la sesión:
READ ONLY
o READ WRITE
. Esta declaración solo se permite cuando no hay
transacción activa.
El comando SET TRANSACTION
puede anular esta configuración.
▶ Ejemplo: SET SESSION CHARACTERISTICS (haz clic para expandir)
En el siguiente ejemplo, se muestra cómo establecer características de 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
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 uno
la etiqueta de recurso se puede establecer por instrucción. La etiqueta no abarca varias instrucciones; se debe configurar por instrucción. Para quitar una etiqueta de solicitud, configúrala
a la cadena vacía (''
).
El valor predeterminado es ''
.
Puedes configurar etiquetas de transacción y de estado para la misma declaración.
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 Solución de problemas con etiquetas de solicitud y de transacción.
▶ Ejemplo: Etiquetas de la sentencia (haz clic para expandir)
En el siguiente ejemplo, se muestra cómo establecer etiquetas de sentencia 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
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. it
debe definirse por transacción. Para quitar una etiqueta de transacción,
configúrala en una cadena vacía (''
). La etiqueta de transacción debe establecerse antes del
se ejecutaron todas las sentencias en la transacción.
El valor predeterminado es ''
.
Puedes configurar etiquetas de transacción y de instrucción para la misma declaración.
Para obtener más información, consulta Solución de problemas con etiquetas de solicitud y de transacción.
▶ Ejemplo: Etiquetas de transacción (haz clic para expandir)
En el siguiente ejemplo, se muestra cómo configurar 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 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 DDL se almacenan en búfer de manera local.
y se envían a Spanner como un 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.
▶ Ejemplo: Lote de DDL (haz clic para expandir)
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;
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 DDL, RUN BATCH
devuelve un error para la primera declaración DDL que Spanner no puede
ejecutar. De lo contrario, RUN BATCH
se muestra de forma correcta.
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 anularán todas las declaraciones DDL anteriores del lote.
▶ Ejemplo: Anular lote de DDL (haz clic para expandir)
En el siguiente ejemplo, se muestra cómo anular 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 declaraciones agrupan las dos declaraciones DML y las envían una 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;
▶ Ejemplo: Lote de DML (haz clic para expandir)
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 Savepoint
Se emulan los puntos de guardado en PGAdapter. Revierte a un lanzamiento de punto de guardado
la transacción completa y reintentarla hasta el punto en que
se estableció. Esta operación fallará con un error AbortedDueToConcurrentModificationException
si cambiaron los datos subyacentes que usó la transacción hasta el punto de guardado.
La creación y el lanzamiento de puntos de guardado siempre tienen éxito cuando la compatibilidad con puntos de guardado es habilitado.
Las siguientes instrucciones habilitan y deshabilitan 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' }
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 Savepoint están habilitados. Revierte a un Savepoint revierte la transacción completa. La operación falla si intentas usar la transacción después de revertir a un punto de guardado.ENABLED
: Todos los comandos de punto de guardado están habilitados. Cómo revertir a un punto de guardado revierte la transacción y se vuelve a intentar en el punto de guardado. Esta operación falla con un errorAbortedDueToConcurrentModificationException
si cambiaron los datos subyacentes que usó la transacción hasta el punto de guardado.
El valor predeterminado es ENABLED
.
Puedes ejecutar esta declaración solo si no hay transacciones activas.
SAVEPOINT nombre_del_punto_de_guardado
SAVEPOINT savepoint-name;
SAVEPOINT
crea un nuevo punto de guardado dentro de la transacción actual.
Una transacción puede revertirse a un punto de guardado para deshacer todas las operaciones que tienen
ejecutado desde que se creó el punto de guardado.
▶ Ejemplo: Punto de guardado (haz clic para expandir)
En el siguiente ejemplo, se muestra cómo usar puntos de guardado 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 nombre_punto_de_restablecimiento
ROLLBACK TO savepoint_name
Revierte la transacción actual al punto de guardado con el nombre especificado.
No se garantiza que la reversión a un punto de guardado tenga éxito en todos los casos.
La reversión a un punto de guardado revierte toda la transacción y vuelve a intentarlo
hasta el punto en el
que se estableció el punto de guardado. Esta operación fallará y mostrará un
AbortedDueToConcurrentModificationException
si los datos subyacentes que tienen
hasta el punto de guardado.
RELEASE [SAVEPOINT] nombre_del_punto_de_guardado
RELEASE savepoint_name
Quita el punto de guardado de la transacción actual. Ya no se puede usar para
ejecuta una sentencia ROLLBACK TO savepoint_name
.
Sentencias preparadas
Las siguientes instrucciones crean y ejecutan instrucciones preparadas.
PREPARACIÓN
PREPARE statement_name [(data_type, ...)] AS statement
Prepara una sentencia en esta conexión. La sentencia se analiza y se valida. por Spanner y se almacena en la memoria en PGAdapter.
▶ Ejemplo: Sentencias preparadas (haz clic para expandir)
En el siguiente ejemplo, se muestra cómo crear y ejecutar sentencias 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;
EJECUTAR
EXECUTE statement_name [(value, ...)]
Ejecuta una sentencia que se creó en esta conexión con PREPARE
.
▶ Ejemplo: Ejecutar (haz clic para expandir)
En el siguiente ejemplo, se muestra cómo preparar y ejecutar sentencias 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
Quita una sentencia preparada de esta conexión.
Copiar
PGAdapter admite un subconjunto del comando COPY
de PostgreSQL.
COPIAR nombre_tabla DE STDIN
COPY table_name FROM STDIN [BINARY]
Copia los datos de stdin
a Spanner. Es más eficiente usar
COPY
para importar un conjunto de datos grande a Spanner y luego ejecutarlo
Declaraciones INSERT
.
COPY
se puede combinar con SPANNER.AUTOCOMMIT_DML_MODE
para ejecutar una transacción no atómica. Esto permite que la transacción ejecute más mutaciones que el límite estándar de mutaciones de transacciones.
▶ Ejemplo: Copiar (haz clic para expandir)
En los siguientes ejemplos, se muestra cómo copiar datos desde y hacia
Spanner con PGAdapter.
create table numbers (number bigint not null primary key, name varchar);
Ejecuta una operación COPY
atómica:
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 supone que PostgreSQL se ejecuta en el puerto 5432 y PGAdapter se ejecuta en el puerto 5433.
Para ver más ejemplos, consulta PGAdapter - Compatibilidad con COPIAS.
COPIAR nombre_tabla EN STDOUT [BINARY]
COPY table_name TO STDOUT [BINARY]
Copia los datos de una tabla o de una consulta a stdout
.
Data Boost y sentencias de consulta particionadas
Data Boost le permite ejecutar consultas de análisis y exportaciones de datos con un en las cargas de trabajo existentes en la instancia aprovisionada de Spanner. Refuerzo de datos solo es compatible con consultas particionadas.
Puedes habilitar Data Boost con la sentencia 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 variosRUN PARTITION 'partition-token'
Cada uno de estos métodos se describe en las siguientes secciones.
SPANNER.DATA_BOOST_ENABLED
SHOW 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
.
▶ Ejemplo: Ejecuta una consulta con Data Boost (haz clic para expandir)
En el siguiente ejemplo, se muestra cómo realizar una consulta usando Data Boost con
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}
Es una propiedad de tipo BOOL
que indica si la conexión usa automáticamente consultas particionadas para todas las consultas que se ejecutan.
- 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
entrue
si quieres que para usar Data Boost para todos para tus consultas.
El valor predeterminado es false
.
▶ Ejemplo: Ejecutar (haz clic para expandir)
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 PARTICIPADA
RUN PARTITIONED QUERY <sql>
Ejecuta una consulta como una consulta particionada en Spanner. Asegúrate de que
SPANNER.DATA_BOOST_ENABLED
se configura como true
para ejecutar la consulta.
Data Boost:
SET SPANNER.DATA_BOOST_ENABLED = true
RUN PARTITIONED QUERY SELECT FirstName, LastName FROM Singers
PGAdapter particiona la consulta de forma interna y ejecuta particiones en
en paralelo. Los resultados se combinan en un conjunto de resultados y se devuelven al
y mantener la integridad de su aplicación. Puedes configurar la cantidad de subprocesos de trabajo que ejecutan particiones
la variable SPANNER.MAX_PARTITIONED_PARALLELISM
.
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
se ejecuta en una conexión independiente en el mismo PGAdapter o en otro
con el comando RUN PARTITION 'partition-token'
.
▶ Ejemplo: Consulta de partición (haz clic para expandir)
En el siguiente ejemplo, se muestra cómo particionar una consulta y, luego, ejecutar cada
partición por separado con 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';
RUN PARTITION 'partition-token'
RUN PARTITION 'partition-token'
Ejecuta una partición de consulta que PARTITION
mostró anteriormente.
. El comando se puede ejecutar con cualquier conexión que esté conectada a
la misma base de datos que la que creó los tokens de partición.
SPANNER.MAX_PARTITIONED_PARALLELISM
Una propiedad de tipo bigint
que indica la cantidad de subprocesos de trabajo
PGAdapter usa 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>
Establece la cantidad máxima de subprocesos de trabajo que puede usar PGAdapter para
ejecutar particiones. Establecer este valor en 0
le indica a PGAdapter lo siguiente:
usa la cantidad máxima de núcleos de CPU
en la máquina cliente.
El valor predeterminado es 0
.
¿Qué sigue?
- Obtén más información para iniciar PGAdapter.
- Consulta una lista completa de controladores y ORM de PostgreSQL compatibles.