Skip to content

Commit 4b6658a

Browse files
authored
docs(features): foreign key checks during Copy To and the On error setting (#134)
1 parent 2288d41 commit 4b6658a

1 file changed

Lines changed: 45 additions & 11 deletions

File tree

‎features/copy-objects.mdx‎

Lines changed: 45 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,9 @@ written until you have read the script.
2828

2929
The funnel beside a table narrows the rows it contributes. See
3030
[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.
3134
</Step>
3235
<Step title="Read the script, then copy">
3336
**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'
232235
references the target's afterwards, so the duplicate stands on its own; one that referenced a third
233236
schema is left as it was.
234237

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.
237267

238268
## Stopping a copy
239269

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.
243278

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.
248282

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.
251285

252286
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.
253287

0 commit comments

Comments
 (0)