Documentation Source Text

Hex Artifact Content
Login

Artifact b231385cc33c7c5f233738e961614926c89516e1:


0000: 3c 74 69 74 6c 65 3e 53 51 4c 69 74 65 20 41 75  <title>SQLite Au
0010: 74 6f 69 6e 63 72 65 6d 65 6e 74 3c 2f 74 69 74  toincrement</tit
0020: 6c 65 3e 0a 3c 74 63 6c 3e 68 64 5f 6b 65 79 77  le>.<tcl>hd_keyw
0030: 6f 72 64 73 20 41 55 54 4f 49 4e 43 52 45 4d 45  ords AUTOINCREME
0040: 4e 54 3c 2f 74 63 6c 3e 0a 3c 68 31 20 61 6c 69  NT</tcl>.<h1 ali
0050: 67 6e 3d 63 65 6e 74 65 72 3e 41 75 74 6f 69 6e  gn=center>Autoin
0060: 63 72 65 6d 65 6e 74 20 49 6e 20 53 51 4c 69 74  crement In SQLit
0070: 65 3c 2f 68 31 3e 0a 0a 3c 68 32 3e 53 75 6d 6d  e</h1>..<h2>Summ
0080: 61 72 79 3c 2f 68 32 3e 0a 0a 3c 6f 6c 20 74 79  ary</h2>..<ol ty
0090: 70 65 3d 22 31 22 3e 0a 3c 6c 69 3e 3c 70 3e 0a  pe="1">.<li><p>.
00a0: 20 20 54 68 65 20 41 55 54 4f 49 4e 43 52 45 4d    The AUTOINCREM
00b0: 45 4e 54 20 6b 65 79 77 6f 72 64 20 69 6d 70 6f  ENT keyword impo
00c0: 73 65 73 20 65 78 74 72 61 20 43 50 55 2c 20 6d  ses extra CPU, m
00d0: 65 6d 6f 72 79 2c 20 64 69 73 6b 20 73 70 61 63  emory, disk spac
00e0: 65 2c 0a 20 20 61 6e 64 20 64 69 73 6b 20 49 2f  e,.  and disk I/
00f0: 4f 20 6f 76 65 72 68 65 61 64 20 61 6e 64 20 73  O overhead and s
0100: 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64  hould be avoided
0110: 20 69 66 20 6e 6f 74 20 73 74 72 69 63 74 6c 79   if not strictly
0120: 20 6e 65 65 64 65 64 2e 0a 20 20 49 74 20 69 73   needed..  It is
0130: 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 65   usually not nee
0140: 64 65 64 2e 0a 3c 6c 69 3e 3c 70 3e 0a 20 20 49  ded..<li><p>.  I
0150: 6e 20 53 51 4c 69 74 65 2c 20 61 20 63 6f 6c 75  n SQLite, a colu
0160: 6d 6e 20 77 69 74 68 20 74 79 70 65 20 49 4e 54  mn with type INT
0170: 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
0180: 20 69 73 20 61 6e 20 61 6c 69 61 73 20 66 6f 72   is an alias for
0190: 20 74 68 65 20 5b 52 4f 57 49 44 5d 0a 20 20 28   the [ROWID].  (
01a0: 65 78 63 65 70 74 20 69 6e 20 5b 57 49 54 48 4f  except in [WITHO
01b0: 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
01c0: 29 20 77 68 69 63 68 20 69 73 20 61 6c 77 61 79  ) which is alway
01d0: 73 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65  s a 64-bit signe
01e0: 64 20 69 6e 74 65 67 65 72 2e 0a 3c 6c 69 3e 3c  d integer..<li><
01f0: 70 3e 0a 20 20 4f 6e 20 61 6e 20 5b 49 4e 53 45  p>.  On an [INSE
0200: 52 54 5d 2c 20 69 66 20 74 68 65 20 52 4f 57 49  RT], if the ROWI
0210: 44 20 6f 72 20 49 4e 54 45 47 45 52 20 50 52 49  D or INTEGER PRI
0220: 4d 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e 20  MARY KEY column 
0230: 69 73 20 6e 6f 74 20 0a 20 20 65 78 70 6c 69 63  is not .  explic
0240: 69 74 6c 79 20 67 69 76 65 6e 20 61 20 76 61 6c  itly given a val
0250: 75 65 2c 20 74 68 65 6e 20 69 74 0a 20 20 77 69  ue, then it.  wi
0260: 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 61 75 74  ll be filled aut
0270: 6f 6d 61 74 69 63 61 6c 6c 79 20 77 69 74 68 20  omatically with 
0280: 61 6e 20 75 6e 75 73 65 64 20 69 6e 74 65 67 65  an unused intege
0290: 72 2c 20 75 73 75 61 6c 6c 79 0a 20 20 6f 6e 65  r, usually.  one
02a0: 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 65 20 6c   more than the l
02b0: 61 72 67 65 73 74 20 52 4f 57 49 44 20 63 75 72  argest ROWID cur
02c0: 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 0a 20  rently in use.. 
02d0: 20 54 68 69 73 20 69 73 20 74 72 75 65 20 72 65   This is true re
02e0: 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
02f0: 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 41  her or not the A
0300: 55 54 4f 49 4e 43 52 45 4d 45 4e 54 20 6b 65 79  UTOINCREMENT key
0310: 77 6f 72 64 20 69 73 20 75 73 65 64 2e 0a 3c 6c  word is used..<l
0320: 69 3e 3c 70 3e 0a 20 20 49 66 20 74 68 65 20 41  i><p>.  If the A
0330: 55 54 4f 49 4e 43 52 45 4d 45 4e 54 20 6b 65 79  UTOINCREMENT key
0340: 77 6f 72 64 20 61 70 70 65 61 72 73 20 61 66 74  word appears aft
0350: 65 72 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41  er INTEGER PRIMA
0360: 52 59 20 4b 45 59 2c 20 74 68 61 74 0a 20 20 63  RY KEY, that.  c
0370: 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 6d  hanges the autom
0380: 61 74 69 63 20 52 4f 57 49 44 20 61 73 73 69 67  atic ROWID assig
0390: 6e 6d 65 6e 74 20 61 6c 67 6f 72 69 74 68 6d 20  nment algorithm 
03a0: 74 6f 20 70 72 65 76 65 6e 74 0a 20 20 74 68 65  to prevent.  the
03b0: 20 72 65 75 73 65 20 6f 66 20 52 4f 57 49 44 73   reuse of ROWIDs
03c0: 20 6f 76 65 72 20 74 68 65 20 6c 69 66 65 74 69   over the lifeti
03d0: 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
03e0: 73 65 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  se.  In other wo
03f0: 72 64 73 2c 0a 20 20 74 68 65 20 70 75 72 70 6f  rds,.  the purpo
0400: 73 65 20 6f 66 20 41 55 54 4f 49 4e 43 52 45 4d  se of AUTOINCREM
0410: 45 4e 54 20 69 73 20 74 6f 20 70 72 65 76 65 6e  ENT is to preven
0420: 74 20 74 68 65 20 72 65 75 73 65 20 6f 66 20 52  t the reuse of R
0430: 4f 57 49 44 73 20 66 72 6f 6d 0a 20 20 70 72 65  OWIDs from.  pre
0440: 76 69 6f 75 73 6c 79 20 64 65 6c 65 74 65 64 20  viously deleted 
0450: 72 6f 77 73 2e 0a 3c 2f 6f 6c 3e 0a 0a 3c 68 32  rows..</ol>..<h2
0460: 3e 42 61 63 6b 67 72 6f 75 6e 64 3c 2f 68 32 3e  >Background</h2>
0470: 0a 0a 3c 70 3e 0a 5e 49 6e 20 53 51 4c 69 74 65  ..<p>.^In SQLite
0480: 2c 20 74 61 62 6c 65 20 72 6f 77 73 20 6e 6f 72  , table rows nor
0490: 6d 61 6c 6c 79 20 68 61 76 65 20 61 20 36 34 2d  mally have a 64-
04a0: 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
04b0: 65 72 20 5b 52 4f 57 49 44 5d 0a 77 68 69 63 68  er [ROWID].which
04c0: 20 69 73 20 75 6e 69 71 75 65 20 61 6d 6f 6e 67   is unique among
04d0: 20 61 6c 6c 20 72 6f 77 73 20 69 6e 20 74 68 65   all rows in the
04e0: 20 73 61 6d 65 20 74 61 62 6c 65 2e 0a 28 5b 57   same table..([W
04f0: 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
0500: 62 6c 65 73 20 61 72 65 20 74 68 65 20 65 78 63  bles are the exc
0510: 65 70 74 69 6f 6e 2e 29 0a 3c 2f 70 3e 0a 0a 3c  eption.).</p>..<
0520: 70 3e 0a 5e 28 59 6f 75 20 63 61 6e 20 61 63 63  p>.^(You can acc
0530: 65 73 73 20 74 68 65 20 52 4f 57 49 44 20 6f 66  ess the ROWID of
0540: 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65   an SQLite table
0550: 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68   using one of th
0560: 65 20 73 70 65 63 69 61 6c 20 63 6f 6c 75 6d 6e  e special column
0570: 0a 6e 61 6d 65 73 20 52 4f 57 49 44 2c 20 5f 52  .names ROWID, _R
0580: 4f 57 49 44 5f 2c 20 6f 72 20 4f 49 44 2e 0a 45  OWID_, or OID..E
0590: 78 63 65 70 74 20 69 66 20 79 6f 75 20 64 65 63  xcept if you dec
05a0: 6c 61 72 65 20 61 6e 20 6f 72 64 69 6e 61 72 79  lare an ordinary
05b0: 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 6f   table column to
05c0: 20 75 73 65 20 6f 6e 65 20 6f 66 20 74 68 6f 73   use one of thos
05d0: 65 20 73 70 65 63 69 61 6c 0a 6e 61 6d 65 73 2c  e special.names,
05e0: 20 74 68 65 6e 20 74 68 65 20 75 73 65 20 6f 66   then the use of
05f0: 20 74 68 61 74 20 6e 61 6d 65 20 77 69 6c 6c 20   that name will 
0600: 72 65 66 65 72 20 74 6f 20 74 68 65 20 64 65 63  refer to the dec
0610: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 6f 74  lared column not
0620: 0a 74 6f 20 74 68 65 20 69 6e 74 65 72 6e 61 6c  .to the internal
0630: 20 52 4f 57 49 44 2e 29 5e 0a 3c 2f 70 3e 0a 0a   ROWID.)^.</p>..
0640: 3c 70 3e 0a 5e 49 66 20 61 20 74 61 62 6c 65 20  <p>.^If a table 
0650: 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 6c 75 6d  contains a colum
0660: 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
0670: 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 2c  ER PRIMARY KEY],
0680: 20 74 68 65 6e 20 74 68 61 74 0a 63 6f 6c 75 6d   then that.colum
0690: 6e 20 62 65 63 6f 6d 65 73 20 61 6e 20 61 6c 69  n becomes an ali
06a0: 61 73 20 66 6f 72 20 74 68 65 20 52 4f 57 49 44  as for the ROWID
06b0: 2e 20 20 5e 59 6f 75 20 63 61 6e 20 74 68 65 6e  .  ^You can then
06c0: 20 61 63 63 65 73 73 20 74 68 65 20 52 4f 57 49   access the ROWI
06d0: 44 0a 75 73 69 6e 67 20 61 6e 79 20 6f 66 20 66  D.using any of f
06e0: 6f 75 72 20 64 69 66 66 65 72 65 6e 74 20 6e 61  our different na
06f0: 6d 65 73 2c 20 74 68 65 20 6f 72 69 67 69 6e 61  mes, the origina
0700: 6c 20 74 68 72 65 65 20 6e 61 6d 65 73 20 64 65  l three names de
0710: 73 63 72 69 62 65 64 20 61 62 6f 76 65 0a 6f 72  scribed above.or
0720: 20 74 68 65 20 6e 61 6d 65 20 67 69 76 65 6e 20   the name given 
0730: 74 6f 20 74 68 65 20 5b 49 4e 54 45 47 45 52 20  to the [INTEGER 
0740: 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c  PRIMARY KEY] col
0750: 75 6d 6e 2e 20 20 5e 41 6c 6c 20 74 68 65 73 65  umn.  ^All these
0760: 20 6e 61 6d 65 73 20 61 72 65 0a 61 6c 69 61 73   names are.alias
0770: 65 73 20 66 6f 72 20 6f 6e 65 20 61 6e 6f 74 68  es for one anoth
0780: 65 72 20 61 6e 64 20 77 6f 72 6b 20 65 71 75 61  er and work equa
0790: 6c 6c 79 20 77 65 6c 6c 20 69 6e 20 61 6e 79 20  lly well in any 
07a0: 63 6f 6e 74 65 78 74 2e 0a 3c 2f 70 3e 0a 0a 3c  context..</p>..<
07b0: 70 3e 0a 5e 57 68 65 6e 20 61 20 6e 65 77 20 72  p>.^When a new r
07c0: 6f 77 20 69 73 20 69 6e 73 65 72 74 65 64 20 69  ow is inserted i
07d0: 6e 74 6f 20 61 6e 20 53 51 4c 69 74 65 20 74 61  nto an SQLite ta
07e0: 62 6c 65 2c 20 74 68 65 20 52 4f 57 49 44 20 63  ble, the ROWID c
07f0: 61 6e 20 65 69 74 68 65 72 0a 62 65 20 73 70 65  an either.be spe
0800: 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f  cified as part o
0810: 66 20 74 68 65 20 49 4e 53 45 52 54 20 73 74 61  f the INSERT sta
0820: 74 65 6d 65 6e 74 20 6f 72 20 69 74 20 63 61 6e  tement or it can
0830: 20 62 65 20 61 73 73 69 67 6e 65 64 0a 61 75 74   be assigned.aut
0840: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 74 68  omatically by th
0850: 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
0860: 65 2e 20 20 5e 28 54 6f 20 73 70 65 63 69 66 79  e.  ^(To specify
0870: 20 61 20 52 4f 57 49 44 20 6d 61 6e 75 61 6c 6c   a ROWID manuall
0880: 79 2c 0a 6a 75 73 74 20 69 6e 63 6c 75 64 65 20  y,.just include 
0890: 69 74 20 69 6e 20 74 68 65 20 6c 69 73 74 20 6f  it in the list o
08a0: 66 20 76 61 6c 75 65 73 20 74 6f 20 62 65 20 69  f values to be i
08b0: 6e 73 65 72 74 65 64 2e 20 20 46 6f 72 20 65 78  nserted.  For ex
08c0: 61 6d 70 6c 65 3a 0a 3c 2f 70 3e 0a 0a 3c 62 6c  ample:.</p>..<bl
08d0: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 43  ockquote><pre>.C
08e0: 52 45 41 54 45 20 54 41 42 4c 45 20 74 65 73 74  REATE TABLE test
08f0: 31 28 61 20 49 4e 54 2c 20 62 20 54 45 58 54 29  1(a INT, b TEXT)
0900: 3b 0a 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 65  ;.INSERT INTO te
0910: 73 74 31 28 72 6f 77 69 64 2c 20 61 2c 20 62 29  st1(rowid, a, b)
0920: 20 56 41 4c 55 45 53 28 31 32 33 2c 20 35 2c 20   VALUES(123, 5, 
0930: 27 68 65 6c 6c 6f 27 29 3b 0a 3c 2f 70 72 65 3e  'hello');.</pre>
0940: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
0950: 0a 3c 70 3e 0a 5e 49 66 20 6e 6f 20 52 4f 57 49  .<p>.^If no ROWI
0960: 44 20 69 73 20 73 70 65 63 69 66 69 65 64 20 6f  D is specified o
0970: 6e 20 74 68 65 20 69 6e 73 65 72 74 2c 20 6f 72  n the insert, or
0980: 20 69 66 20 74 68 65 20 73 70 65 63 69 66 69 65   if the specifie
0990: 64 20 52 4f 57 49 44 20 68 61 73 20 61 20 76 61  d ROWID has a va
09a0: 6c 75 65 0a 6f 66 20 4e 55 4c 4c 2c 20 74 68 65  lue.of NULL, the
09b0: 6e 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  n an appropriate
09c0: 20 52 4f 57 49 44 20 69 73 20 63 72 65 61 74 65   ROWID is create
09d0: 64 0a 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d.automatically.
09e0: 20 20 5e 54 68 65 20 75 73 75 61 6c 20 61 6c 67    ^The usual alg
09f0: 6f 72 69 74 68 6d 20 69 73 20 74 6f 20 67 69 76  orithm is to giv
0a00: 65 20 74 68 65 20 6e 65 77 6c 79 20 63 72 65 61  e the newly crea
0a10: 74 65 64 20 72 6f 77 0a 61 20 52 4f 57 49 44 20  ted row.a ROWID 
0a20: 74 68 61 74 20 69 73 20 6f 6e 65 20 6c 61 72 67  that is one larg
0a30: 65 72 20 74 68 61 6e 20 74 68 65 20 6c 61 72 67  er than the larg
0a40: 65 73 74 20 52 4f 57 49 44 20 69 6e 20 74 68 65  est ROWID in the
0a50: 20 74 61 62 6c 65 20 70 72 69 6f 72 0a 74 6f 20   table prior.to 
0a60: 74 68 65 20 69 6e 73 65 72 74 2e 20 20 5e 49 66  the insert.  ^If
0a70: 20 74 68 65 20 74 61 62 6c 65 20 69 73 20 69 6e   the table is in
0a80: 69 74 69 61 6c 6c 79 20 65 6d 70 74 79 2c 20 74  itially empty, t
0a90: 68 65 6e 20 61 20 52 4f 57 49 44 20 6f 66 20 31  hen a ROWID of 1
0aa0: 20 69 73 0a 75 73 65 64 2e 20 20 5e 49 66 20 74   is.used.  ^If t
0ab0: 68 65 20 6c 61 72 67 65 73 74 20 52 4f 57 49 44  he largest ROWID
0ac0: 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65   is equal to the
0ad0: 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
0ae0: 65 20 69 6e 74 65 67 65 72 0a 28 39 32 32 33 33  e integer.(92233
0af0: 37 32 30 33 36 38 35 34 37 37 35 38 30 37 29 20  72036854775807) 
0b00: 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
0b10: 65 0a 65 6e 67 69 6e 65 20 73 74 61 72 74 73 20  e.engine starts 
0b20: 70 69 63 6b 69 6e 67 20 70 6f 73 69 74 69 76 65  picking positive
0b30: 20 63 61 6e 64 69 64 61 74 65 20 52 4f 57 49 44   candidate ROWID
0b40: 73 20 61 74 20 72 61 6e 64 6f 6d 20 75 6e 74 69  s at random unti
0b50: 6c 20 69 74 20 66 69 6e 64 73 20 6f 6e 65 0a 74  l it finds one.t
0b60: 68 61 74 20 69 73 20 6e 6f 74 20 70 72 65 76 69  hat is not previ
0b70: 6f 75 73 6c 79 20 75 73 65 64 2e 0a 5e 49 66 20  ously used..^If 
0b80: 6e 6f 20 75 6e 75 73 65 64 20 52 4f 57 49 44 20  no unused ROWID 
0b90: 63 61 6e 20 62 65 20 66 6f 75 6e 64 20 61 66 74  can be found aft
0ba0: 65 72 20 61 20 72 65 61 73 6f 6e 61 62 6c 65 20  er a reasonable 
0bb0: 6e 75 6d 62 65 72 20 6f 66 20 61 74 74 65 6d 70  number of attemp
0bc0: 74 73 2c 0a 74 68 65 20 69 6e 73 65 72 74 20 6f  ts,.the insert o
0bd0: 70 65 72 61 74 69 6f 6e 20 66 61 69 6c 73 20 77  peration fails w
0be0: 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ith an [SQLITE_F
0bf0: 55 4c 4c 5d 20 65 72 72 6f 72 2e 0a 5e 49 66 20  ULL] error..^If 
0c00: 6e 6f 20 6e 65 67 61 74 69 76 65 20 52 4f 57 49  no negative ROWI
0c10: 44 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 73  D values are ins
0c20: 65 72 74 65 64 20 65 78 70 6c 69 63 69 74 6c 79  erted explicitly
0c30: 2c 20 74 68 65 6e 20 61 75 74 6f 6d 61 74 69 63  , then automatic
0c40: 61 6c 6c 79 20 0a 67 65 6e 65 72 61 74 65 64 20  ally .generated 
0c50: 52 4f 57 49 44 20 76 61 6c 75 65 73 20 77 69 6c  ROWID values wil
0c60: 6c 20 61 6c 77 61 79 73 20 62 65 20 67 72 65 61  l always be grea
0c70: 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2e 0a 3c  ter than zero..<
0c80: 2f 70 3e 0a 0a 3c 70 3e 0a 5e 54 68 65 20 6e 6f  /p>..<p>.^The no
0c90: 72 6d 61 6c 20 52 4f 57 49 44 20 73 65 6c 65 63  rmal ROWID selec
0ca0: 74 69 6f 6e 20 61 6c 67 6f 72 69 74 68 6d 20 64  tion algorithm d
0cb0: 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 0a 77  escribed above.w
0cc0: 69 6c 6c 20 67 65 6e 65 72 61 74 65 20 6d 6f 6e  ill generate mon
0cd0: 6f 74 6f 6e 69 63 61 6c 6c 79 20 69 6e 63 72 65  otonically incre
0ce0: 61 73 69 6e 67 0a 75 6e 69 71 75 65 20 52 4f 57  asing.unique ROW
0cf0: 49 44 73 20 61 73 20 6c 6f 6e 67 20 61 73 20 79  IDs as long as y
0d00: 6f 75 20 6e 65 76 65 72 20 75 73 65 20 74 68 65  ou never use the
0d10: 20 6d 61 78 69 6d 75 6d 20 52 4f 57 49 44 20 76   maximum ROWID v
0d20: 61 6c 75 65 20 61 6e 64 20 79 6f 75 20 6e 65 76  alue and you nev
0d30: 65 72 0a 64 65 6c 65 74 65 20 74 68 65 20 65 6e  er.delete the en
0d40: 74 72 79 20 69 6e 20 74 68 65 20 74 61 62 6c 65  try in the table
0d50: 20 77 69 74 68 20 74 68 65 20 6c 61 72 67 65 73   with the larges
0d60: 74 20 52 4f 57 49 44 2e 20 0a 5e 49 66 20 79 6f  t ROWID. .^If yo
0d70: 75 20 65 76 65 72 20 64 65 6c 65 74 65 20 72 6f  u ever delete ro
0d80: 77 73 20 6f 72 20 69 66 20 79 6f 75 20 65 76 65  ws or if you eve
0d90: 72 20 63 72 65 61 74 65 20 61 20 72 6f 77 20 77  r create a row w
0da0: 69 74 68 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  ith the maximum 
0db0: 70 6f 73 73 69 62 6c 65 0a 52 4f 57 49 44 2c 20  possible.ROWID, 
0dc0: 74 68 65 6e 20 52 4f 57 49 44 73 20 66 72 6f 6d  then ROWIDs from
0dd0: 20 70 72 65 76 69 6f 75 73 6c 79 20 64 65 6c 65   previously dele
0de0: 74 65 64 20 72 6f 77 73 20 6d 69 67 68 74 20 62  ted rows might b
0df0: 65 20 72 65 75 73 65 64 20 77 68 65 6e 20 63 72  e reused when cr
0e00: 65 61 74 69 6e 67 0a 6e 65 77 20 72 6f 77 73 20  eating.new rows 
0e10: 61 6e 64 20 6e 65 77 6c 79 20 63 72 65 61 74 65  and newly create
0e20: 64 20 52 4f 57 49 44 73 20 6d 69 67 68 74 20 6e  d ROWIDs might n
0e30: 6f 74 20 62 65 20 69 6e 20 73 74 72 69 63 74 6c  ot be in strictl
0e40: 79 20 61 73 63 65 6e 64 69 6e 67 20 6f 72 64 65  y ascending orde
0e50: 72 2e 0a 3c 2f 70 3e 0a 0a 0a 3c 68 32 3e 54 68  r..</p>...<h2>Th
0e60: 65 20 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 20  e AUTOINCREMENT 
0e70: 4b 65 79 77 6f 72 64 3c 2f 68 32 3e 0a 0a 3c 70  Keyword</h2>..<p
0e80: 3e 0a 5e 49 66 20 61 20 63 6f 6c 75 6d 6e 20 68  >.^If a column h
0e90: 61 73 20 74 68 65 20 74 79 70 65 20 49 4e 54 45  as the type INTE
0ea0: 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20  GER PRIMARY KEY 
0eb0: 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 20 74 68  AUTOINCREMENT th
0ec0: 65 6e 20 61 20 73 6c 69 67 68 74 6c 79 0a 64 69  en a slightly.di
0ed0: 66 66 65 72 65 6e 74 20 52 4f 57 49 44 20 73 65  fferent ROWID se
0ee0: 6c 65 63 74 69 6f 6e 20 61 6c 67 6f 72 69 74 68  lection algorith
0ef0: 6d 20 69 73 20 75 73 65 64 2e 20 20 0a 5e 54 68  m is used.  .^Th
0f00: 65 20 52 4f 57 49 44 20 63 68 6f 73 65 6e 20 66  e ROWID chosen f
0f10: 6f 72 20 74 68 65 20 6e 65 77 20 72 6f 77 20 69  or the new row i
0f20: 73 20 61 74 20 6c 65 61 73 74 20 6f 6e 65 20 6c  s at least one l
0f30: 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6c  arger than the l
0f40: 61 72 67 65 73 74 20 52 4f 57 49 44 0a 74 68 61  argest ROWID.tha
0f50: 74 20 68 61 73 20 65 76 65 72 20 62 65 66 6f 72  t has ever befor
0f60: 65 20 65 78 69 73 74 65 64 20 69 6e 20 74 68 61  e existed in tha
0f70: 74 20 73 61 6d 65 20 74 61 62 6c 65 2e 20 20 5e  t same table.  ^
0f80: 49 66 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  If the table has
0f90: 20 6e 65 76 65 72 0a 62 65 66 6f 72 65 20 63 6f   never.before co
0fa0: 6e 74 61 69 6e 65 64 20 61 6e 79 20 64 61 74 61  ntained any data
0fb0: 2c 20 74 68 65 6e 20 61 20 52 4f 57 49 44 20 6f  , then a ROWID o
0fc0: 66 20 31 20 69 73 20 75 73 65 64 2e 20 20 5e 49  f 1 is used.  ^I
0fd0: 66 20 74 68 65 20 74 61 62 6c 65 0a 68 61 73 20  f the table.has 
0fe0: 70 72 65 76 69 6f 75 73 6c 79 20 68 65 6c 64 20  previously held 
0ff0: 61 20 72 6f 77 20 77 69 74 68 20 74 68 65 20 6c  a row with the l
1000: 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20  argest possible 
1010: 52 4f 57 49 44 2c 20 74 68 65 6e 20 6e 65 77 20  ROWID, then new 
1020: 49 4e 53 45 52 54 73 0a 61 72 65 20 6e 6f 74 20  INSERTs.are not 
1030: 61 6c 6c 6f 77 65 64 20 61 6e 64 20 61 6e 79 20  allowed and any 
1040: 61 74 74 65 6d 70 74 20 74 6f 20 69 6e 73 65 72  attempt to inser
1050: 74 20 61 20 6e 65 77 20 72 6f 77 20 77 69 6c 6c  t a new row will
1060: 20 66 61 69 6c 20 77 69 74 68 20 61 6e 0a 53 51   fail with an.SQ
1070: 4c 49 54 45 5f 46 55 4c 4c 20 65 72 72 6f 72 2e  LITE_FULL error.
1080: 20 20 5e 28 4f 6e 6c 79 20 52 4f 57 49 44 20 76    ^(Only ROWID v
1090: 61 6c 75 65 73 20 66 72 6f 6d 20 70 72 65 76 69  alues from previ
10a0: 6f 75 73 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  ous transactions
10b0: 20 74 68 61 74 0a 77 65 72 65 20 63 6f 6d 6d 69   that.were commi
10c0: 74 74 65 64 20 61 72 65 20 63 6f 6e 73 69 64 65  tted are conside
10d0: 72 65 64 2e 20 20 52 4f 57 49 44 20 76 61 6c 75  red.  ROWID valu
10e0: 65 73 20 74 68 61 74 20 77 65 72 65 20 72 6f 6c  es that were rol
10f0: 6c 65 64 20 62 61 63 6b 0a 61 72 65 20 69 67 6e  led back.are ign
1100: 6f 72 65 64 20 61 6e 64 20 63 61 6e 20 62 65 20  ored and can be 
1110: 72 65 75 73 65 64 2e 29 5e 0a 3c 2f 70 3e 0a 0a  reused.)^.</p>..
1120: 3c 70 3e 0a 5e 53 51 4c 69 74 65 20 6b 65 65 70  <p>.^SQLite keep
1130: 73 20 74 72 61 63 6b 20 6f 66 20 74 68 65 20 6c  s track of the l
1140: 61 72 67 65 73 74 20 52 4f 57 49 44 20 74 68 61  argest ROWID tha
1150: 74 20 61 20 74 61 62 6c 65 20 68 61 73 20 65 76  t a table has ev
1160: 65 72 20 68 65 6c 64 20 75 73 69 6e 67 0a 61 6e  er held using.an
1170: 20 5b 69 6e 74 65 72 6e 61 6c 20 74 61 62 6c 65   [internal table
1180: 5d 20 6e 61 6d 65 64 20 22 5b 73 71 6c 69 74 65  ] named "[sqlite
1190: 5f 73 65 71 75 65 6e 63 65 5d 22 2e 0a 5e 54 68  _sequence]"..^Th
11a0: 65 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63  e sqlite_sequenc
11b0: 65 20 74 61 62 6c 65 20 69 73 20 63 72 65 61 74  e table is creat
11c0: 65 64 0a 61 6e 64 20 69 6e 69 74 69 61 6c 69 7a  ed.and initializ
11d0: 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
11e0: 20 77 68 65 6e 65 76 65 72 20 61 20 6e 6f 72 6d   whenever a norm
11f0: 61 6c 20 74 61 62 6c 65 20 74 68 61 74 20 63 6f  al table that co
1200: 6e 74 61 69 6e 73 20 61 6e 0a 41 55 54 4f 49 4e  ntains an.AUTOIN
1210: 43 52 45 4d 45 4e 54 20 63 6f 6c 75 6d 6e 20 69  CREMENT column i
1220: 73 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 65  s created.  ^The
1230: 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
1240: 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 20  sqlite_sequence 
1250: 74 61 62 6c 65 0a 63 61 6e 20 62 65 20 6d 6f 64  table.can be mod
1260: 69 66 69 65 64 20 75 73 69 6e 67 20 6f 72 64 69  ified using ordi
1270: 6e 61 72 79 20 55 50 44 41 54 45 2c 20 49 4e 53  nary UPDATE, INS
1280: 45 52 54 2c 20 61 6e 64 20 44 45 4c 45 54 45 20  ERT, and DELETE 
1290: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 5e 42 75 74  statements..^But
12a0: 20 6d 61 6b 69 6e 67 20 6d 6f 64 69 66 69 63 61   making modifica
12b0: 74 69 6f 6e 73 20 74 6f 20 74 68 69 73 20 74 61  tions to this ta
12c0: 62 6c 65 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ble will likely 
12d0: 70 65 72 74 75 72 62 20 74 68 65 20 41 55 54 4f  perturb the AUTO
12e0: 49 4e 43 52 45 4d 45 4e 54 0a 6b 65 79 20 67 65  INCREMENT.key ge
12f0: 6e 65 72 61 74 69 6f 6e 20 61 6c 67 6f 72 69 74  neration algorit
1300: 68 6d 2e 20 20 4d 61 6b 65 20 73 75 72 65 20 79  hm.  Make sure y
1310: 6f 75 20 6b 6e 6f 77 20 77 68 61 74 20 79 6f 75  ou know what you
1320: 20 61 72 65 20 64 6f 69 6e 67 20 62 65 66 6f 72   are doing befor
1330: 65 0a 79 6f 75 20 75 6e 64 65 72 74 61 6b 65 20  e.you undertake 
1340: 73 75 63 68 20 63 68 61 6e 67 65 73 2e 0a 3c 2f  such changes..</
1350: 70 3e 0a 0a 3c 70 3e 0a 54 68 65 20 62 65 68 61  p>..<p>.The beha
1360: 76 69 6f 72 20 69 6d 70 6c 65 6d 65 6e 74 65 64  vior implemented
1370: 20 62 79 20 74 68 65 20 41 55 54 4f 49 4e 43 52   by the AUTOINCR
1380: 45 4d 45 4e 54 20 6b 65 79 77 6f 72 64 20 69 73  EMENT keyword is
1390: 20 73 75 62 74 6c 79 20 64 69 66 66 65 72 65 6e   subtly differen
13a0: 74 0a 66 72 6f 6d 20 74 68 65 20 64 65 66 61 75  t.from the defau
13b0: 6c 74 20 62 65 68 61 76 69 6f 72 2e 20 20 5e 57  lt behavior.  ^W
13c0: 69 74 68 20 41 55 54 4f 49 4e 43 52 45 4d 45 4e  ith AUTOINCREMEN
13d0: 54 2c 20 72 6f 77 73 20 77 69 74 68 20 61 75 74  T, rows with aut
13e0: 6f 6d 61 74 69 63 61 6c 6c 79 0a 73 65 6c 65 63  omatically.selec
13f0: 74 65 64 20 52 4f 57 49 44 73 20 61 72 65 20 67  ted ROWIDs are g
1400: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 68 61 76  uaranteed to hav
1410: 65 20 52 4f 57 49 44 73 20 74 68 61 74 20 68 61  e ROWIDs that ha
1420: 76 65 20 6e 65 76 65 72 20 62 65 65 6e 20 75 73  ve never been us
1430: 65 64 0a 62 65 66 6f 72 65 20 62 79 20 74 68 65  ed.before by the
1440: 20 73 61 6d 65 20 74 61 62 6c 65 20 69 6e 20 74   same table in t
1450: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
1460: 2e 20 20 5e 41 6e 64 20 74 68 65 20 61 75 74 6f  .  ^And the auto
1470: 6d 61 74 69 63 61 6c 6c 79 20 67 65 6e 65 72 61  matically genera
1480: 74 65 64 0a 52 4f 57 49 44 73 20 61 72 65 20 67  ted.ROWIDs are g
1490: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
14a0: 6d 6f 6e 6f 74 6f 6e 69 63 61 6c 6c 79 20 69 6e  monotonically in
14b0: 63 72 65 61 73 69 6e 67 2e 20 20 54 68 65 73 65  creasing.  These
14c0: 20 61 72 65 20 69 6d 70 6f 72 74 61 6e 74 0a 70   are important.p
14d0: 72 6f 70 65 72 74 69 65 73 20 69 6e 20 63 65 72  roperties in cer
14e0: 74 61 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tain application
14f0: 73 2e 20 20 42 75 74 20 69 66 20 79 6f 75 72 20  s.  But if your 
1500: 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
1510: 20 6e 6f 74 0a 6e 65 65 64 20 74 68 65 73 65 20   not.need these 
1520: 70 72 6f 70 65 72 74 69 65 73 2c 20 79 6f 75 20  properties, you 
1530: 73 68 6f 75 6c 64 20 70 72 6f 62 61 62 6c 79 20  should probably 
1540: 73 74 61 79 20 77 69 74 68 20 74 68 65 20 64 65  stay with the de
1550: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 0a 73  fault behavior.s
1560: 69 6e 63 65 20 74 68 65 20 75 73 65 20 6f 66 20  ince the use of 
1570: 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 20 72 65  AUTOINCREMENT re
1580: 71 75 69 72 65 73 20 61 64 64 69 74 69 6f 6e 61  quires additiona
1590: 6c 20 77 6f 72 6b 20 74 6f 20 62 65 20 64 6f 6e  l work to be don
15a0: 65 0a 61 73 20 65 61 63 68 20 72 6f 77 20 69 73  e.as each row is
15b0: 20 69 6e 73 65 72 74 65 64 20 61 6e 64 20 74 68   inserted and th
15c0: 75 73 20 63 61 75 73 65 73 20 49 4e 53 45 52 54  us causes INSERT
15d0: 73 20 74 6f 20 72 75 6e 20 61 20 6c 69 74 74 6c  s to run a littl
15e0: 65 20 73 6c 6f 77 65 72 2e 0a 3c 2f 70 3e 0a 0a  e slower..</p>..
15f0: 3c 70 3e 5e 4e 6f 74 65 20 74 68 61 74 20 22 6d  <p>^Note that "m
1600: 6f 6e 6f 74 6f 6e 69 63 61 6c 6c 79 20 69 6e 63  onotonically inc
1610: 72 65 61 73 69 6e 67 22 20 64 6f 65 73 20 6e 6f  reasing" does no
1620: 74 20 69 6d 70 6c 79 20 74 68 61 74 20 74 68 65  t imply that the
1630: 20 52 4f 57 49 44 20 61 6c 77 61 79 73 0a 69 6e   ROWID always.in
1640: 63 72 65 61 73 65 73 20 62 79 20 65 78 61 63 74  creases by exact
1650: 6c 79 20 6f 6e 65 2e 20 20 5e 4f 6e 65 20 69 73  ly one.  ^One is
1660: 20 74 68 65 20 75 73 75 61 6c 20 69 6e 63 72 65   the usual incre
1670: 6d 65 6e 74 2e 20 20 5e 48 6f 77 65 76 65 72 2c  ment.  ^However,
1680: 20 69 66 20 61 6e 0a 69 6e 73 65 72 74 20 66 61   if an.insert fa
1690: 69 6c 73 20 64 75 65 20 74 6f 20 28 66 6f 72 20  ils due to (for 
16a0: 65 78 61 6d 70 6c 65 29 20 61 20 75 6e 69 71 75  example) a uniqu
16b0: 65 6e 65 73 73 20 63 6f 6e 73 74 72 61 69 6e 74  eness constraint
16c0: 2c 20 74 68 65 20 52 4f 57 49 44 20 6f 66 0a 74  , the ROWID of.t
16d0: 68 65 20 66 61 69 6c 65 64 20 69 6e 73 65 72 74  he failed insert
16e0: 69 6f 6e 20 61 74 74 65 6d 70 74 20 6d 69 67 68  ion attempt migh
16f0: 74 20 6e 6f 74 20 62 65 20 72 65 75 73 65 64 20  t not be reused 
1700: 6f 6e 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  on subsequent in
1710: 73 65 72 74 73 2c 0a 72 65 73 75 6c 74 69 6e 67  serts,.resulting
1720: 20 69 6e 20 67 61 70 73 20 69 6e 20 74 68 65 20   in gaps in the 
1730: 52 4f 57 49 44 20 73 65 71 75 65 6e 63 65 2e 20  ROWID sequence. 
1740: 20 5e 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 20   ^AUTOINCREMENT 
1750: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
1760: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 63 68  automatically ch
1770: 6f 73 65 6e 20 52 4f 57 49 44 73 20 77 69 6c 6c  osen ROWIDs will
1780: 20 62 65 20 69 6e 63 72 65 61 73 69 6e 67 20 62   be increasing b
1790: 75 74 20 6e 6f 74 20 74 68 61 74 20 74 68 65 79  ut not that they
17a0: 20 77 69 6c 6c 20 62 65 0a 73 65 71 75 65 6e 74   will be.sequent
17b0: 69 61 6c 2e 3c 2f 70 3e 0a 0a 3c 70 3e 42 65 63  ial.</p>..<p>Bec
17c0: 61 75 73 65 20 41 55 54 4f 49 4e 43 52 45 4d 45  ause AUTOINCREME
17d0: 4e 54 20 6b 65 79 77 6f 72 64 20 63 68 61 6e 67  NT keyword chang
17e0: 65 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  es the behavior 
17f0: 6f 66 20 74 68 65 20 52 4f 57 49 44 20 73 65 6c  of the ROWID sel
1800: 65 63 74 69 6f 6e 0a 61 6c 67 6f 72 69 74 68 6d  ection.algorithm
1810: 2c 20 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 20  , AUTOINCREMENT 
1820: 69 73 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 6f  is not allowed o
1830: 6e 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44  n [WITHOUT ROWID
1840: 5d 20 74 61 62 6c 65 73 20 6f 72 20 6f 6e 20 61  ] tables or on a
1850: 6e 79 0a 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  ny.table column 
1860: 6f 74 68 65 72 20 74 68 61 6e 20 49 4e 54 45 47  other than INTEG
1870: 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 2e 20  ER PRIMARY KEY. 
1880: 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f   ^Any attempt to
1890: 20 75 73 65 20 0a 41 55 54 4f 49 4e 43 52 45 4d   use .AUTOINCREM
18a0: 45 4e 54 20 6f 6e 20 61 20 5b 57 49 54 48 4f 55  ENT on a [WITHOU
18b0: 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 20 6f  T ROWID] table o
18c0: 72 20 6f 6e 20 61 20 63 6f 6c 75 6d 6e 20 6f 74  r on a column ot
18d0: 68 65 72 20 74 68 61 6e 20 74 68 65 0a 49 4e 54  her than the.INT
18e0: 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
18f0: 20 63 6f 6c 75 6d 6e 20 72 65 73 75 6c 74 73 20   column results 
1900: 69 6e 20 61 6e 20 65 72 72 6f 72 2e 3c 2f 70 3e  in an error.</p>
1910: 0a                                               .