diff options
Diffstat (limited to 'static/netbsd/man3/sqlite3session_attach.3')
| -rw-r--r-- | static/netbsd/man3/sqlite3session_attach.3 | 86 |
1 files changed, 86 insertions, 0 deletions
diff --git a/static/netbsd/man3/sqlite3session_attach.3 b/static/netbsd/man3/sqlite3session_attach.3 new file mode 100644 index 00000000..99b73e7e --- /dev/null +++ b/static/netbsd/man3/sqlite3session_attach.3 @@ -0,0 +1,86 @@ +.Dd January 24, 2024 +.Dt SQLITE3SESSION_ATTACH 3 +.Os +.Sh NAME +.Nm sqlite3session_attach +.Nd attach a table to a session object +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3session_attach +.Fa "sqlite3_session *pSession" +.Fa "const char *zTab" +.Fc +.Sh DESCRIPTION +If argument zTab is not NULL, then it is the name of a table to attach +to the session object passed as the first argument. +All subsequent changes made to the table while the session object is +enabled will be recorded. +See documentation for +.Fn sqlite3session_changeset +for further details. +.Pp +Or, if argument zTab is NULL, then changes are recorded for all tables +in the database. +If additional tables are added to the database (by executing "CREATE +TABLE" statements) after this call is made, changes for the new tables +are also recorded. +.Pp +Changes can only be recorded for tables that have a PRIMARY KEY explicitly +defined as part of their CREATE TABLE statement. +It does not matter if the PRIMARY KEY is an "INTEGER PRIMARY KEY" (rowid +alias) or not. +The PRIMARY KEY may consist of a single column, or may be a composite +key. +.Pp +It is not an error if the named table does not exist in the database. +Nor is it an error if the named table does not have a PRIMARY KEY. +However, no changes will be recorded in either of these scenarios. +.Pp +Changes are not recorded for individual rows that have NULL values +stored in one or more of their PRIMARY KEY columns. +.Pp +SQLITE_OK is returned if the call completes without error. +Or, if an error occurs, an SQLite error code (e.g. SQLITE_NOMEM) is +returned. +.Ss Special sqlite_stat1 Handling +As of SQLite version 3.22.0, the "sqlite_stat1" table is an exception +to some of the rules above. +In SQLite, the schema of sqlite_stat1 is: +.Bd -literal + CREATE TABLE sqlite_stat1(tbl,idx,stat) +.Ed +.Pp +Even though sqlite_stat1 does not have a PRIMARY KEY, changes are recorded +for it as if the PRIMARY KEY is (tbl,idx). +Additionally, changes are recorded for rows for which (idx IS NULL) +is true. +However, for such rows a zero-length blob (SQL value X'') is stored +in the changeset or patchset instead of a NULL value. +This allows such changesets to be manipulated by legacy implementations +of sqlite3changeset_invert(), concat() and similar. +.Pp +The sqlite3changeset_apply() function automatically converts the zero-length +blob back to a NULL value when updating the sqlite_stat1 table. +However, if the application calls sqlite3changeset_new(), sqlite3changeset_old() +or sqlite3changeset_conflict on a changeset iterator directly (including +on a changeset iterator passed to a conflict-handler callback) then +the X'' value is returned. +The application must translate X'' to NULL itself if required. +.Pp +Legacy (older than 3.22.0) versions of the sessions module cannot capture +changes made to the sqlite_stat1 table. +Legacy versions of the sqlite3changeset_apply() function silently ignore +any modifications to the sqlite_stat1 table that are part of a changeset +or patchset. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 11101. +.Bd -literal +SQLITE_API int sqlite3session_attach( + sqlite3_session *pSession, /* Session object */ + const char *zTab /* Table name */ +); +.Ed +.Sh SEE ALSO +.Xr sqlite3session_changeset 3 |