sql.sqlite.blob

import sql.sqlite.blob

sql lifts part of this module out to its own top level; each name below is shown with the path that reaches it. Anything still spelled sql.sqlite.blob.* needs import sql.sqlite.blob.

Reading and writing a single blob-valued cell a piece at a time.

A large value stored in a database is usually read with a select, which means the whole of it arrives at once. For a hundred megabyte file that is a hundred megabytes of memory to move a copy from one place to another. A blob handle opens one cell and reads or writes windows of it, so the memory needed is the size of the window.

var blob = db.native().blob('main', 'files', 'content', id, false)

var at = 0
while at < blob.length() {
  var chunk = blob.read(at, 65536.min(blob.length() - at))
  out.write(chunk)
  at += chunk.length()
}

blob.close()

The cell has to exist and already be the right size: SQLite cannot grow a blob through this interface. The usual approach is to insert zeroblob(n) for the final size and then write into it.

Classes

Blob

class sql.sqlite.Blob

An open blob handle.

• printable — has a @to_string(), so echo and print() show something useful

Constructor

sql.sqlite.Blob(handle, writable)

Parameters

• ptr — handle The native blob handle.
• writable (bool) — Whether it was opened for writing.

Blob.length()

sql.sqlite.Blob.length() -> number

How many bytes the blob holds. Fixed for the handle’s lifetime.

Returns number

Blob.is_writable()

sql.sqlite.Blob.is_writable() -> bool

Whether this handle may write.

Returns bool

Blob.read()

sql.sqlite.Blob.read(offset: number, length: number) -> bytes

Reads length bytes starting at offset.

Parameters

• offset (number)
• length (number)

Returns bytes

Raises SqlError if the window runs past the end of the blob.

Blob.read_all()

sql.sqlite.Blob.read_all() -> bytes

Reads the whole blob. Defeats the point of a blob handle, and is here for the case where one turns out to be small.

Returns bytes

Blob.write()

sql.sqlite.Blob.write(data, offset: number)

Writes data starting at offset.

Parameters

• data (bytes)
• offset (number)

Raises SqlError if the handle is read-only or the write would run past the end.

Blob.reopen()

sql.sqlite.Blob.reopen(rowid: number)

Points this handle at the same column of a different row.

Cheaper than closing and opening again, which is why it exists.

Parameters

• rowid (number)

Blob.close()

sql.sqlite.Blob.close()

Releases the handle. Safe to call more than once.

Blob.is_closed()

sql.sqlite.Blob.is_closed() -> bool

Whether this handle has been closed.

Returns bool

Blob.to_string()

sql.sqlite.Blob.to_string()

2026, Richard Ore and Zuri contributors