[{"data":1,"prerenderedAt":936},["ShallowReactive",2],{"docs-\u002Fdocs\u002Fstreams\u002Ftarget-data-policies":3},{"id":4,"title":5,"body":6,"description":927,"extension":928,"meta":929,"navigation":930,"path":931,"redirect":932,"seo":933,"stem":934,"__hash__":935},"docs\u002Fdocs\u002Fstreams\u002Ftarget-data-policies.md","Target Schema and Data Policies",{"type":7,"value":8,"toc":910},"minimark",[9,13,25,28,41,44,47,52,97,111,115,181,185,269,274,281,284,298,307,311,315,365,369,431,435,517,521,524,565,570,581,586,597,601,618,622,625,759,762,845,849,852,868,872,906],[10,11,5],"h1",{"id":12},"target-schema-and-data-policies",[14,15,16,20,21,24],"p",{},[17,18,19],"code",{},"schemaPolicy"," and ",[17,22,23],{},"writeMode"," control what DBConvert Streams does when the target already has tables or rows.",[14,26,27],{},"Use this page when:",[29,30,31,35,38],"ul",{},[32,33,34],"li",{},"target tables may already exist",[32,36,37],{},"target tables may already contain data",[32,39,40],{},"you need to choose between safe-stop, append, refresh, or upsert behavior",[14,42,43],{},"These fields apply to MySQL and PostgreSQL database targets. Other target types accept only the mode defaults.",[14,45,46],{},"In the UI, these options are shown with friendly labels. The API values are listed in the reference tables below.",[48,49,51],"h2",{"id":50},"defaults","Defaults",[53,54,55,71],"table",{},[56,57,58],"thead",{},[59,60,61,65,68],"tr",{},[62,63,64],"th",{},"Mode",[62,66,67],{},"Schema policy",[62,69,70],{},"Write mode",[72,73,74,86],"tbody",{},[59,75,76,80,83],{},[77,78,79],"td",{},"Load",[77,81,82],{},"Fail if exists (safe default)",[77,84,85],{},"Fail if not empty (safe default)",[59,87,88,91,94],{},[77,89,90],{},"CDC",[77,92,93],{},"Validate existing",[77,95,96],{},"Upsert (recommended for CDC)",[14,98,99,102,103,106,107,110],{},[17,100,101],{},"mode=cdc"," supports ",[17,104,105],{},"writeMode=upsert"," (default) or ",[17,108,109],{},"writeMode=append",". Any other value is rejected at startup.",[48,112,114],{"id":113},"common-policy-pairs","Common policy pairs",[53,116,117,128],{},[56,118,119],{},[59,120,121,124,126],{},[62,122,123],{},"Situation",[62,125,67],{},[62,127,70],{},[72,129,130,140,150,160,171],{},[59,131,132,135,137],{},[77,133,134],{},"Target schema managed outside the stream",[77,136,93],{},[77,138,139],{},"Fail if not empty (Load) or Upsert (CDC)",[59,141,142,145,148],{},[77,143,144],{},"Add only missing tables",[77,146,147],{},"Create missing only",[77,149,85],{},[59,151,152,155,157],{},[77,153,154],{},"Initial Load + CDC into a new target",[77,156,147],{},[77,158,159],{},"Upsert",[59,161,162,165,168],{},[77,163,164],{},"Rebuild selected target tables from scratch",[77,166,167],{},"Drop and recreate",[77,169,170],{},"Append",[59,172,173,176,178],{},[77,174,175],{},"Refresh data in existing tables without recreating them",[77,177,93],{},[77,179,180],{},"Truncate and load",[48,182,184],{"id":183},"schema-policy-values","Schema policy values",[53,186,187,203],{},[56,188,189],{},[59,190,191,194,197,200],{},[62,192,193],{},"Label in UI",[62,195,196],{},"API value",[62,198,199],{},"Description in UI",[62,201,202],{},"Notes",[72,204,205,220,235,250],{},[59,206,207,209,214,217],{},[77,208,82],{},[77,210,211],{},[17,212,213],{},"fail_if_exists",[77,215,216],{},"Raises an error if any target table already exists. Safest option for first-time runs.",[77,218,219],{},"No DDL is executed.",[59,221,222,224,229,232],{},[77,223,93],{},[77,225,226],{},[17,227,228],{},"validate_existing",[77,230,231],{},"Uses existing target tables as-is. Schema compatibility will be verified.",[77,233,234],{},"No DDL is executed. See checks below.",[59,236,237,239,244,247],{},[77,238,147],{},[77,240,241],{},[17,242,243],{},"create_missing_only",[77,245,246],{},"Creates only tables that don't exist yet. Existing tables are left unchanged.",[77,248,249],{},"No drop or alter is done on existing tables.",[59,251,252,254,259,262],{},[77,253,167],{},[77,255,256],{},[17,257,258],{},"drop_and_recreate",[77,260,261],{},"Drops and recreates all target tables from source schema. All existing target data will be lost.",[77,263,264,265,268],{},"MySQL disables foreign key checks during the drop step. PostgreSQL uses ",[17,266,267],{},"DROP TABLE ... CASCADE",".",[270,271,273],"h3",{"id":272},"create-missing-only-behavior","Create missing only behavior",[14,275,276,277,280],{},"Use ",[278,279,147],"strong",{}," when DBConvert Streams should create target tables\nthat are not present yet, while leaving existing target tables under operator\ncontrol.",[14,282,283],{},"This policy:",[29,285,286,289,292,295],{},[32,287,288],{},"creates only selected target tables that are missing",[32,290,291],{},"validates existing selected target tables instead of replacing them",[32,293,294],{},"does not alter, drop, truncate, or clean existing target tables",[32,296,297],{},"still applies the selected write mode after structure creation",[14,299,300,301,303,304,306],{},"For Initial Load + CDC, pair ",[278,302,147],{}," with ",[278,305,159],{}," when\nstarting with a new target. DBConvert Streams can create missing tables first,\nthen verifies that the selected target tables are empty before copying existing\nsource rows. Existing tables must still be compatible and empty for the first\nbootstrap copy.",[48,308,310],{"id":309},"validate-existing-checks","Validate existing checks",[270,312,314],{"id":313},"startup-fails-when","Startup fails when",[53,316,317,327],{},[56,318,319],{},[59,320,321,324],{},[62,322,323],{},"Check",[62,325,326],{},"What it means",[72,328,329,337,345,353],{},[59,330,331,334],{},[77,332,333],{},"Missing table or column",[77,335,336],{},"The target schema does not contain the required objects.",[59,338,339,342],{},[77,340,341],{},"Incompatible or narrower mapped type",[77,343,344],{},"The target type cannot safely store the mapped source values.",[59,346,347,350],{},[77,348,349],{},"Source nullable vs target NOT NULL mismatch",[77,351,352],{},"Source data may contain nulls that the target would reject.",[59,354,355,358],{},[77,356,357],{},"Required key contract issue",[77,359,360,361,364],{},"CDC or ",[17,362,363],{},"upsert"," needs keys that are missing or incompatible on the target.",[270,366,368],{"id":367},"warnings-are-emitted-for","Warnings are emitted for",[53,370,371,381],{},[56,372,373],{},[59,374,375,378],{},[62,376,377],{},"Difference",[62,379,380],{},"Why it stays non-blocking",[72,382,383,391,399,407,415,423],{},[59,384,385,388],{},[77,386,387],{},"Compatible type differences",[77,389,390],{},"The target type differs, but remains compatible with the mapped source type.",[59,392,393,396],{},[77,394,395],{},"Source NOT NULL vs target nullable",[77,397,398],{},"The target is less strict than the source.",[59,400,401,404],{},[77,402,403],{},"Default differences",[77,405,406],{},"Default values differ after normalization.",[59,408,409,412],{},[77,410,411],{},"Primary key definition differences when a key is not required",[77,413,414],{},"Key shape differs, but the selected mode does not require it for correctness.",[59,416,417,420],{},[77,418,419],{},"Index, foreign key, or check constraint differences",[77,421,422],{},"Structural differences exist outside the required compatibility contract.",[59,424,425,428],{},[77,426,427],{},"Collation or charset differences",[77,429,430],{},"Text settings differ, but the table can still be used.",[48,432,434],{"id":433},"write-mode-values","Write mode values",[53,436,437,449],{},[56,438,439],{},[59,440,441,443,445,447],{},[62,442,193],{},[62,444,196],{},[62,446,199],{},[62,448,202],{},[72,450,451,470,485,503],{},[59,452,453,455,460,463],{},[77,454,85],{},[77,456,457],{},[17,458,459],{},"fail_if_not_empty",[77,461,462],{},"Raises an error if any target table already contains data. Safest option for first-time loads.",[77,464,465,466,469],{},"Uses a fast ",[17,467,468],{},"LIMIT 1"," check rather than a full row count.",[59,471,472,474,479,482],{},[77,473,170],{},[77,475,476],{},[17,477,478],{},"append",[77,480,481],{},"Adds source data to existing rows using plain INSERT.",[77,483,484],{},"Existing rows stay untouched. Duplicate key conflicts surface as errors. The writer also emits a startup warning when reruns are likely to hit existing primary or unique keys.",[59,486,487,489,494,497],{},[77,488,180],{},[77,490,491],{},[17,492,493],{},"truncate_and_load",[77,495,496],{},"Deletes all existing rows before loading. Target tables are emptied first.",[77,498,499,500,268],{},"MySQL uses child-first truncate order. PostgreSQL uses ",[17,501,502],{},"TRUNCATE ... CASCADE",[59,504,505,507,511,514],{},[77,506,159],{},[77,508,509],{},[17,510,363],{},[77,512,513],{},"Updates matching rows by primary key, inserts new ones. Safe for reruns.",[77,515,516],{},"Requires primary keys.",[48,518,520],{"id":519},"write-modes-for-cdc","Write modes for CDC",[14,522,523],{},"CDC streams support two write modes:",[53,525,526,538],{},[56,527,528],{},[59,529,530,532,535],{},[62,531,70],{},[62,533,534],{},"Behavior",[62,536,537],{},"Best for",[72,539,540,553],{},[59,541,542,547,550],{},[77,543,544,546],{},[278,545,159],{}," (default)",[77,548,549],{},"Matches rows by primary key. Inserts new rows, updates existing ones.",[77,551,552],{},"Most CDC workloads. Safe for reruns and restarts.",[59,554,555,559,562],{},[77,556,557],{},[278,558,170],{},[77,560,561],{},"Uses plain INSERT. No duplicate checking.",[77,563,564],{},"Append-only tables (e.g. event logs, audit trails) where rows are never updated or deleted. Faster than upsert because it skips the primary key lookup on each write.",[14,566,567],{},[278,568,569],{},"When to use append for CDC:",[29,571,572,575,578],{},[32,573,574],{},"The source table is insert-only (no UPDATEs or DELETEs).",[32,576,577],{},"You want maximum write throughput and are willing to accept duplicate-key errors if the stream is restarted.",[32,579,580],{},"The target table has no primary key or unique constraints that could cause conflicts.",[14,582,583],{},[278,584,585],{},"When to stick with upsert:",[29,587,588,591,594],{},[32,589,590],{},"The source issues UPDATEs or DELETEs (upsert handles all three event types correctly).",[32,592,593],{},"You need idempotent reruns (e.g. replaying from a WAL position).",[32,595,596],{},"The target table has primary or unique keys.",[48,598,600],{"id":599},"structure-only-runs","Structure-Only Runs",[14,602,603,604,607,608,611,612,614,615,617],{},"When ",[17,605,606],{},"skipData=true"," or the stream is started with ",[17,609,610],{},"structureOnly=true",", ",[17,613,19],{}," is still applied and ",[17,616,23],{}," is ignored.",[48,619,621],{"id":620},"api-examples","API examples",[14,623,624],{},"Load mode with safe defaults:",[626,627,632],"pre",{"className":628,"code":629,"language":630,"meta":631,"style":631},"language-json shiki shiki-themes github-light github-dark","{\n  \"mode\": \"load\",\n  \"target\": {\n    \"id\": \"conn_target\",\n    \"spec\": {\n      \"db\": {\n        \"database\": \"analytics\",\n        \"schemaPolicy\": \"validate_existing\",\n        \"writeMode\": \"fail_if_not_empty\"\n      }\n    }\n  }\n}\n","json","",[17,633,634,643,660,669,682,690,698,711,724,735,741,747,753],{"__ignoreMap":631},[635,636,639],"span",{"class":637,"line":638},"line",1,[635,640,642],{"class":641},"sVt8B","{\n",[635,644,646,650,653,657],{"class":637,"line":645},2,[635,647,649],{"class":648},"sj4cs","  \"mode\"",[635,651,652],{"class":641},": ",[635,654,656],{"class":655},"sZZnC","\"load\"",[635,658,659],{"class":641},",\n",[635,661,663,666],{"class":637,"line":662},3,[635,664,665],{"class":648},"  \"target\"",[635,667,668],{"class":641},": {\n",[635,670,672,675,677,680],{"class":637,"line":671},4,[635,673,674],{"class":648},"    \"id\"",[635,676,652],{"class":641},[635,678,679],{"class":655},"\"conn_target\"",[635,681,659],{"class":641},[635,683,685,688],{"class":637,"line":684},5,[635,686,687],{"class":648},"    \"spec\"",[635,689,668],{"class":641},[635,691,693,696],{"class":637,"line":692},6,[635,694,695],{"class":648},"      \"db\"",[635,697,668],{"class":641},[635,699,701,704,706,709],{"class":637,"line":700},7,[635,702,703],{"class":648},"        \"database\"",[635,705,652],{"class":641},[635,707,708],{"class":655},"\"analytics\"",[635,710,659],{"class":641},[635,712,714,717,719,722],{"class":637,"line":713},8,[635,715,716],{"class":648},"        \"schemaPolicy\"",[635,718,652],{"class":641},[635,720,721],{"class":655},"\"validate_existing\"",[635,723,659],{"class":641},[635,725,727,730,732],{"class":637,"line":726},9,[635,728,729],{"class":648},"        \"writeMode\"",[635,731,652],{"class":641},[635,733,734],{"class":655},"\"fail_if_not_empty\"\n",[635,736,738],{"class":637,"line":737},10,[635,739,740],{"class":641},"      }\n",[635,742,744],{"class":637,"line":743},11,[635,745,746],{"class":641},"    }\n",[635,748,750],{"class":637,"line":749},12,[635,751,752],{"class":641},"  }\n",[635,754,756],{"class":637,"line":755},13,[635,757,758],{"class":641},"}\n",[14,760,761],{},"CDC mode with append (insert-only workload):",[626,763,765],{"className":628,"code":764,"language":630,"meta":631,"style":631},"{\n  \"mode\": \"cdc\",\n  \"target\": {\n    \"id\": \"conn_target\",\n    \"spec\": {\n      \"db\": {\n        \"database\": \"analytics\",\n        \"writeMode\": \"append\"\n      }\n    }\n  }\n}\n",[17,766,767,771,782,788,798,804,810,820,829,833,837,841],{"__ignoreMap":631},[635,768,769],{"class":637,"line":638},[635,770,642],{"class":641},[635,772,773,775,777,780],{"class":637,"line":645},[635,774,649],{"class":648},[635,776,652],{"class":641},[635,778,779],{"class":655},"\"cdc\"",[635,781,659],{"class":641},[635,783,784,786],{"class":637,"line":662},[635,785,665],{"class":648},[635,787,668],{"class":641},[635,789,790,792,794,796],{"class":637,"line":671},[635,791,674],{"class":648},[635,793,652],{"class":641},[635,795,679],{"class":655},[635,797,659],{"class":641},[635,799,800,802],{"class":637,"line":684},[635,801,687],{"class":648},[635,803,668],{"class":641},[635,805,806,808],{"class":637,"line":692},[635,807,695],{"class":648},[635,809,668],{"class":641},[635,811,812,814,816,818],{"class":637,"line":700},[635,813,703],{"class":648},[635,815,652],{"class":641},[635,817,708],{"class":655},[635,819,659],{"class":641},[635,821,822,824,826],{"class":637,"line":713},[635,823,729],{"class":648},[635,825,652],{"class":641},[635,827,828],{"class":655},"\"append\"\n",[635,830,831],{"class":637,"line":726},[635,832,740],{"class":641},[635,834,835],{"class":637,"line":737},[635,836,746],{"class":641},[635,838,839],{"class":637,"line":743},[635,840,752],{"class":641},[635,842,843],{"class":637,"line":749},[635,844,758],{"class":641},[48,846,848],{"id":847},"verification","Verification",[14,850,851],{},"After you start the stream:",[29,853,854,857,863],{},[32,855,856],{},"confirm the selected schema policy and write mode appear as expected in the saved stream configuration",[32,858,859,860,862],{},"if you use ",[17,861,228],{},", review startup warnings before treating the run as production-ready",[32,864,859,865,867],{},[17,866,478],{},", watch for duplicate-key warnings before rerunning the same load",[48,869,871],{"id":870},"related-docs","Related Docs",[29,873,874,882,888,894,900],{},[32,875,876,881],{},[877,878,880],"a",{"href":879},"\u002Fdocs\u002Fstreams\u002Fdatabase-structure-options","Database Structure Options"," — tables, indexes, and foreign key creation strategies",[32,883,884],{},[877,885,887],{"href":886},"\u002Fdocs\u002Fstreams\u002Fstream-configuration-guide","Stream Configuration Guide",[32,889,890],{},[877,891,893],{"href":892},"\u002Fdocs\u002Fstreams\u002Fstream-config-reference","Stream Configuration Reference",[32,895,896],{},[877,897,899],{"href":898},"\u002Fdocs\u002Fintegration\u002Fconversion-mode","Load Mode",[32,901,902],{},[877,903,905],{"href":904},"\u002Fdocs\u002Fintegration\u002Fwhat-is-cdc","CDC Mode",[907,908,909],"style",{},"html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":631,"searchDepth":645,"depth":645,"links":911},[912,913,914,917,921,922,923,924,925,926],{"id":50,"depth":645,"text":51},{"id":113,"depth":645,"text":114},{"id":183,"depth":645,"text":184,"children":915},[916],{"id":272,"depth":662,"text":273},{"id":309,"depth":645,"text":310,"children":918},[919,920],{"id":313,"depth":662,"text":314},{"id":367,"depth":662,"text":368},{"id":433,"depth":645,"text":434},{"id":519,"depth":645,"text":520},{"id":599,"depth":645,"text":600},{"id":620,"depth":645,"text":621},{"id":847,"depth":645,"text":848},{"id":870,"depth":645,"text":871},"Control how DBConvert Streams handles existing target tables and data during stream execution.","md",{},false,"\u002Fdocs\u002Fstreams\u002Ftarget-data-policies",null,{"title":5,"description":927},"docs\u002Fstreams\u002Ftarget-data-policies","sxoFS8gwo97DavJWOGxOQLBqLnLkFZs8H4FlV-H7bZ8",1783896284844]