database/sqlite
1
0
Fork 0
mirror of https://github.com/sqlite/sqlite.git synced 2025-07-24 22:22:08 +03:00
Code Activity

Further improvements to documentation in sqlite3session.h.

Browse Source 
FossilOrigin-Name: 07019bb9e8d8f2445d1e0342f74ab520e9804cb5
This commit is contained in:
dan
2011-03-18 16:13:53 +00:00
parent ea022cffdd
commit 2635a3be20
6 changed files with 159 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

163
ext/session/sqlite3session.h
View File

@ -375,7 +375,24 @@ int sqlite3changeset_conflict(
int sqlite3changeset_finalize(sqlite3_changeset_iter *pIter);
/*
** Invert a changeset object.
** This function is used to "invert" a changeset object. Applying an inverted
** changeset to a database reverses the effects of applying the uninverted
** changeset. Specifically:
**
** <ul>
** <li> Each DELETE change is changed to an INSERT, and
** <li> Each INSERT change is changed to a DELETE, and
** <li> For each UPDATE change, the old.* and new.* values are exchanged.
** </ul>
**
** If successful, a pointer to a buffer containing the inverted changeset
** is stored in *ppOut, the size of the same buffer is stored in *pnOut, and
** SQLITE_OK is returned. If an error occurs, both *pnOut and *ppOut are
** zeroed and an SQLite error code returned.
**
** It is the responsibility of the caller to eventually call sqlite3_free()
** on the *ppOut pointer to free the buffer allocation following a successful
** call to this function.
*/
int sqlite3changeset_invert(
int nIn, void *pIn, /* Input changeset */
@ -383,12 +400,124 @@ int sqlite3changeset_invert(
);
/*
** Apply a changeset to a database.
** Apply a changeset to a database. This function attempts to update the
** "main" database attached to handle db with the changes found in the
** changeset passed via the second and third arguments.
**
** For each change in the changeset, this function tests that the target
** database contains a compatible table. A table is considered compatible
** if all of the following are true:
**
** <ul>
** <li> The table has the same name as the name recorded in the
** changeset, and
** <li> The table has the same number of columns as recorded in the
** changeset, and
** <li> The table has primary key columns in the same position as
** recorded in the changeset.
** </ul>
**
** If there is no compatible table, it is not an error, but the change is
** not applied. A warning message is issued via the sqlite3_log() mechanism
** with the error code SQLITE_SCHEMA. At most one such warning is issued for
** each table in the changeset.
**
** Otherwise, if there is a compatible table, an attempt is made to modify
** the table contents according to the UPDATE, INSERT or DELETE change.
** If a change cannot be applied cleanly, the conflict handler function
** passed as the fourth argument to sqlite3changeset_apply() may be invoked.
** A description of exactly when the conflict handler is invoked for each
** type of change is below.
**
** Each time the conflict handler function is invoked, it must return one
** of [SQLITE_CHANGESET_OMIT], [SQLITE_CHANGESET_ABORT] or
** [SQLITE_CHANGESET_REPLACE]. SQLITE_CHANGESET_REPLACE may only be returned
** if the second argument passed to the conflict handler is either
** SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If the conflict-handler
** returns an illegal value, any changes already made are rolled back and
** the call to sqlite3changeset_apply() returns SQLITE_MISUSE. Different
** actions are taken by sqlite3changeset_apply() depending on the value
** returned by each invocation of the conflict-handler function. Refer to
** the documentation for the three
** [SQLITE_CHANGESET_OMIT|available return values] for details.
**
** <dl>
** <dt>DELETE Changes<dd>
** For each DELETE change, this function checks if the target database
** contains a row with the same primary key value (or values) as the
** original row values stored in the changeset. If it does, and the values
** stored in all non-primary key columns also match the values stored in
** the changeset the row is deleted from the target database.
**
** If a row with matching primary key values is found, but one or more of
** the non-primary key fields contains a value different from the original
** row value stored in the changeset, the conflict-handler function is
** invoked with [SQLITE_CHANGESET_DATA] as the second argument.
**
** If no row with matching primary key values is found in the database,
** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
** passed as the second argument.
**
** If the DELETE operation is attempted, but SQLite returns SQLITE_CONSTRAINT
** (which can only happen if a foreign key constraint is violated), the
** conflict-handler function is invoked with [SQLITE_CHANGESET_CONSTRAINT]
** passed as the second argument. This includes the case where the DELETE
** operation is attempted because an earlier call to the conflict handler
** function returned [SQLITE_CHANGESET_REPLACE].
**
** <dt>INSERT Changes<dd>
** For each INSERT change, an attempt is made to insert the new row into
** the database.
**
** If the attempt to insert the row fails because the database already
** contains a row with the same primary key values, the conflict handler
** function is invoked with the second argument set to
** [SQLITE_CHANGESET_CONFLICT].
**
** If the attempt to insert the row fails because of some other constraint
** violation (e.g. NOT NULL or UNIQUE), the conflict handler function is
** invoked with the second argument set to [SQLITE_CHANGESET_CONSTRAINT].
** This includes the case where the INSERT operation is re-attempted because
** an earlier call to the conflict handler function returned
** [SQLITE_CHANGESET_REPLACE].
**
** <dt>UPDATE Changes<dd>
** For each DELETE change, this function checks if the target database
** contains a row with the same primary key value (or values) as the
** original row values stored in the changeset. If it does, and the values
** stored in all non-primary key columns also match the values stored in
** the changeset the row is updated within the target database.
**
** If a row with matching primary key values is found, but one or more of
** the non-primary key fields contains a value different from an original
** row value stored in the changeset, the conflict-handler function is
** invoked with [SQLITE_CHANGESET_DATA] as the second argument. Since
** UPDATE changes only contain values for non-primary key fields that are
** to be modified, only those fields need to match the original values to
** avoid the SQLITE_CHANGESET_DATA conflict-handler callback.
**
** If no row with matching primary key values is found in the database,
** the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
** passed as the second argument.
**
** If the UPDATE operation is attempted, but SQLite returns
** SQLITE_CONSTRAINT, the conflict-handler function is invoked with
** [SQLITE_CHANGESET_CONSTRAINT] passed as the second argument.
** This includes the case where the UPDATE operation is attempted after
** an earlier call to the conflict handler function returned
** [SQLITE_CHANGESET_REPLACE].
** </dl>
**
** It is safe to execute SQL statements, including those that write to the
** table that the callback related to, from within the xConflict callback.
** This can be used to further customize the applications conflict
** resolution strategy.
**
** All changes made by this function are enclosed in a savepoint transaction.
** If any other error (aside from a constraint failure when attempting to
** write to the target database) occurs, then the savepoint transaction is
** rolled back, restoring the target database to its original state, and an
** SQLite error code returned.
*/
int sqlite3changeset_apply(
sqlite3 *db, /* Apply change to "main" db of this handle */
@ -403,9 +532,10 @@ int sqlite3changeset_apply(
);
/*
** Values passed as the second argument to a conflict-handler.
** Values that may be passed as the second argument to a conflict-handler.
**
** SQLITE_CHANGESET_DATA:
** <dl>
** <dt>SQLITE_CHANGESET_DATA<dd>
** The conflict handler is invoked with CHANGESET_DATA as the second argument
** when processing a DELETE or UPDATE change if a row with the required
** PRIMARY KEY fields is present in the database, but one or more other
@ -415,7 +545,7 @@ int sqlite3changeset_apply(
** The conflicting row, in this case, is the database row with the matching
** primary key.
**
** SQLITE_CHANGESET_NOTFOUND:
** <dt>SQLITE_CHANGESET_NOTFOUND<dd>
** The conflict handler is invoked with CHANGESET_NOTFOUND as the second
** argument when processing a DELETE or UPDATE change if a row with the
** required PRIMARY KEY fields is not present in the database.
@ -423,21 +553,22 @@ int sqlite3changeset_apply(
** There is no conflicting row in this case. The results of invoking the
** sqlite3changeset_conflict() API are undefined.
**
** SQLITE_CHANGESET_CONFLICT:
** <dt>SQLITE_CHANGESET_CONFLICT<dd>
** CHANGESET_CONFLICT is passed as the second argument to the conflict
** handler while processing an UPDATE or an INSERT if the operation would
** result in duplicate primary key values.
** handler while processing an INSERT change if the operation would result
** in duplicate primary key values.
**
** The conflicting row in this case is the database row with the matching
** primary key.
**
** SQLITE_CHANGESET_CONSTRAINT:
** <dt>SQLITE_CHANGESET_CONSTRAINT<dd>
** If any other constraint violation occurs while applying a change (i.e.
** a FOREIGN KEY, UNIQUE, CHECK or NOT NULL constraint), the conflict
** handler is invoked with CHANGESET_CONSTRAINT as the second argument.
**
** There is no conflicting row in this case. The results of invoking the
** sqlite3changeset_conflict() API are undefined.
** </dl>
*/
#define SQLITE_CHANGESET_DATA 1
#define SQLITE_CHANGESET_NOTFOUND 2
@ -447,12 +578,13 @@ int sqlite3changeset_apply(
/*
** Valid return values from a conflict-handler.
**
** SQLITE_CHANGESET_OMIT:
** <dl>
** <dt>SQLITE_CHANGESET_OMIT<dd>
** If a conflict handler returns this value no special action is taken. The
** change is not applied. The session module continues to the next change
** in the changeset.
** change that caused the conflict is not applied. The session module
** continues to the next change in the changeset.
**
** SQLITE_CHANGESET_REPLACE:
** <dt>SQLITE_CHANGESET_REPLACE<dd>
** This value may only be returned if the second argument to the conflict
** handler was SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If this
** is not the case, any changes applied so far are rolled back and the
@ -467,9 +599,10 @@ int sqlite3changeset_apply(
** second attempt to apply the change is made. If this second attempt fails,
** the original row is restored to the database before continuing.
**
** SQLITE_CHANGESET_ABORT:
** <dt>SQLITE_CHANGESET_ABORT<dd>
** If this value is returned, any changes applied so far are rolled back
** and the call to sqlite3changeset_apply() returns SQLITE_MISUSE.
** and the call to sqlite3changeset_apply() returns SQLITE_ABORT.
** </dl>
*/
#define SQLITE_CHANGESET_OMIT 0
#define SQLITE_CHANGESET_REPLACE 1

0
install-sh Executable file → Normal file
View File

30
manifest
View File

@ -1,8 +1,5 @@
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
C Fix\sa\smemory\sallocation\sissues\sin\sthe\spreupdate\shook\sso\sthat\sthe\shook.test\nscript\sruns\sclean\sin\svalgrind.
D 2011-03-18T15:13:31.545
C Further\simprovements\sto\sdocumentation\sin\ssqlite3session.h.
D 2011-03-18T16:13:53
F Makefile.arm-wince-mingw32ce-gcc d6df77f1f48d690bd73162294bbba7f59507c72f
F Makefile.in 27701a1653595a1f2187dc61c8117e00a6c1d50f
F Makefile.linux-gcc 91d710bdc4998cb015f39edf3cb314ec4f4d7e23
@ -103,9 +100,9 @@ F ext/rtree/sqlite3rtree.h 1af0899c63a688e272d69d8e746f24e76f10a3f0
F ext/rtree/tkt3363.test 142ab96eded44a3615ec79fba98c7bde7d0f96de
F ext/rtree/viewrtree.tcl eea6224b3553599ae665b239bd827e182b466024
F ext/session/sqlite3session.c 4183792547af5b5d3ec1c8a3f858beb172682503
F ext/session/sqlite3session.h 3e342facbb95589dfba34545df383df68cc44ebf
F ext/session/sqlite3session.h 9551c002efd5fde07c52994c6b592308e0df2d6a
F ext/session/test_session.c 2559ef68e421c7fb83e2c19ef08a17343b70d535
F install-sh 9d4de14ab9fb0facae2f48780b874848cbf2f895 x
F install-sh 9d4de14ab9fb0facae2f48780b874848cbf2f895
F ltmain.sh 3ff0879076df340d2e23ae905484d8c15d5fdea8
F main.mk ae0868e05c76eaa8a0ae3d6927a949b1c8e810d7
F mkdll.sh 7d09b23c05d56532e9d44a50868eb4b12ff4f74a
@ -608,7 +605,7 @@ F test/permutations.test 5b2a4cb756ffb2407cb4743163668d1d769febb6
F test/pragma.test fdfc09067ea104a0c247a1a79d8093b56656f850
F test/pragma2.test 5364893491b9231dd170e3459bfc2e2342658b47
F test/printf.test 05970cde31b1a9f54bd75af60597be75a5c54fea
F test/progress.test 5b075c3c790c7b2a61419bc199db87aaf48b8301
F test/progress.test 5b075c3c790c7b2a61419bc199db87aaf48b8301 x
F test/ptrchng.test ef1aa72d6cf35a2bbd0869a649b744e9d84977fc
F test/quick.test 1681febc928d686362d50057c642f77a02c62e57
F test/quota.test ddafe133653093eb9a99ccd6264884ae43f9c9b8
@ -896,7 +893,7 @@ F tool/genfkey.test 4196a8928b78f51d54ef58e99e99401ab2f0a7e5
F tool/lemon.c dfd81a51b6e27e469ba21d01a75ddf092d429027
F tool/lempar.c 01ca97f87610d1dac6d8cd96ab109ab1130e76dc
F tool/mkkeywordhash.c d2e6b4a5965e23afb80fbe74bb54648cd371f309
F tool/mkopts.tcl 66ac10d240cc6e86abd37dc908d50382f84ff46e
F tool/mkopts.tcl 66ac10d240cc6e86abd37dc908d50382f84ff46e x
F tool/mkspeedsql.tcl a1a334d288f7adfe6e996f2e712becf076745c97
F tool/mksqlite3c.tcl cf44512a48112b1ba09590548660a5a6877afdb3
F tool/mksqlite3h.tcl d76c226a5e8e1f3b5f6593bcabe5e98b3b1ec9ff
@ -921,14 +918,7 @@ F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff
F tool/speedtest8.c 2902c46588c40b55661e471d7a86e4dd71a18224
F tool/speedtest8inst1.c 293327bc76823f473684d589a8160bde1f52c14e
F tool/vdbe-compress.tcl d70ea6d8a19e3571d7ab8c9b75cba86d1173ff0f
P e73e9082f3b14088752717193a10dd7657deb8af
R 150a0d4d8ebf26c7dc0eae89afa852c9
U drh
Z f580a5a873ab613c2a5bfc6ce81e4e03
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
iD8DBQFNg3aeoxKgR168RlERAnluAJ9mJTScCzmLzWj8hzyPNreCvcU53ACcDZ+U
AOCmfmp9NGd52IWhvYcR1co=
=4fKC
-----END PGP SIGNATURE-----
P bd94f4c8b1c4590c437030f0122015f1a37e2582
R fb83d41281a4d5ba8505f15c6f6b6372
U dan
Z ff00d37e3af9047c8539a141cf64a629

2
manifest.uuid
View File

@ -1 +1 @@
bd94f4c8b1c4590c437030f0122015f1a37e2582
07019bb9e8d8f2445d1e0342f74ab520e9804cb5

0
test/progress.test Normal file → Executable file
View File

0
tool/mkopts.tcl Normal file → Executable file
View File