Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Comprendre les dossiers du CDC
**Important**
Cette fonctionnalité est fournie sous forme d' AWS aperçu et est sujette à modification. Pour plus d'informations, consultez la section 2, Bêtas et aperçus, des conditions de [AWS service](https://aws.amazon.com/service-terms/). Pour en savoir plus sur la tarification des flux CDC, consultez la [page de tarification d'Aurora DSQL](https://aws.amazon.com/rds/aurora/dsql/pricing/).
Avant la mise à disposition générale, nous ajouterons de nouveaux types d'opérations (`"op": "u"`pour les mises à jour) à votre charge utile de diffusion. Pour vous assurer que votre application gère ces modifications sans modification, considérez toute valeur non reconnue comme une `op` valeur ajoutée en appliquant la `after` charge utile. Consultez [Comprendre les dossiers du CDC](#cdc-record-format) pour plus de détails.
Aurora DSQL CDC fournit chaque modification sous forme d'enregistrement JSON. L'enregistrement utilise une structure d'enveloppe avec le type d'opération, les images avant et après les lignes et les métadonnées de la source.
## Comment les enregistrements sont mappés à Amazon Kinesis
Aurora DSQL écrit chaque enregistrement CDC sous la forme d'un enregistrement Kinesis unique. Le `Data` champ de l'enregistrement Kinesis contient la charge utile JSON. Aurora DSQL utilise une clé de partition Kinesis aléatoire pour répartir les enregistrements CDC de manière uniforme sur les partitions. Pour lire toutes les modifications, consommez toutes les partitions du flux de données Kinesis. Si un enregistrement dépasse la limite de taille d'enregistrement Kinesis, Aurora DSQL le divise en plusieurs enregistrements Kinesis. Pour en savoir plus, consultez [Gestion de dossiers surdimensionnés](#cdc-oversized-records).
**Note**
Un enregistrement Kinesis contient un `Data` blob. Les valeurs des clés primaires apparaissent dans le `before` champ de la charge utile JSON pour les suppressions, ou dans le `after` champ pour les insertions et les mises à jour. Pour extraire la clé primaire à des fins de traitement en aval, lisez-la dans le champ approprié de la charge utile.
## Clé primaire dans la charge utile
Pour les tables dotées d'une clé primaire, les valeurs des colonnes de clé primaire apparaissent dans la charge utile :
+ Pour les **insertions** et les **mises à jour**, la charge utile inclut les colonnes clés primaires ainsi que toutes les autres colonnes du `after` champ.
+ Pour les **suppressions**, les colonnes de clé primaire apparaissent dans le `before` champ.
Prenons l'exemple d'une table avec une clé primaire composite :
```
CREATE TABLE order_items (
order_id INT,
item_id INT,
quantity INT,
price NUMERIC,
PRIMARY KEY (order_id, item_id)
);
```
Une suppression sur cette table produit une charge utile où`"before": {"order_id": 1001, "item_id": 42}`.
## Charge utile record
La charge utile utilise le format d'enveloppe JSON suivant.
**Exemple INSERT**
L'exemple suivant montre un enregistrement CDC pour une opération d'insertion :
```
{
"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
}
```
**Exemple de mise à jour**
L'exemple suivant montre à quoi ressemblera un enregistrement CDC produit par une `UPDATE` instruction une fois qu'Aurora DSQL commencera à émettre `op: "u"` :
**Important**
Actuellement, Aurora DSQL émet à la fois `op: "c"` pour les insertions et les mises à jour. Une version ultérieure sera émise `op: "u"` pour les mises à jour et `op: "c"` pour les insertions. Concevez votre application de manière à `c` ce `u` qu'elle `d` soit adaptée et que votre consommateur continue de travailler tout au long de la transition.
```
{
"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
}
```
**Exemple DELETE**
Pour les suppressions effectuées sur des tables avec une clé primaire, le `before` champ contient les valeurs de clé primaire de la ligne supprimée :
```
{
"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
}
```
## Champs de charge utile
| Champ | Description |
| --- |--- |
| type | Type d'enregistrement. fullpour un enregistrement complet qui inclut les données en ligne before et after les valeurs. chunkedpour un enregistrement principal qui référence des enregistrements fragmentés pour une ou les deux images. fragmentpour un élément individuel d'une image fragmentée. Pour en savoir plus, consultez [Gestion de dossiers surdimensionnés](#cdc-oversized-records). |
| op | Type d'opération. c= créer (insérer), u = mettre à jour, d = supprimer. Actuellement, Aurora DSQL émet à la fois c pour les insertions et les mises à jour. Une version ultérieure sera émise u pour les mises à jour et c pour les insertions. Concevez votre application de manière à gérer les trois valeurs. |
| before | Pour les suppressions effectuées sur des tables avec une clé primaire, contient les valeurs de clé primaire de la ligne supprimée. Aurora DSQL définit ce champ sur null pour les insertions, les mises à jour et les suppressions sur des tables sans clé primaire. |
| after | État complet de la ligne après la modification, y compris toutes les colonnes. Aurora DSQL définit ce champ sur « null pour les suppressions ». |
| chunked | Présent uniquement quand type c'est le caschunked. Contient des métadonnées de réassemblage pour l'beforeimage, l'afterimage ou les deux. Aurora DSQL omet l'image fragmentée du niveau supérieur before ou du after champ et la place en dessous. chunked Pour en savoir plus, consultez [Gestion de dossiers surdimensionnés](#cdc-oversized-records). |
| source.version | Version du format de métadonnées source du CDC. La version actuelle est 1.0. |
| source.ts\_ms | L'horodatage de validation de la transaction en millisecondes depuis l'ère Unix, le temps universel coordonné (UTC). |
| source.ts\_ns | Horodatage de validation de la transaction en nanosecondes, UTC. L'horodatage le plus précis disponible. Utilisez ce champ pour établir un ordre total des transactions. |
| source.txId | Identifiant de transaction unique, codé en base32. Tous les enregistrements d'une même transaction ont la même txId valeur. Utilisez ce champ pour regrouper les enregistrements qui appartiennent à la même transaction. |
| source.schema | Le nom du schéma PostgreSQL (par exemple,). public |
| source.table | Nom de la table. |
| source.db | Nom de la base de données. Toujours postgres pour Aurora DSQL. |
| source.cluster | L'identifiant du cluster SQL Aurora. |
| ts\_ms | Heure à laquelle le système CDC a traité l'enregistrement, en millisecondes, UTC. La différence entre ts\_ms et source.ts\_ms est une mesure du délai de réplication. |
| ts\_ns | Heure à laquelle le système CDC a traité l'enregistrement, en nanosecondes, UTC. |
## Détails du format
Les informations suivantes décrivent comment Aurora DSQL CDC met en forme les enregistrements. Concevez votre application pour gérer ces comportements.
+ **Image rémanente complète pour les insertions et les mises à jour.** Aurora DSQL inclut l'état complet de la ligne dans le `after` champ pour toutes les écritures. Le `before` champ est `null` destiné aux insertions et aux mises à jour. Actuellement, les insertions et les mises à jour l'utilisent`op: "c"`, mais une version ultérieure émettra `op: "u"` des mises à jour. Concevez votre application pour qu'elle utilise `source.ts_ns` chaque clé primaire pour la commande plutôt que de vous fier au `op` champ pour faire la distinction entre les encarts et les mises à jour.
+ **Post-change état de ligne uniquement.** Les enregistrements du CDC incluent l'état complet de la ligne après chaque modification. État de la ligne avant qu'une mise à jour ne soit incluse. Pour les suppressions effectuées sur des tables comportant une clé primaire, le `before` champ contient les valeurs de la clé primaire.
+ **Types numériques sérialisés sous forme de chaînes.** Aurora DSQL sérialise `numeric` et `decimal` valorise sous forme de chaînes JSON afin de préserver une précision exacte.
+ **Données binaires encodées en Base64.** Aurora DSQL code les `bytea` valeurs sous forme de chaînes Base64.
+ **Valeurs numériques et à virgule flottante spéciales.** Aurora SQL sérialise NaN et ±Infinity sous forme de chaînes`"NaN"`, `"Infinity"` et. `"-Infinity"` Cela s'applique à `real``double precision`, et aux `numeric` types.
+ **Colonnes JSON sérialisées sous forme de chaînes JSON.** Aurora DSQL sérialise les valeurs des `json` colonnes sous forme de chaînes JSON contenant le texte JSON brut stocké dans la colonne. Analysez la valeur de chaîne dans votre application (par exemple, avec JavaScript ou `JSON.parse` `json.loads` dans Python) pour accéder à la valeur JSON sous-jacente.
+ **Les valeurs de débordement sont émises sous la forme nulle.** Si une valeur ne peut pas être représentée dans le type JSON cible lors de la sérialisation, Aurora DSQL émet du JSON `null` pour cette colonne. Cela s'applique aux `interval` valeurs dont le total des microsecondes dépasse la plage des entiers signés de 64 bits (± 9 223 372 036 854 775 807 microsecondes, soit environ ± 292 271 ans). Concevez votre application pour gérer `null` les valeurs inattendues dans les colonnes qui ne sont pas nullables dans le schéma de base de données.
+ **Les enregistrements surdimensionnés sont divisés en morceaux.** Si un enregistrement dépasse la limite de taille d'enregistrement d'Amazon Kinesis, Aurora DSQL divise l'`after`image `before` ou l'image concernée en fragments et les fournit sous forme d'enregistrements Kinesis distincts afin que vous continuiez à recevoir la modification. Concevez votre application pour réassembler les images. Pour en savoir plus, consultez [Gestion de dossiers surdimensionnés](#cdc-oversized-records).
## Gestion de dossiers surdimensionnés
Lorsque le JSON sérialisé d'un enregistrement CDC dépasse 9 MiB, Aurora DSQL divise les images et fournit plusieurs enregistrements `before` and/or `after` Kinesis. Chaque enregistrement contient un `type` champ de niveau supérieur qui indique sa structure : `full` pour un enregistrement complet, `chunked` pour un enregistrement principal faisant référence à des fragments et `fragment` pour un élément individuel d'une image fragmentée. Les `ts_ns` champs`op`, `source``ts_ms`, et d'un enregistrement principal fragmenté se comportent de la même manière que ceux d'un enregistrement complet. Les enregistrements qui rentrent dans un seul enregistrement Kinesis sont `type` configurés `full` et ne nécessitent aucune manipulation supplémentaire.
A `chunk_id` est stable d'une tentative à l'autre. Si Aurora DSQL relivre un fragment, celui-ci est identique à la livraison d'origine, de sorte `chunk_id` que votre application peut continuer à être mise en mémoire tampon sous le même identifiant sans gérer les ensembles partiels issus de tentatives précédentes.
**Record principal**
Un enregistrement principal fragmenté remplace le niveau supérieur `before` ou le `after` champ de l'image divisée par un `chunked` objet qui décrit comment le réassembler. Chaque entrée ci-dessous `chunked` possède un `chunk_id` (l'identifiant qui lie les fragments à cet enregistrement), `total_fragments` (le nombre de fragments composant cette image) et `crc32c` (une somme de contrôle CRC32C, sous forme de chaîne décimale, sur le texte de l'image réassemblé). Si une image est en ligne et que l'autre est découpée, l'image en ligne apparaît toujours au niveau supérieur sous forme de valeur 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
}
```
**Enregistrement fragmenté**
Chaque fragment est son propre enregistrement Kinesis avec trois champs `type` définis `chunked.after.chunk_id` sur : `chunk_id` correspond à `fragment` la valeur de l'enregistrement correspondant `chunked.before.chunk_id` ou de l'enregistrement principal, `index` correspond à la position de base zéro du fragment dans l'image et `data` constitue un segment du texte JSON de l'image divisé en limites de UTF-8 caractères (la `data` valeur de chaque fragment est une UTF-8 chaîne valide en soi). Comme Aurora DSQL CDC utilise le `UNORDERED` mode et des clés de partition aléatoires, les fragments et l'enregistrement principal peuvent arriver sur différentes partitions et dans n'importe quel ordre. Pour lire tous les fragments, consommez tous les fragments du flux de données Kinesis. Pour plus d'informations sur les commandes de livraison, consultez[Commande](cdc-streams.md#cdc-ordering).
```
{
"type": "fragment",
"chunk_id": "{{chunk-id}}",
"index": 0,
"data": "{{partial-JSON-text}}"
}
```
Pour réassembler une image surdimensionnée, mettez chaque enregistrement en mémoire tampon `type` `fragment` par son. `chunk_id` Lorsque vous recevez un enregistrement principal avec `type``chunked`, attendez d'avoir des `total_fragments` fragments pour chaque enregistrement `chunk_id` référencé sous `chunked.before` ou`chunked.after`, triez les fragments par `index` ordre croissant et concaténez les chaînes. `data` Le résultat concaténé est l'original `before` ou l'`after`objet sous forme de texte JSON. Analysez-le pour accéder aux valeurs des colonnes. Pour vérifier l'intégrité de la livraison, calculez CRC32C sur la chaîne concaténée et comparez le résultat à ou. `chunked.before.crc32c` `chunked.after.crc32c`
## Sérialisation des types de données
Les tableaux suivants décrivent comment Aurora DSQL sérialise chaque type de données PostgreSQL dans les enregistrements CDC.
### Types d’entier
| Type de PostgreSQL | Représentation JSON | Exemple |
| --- |--- |--- |
| smallint (int2) | Numéro JSON | 42 |
| integer (int4) | Numéro JSON | 1001 |
| bigint (int8) | Numéro JSON | 9223372036854775807 |
| oid | Numéro JSON (non signé) | 16384 |
Les valeurs `bigint` supérieures à ±2^53 peuvent perdre en précision dans les environnements. JavaScript Utilisez BigInt des bibliothèques de précision arbitraire dans ces cas.
### Floating-point types
| Type de PostgreSQL | Représentation JSON | Exemple | Remarques |
| --- |--- |--- |--- |
| real (float4) | Numéro JSON | 3.14159 | NaN et ±Infinity sont sérialisés sous forme de chaînes"NaN",,"Infinity". "-Infinity" |
| double precision (float8) | Numéro JSON | 3.141592653589793 | Même gestion des valeurs spéciales quereal. |
| numeric / decimal | chaîne JSON | "123.45" | Toujours une corde pour préserver la précision exacte. NaN et ±Infinity sont sérialisés sous forme de chaînes"NaN",,"Infinity". "-Infinity" |
### Booléen
| Type de PostgreSQL | Représentation JSON | Exemple |
| --- |--- |--- |
| boolean | booléen JSON | true ou false |
### Types caractères
| Type de PostgreSQL | Représentation JSON | Exemple |
| --- |--- |--- |
| varchar / text | chaîne JSON | "Hello, world\!" |
| bpchar (char(n)) | chaîne JSON | "ABC"(espaces de traînée supprimés) |
| name | chaîne JSON | "pg\_class" |
| "char"(à un octet) | chaîne JSON | "A" |
### Binaire
| Type de PostgreSQL | Représentation JSON | Exemple |
| --- |--- |--- |
| bytea | Chaîne JSON (Base64) | "SGVsbG8gV29ybGQh" |
### Types de date et d'heure
| Type de PostgreSQL | Représentation JSON | Exemple | Remarques |
| --- |--- |--- |--- |
| date | Numéro JSON (jours depuis l'époque Unix) | 19797 | \+infinityet -infinity sont représentés sous forme de nombres de jours sentinelles dérivés de l'arithmétique du décalage entre les époques. Ces valeurs ne correspondent pas à des dates calendaires significatives. |
| time | Numéro JSON (microsecondes depuis minuit) | 52200123456 | |
| timetz | Numéro JSON (microsecondes depuis minuit, UTC) | 52200123456 | L'heure locale est ajustée à l'heure UTC en appliquant le décalage de fuseau horaire enregistré (secondes à l'ouest de l'UTC). Le résultat est encapsulé dans une plage de [0, 86400000000) microsecondes. |
| timestamp | Numéro JSON (microsecondes depuis l'époque Unix) | 1710510600123456 | ±Infinity correspond aux valeurs sentinelles : 9223372036825200000 pour \+infinity et -9223372036832400000 pour. -infinity |
| timestamptz | Numéro JSON (microsecondes depuis l'époque Unix) | 1710510600123456 | Stocké et émis en UTC. Mêmes valeurs sentinelles ±infinity que. timestamp |
| interval | Numéro JSON (total approximatif en microsecondes) | 2802603000000 | Les mois sont estimés à 30,4375 jours (2 629 800 secondes). Le total est calculé comme suit(months × 2,629,800 \+ days × 86,400) × 1,000,000 \+ microseconds. Si le résultat dépasse la plage d'entiers signés de 64 bits (± 9 223 372 036 854 775 807 microsecondes, soit environ ± 292 271 ans), Aurora DSQL émet du JSON pour la colonne. null |
### Autres types
| Type de PostgreSQL | Représentation JSON | Exemple |
| --- |--- |--- |
| uuid | Chaîne JSON (format hexadécimal standard 8-4-4-4-12) | "550e8400-e29b-41d4-a716-446655440000" |
| oidvector | Tableau vide JSON | [] |
| json | Chaîne JSON contenant le texte JSON brut | "{\\"key\\": \\"value\\"}" |
### Valeurs NULL
Quel que soit le type de données, les valeurs des `NULL` colonnes sont représentées au format JSON`null`.
## Évolution du schéma dans les dossiers du CDC
Lorsque vous modifiez le schéma d'une table, par exemple en ajoutant, en supprimant ou en renommant une colonne, les enregistrements CDC reflètent le changement à partir de la transaction qui a validé le changement DDL. Les enregistrements des transactions validées avant la modification du DDL utilisent le schéma précédent. Par exemple :
+ Si vous ajoutez une colonne, les enregistrements des transactions précédentes n'incluent pas la nouvelle colonne. Les enregistrements à partir de la transaction d'ajout incluent la nouvelle colonne.
+ Si vous supprimez une colonne, les enregistrements depuis la transaction de suppression n'incluent plus cette colonne.
+ Si vous renommez une colonne, les enregistrements enregistrés à partir de la transaction de changement de nom utilisent le nouveau nom de colonne.
Suivez les modifications du schéma chez votre consommateur en aval en inspectant les noms de colonnes présents dans chaque enregistrement `after` et chaque `before` champ. Le `source.version` champ de chaque enregistrement identifie le format d'enveloppe du CDC.