Documentation Source Text

Hex Artifact Content
Login

Artifact 1ad44025d4f9e5f521cf87e0e387955e566fa8eb:


0000: 3c 74 69 74 6c 65 3e 43 6f 6e 73 74 72 61 69 6e  <title>Constrain
0010: 74 20 43 6f 6e 66 6c 69 63 74 20 52 65 73 6f 6c  t Conflict Resol
0020: 75 74 69 6f 6e 20 69 6e 20 53 51 4c 69 74 65 3c  ution in SQLite<
0030: 2f 74 69 74 6c 65 3e 0a 0a 3c 68 31 3e 43 6f 6e  /title>..<h1>Con
0040: 73 74 72 61 69 6e 74 20 43 6f 6e 66 6c 69 63 74  straint Conflict
0050: 20 52 65 73 6f 6c 75 74 69 6f 6e 20 69 6e 20 53   Resolution in S
0060: 51 4c 69 74 65 3c 2f 68 31 3e 0a 0a 3c 70 3e 0a  QLite</h1>..<p>.
0070: 49 6e 20 6d 6f 73 74 20 53 51 4c 20 64 61 74 61  In most SQL data
0080: 62 61 73 65 73 2c 20 69 66 20 79 6f 75 20 68 61  bases, if you ha
0090: 76 65 20 61 20 5b 55 4e 49 51 55 45 5d 2c 20 5b  ve a [UNIQUE], [
00a0: 4e 4f 54 20 4e 55 4c 4c 5d 2c 20 6f 72 0a 5b 43  NOT NULL], or.[C
00b0: 48 45 43 4b 5d 20 63 6f 6e 73 74 72 61 69 6e 74  HECK] constraint
00c0: 20 6f 6e 0a 61 20 74 61 62 6c 65 20 61 6e 64 20   on.a table and 
00d0: 79 6f 75 20 74 72 79 20 74 6f 20 64 6f 20 61 6e  you try to do an
00e0: 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 49 4e   [UPDATE] or [IN
00f0: 53 45 52 54 5d 20 74 68 61 74 20 76 69 6f 6c 61  SERT] that viola
0100: 74 65 73 0a 74 68 65 20 63 6f 6e 73 74 72 61 69  tes.the constrai
0110: 6e 74 2c 20 74 68 65 20 64 61 74 61 62 61 73 65  nt, the database
0120: 20 77 69 6c 6c 20 61 62 6f 72 74 20 74 68 65 20   will abort the 
0130: 6f 70 65 72 61 74 69 6f 6e 20 69 6e 0a 70 72 6f  operation in.pro
0140: 67 72 65 73 73 2c 20 62 61 63 6b 20 6f 75 74 20  gress, back out 
0150: 61 6e 79 20 70 72 69 6f 72 20 63 68 61 6e 67 65  any prior change
0160: 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
0170: 68 20 74 68 65 20 73 61 6d 65 0a 55 50 44 41 54  h the same.UPDAT
0180: 45 20 6f 72 20 49 4e 53 45 52 54 20 73 74 61 74  E or INSERT stat
0190: 65 6d 65 6e 74 2c 20 61 6e 64 20 72 65 74 75 72  ement, and retur
01a0: 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 54 68 69 73  n an error..This
01b0: 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
01c0: 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
01d0: 74 65 2c 20 74 68 6f 75 67 68 20 53 51 4c 69 74  te, though SQLit
01e0: 65 20 61 6c 73 6f 20 61 6c 6c 6f 77 73 20 6f 6e  e also allows on
01f0: 65 20 74 6f 0a 64 65 66 69 6e 65 20 61 6c 74 65  e to.define alte
0200: 72 6e 61 74 69 76 65 20 77 61 79 73 20 66 6f 72  rnative ways for
0210: 20 64 65 61 6c 69 6e 67 20 77 69 74 68 20 63 6f   dealing with co
0220: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
0230: 6f 6e 73 2e 0a 54 68 69 73 20 61 72 74 69 63 6c  ons..This articl
0240: 65 20 64 65 73 63 72 69 62 65 73 20 74 68 6f 73  e describes thos
0250: 65 20 61 6c 74 65 72 6e 61 74 69 76 65 73 20 61  e alternatives a
0260: 6e 64 20 68 6f 77 20 74 6f 20 75 73 65 20 74 68  nd how to use th
0270: 65 6d 2e 0a 3c 2f 70 3e 0a 0a 3c 68 32 3e 43 6f  em..</p>..<h2>Co
0280: 6e 66 6c 69 63 74 20 52 65 73 6f 6c 75 74 69 6f  nflict Resolutio
0290: 6e 20 41 6c 67 6f 72 69 74 68 6d 73 3c 2f 68 32  n Algorithms</h2
02a0: 3e 0a 0a 3c 70 3e 0a 53 51 4c 69 74 65 20 64 65  >..<p>.SQLite de
02b0: 66 69 6e 65 73 20 66 69 76 65 20 63 6f 6e 73 74  fines five const
02c0: 72 61 69 6e 74 20 63 6f 6e 66 6c 69 63 74 20 72  raint conflict r
02d0: 65 73 6f 6c 75 74 69 6f 6e 20 61 6c 67 6f 72 69  esolution algori
02e0: 74 68 6d 73 0a 61 73 20 66 6f 6c 6c 6f 77 73 3a  thms.as follows:
02f0: 0a 3c 2f 70 3e 0a 0a 3c 64 6c 3e 0a 3c 64 74 3e  .</p>..<dl>.<dt>
0300: 3c 62 3e 52 4f 4c 4c 42 41 43 4b 3c 2f 62 3e 3c  <b>ROLLBACK</b><
0310: 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 57 68 65 6e  /dt>.<dd><p>When
0320: 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
0330: 6f 6c 61 74 69 6f 6e 20 6f 63 63 75 72 73 2c 20  olation occurs, 
0340: 61 6e 20 69 6d 6d 65 64 69 61 74 65 20 52 4f 4c  an immediate ROL
0350: 4c 42 41 43 4b 0a 6f 63 63 75 72 73 2c 20 74 68  LBACK.occurs, th
0360: 75 73 20 65 6e 64 69 6e 67 20 74 68 65 20 63 75  us ending the cu
0370: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
0380: 6e 2c 20 61 6e 64 20 74 68 65 20 63 6f 6d 6d 61  n, and the comma
0390: 6e 64 20 61 62 6f 72 74 73 0a 77 69 74 68 20 61  nd aborts.with a
03a0: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20   return code of 
03b0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
03c0: 54 2e 20 20 49 66 20 6e 6f 20 74 72 61 6e 73 61  T.  If no transa
03d0: 63 74 69 6f 6e 20 69 73 0a 61 63 74 69 76 65 20  ction is.active 
03e0: 28 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 20  (other than the 
03f0: 69 6d 70 6c 69 65 64 20 74 72 61 6e 73 61 63 74  implied transact
0400: 69 6f 6e 20 74 68 61 74 20 69 73 20 63 72 65 61  ion that is crea
0410: 74 65 64 20 6f 6e 20 65 76 65 72 79 0a 63 6f 6d  ted on every.com
0420: 6d 61 6e 64 29 20 74 68 65 6e 20 74 68 69 73 20  mand) then this 
0430: 61 6c 67 6f 72 69 74 68 6d 20 77 6f 72 6b 73 20  algorithm works 
0440: 74 68 65 20 73 61 6d 65 20 61 73 20 41 42 4f 52  the same as ABOR
0450: 54 2e 3c 2f 70 3e 3c 2f 64 64 3e 0a 0a 3c 64 74  T.</p></dd>..<dt
0460: 3e 3c 62 3e 41 42 4f 52 54 3c 2f 62 3e 3c 2f 64  ><b>ABORT</b></d
0470: 74 3e 0a 3c 64 64 3e 3c 70 3e 57 68 65 6e 20 61  t>.<dd><p>When a
0480: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
0490: 61 74 69 6f 6e 20 6f 63 63 75 72 73 2c 20 74 68  ation occurs, th
04a0: 65 20 63 6f 6d 6d 61 6e 64 20 62 61 63 6b 73 20  e command backs 
04b0: 6f 75 74 0a 61 6e 79 20 70 72 69 6f 72 20 63 68  out.any prior ch
04c0: 61 6e 67 65 73 20 69 74 20 6d 69 67 68 74 20 68  anges it might h
04d0: 61 76 65 20 6d 61 64 65 20 61 6e 64 20 61 62 6f  ave made and abo
04e0: 72 74 73 20 77 69 74 68 20 61 20 72 65 74 75 72  rts with a retur
04f0: 6e 20 63 6f 64 65 0a 6f 66 20 53 51 4c 49 54 45  n code.of SQLITE
0500: 5f 43 4f 4e 53 54 52 41 49 4e 54 2e 20 20 42 75  _CONSTRAINT.  Bu
0510: 74 20 6e 6f 20 52 4f 4c 4c 42 41 43 4b 20 69 73  t no ROLLBACK is
0520: 20 65 78 65 63 75 74 65 64 20 73 6f 20 63 68 61   executed so cha
0530: 6e 67 65 73 0a 66 72 6f 6d 20 70 72 69 6f 72 20  nges.from prior 
0540: 63 6f 6d 6d 61 6e 64 73 20 77 69 74 68 69 6e 20  commands within 
0550: 74 68 65 20 73 61 6d 65 20 74 72 61 6e 73 61 63  the same transac
0560: 74 69 6f 6e 0a 61 72 65 20 70 72 65 73 65 72 76  tion.are preserv
0570: 65 64 2e 20 20 54 68 69 73 20 69 73 20 74 68 65  ed.  This is the
0580: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
0590: 72 20 66 6f 72 20 53 51 4c 69 74 65 2e 3c 2f 70  r for SQLite.</p
05a0: 3e 3c 2f 64 64 3e 0a 0a 3c 64 74 3e 3c 62 3e 46  ></dd>..<dt><b>F
05b0: 41 49 4c 3c 2f 62 3e 3c 2f 64 74 3e 0a 3c 64 64  AIL</b></dt>.<dd
05c0: 3e 3c 70 3e 57 68 65 6e 20 61 20 63 6f 6e 73 74  ><p>When a const
05d0: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
05e0: 6f 63 63 75 72 73 2c 20 74 68 65 20 63 6f 6d 6d  occurs, the comm
05f0: 61 6e 64 20 61 62 6f 72 74 73 20 77 69 74 68 20  and aborts with 
0600: 61 0a 72 65 74 75 72 6e 20 63 6f 64 65 20 53 51  a.return code SQ
0610: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 2e  LITE_CONSTRAINT.
0620: 20 20 42 75 74 20 61 6e 79 20 63 68 61 6e 67 65    But any change
0630: 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  s to the databas
0640: 65 20 74 68 61 74 0a 74 68 65 20 63 6f 6d 6d 61  e that.the comma
0650: 6e 64 20 6d 61 64 65 20 70 72 69 6f 72 20 74 6f  nd made prior to
0660: 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
0670: 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  e constraint vio
0680: 6c 61 74 69 6f 6e 0a 61 72 65 20 70 72 65 73 65  lation.are prese
0690: 72 76 65 64 20 61 6e 64 20 61 72 65 20 6e 6f 74  rved and are not
06a0: 20 62 61 63 6b 65 64 20 6f 75 74 2e 20 20 46 6f   backed out.  Fo
06b0: 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e  r example, if an
06c0: 20 55 50 44 41 54 45 0a 73 74 61 74 65 6d 65 6e   UPDATE.statemen
06d0: 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 20  t encountered a 
06e0: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
06f0: 74 69 6f 6e 20 6f 6e 20 74 68 65 20 31 30 30 74  tion on the 100t
0700: 68 20 72 6f 77 20 74 68 61 74 0a 69 74 20 61 74  h row that.it at
0710: 74 65 6d 70 74 73 20 74 6f 20 75 70 64 61 74 65  tempts to update
0720: 2c 20 74 68 65 6e 20 74 68 65 20 66 69 72 73 74  , then the first
0730: 20 39 39 20 72 6f 77 20 63 68 61 6e 67 65 73 20   99 row changes 
0740: 61 72 65 20 70 72 65 73 65 72 76 65 64 0a 62 75  are preserved.bu
0750: 74 20 63 68 61 6e 67 65 20 74 6f 20 72 6f 77 73  t change to rows
0760: 20 31 30 30 20 61 6e 64 20 62 65 79 6f 6e 64 20   100 and beyond 
0770: 6e 65 76 65 72 20 6f 63 63 75 72 2e 3c 2f 70 3e  never occur.</p>
0780: 3c 2f 64 64 3e 0a 0a 3c 64 74 3e 3c 62 3e 49 47  </dd>..<dt><b>IG
0790: 4e 4f 52 45 3c 2f 62 3e 3c 2f 64 74 3e 0a 3c 64  NORE</b></dt>.<d
07a0: 64 3e 3c 70 3e 57 68 65 6e 20 61 20 63 6f 6e 73  d><p>When a cons
07b0: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
07c0: 20 6f 63 63 75 72 73 2c 20 74 68 65 20 6f 6e 65   occurs, the one
07d0: 20 72 6f 77 20 74 68 61 74 20 63 6f 6e 74 61 69   row that contai
07e0: 6e 73 0a 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  ns.the constrain
07f0: 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
0800: 6f 74 20 69 6e 73 65 72 74 65 64 20 6f 72 20 63  ot inserted or c
0810: 68 61 6e 67 65 64 2e 20 20 42 75 74 20 74 68 65  hanged.  But the
0820: 20 63 6f 6d 6d 61 6e 64 0a 63 6f 6e 74 69 6e 75   command.continu
0830: 65 73 20 65 78 65 63 75 74 69 6e 67 20 6e 6f 72  es executing nor
0840: 6d 61 6c 6c 79 2e 20 20 4f 74 68 65 72 20 72 6f  mally.  Other ro
0850: 77 73 20 62 65 66 6f 72 65 20 61 6e 64 20 61 66  ws before and af
0860: 74 65 72 20 74 68 65 20 72 6f 77 20 74 68 61 74  ter the row that
0870: 0a 63 6f 6e 74 61 69 6e 65 64 20 74 68 65 20 63  .contained the c
0880: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
0890: 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ion continue to 
08a0: 62 65 20 69 6e 73 65 72 74 65 64 20 6f 72 20 75  be inserted or u
08b0: 70 64 61 74 65 64 0a 6e 6f 72 6d 61 6c 6c 79 2e  pdated.normally.
08c0: 20 20 4e 6f 20 65 72 72 6f 72 20 69 73 20 72 65    No error is re
08d0: 74 75 72 6e 65 64 2e 3c 2f 70 3e 3c 2f 64 64 3e  turned.</p></dd>
08e0: 0a 0a 3c 64 74 3e 3c 62 3e 52 45 50 4c 41 43 45  ..<dt><b>REPLACE
08f0: 3c 2f 62 3e 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70  </b></dt>.<dd><p
0900: 3e 57 68 65 6e 20 61 20 55 4e 49 51 55 45 20 63  >When a UNIQUE c
0910: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
0920: 69 6f 6e 20 6f 63 63 75 72 73 2c 20 74 68 65 20  ion occurs, the 
0930: 70 72 65 2d 65 78 69 73 74 69 6e 67 20 72 6f 77  pre-existing row
0940: 0a 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65  .that caused the
0950: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
0960: 61 74 69 6f 6e 20 69 73 20 72 65 6d 6f 76 65 64  ation is removed
0970: 20 70 72 69 6f 72 20 74 6f 20 69 6e 73 65 72 74   prior to insert
0980: 69 6e 67 0a 6f 72 20 75 70 64 61 74 69 6e 67 20  ing.or updating 
0990: 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 2e  the current row.
09a0: 20 20 54 68 75 73 20 74 68 65 20 69 6e 73 65 72    Thus the inser
09b0: 74 20 6f 72 20 75 70 64 61 74 65 20 61 6c 77 61  t or update alwa
09c0: 79 73 20 6f 63 63 75 72 73 2e 0a 54 68 65 20 63  ys occurs..The c
09d0: 6f 6d 6d 61 6e 64 20 63 6f 6e 74 69 6e 75 65 73  ommand continues
09e0: 20 65 78 65 63 75 74 69 6e 67 20 6e 6f 72 6d 61   executing norma
09f0: 6c 6c 79 2e 20 20 4e 6f 20 65 72 72 6f 72 20 69  lly.  No error i
0a00: 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 70 3e 3c  s returned.</p><
0a10: 2f 64 64 3e 0a 3c 2f 64 6c 3e 0a                 /dd>.</dl>.