Noções básicas sobre os registros de CDC

A CDC do Aurora DSQL entrega cada alteração como um registro JSON. O registro usa uma estrutura de envelope com tipo de operação, imagens da linha antes e depois e metadados de origem.

Como os registros são mapeados para o Amazon Kinesis

O Aurora DSQL grava cada registro de CDC como um único registro do Kinesis. O campo Data do registro do Kinesis contém a carga útil JSON. O Aurora DSQL usa uma chave de partição do Kinesis aleatória para distribuir os registros de CDC uniformemente entre os fragmentos. Para ler todas as alterações, consuma todos os fragmentos no fluxo de dados do Kinesis. Se um registro exceder o limite de tamanho do registro do Kinesis, o Aurora DSQL o dividirá em vários registros do Kinesis. Para obter detalhes, consulte Processamento de registros de tamanho grande.

Chave primária na carga útil

Para tabelas com uma chave primária, os valores da coluna da chave primária aparecem na carga útil:

Por exemplo, considere uma tabela com uma chave primária composta:

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

Uma exclusão nessa tabela produz uma carga útil onde "before": {"order_id": 1001, "item_id": 42}.

Carga útil de registros

A carga útil usa o seguinte formato de envelope JSON.

Exemplo de INSERT

O exemplo a seguir mostra um registro de CDC para uma operação de inserção:

{
    "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
}

Exemplo de UPDATE

O exemplo a seguir mostra a aparência de um registro de CDC produzido por uma instrução UPDATE depois que o Aurora DSQL começar 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
}

Exemplo de DELETE

Para exclusões em tabelas com uma chave primária, o campo before contém os valores da chave primária da linha excluída:

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

Detalhes do formato

Os detalhes a seguir descrevem como a CDC do Aurora DSQL formata registros. Crie seu aplicativo para lidar com esses comportamentos.

Processamento de registros de tamanho grande

Quando o JSON serializado de um registro de CDC excede 9 MiB, o Aurora DSQL divide as imagens before e/ou after, entregando vários registros do Kinesis. Cada registro contém um campo type de nível superior que indica a estrutura: full para um registro completo, chunked para um registro principal que faz referência a fragmentos e fragment para uma parte individual de uma imagem fragmentada. Os campos op, source, ts_ms e ts_ns em um registro principal fragmentado se comportam da mesma forma que em um registro completo. Os registros que cabem em um único registro do Kinesis possuem type definido como full e não exigem nenhum tratamento adicional.

chunk_id é estável em todas as tentativas. Se o Aurora DSQL reentregar um fragmento, ele carregará o mesmo chunk_id que a entrega original, para que seu aplicativo possa continuar armazenando em buffer com o mesmo identificador sem processar conjuntos parciais de tentativas anteriores.

Registro principal

Um registro principal fragmentado substitui o campo before ou after de nível superior da imagem dividida por um objeto chunked que descreve como remontá-la. Cada entrada em chunked tem um chunk_id (o identificador que vincula fragmentos a esse registro), total_fragments (o número de fragmentos que compõem essa imagem) e crc32c (uma soma de verificação CRC32C, como uma string decimal, sobre o texto da imagem remontada). Se uma imagem estiver em linha e a outra estiver fragmentada, a imagem em linha ainda aparecerá no nível superior como um valor ou 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 fragmentado

Cada fragmento é seu próprio registro do Kinesis com type definido como fragment e três campos: chunk_id corresponde ao valor no registro chunked.before.chunk_id ou chunked.after.chunk_id correspondente no registro principal, index é a posição com base em zero do fragmento na imagem e data é um segmento do texto JSON da imagem dividido em limites de caracteres UTF-8 (o valor data de cada fragmento é uma string UTF-8 válida por si só). Como a CDC do Aurora DSQL usa chaves de partição de modo UNORDERED e aleatórias, os fragmentos e o registro principal podem chegar a fragmentos diferentes e em qualquer ordem. Para ler todos os fragmentos, consuma todos os fragmentos no fluxo de dados do Kinesis. Para obter mais informações sobre a ordem de entrega, consulte Ordem.

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

Para remontar uma imagem grande, armazene cada registro em buffer com type fragment por chunk_id. Ao receber um registro principal com type chunked, espere até ter fragmentos total_fragments para cada chunk_id referenciado em chunked.before ou chunked.after, classifique os fragmentos por index em ordem ascendente e concatene as strings data. O resultado concatenado é o objeto before ou after original como texto JSON. Analise-o para acessar os valores da coluna. Para verificar a integridade da entrega, calcule o CRC32C na string concatenada e compare o resultado com chunked.before.crc32c ou chunked.after.crc32c.

Serialização de tipo de dados

As tabelas a seguir descrevem como o Aurora DSQL serializa cada tipo de dados do PostgreSQL nos registros de CDC.

Tipos de inteiros

Valores de bigint acima de ±2^53 podem perder a precisão em ambientes JavaScript. Use BigInt ou bibliotecas de precisão arbitrária nesses casos.

Tipos de ponto flutuante

Booleano

Tipos de caracteres

Binário

Tipos de data e hora

Outros tipos

Valores NULL

Para qualquer tipo de dados, os valores das colunas NULL são representados como null JSON.

Evolução do esquema nos registros de CDC

Quando você modifica o esquema de uma tabela (por exemplo, adicionando, eliminando ou renomeando uma coluna), os registros de CDC refletem a alteração a partir da transação que confirmou a alteração de DDL. Os registros de transações confirmadas antes da alteração de DDL usam o esquema anterior. Por exemplo:

Acompanhe as alterações de esquema em seu consumidor posterior inspecionando os nomes das colunas presentes nos campos after e before de cada registro. O campo source.version em cada registro identifica o formato do envelope de CDC.