SQLITE3CHANGESET_START(3) | Library Functions Manual | SQLITE3CHANGESET_START(3)

# NAME

`sqlite3changeset_start`, `sqlite3changeset_start_v2` — create an iterator to traverse a changeset

# SYNOPSIS

`#include <sqlite3.h>`

int
`sqlite3changeset_start`(sqlite3_changeset_iter **pp, int nChangeset, void *pChangeset);

int
`sqlite3changeset_start_v2`(sqlite3_changeset_iter **pp, int nChangeset, void *pChangeset, int flags);

# DESCRIPTION

Create an iterator used to iterate through the contents of a changeset. If successful, *pp is set to point to the iterator handle and SQLITE_OK is returned. Otherwise, if an error occurs, *pp is set to zero and an SQLite error code is returned.

The following functions can be used to advance and query a changeset iterator created by this function:

- `sqlite3changeset_next`()
- `sqlite3changeset_op`()
- `sqlite3changeset_new`()
- `sqlite3changeset_old`()

It is the responsibility of the caller to eventually destroy the iterator by passing it to `sqlite3changeset_finalize`(). The buffer containing the changeset (pChangeset) must remain valid until after the iterator is destroyed.

Assuming the changeset blob was created by one of the `sqlite3session_changeset`(), `sqlite3changeset_concat`() or `sqlite3changeset_invert`() functions, all changes within the changeset that apply to a single table are grouped together. This means that when an application iterates through a changeset using an iterator created by this function, all changes that relate to a single table are visited consecutively. There is no chance that the iterator will visit a change the applies to table X, then one for table Y, and then later on visit another change for table X.

The behavior of sqlite3changeset_start_v2() and its streaming equivalent may be modified by passing a combination of supported flags as the 4th parameter.

Note that the sqlite3changeset_start_v2() API is still experimental and therefore subject to change.

# IMPLEMENTATION NOTES

These declarations were extracted from the interface documentation at line 11435.

    SQLITE_API int sqlite3changeset_start(
      sqlite3_changeset_iter **pp,    /* OUT: New changeset iterator handle */
      int nChangeset,                 /* Size of changeset blob in bytes */
      void *pChangeset                /* Pointer to blob containing changeset */
    );
    SQLITE_API int sqlite3changeset_start_v2(
      sqlite3_changeset_iter **pp,    /* OUT: New changeset iterator handle */
      int nChangeset,                 /* Size of changeset blob in bytes */
      void *pChangeset,               /* Pointer to blob containing changeset */
      int flags                       /* SESSION_CHANGESETSTART_* flags */
    );

# SEE ALSO

sqlite3changeset_concat(3), sqlite3changeset_finalize(3), sqlite3changeset_invert(3), sqlite3changeset_new(3), sqlite3changeset_next(3), sqlite3changeset_old(3), sqlite3changeset_op(3), sqlite3session_changeset(3), SQLITE_CHANGESETSTART_INVERT(3)

January 24, 2024 | NetBSD 11.0