Descripción de los registros de CDC

La CDC de Aurora DSQL entrega cada cambio como un registro JSON. El registro utiliza una estructura de sobre que incluye el tipo de operación, imágenes de la fila antes y después, y metadatos de origen.

Cómo se asignan los registros a Amazon Kinesis

Aurora DSQL escribe cada registro de CDC como un único registro de Kinesis. El campo Data del registro de Kinesis contiene la carga útil JSON. Aurora DSQL utiliza una clave de partición de Kinesis asignada al azar para distribuir los registros de CDC de manera uniforme entre las particiones. Para leer todos los cambios, consuma todas las particiones del flujo de datos de Kinesis. Si un registro supera el límite de tamaño de los registros de Kinesis, Aurora DSQL lo divide en varios registros de Kinesis. Para obtener más información, consulte Gestión de los registros sobredimensionados.

Clave principal de la carga útil

En el caso de las tablas con una clave principal, los valores de la columna de la clave principal aparecen en la carga útil:

Veamos como ejemplo una tabla con una clave primaria compuesta:

CREATE TABLE order_items (
    order_id INT,
    item_id INT,
    quantity INT,
    price NUMERIC,
    PRIMARY KEY (order_id, item_id)
);

Si se realiza una eliminación en esta tabla, se genera una carga útil, donde "before": {"order_id": 1001, "item_id": 42}.

Carga útil de registro

La carga útil utiliza el siguiente formato de sobre JSON.

Ejemplo de INSERT

En el siguiente ejemplo, se muestra un registro de CDC para una operación de inserción:

{
    "type": "full",
    "op": "c",
    "before": null,
    "after": {"order_id": 1001, "item_id": 42, "quantity": 5, "price": "29.99"},
    "source": {
        "version": "1.0",
        "ts_ms": 1705318200000,
        "ts_ns": 1705318200000000000,
        "txId": "ffthunp5stx6ffs2vyfqoatmfu",
        "schema": "public",
        "table": "order_items",
        "db": "postgres",
        "cluster": "kmabugltfmjdaj2siqr2qbxgju"
    },
    "ts_ms": 1705318200125,
    "ts_ns": 1705318200125483291
}

Ejemplo de UPDATE

En el siguiente ejemplo, se muestra cómo será un registro de CDC generado por una instrucción UPDATE una vez que Aurora DSQL comience a emitir op: "u":

{
    "type": "full",
    "op": "u",
    "before": null,
    "after": {"order_id": 1001, "item_id": 42, "quantity": 10, "price": "29.99"},
    "source": {
        "version": "1.0",
        "ts_ms": 1705318300000,
        "ts_ns": 1705318300000000000,
        "txId": "qvtiesgmd55cvlfukm3dfuotji",
        "schema": "public",
        "table": "order_items",
        "db": "postgres",
        "cluster": "kmabugltfmjdaj2siqr2qbxgju"
    },
    "ts_ms": 1705318300125,
    "ts_ns": 1705318300125483291
}

Ejemplo de DELETE

En el caso de las eliminaciones en tablas con una clave principal, el campo before contiene los valores de la clave principal de la fila eliminada:

{
    "type": "full",
    "op": "d",
    "before": {"order_id": 1001, "item_id": 42},
    "after": null,
    "source": {
        "version": "1.0",
        "ts_ms": 1705318400000,
        "ts_ns": 1705318400000000000,
        "txId": "xyzabc123def456ghi789jklmno",
        "schema": "public",
        "table": "order_items",
        "db": "postgres",
        "cluster": "kmabugltfmjdaj2siqr2qbxgju"
    },
    "ts_ms": 1705318400125,
    "ts_ns": 1705318400125483291
}

Campos de carga útil

Detalles del formato

En los siguientes detalles se describe cómo la CDC de Aurora DSQL formatea los registros. Diseñe la aplicación para gestionar estos comportamientos.

Gestión de los registros sobredimensionados

Cuando el JSON serializado de un registro de CDC supera los 9 MiB, Aurora DSQL divide las imágenes before y after, y entrega varios registros de Kinesis. Cada registro contiene un campo type de nivel superior que indica su estructura: full para un registro completo, chunked para un registro principal que hace referencia a fragmentos y fragment para una parte individual de una imagen fragmentada. Los campos op, source, ts_ms y ts_ns de un registro principal fragmentado se comportan igual que en un registro completo. Los registros que caben en un único registro de Kinesis tienen type establecido en full y no requieren ningún tratamiento adicional.

Un chunk_id es estable en todos los reintentos. Si Aurora DSQL vuelve a entregar un fragmento, este contiene el mismo chunk_id que la entrega original, por lo que su aplicación puede continuar almacenando en búfer bajo el mismo identificador sin tener que gestionar conjuntos parciales de intentos anteriores.

Registro principal

Un registro principal fragmentado sustituye el campo before o after de nivel superior de la imagen dividida por un objeto chunked que describe cómo volver a ensamblarla. Cada entrada bajo chunked tiene chunk_id (el identificador que vincula los fragmentos a este registro), total_fragments (el número de fragmentos que componen esa imagen) y crc32c (una suma de comprobación de CRC32C, como cadena decimal, sobre el texto de la imagen reensamblada). Si una imagen está en línea y la otra está fragmentada, la imagen en línea sigue apareciendo en el nivel superior como un valor o como null.

{
    "type": "chunked",
    "op": "c",
    "before": null,
    "after": null,
    "source": {
        "version": "1.0",
        "ts_ms": 1705318200000,
        "ts_ns": 1705318200000000000,
        "txId": "ffthunp5stx6ffs2vyfqoatmfu",
        "schema": "public",
        "table": "order_items",
        "db": "postgres",
        "cluster": "cluster-id"
    },
    "chunked": {
        "after": {
            "chunk_id": "chunk-id",
            "total_fragments": 3,
            "crc32c": "2073618257"
        }
    },
    "ts_ms": 1705318200125,
    "ts_ns": 1705318200125483291
}

Registro de fragmentos

Cada fragmento constituye un registro independiente de Kinesis con type establecido en fragment y tres campos: chunk_id coincide con el valor del campo chunked.before.chunk_id o chunked.after.chunk_id del registro principal; index es la posición, contada a partir de cero, del fragmento dentro de la imagen; y data es un segmento del texto JSON de la imagen dividido de acuerdo con los límites de caracteres UTF-8 (el valor data de cada fragmento es, por sí mismo, una cadena UTF-8 válida). Dado que CDC de Aurora DSQL utiliza el modo UNORDERED y claves de partición asignadas al azar, los fragmentos y el registro principal pueden llegar a diferentes particiones y en cualquier orden. Para leer todos los fragmentos, consuma todas las particiones del flujo de datos de Kinesis. Para obtener más información acerca del orden de entrega, consulte Ordenación.

{
    "type": "fragment",
    "chunk_id": "chunk-id",
    "index": 0,
    "data": "partial-JSON-text"
}

Para volver a ensamblar una imagen sobredimensionada, almacene cada registro en búfer con type fragment por su chunk_id. Cuando reciba un registro principal con type chunked, espere hasta tener total_fragments fragmentos para cada chunk_id al que se hace referencia en chunked.before o chunked.after, ordene los fragmentos por index en orden ascendente y concatene las cadenas data. El resultado concatenado es el objeto original before o after como texto JSON; analícelo para acceder a los valores de las columnas. Para verificar la integridad de la entrega, calcule el CRC32C sobre la cadena concatenada y compare el resultado con chunked.before.crc32c o chunked.after.crc32c.

Serialización de tipos de datos

En las siguientes tablas se describe cómo Aurora DSQL serializa cada tipo de datos de PostgreSQL en registros de CDC.

Tipos de enteros

Los valores de bigint superiores a ±2^53 pueden perder precisión en los entornos de JavaScript. En esos casos, utilice BigInt o bibliotecas de precisión arbitraria.

Tipos de números en coma flotante

Booleano

Tipos de caracteres

Binario

Tipos de fecha y hora

Otros tipos

Valores NULL

Para cualquier tipo de datos, los valores de las columnas NULL se representan como JSON null.

Evolución del esquema en los registros de CDC

Cuando se modifica el esquema de una tabla —por ejemplo, al añadir, eliminar o renombrar una columna—, los registros de CDC reflejan el cambio a partir de la transacción que confirmó el cambio de DDL. Los registros de las transacciones confirmadas antes del cambio de DDL utilizan el esquema anterior. Por ejemplo:

Realice un seguimiento de los cambios de esquema en su consumidor posterior inspeccionando los nombres de columna presentes en los campos after y before de cada registro. El campo source.version de cada registro identifica el formato del sobre de CDC.