.Dd January 24, 2024
.Dt SQLITE3_DESERIALIZE 3
.Os
.Sh NAME
.Nm sqlite3_deserialize
.Nd deserialize a database
.Sh SYNOPSIS
.In sqlite3.h
.Ft int
.Fo sqlite3_deserialize
.Fa "sqlite3 *db"
.Fa "const char *zSchema"
.Fa "unsigned char *pData"
.Fa "sqlite3_int64 szDb"
.Fa "sqlite3_int64 szBuf"
.Fa "unsigned mFlags"
.Fc
.Sh 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.
.Pp
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.
.Pp
Applications must not modify the buffer P or invalidate it before the
database connection D is closed.
.Pp
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.
.Pp
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.
.Pp
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.
.Pp
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
.Fn sqlite3_free
is invoked on argument P prior to returning.
.Pp
This interface is omitted if SQLite is compiled with the SQLITE_OMIT_DESERIALIZE
option.
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 10702.
.Bd -literal
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 */
);
.Ed
.Sh SEE ALSO
.Xr sqlite3 3 ,
.Xr sqlite3_malloc 3 ,
.Xr SQLITE_OK 3