Alpha

These pages are built from turborel-py’s main, turborel 0.0.0. Anything may change from one build to the next: SQL, API, protocol and files alike.

Large Objects

NAME

turborel.client.Connection: large objects read by their locators, and written a piece at a time.

SYNOPSIS

conn.read_lob(lob, start, count, *, characters=False) -> bytes
conn.lob_reader(lob) -> LobReader
conn.create_lob(*, binary) -> LobWriter
conn.free_lob(lob) -> Complete
conn.hold_lob(lob) -> Complete

LobWriter.write(data) -> int
LobWriter.flush()
LobWriter.finish() -> LobLocator

Lob = LobLocator | str | bytes
CHUNK_OCTETS = 262144
LOB_INLINE_OCTETS = 65536

DESCRIPTION

Values. A CLOB or BLOB of at most the server's SERVER.LOB_INLINE_BYTES comes whole in its row, a str or bytes; a longer one as a LobLocator: binary, locator, octets and, of a CLOB, characters. A parameter is a large object sent whole when wrapped in turborel.LargeObject, or a LobLocator the client made or was given.

Reading. read_lob reads at most count octets of lob from octet start, from 0, or with characters a CLOB's whole characters, as UTF-8; at most CHUNK_OCTETS, 256 KiB, a read, fewer only at its end or a chunk's. lob_reader gives lob's octets as a binary stream (io.RawIOBase), a chunk read at a time. A value held whole is read from itself, with no request.

Lasting. A locator is valid until its transaction ends, and a result that sent one keeps its transaction active, under autocommit too. free_lob ends it, and the value it named. hold_lob keeps it valid past its transaction's commit, until it is freed or a rollback ends it.

Writing. create_lob makes an empty BLOB if binary, else an empty CLOB, and gives a LobWriter, a binary stream. write adds octets, a CLOB's UTF-8, a character free to split between writes, sent in Appends of CHUNK_OCTETS; flush sends what is waiting; finish sends the rest and gives the LobLocator, its lengths counted, to pass as a parameter within its transaction. The server checks a CLOB's octets as UTF-8 as each Append comes: an octet that is not refuses its Append, SQLSTATE 22021, and every Append after it and the CLOB's use; a CLOB that ends within a character is refused, 22021, where it is used. LOB_INLINE_OCTETS is the longest field an import sends whole for a large object column.

ERRORS

Condition SQLCODE, SQLSTATE
A locator no longer valid the server's, 0F001
free_lob or hold_lob of a value held whole -301, 22000
A CLOB written that is not UTF-8, by the Append that sends it and each after, or one ending within a character, where it is used the server's, 22021
A CLOB written longer than its column the server's, 22001
A reply out of turn -919, 08006, the connection lost
A server that sent less of a value than its length, to a LobReader -919, 08006; the connection goes on

EXAMPLES

from turborel import LargeObject
from turborel.client import Trust, connect

conn = connect(("127.0.0.1", 7422), "ANN", Trust())
conn.query("CREATE TABLE BLOBS (DATA BLOB(1M))")
conn.execute(
    conn.prepare("INSERT INTO BLOBS VALUES (?)"),
    (LargeObject(bytes(range(256)) * 300),),
)
conn.query("COMMIT")
[(data,)] = conn.query("SELECT DATA FROM BLOBS").rows
print(data)
print(conn.read_lob(data, 254, 4))
conn.query("ROLLBACK")
LobLocator(binary=True, locator=1, octets=76800, characters=76800)
b'\xfe\xff\x00\x01'

SEE ALSO

Large Objects, the chapter; Statements and Cursors.