You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 4b6658a
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: features/copy-objects.mdx
+45-11Lines changed: 45 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -28,6 +28,9 @@ written until you have read the script.
28
28
29
29
The funnel beside a table narrows the rows it contributes. See
30
30
[Copying part of a table](#copying-part-of-a-table).
31
+
32
+
**On error** chooses what a failure does: stop and roll back, stop and keep what ran, or skip
33
+
that object and continue.
31
34
</Step>
32
35
<Steptitle="Read the script, then copy">
33
36
**Continue** reads both databases and shows the DDL that will run, the rows each table expects,
@@ -232,22 +235,53 @@ A copied foreign key is repointed at the copy. A key that referenced the source'
232
235
references the target's afterwards, so the duplicate stands on its own; one that referenced a third
233
236
schema is left as it was.
234
237
235
-
Two tables that reference each other cannot be ordered. The second `CREATE TABLE` fails, its error
236
-
appears in the result, and the rest of the copy is unaffected.
238
+
Order alone cannot place two tables that reference each other, or a table that references itself
239
+
with a child row ahead of its parent. Under **Stop and roll back**, when the copy creates every table
240
+
it fills and every key those tables hold points at a table the copy fills with all of its rows, the
241
+
rows are written with the target's foreign key checks off where the engine can turn them off for one
242
+
session, as MySQL and MariaDB can, and the session gets back the setting it had.
243
+
244
+
Turning the checks back on checks nothing already written, so before it commits the copy counts, for
245
+
every key, the rows that point at nothing. A source row whose parent is already gone, or one read
246
+
while the source was changing, fails the copy there, the result names the table and the key, and
247
+
every row is put back.
248
+
249
+
The checks stay on otherwise, and such a row fails with the result naming its table:
250
+
251
+
- A key to a table outside the copy, or to one narrowed by a filter or a row limit.
252
+
-**Data only**, or **Add rows to it** on a table the target already has. The target keeps its own
253
+
keys there, and the source cannot say where they point.
254
+
- A target with no transactions, where a failure could not take the rows back.
255
+
- A target account that cannot read the tables it writes, so the copy could not count what each key
256
+
refuses.
257
+
- PostgreSQL, because its switch also stops the target's own triggers and needs a superuser.
258
+
-**Stop and keep what ran** and **Skip and continue**, since what they keep after a failure can
259
+
leave a child's parent missing.
260
+
261
+
Emptying a table for a Replace keeps the checks on, so a table that references it, selected or not,
262
+
applies its own `ON DELETE` rule.
263
+
264
+
Two tables that reference each other are created with checks off on MySQL and MariaDB when the copy
265
+
holds both. On PostgreSQL the second `CREATE TABLE` fails, its error appears in the result, and the
266
+
rest of the copy is unaffected.
237
267
238
268
## Stopping a copy
239
269
240
-
**Stop** takes effect at the next batch boundary. Each table is its own transaction where the engine
241
-
supports one, so the table being copied rolls back and the tables already finished stay. A driver
242
-
blocked inside a network call finishes that batch first.
270
+
**Stop** takes effect at the next batch boundary. A driver blocked inside a network call finishes that
271
+
batch first.
272
+
273
+
Under **Stop and roll back** the whole data phase is one transaction where the engine supports one,
274
+
so stopping it or a failure puts every row back. A MySQL table on a storage engine without
275
+
transactions, such as MyISAM, keeps its rows through that, and the result counts them. A Replace that removes the target's rows empties
276
+
every table inside it before any of them is filled, so that a cascading foreign key cannot reach a
277
+
table you did not select.
243
278
244
-
A Replace that removes the target's rows is the exception: every table is emptied before any of them
245
-
is filled, so that a cascading foreign key cannot reach a table you did not select, and the whole
246
-
data phase is then one transaction. Stopping it, or a failure under **Stop and roll back**, puts
247
-
every row back. **Skip and continue** promises no rollback, so there the clearing stands.
279
+
The other two settings commit each batch as it is written, so stopping or a failure keeps what was
280
+
written. There the clearing stands, a table whose emptying failed gets no rows, and the structure is
281
+
not one transaction either, so what was created before a failure stays.
248
282
249
-
A stopped copy reports only what was committed. The table it was in the middle of counts as neither
250
-
copied nor failed.
283
+
The result counts only the rows the target kept, including the batches a failed table wrote before
284
+
its error.
251
285
252
286
When the target connection already holds a transaction, the copy runs inside it and opens none of its own. Nothing it wrote is committed until you commit that transaction, and the result says so.
0 commit comments