.Dd January 24, 2024
.Dt SQLITE3_CLOSE 3
.Os
.Sh NAME
.Nm sqlite3_close ,
.Nm sqlite3_close_v2
.Nd closing a database connection
.Sh SYNOPSIS
.In sqlite3.h
.Ft int
.Fo sqlite3_close
.Fa "sqlite3*"
.Fc
.Ft int
.Fo sqlite3_close_v2
.Fa "sqlite3*"
.Fc
.Sh DESCRIPTION
The sqlite3_close() and sqlite3_close_v2() routines are destructors
for the sqlite3 object.
Calls to sqlite3_close() and sqlite3_close_v2() return SQLITE_OK
if the sqlite3 object is successfully destroyed and all associated
resources are deallocated.
.Pp
Ideally, applications should finalize all prepared statements,
close all BLOB handles, and finish all sqlite3_backup
objects associated with the sqlite3 object prior to attempting
to close the object.
If the database connection is associated with unfinalized prepared
statements, BLOB handlers, and/or unfinished sqlite3_backup objects
then sqlite3_close() will leave the database connection open and return
SQLITE_BUSY.
If sqlite3_close_v2() is called with unfinalized prepared statements,
unclosed BLOB handlers, and/or unfinished sqlite3_backups, it returns
SQLITE_OK regardless, but instead of deallocating the database
connection immediately, it marks the database connection as an unusable
"zombie" and makes arrangements to automatically deallocate the database
connection after all prepared statements are finalized, all BLOB handles
are closed, and all backups have finished.
The sqlite3_close_v2() interface is intended for use with host languages
that are garbage collected, and where the order in which destructors
are called is arbitrary.
.Pp
If an sqlite3 object is destroyed while a transaction is open,
the transaction is automatically rolled back.
.Pp
The C parameter to sqlite3_close(C) and sqlite3_close_v2(C)
must be either a NULL pointer or an sqlite3 object pointer obtained
from
.Fn sqlite3_open ,
.Fn sqlite3_open16 ,
or
.Fn sqlite3_open_v2 ,
and not previously closed.
Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer argument
is a harmless no-op.
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 316.
.Bd -literal
SQLITE_API int sqlite3_close(sqlite3*);
SQLITE_API int sqlite3_close_v2(sqlite3*);
.Ed
.Sh SEE ALSO
.Xr sqlite3 3 ,
.Xr sqlite3_backup 3 ,
.Xr sqlite3_backup_init 3 ,
.Xr sqlite3_blob 3 ,
.Xr sqlite3_blob_close 3 ,
.Xr sqlite3_finalize 3 ,
.Xr sqlite3_open 3 ,
.Xr sqlite3_stmt 3 ,
.Xr SQLITE_OK 3