A blob is a SQLite datatype representing a sequence of bytes. It can be zero or more bytes in size.
SQLite blobs have an absolute maximum size of 2GB and a default maximum size of 1GB.
An alternate approach to using blobs is to store the data in files and store the filename in the database. Doing so loses the ACID properties of SQLite.
If you want to insert a blob into a row, you previously needed to supply the entire blob in one go. To read just one byte also required retrieving the blob in its entireity. For example to insert a 100MB file you would have done:
largedata=open("largefile", "rb").read()
cur.execute("insert into foo values(?)", (buffer(largedata),))
SQLite 3.5 allowed for incremental Blob I/O so you can read and write blobs in small amounts. You cannot change the size of a blob so you need to reserve space which you do through zeroblob which creates a blob of the specified size but full of zero bytes. For example you would reserve space for your 100MB one of these two ways:
cur.execute("insert into foo values(zeroblob(100000000))")
cur.execute("insert into foo values(?),
(apsw.zeroblob(100000000),))
This class is used for the second way. Once a blob exists in the database, you then use the blob class to read and write its contents.
This object is created by Connection.blobopen() and provides access to a blob in the database. It behaves like a Python file. At the C level it wraps a sqlite3_blob.
Note
You cannot change the size of a blob using this object. You should create it with the correct size in advance either by using zeroblob or the zeroblob() function.
See the example.
You can use a blob as a context manager as defined in PEP 0343. When you use with statement, the blob is always closed on exit from the block, even if an exception occurred in the block.
For example:
with connection.blobopen() as blob:
blob.write("...")
res=blob.read(1024)
Closes the blob. Note that even if an error occurs the blob is still closed (see SQLite ticket #2815).
Note
In some cases errors that technically occurred in the read() and write() routines may not be reported until close is called. Similarly errors that occurred in those methods (eg calling write() on a read-only blob) may also be re-reported in close(). (This behaviour is what the underlying SQLite APIs do - it is not APSW doing it.)
It is okay to call close() multiple times.
Parameter: | force – Ignores any errors during close. |
---|
Calls: sqlite3_blob_close
Returns the size of the blob in bytes.
Calls: sqlite3_blob_bytes
Reads amount of data requested, or till end of file, whichever is earlier. Attempting to read beyond the end of the blob returns the empty string/bytes, in the same manner as end of file on normal file objects.
Return type: | (Python 2) string (Python 3) bytes |
---|
Calls: sqlite3_blob_read
Changes current position to offset biased by whence.
Parameters: |
|
---|---|
Raises ValueError: | |
If the resulting offset is before the begining (less than zero) or beyond the end of the blob. |
Writes the data to the blob.
Parameter: | data – (Python 2) buffer or string. (Python 3) buffer or bytes. |
---|---|
Raises TypeError: | |
Wrong data type | |
Raises ValueError: | |
If the data would go beyond the end of the blob. You cannot increase the size of a blob by writing beyond the end. You need to use zeroblob to set the desired size first when inserting the blob. |
Calls: sqlite3_blob_write