Documentation Source Text

<title>Constraint Conflict Resolution in SQLite</title>

<h1>Constraint Conflict Resolution in SQLite</h1>

<p>
In most SQL databases, if you have a UNIQUE constraint on

a table and you try to do an UPDATE or INSERT that violates
the constraint, the database will abort the operation in
progress, back out any prior changes associated with the same
UPDATE or INSERT statement, and return an error.
This is the default behavior of SQLite, though SQLite also allows one to
define alternative ways for dealing with constraint violations.
This article describes those alternatives and how to use them.
</p>

<title>Constraint Conflict Resolution in SQLite</title>

<h1>Constraint Conflict Resolution in SQLite</h1>

<p>
In most SQL databases, if you have a [UNIQUE], [NOT NULL], or
[CHECK] constraint on
a table and you try to do an [UPDATE] or [INSERT] that violates
the constraint, the database will abort the operation in
progress, back out any prior changes associated with the same
UPDATE or INSERT statement, and return an error.
This is the default behavior of SQLite, though SQLite also allows one to
define alternative ways for dealing with constraint violations.
This article describes those alternatives and how to use them.
</p>

<h2>1.0 Introduction</h2>

<p>For most applications, the recommended method for building
SQLite is to use <a href="amalgamation.html">the amalgamation</a> code
file, <b>sqlite3.c</b>, and its corresponding header file
<b>sqlite3.h</b>.  The sqlite3.c code file should compile and
run on any Unix, Windows, OS/2, or Mac OS X system without any changes
or special compiler options.  Most applications can simply include
the sqlite3.c file together with the other C code files that make
up the application, compile them all together, and have working
and well configured version of SQLite.</p>

<blockquote><i>Most applications work great with SQLite in its
default configuration and with no special compile-time configuration.

<h2>1.0 Introduction</h2>

<p>For most applications, the recommended method for building
SQLite is to use <a href="amalgamation.html">the amalgamation</a> code
file, <b>sqlite3.c</b>, and its corresponding header file
<b>sqlite3.h</b>.  The sqlite3.c code file should compile and
run on any unix, Windows system without any changes
or special compiler options.  Most applications can simply include
the sqlite3.c file together with the other C code files that make
up the application, compile them all together, and have working
and well configured version of SQLite.</p>

<blockquote><i>Most applications work great with SQLite in its
default configuration and with no special compile-time configuration.

  This page describes features of SQL that SQLite does not support.
}


heading {SQLite Features and Extensions} {
  Pages describing specific features or extension modules of SQLite.
}


doc {Asynchronous IO Mode} {asyncvfs.html} {
  This page describes the asynchronous IO extension developed alongside
  SQLite. Using asynchronous IO can cause SQLite to appear more responsive
  by delegating database writes to a background thread.  <i>NB:  This
  extension is deprecated.  [WAL mode] is recommended as a replacement.</i>
}
doc {Foreign Key Support} {foreignkeys.html} {
  This document describes the support for foreign key constraints introduced
  in version 3.6.19.
}
doc {Full Text Search} {fts3.html} {
  A description of the SQLite Full Text Search (FTS3) extension.
................................................................................

heading {Obsolete Documents} {
  These documents either pertain to SQLite version 2 or were written
  during the transition period between versions 2 and 3 (circa 2004).
  This documents are no longer up-to-date.  They are retained for 
  historical reference.
}






doc {Version 2 C/C++ API} {c_interface.html} {
  A description of the C/C++ interface bindings for SQLite through version 
  2.8
}
doc {Version 2 DataTypes } {datatypes.html} {
  A description of how SQLite version 2 handles SQL datatypes.
  Short summary:  Everything is a string.

  This page describes features of SQL that SQLite does not support.
}


heading {SQLite Features and Extensions} {
  Pages describing specific features or extension modules of SQLite.
}

doc {Autoincrement} {autoind.html} {
  A description of the AUTOINCREMENT keyword in SQLite, what it does,
  why it is sometimes useful, and why it should be avoided if not
  strictly necessary.


}
doc {Foreign Key Support} {foreignkeys.html} {
  This document describes the support for foreign key constraints introduced
  in version 3.6.19.
}
doc {Full Text Search} {fts3.html} {
  A description of the SQLite Full Text Search (FTS3) extension.
................................................................................

heading {Obsolete Documents} {
  These documents either pertain to SQLite version 2 or were written
  during the transition period between versions 2 and 3 (circa 2004).
  This documents are no longer up-to-date.  They are retained for 
  historical reference.
}
doc {Asynchronous IO Mode} {asyncvfs.html} {
  This page describes the asynchronous IO extension developed alongside
  SQLite. Using asynchronous IO can cause SQLite to appear more responsive
  by delegating database writes to a background thread.  <i>NB:  This
  extension is deprecated.  [WAL mode] is recommended as a replacement.</i>
}
doc {Version 2 C/C++ API} {c_interface.html} {
  A description of the C/C++ interface bindings for SQLite through version 
  2.8
}
doc {Version 2 DataTypes } {datatypes.html} {
  A description of how SQLite version 2 handles SQL datatypes.
  Short summary:  Everything is a string.

<h4>1.2.2 Page Size</h4>

<p>The two-byte value beginning at offset 16 determines the page size of 
the database.  For SQLite versions 3.7.0.1 and earlier, this value is 
interpreted as a big-endian integer and must be a power of two between
512 and 32768, inclusive.  Beginning with SQLite version 3.7.1, a page
size of 65536 bytes is supported.  The value 65536 will not fit in a
two-byte integer, so to specify a 65536-byte page size, the value is
at offset 16 is 0x00 0x01.
This value can be interpreted as a big-endian
1 and thought of is as a magic number to represent the 65536 page size.
Or one can view the two-byte field as a little endian number and say
that it represents the page size divided by 256.  These two 
interpretations of the page-size field are equivalent.</p>

<h4>1.2.2 Page Size</h4>

<p>The two-byte value beginning at offset 16 determines the page size of 
the database.  For SQLite versions 3.7.0.1 and earlier, this value is 
interpreted as a big-endian integer and must be a power of two between
512 and 32768, inclusive.  Beginning with SQLite version 3.7.1, a page
size of 65536 bytes is supported.  The value 65536 will not fit in a
two-byte integer, so to specify a 65536-byte page size, the value
at offset 16 is 0x00 0x01.
This value can be interpreted as a big-endian
1 and thought of is as a magic number to represent the 65536 page size.
Or one can view the two-byte field as a little endian number and say
that it represents the page size divided by 256.  These two 
interpretations of the page-size field are equivalent.</p>