# Blob Input/Output

A blob is a SQLite datatype representing a sequence of bytes. It can be zero or more bytes in size. Blobs cannot be resized, but you can read and overwrite parts of them.

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. There are benchmarks.

## zeroblob class

class apsw.zeroblob(size: int)

  If you want to insert a blob into a row, you need to supply the entire blob in one go. Using this class or function allocates the space in the database filling it with zeroes.

  You can then overwrite parts in smaller chunks, without having to do it all at once. The example shows how to use it.

  Parameters:

    size – Number of zeroed bytes to create

zeroblob.length() → int

  Size of zero blob in bytes.

## Blob class

class apsw.Blob

  This object is created by `Connection.blob_open()` and provides access to a blob in the database. It behaves like a Python `file` in binary mode. 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.

Blob.__aenter__() → Self

  Async only

  Async context manager enter

Blob.__aexit__(etype: type[BaseException] | None, evalue: BaseException | None, etraceback: TracebackType | None) → None

  Async only

  Async context manager exit

Blob.__enter__() → Blob

  Sync only

  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.blob_open() as blob:
          blob.write("...")
          res=blob.read(1024)

Blob.__exit__(etype: type[BaseException] | None, evalue: BaseException | None, etraceback: TracebackType | None) → bool

  Sync only

  Implements context manager in conjunction with `__enter__()`. Any exception that happened in the with block is raised after closing the blob.

Blob.aclose(force: bool = False) → None

  Close

  Async version of `close()`

Blob.close(force: bool = False) → None

  Close

  Closes the blob. Note that even if an error occurs the blob is still closed.

  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.

  Parameters:

    force – Ignores any errors during close.

  Calls: sqlite3_blob_close

Blob.closed: bool

  Value

  Indicates if the blob has been closed.

Blob.fileno() → int

  Value

  Always raises `OSError` because there is no underlying file descriptor.

Blob.flush() → None

  Sync / Async

  Does nothing. There is no intermediate buffer, and SQLite’s overall transaction/savepoint handling deals with database commits.

Blob.isatty() → False

  Value

  Blobs are never interactive.

Blob.length() → int

  Value

  Returns the size of the blob in bytes.

  Calls: sqlite3_blob_bytes

Blob.read(length: int = -1) → bytes

  Sync / Async

  Reads amount of data requested, or till end of file, whichever is earlier. Attempting to read beyond the end of the blob returns an empty bytes in the same manner as end of file on normal file objects. Negative numbers read all remaining data.

  Calls: sqlite3_blob_read

Blob.read_into(buffer: bytearray | array[Any] | memoryview, offset: int = 0, length: int = -1) → None

  Sync / Async

  Reads from the blob into a buffer you have supplied. This method is useful if you already have a buffer like object that data is being assembled in, and avoids allocating results in `Blob.read()` and then copying into buffer.

  Parameters:

    - buffer – A writable buffer like object. There is a `bytearray` type that is very useful. `Arrays` also work.

    - offset – The position to start writing into the buffer defaulting to the beginning.

    - length – How much of the blob to read. The default is the remaining space left in the buffer. Note that if there is more space available than blob left then you will get a ValueError exception.

  Calls: sqlite3_blob_read

Blob.readable() → True

  Value

  You can always read from a blob

Blob.readall() → bytes

  Sync / Async

  Read all data until the end of the blob

Blob.readline(size: int = -1) → bytes

  Sync / Async

  Always raises `io.UnsupportedOperation`. You can wrap with `io.BufferedReader`.

Blob.readlines(hint: int = -1) → list[bytes]

  Sync / Async

  Always raises `io.UnsupportedOperation`. You can wrap with `io.BufferedReader`.

Blob.reopen(rowid: int) → None

  Sync / Async

  Change this blob object to point to a different row. It can be faster than closing an existing blob an opening a new one.

  Calls: sqlite3_blob_reopen

Blob.seek(offset: int, whence: int = 0) → None

  Value

  Changes current position to offset biased by whence.

  Parameters:

    - offset – New position to seek to. Can be positive or negative number.

    - whence – Use 0 if offset is relative to the beginning of the blob, 1 if offset is relative to the current position, and 2 if offset is relative to the end of the blob.

  Raises:

    ValueError – If the resulting offset is before the beginning (less than zero) or beyond the end of the blob.

Blob.seekable() → True

  Value

  You can always seek in a blob

Blob.tell() → int

  Value

  Returns the current offset.

Blob.truncate(size=None) → None

  Sync / Async

  Always raises `io.UnsupportedOperation`. You cannot change the size of a blob.

Blob.writable() → bool

  Value

  Returns True if the blob was open for writing, else False.

Blob.write(data: Buffer) → int

  Sync / Async

  Writes the data to the blob.

  Returns the number of bytes written, which will be all of them.

  Parameters:

    data – Buffer to write

  Raises:

    - TypeError – Wrong data type

    - 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

Blob.writelines(lines) → None

  Sync / Async

  Always raises `io.UnsupportedOperation`. You can wrap with `io.BufferedWriter`.