SQLITE3_DESERIALIZE(3)

SQLITE3_DESERIALIZE(3) | Library Functions Manual | SQLITE3_DESERIALIZE(3)

# NAME

`sqlite3_deserialize` — deserialize a database

# SYNOPSIS

`#include <sqlite3.h>`

int
`sqlite3_deserialize`(sqlite3 *db, const char *zSchema, unsigned char *pData, sqlite3_int64 szDb, sqlite3_int64 szBuf, unsigned mFlags);

# DESCRIPTION

The sqlite3_deserialize(D,S,P,N,M,F) interface causes the database connection D to disconnect from database S and then reopen S as an in-memory database based on the serialization contained in P. The serialized database P is N bytes in size. M is the size of the buffer P, which might be larger than N. If M is larger than N, and the SQLITE_DESERIALIZE_READONLY bit is not set in F, then SQLite is permitted to add content to the in-memory database as long as the total size does not exceed M bytes.

If the SQLITE_DESERIALIZE_FREEONCLOSE bit is set in F, then SQLite will invoke sqlite3_free() on the serialization buffer when the database connection closes. If the SQLITE_DESERIALIZE_RESIZEABLE bit is set, then SQLite will try to increase the buffer size using sqlite3_realloc64() if writes on the database cause it to grow larger than M bytes.

Applications must not modify the buffer P or invalidate it before the database connection D is closed.

The sqlite3_deserialize() interface will fail with SQLITE_BUSY if the database is currently in a read transaction or is involved in a backup operation.

It is not possible to deserialized into the TEMP database. If the S argument to sqlite3_deserialize(D,S,P,N,M,F) is "temp" then the function returns SQLITE_ERROR.

The deserialized database should not be in WAL mode. If the database is in WAL mode, then any attempt to use the database file will result in an SQLITE_CANTOPEN error. The application can set the file format version numbers (bytes 18 and 19) of the input database P to 0x01 prior to invoking sqlite3_deserialize(D,S,P,N,M,F) to force the database file into rollback mode and work around this limitation.

If sqlite3_deserialize(D,S,P,N,M,F) fails for any reason and if the SQLITE_DESERIALIZE_FREEONCLOSE bit is set in argument F, then `sqlite3_free`() is invoked on argument P prior to returning.

This interface is omitted if SQLite is compiled with the SQLITE_OMIT_DESERIALIZE option.

# IMPLEMENTATION NOTES

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

    SQLITE_API int sqlite3_deserialize(
      sqlite3 *db,            /* The database connection */
      const char *zSchema,    /* Which DB to reopen with the deserialization */
      unsigned char *pData,   /* The serialized database content */
      sqlite3_int64 szDb,     /* Number bytes in the deserialization */
      sqlite3_int64 szBuf,    /* Total size of buffer pData[] */
      unsigned mFlags         /* Zero or more SQLITE_DESERIALIZE_* flags */
    );

# SEE ALSO

sqlite3(3), sqlite3_malloc(3), SQLITE_OK(3)

January 24, 2024 | NetBSD 11.0