Large object functions ====================== The ``bdr.lo_*`` functions are the replicated equivalents of the `PostgreSQL large object server-side functions `_ . Each function operates on ``bdr.pgd_largeobject`` instead of ``pg_catalog.largeobject`` . Behavior and parameter semantics are identical to the PostgreSQL equivalents unless noted otherwise. For an overview of replicated large objects, see :ref:`Replicated large objects ` . Large object interface ---------------------- bdr.lo_creat ^^^^^^^^^^^^ Creates a new large object. The ``mode`` argument is ignored but accepted for compatibility. Returns the OID of the new large object. Synopsis ^^^^^^^^ .. code:: sql bdr.lo_creat(mode int4) returns oid Parameters ^^^^^^^^^^ - ``mode`` — Ignored. Accepted for compatibility with the PostgreSQL ``lo_creat`` interface. bdr.lo_create ^^^^^^^^^^^^^ Creates a new large object with the given OID. Returns the OID of the large object. .. _synopsis-1: Synopsis ^^^^^^^^ .. code:: sql bdr.lo_create(lobjId oid) returns oid .. _parameters-1: Parameters ^^^^^^^^^^ - ``lobjId`` — OID to assign to the new large object. Pass ``0`` to have an OID assigned automatically. bdr.lo_open ^^^^^^^^^^^ Opens an existing large object for reading or writing. Returns a large object file descriptor for use in subsequent operations. .. _synopsis-2: Synopsis ^^^^^^^^ .. code:: sql bdr.lo_open(lobjId oid, mode int4) returns int4 .. _parameters-2: Parameters ^^^^^^^^^^ - ``lobjId`` — OID of the large object to open. - ``mode`` — Access mode. Use ``INV_READ`` (0x40000) for read access, ``INV_WRITE`` (0x20000) for write access, or both combined. bdr.lo_close ^^^^^^^^^^^^ Closes a large object file descriptor. .. _synopsis-3: Synopsis ^^^^^^^^ .. code:: sql bdr.lo_close(fd int4) returns int4 .. _parameters-3: Parameters ^^^^^^^^^^ - ``fd`` — File descriptor returned by ``bdr.lo_open`` . bdr.loread ^^^^^^^^^^ Reads up to ``len`` bytes from the large object at the current seek position. .. _synopsis-4: Synopsis ^^^^^^^^ .. code:: sql bdr.loread(fd int4, len int4) returns bytea .. _parameters-4: Parameters ^^^^^^^^^^ - ``fd`` — File descriptor returned by ``bdr.lo_open`` . - ``len`` — Maximum number of bytes to read. bdr.lowrite ^^^^^^^^^^^ Writes data to the large object at the current seek position. Returns the number of bytes written. .. _synopsis-5: Synopsis ^^^^^^^^ .. code:: sql bdr.lowrite(fd int4, buf bytea) returns int4 .. _parameters-5: Parameters ^^^^^^^^^^ - ``fd`` — File descriptor returned by ``bdr.lo_open`` . - ``buf`` — Data to write. bdr.lo_lseek ^^^^^^^^^^^^ Moves the current seek position for the large object descriptor. .. _synopsis-6: Synopsis ^^^^^^^^ .. code:: sql bdr.lo_lseek(fd int4, offset int4, whence int4) returns int4 .. _parameters-6: Parameters ^^^^^^^^^^ - ``fd`` — File descriptor returned by ``bdr.lo_open`` . - ``offset`` — Byte offset to seek to. - ``whence`` — Seek mode: ``SEEK_SET`` (0) from the start, ``SEEK_CUR`` (1) from the current position, or ``SEEK_END`` (2) from the end. bdr.lo_lseek64 ^^^^^^^^^^^^^^ 64-bit version of ``bdr.lo_lseek`` . .. _synopsis-7: Synopsis ^^^^^^^^ .. code:: sql bdr.lo_lseek64(fd int4, offset int64, whence int4) returns int64 .. _parameters-7: Parameters ^^^^^^^^^^ - ``fd`` — File descriptor returned by ``bdr.lo_open`` . - ``offset`` — Byte offset to seek to. - ``whence`` — Seek mode: ``SEEK_SET`` (0), ``SEEK_CUR`` (1), or ``SEEK_END`` (2). bdr.lo_tell ^^^^^^^^^^^ Returns the current seek position of the large object descriptor. .. _synopsis-8: Synopsis ^^^^^^^^ .. code:: sql bdr.lo_tell(fd int4) returns int4 .. _parameters-8: Parameters ^^^^^^^^^^ - ``fd`` — File descriptor returned by ``bdr.lo_open`` . bdr.lo_tell64 ^^^^^^^^^^^^^ 64-bit version of ``bdr.lo_tell`` . .. _synopsis-9: Synopsis ^^^^^^^^ .. code:: sql bdr.lo_tell64(fd int4) returns int64 .. _parameters-9: Parameters ^^^^^^^^^^ - ``fd`` — File descriptor returned by ``bdr.lo_open`` . bdr.lo_truncate ^^^^^^^^^^^^^^^ Truncates the large object to the given length in bytes. .. _synopsis-10: Synopsis ^^^^^^^^ .. code:: sql bdr.lo_truncate(fd int4, len int4) returns int4 .. _parameters-10: Parameters ^^^^^^^^^^ - ``fd`` — File descriptor returned by ``bdr.lo_open`` . - ``len`` — New length of the large object in bytes. bdr.lo_truncate64 ^^^^^^^^^^^^^^^^^ 64-bit version of ``bdr.lo_truncate`` . .. _synopsis-11: Synopsis ^^^^^^^^ .. code:: sql bdr.lo_truncate64(fd int4, len int64) returns int4 .. _parameters-11: Parameters ^^^^^^^^^^ - ``fd`` — File descriptor returned by ``bdr.lo_open`` . - ``len`` — New length of the large object in bytes. bdr.lo_unlink ^^^^^^^^^^^^^ Deletes the large object with the given OID. .. _synopsis-12: Synopsis ^^^^^^^^ .. code:: sql bdr.lo_unlink(lobjId oid) returns int4 .. _parameters-12: Parameters ^^^^^^^^^^ - ``lobjId`` — OID of the large object to delete. bdr.lo_import ^^^^^^^^^^^^^ Imports a file from the server’s filesystem as a new large object. Returns the OID of the new object. Requires superuser privilege. .. _synopsis-13: Synopsis ^^^^^^^^ .. code:: sql bdr.lo_import(filename text) returns oid .. _parameters-13: Parameters ^^^^^^^^^^ - ``filename`` — Absolute path of the file to import on the server’s filesystem. bdr.lo_import_with_oid ^^^^^^^^^^^^^^^^^^^^^^ Imports a file from the server’s filesystem as a large object with a specific OID. Requires superuser privilege. .. _synopsis-14: Synopsis ^^^^^^^^ .. code:: sql bdr.lo_import_with_oid(filename text, lobjId oid) returns oid .. _parameters-14: Parameters ^^^^^^^^^^ - ``filename`` — Absolute path of the file to import on the server’s filesystem. - ``lobjId`` — OID to assign to the new large object. bdr.lo_export ^^^^^^^^^^^^^ Exports a large object to a file on the server’s filesystem. Requires superuser privilege. .. _synopsis-15: Synopsis ^^^^^^^^ .. code:: sql bdr.lo_export(lobjId oid, filename text) returns int4 .. _parameters-15: Parameters ^^^^^^^^^^ - ``lobjId`` — OID of the large object to export. - ``filename`` — Absolute path of the destination file on the server’s filesystem. bdr.lo_get ^^^^^^^^^^ Returns the entire contents of the large object as a ``bytea`` value. .. _synopsis-16: Synopsis ^^^^^^^^ .. code:: sql bdr.lo_get(lobjId oid) returns bytea .. _parameters-16: Parameters ^^^^^^^^^^ - ``lobjId`` — OID of the large object to read. bdr.lo_get_fragment ^^^^^^^^^^^^^^^^^^^ Returns a portion of the large object as a ``bytea`` value. .. _synopsis-17: Synopsis ^^^^^^^^ .. code:: sql bdr.lo_get_fragment(lobjId oid, offset int64, length int4) returns bytea .. _parameters-17: Parameters ^^^^^^^^^^ - ``lobjId`` — OID of the large object to read. - ``offset`` — Byte offset within the large object to start reading from. - ``length`` — Maximum number of bytes to return. bdr.lo_from_bytea ^^^^^^^^^^^^^^^^^ Creates a new large object from a ``bytea`` value. Returns the OID of the new object. .. _synopsis-18: Synopsis ^^^^^^^^ .. code:: sql bdr.lo_from_bytea(lobjId oid, data bytea) returns oid .. _parameters-18: Parameters ^^^^^^^^^^ - ``lobjId`` — OID to assign to the new large object. Pass ``0`` to have an OID assigned automatically. - ``data`` — Initial contents of the large object. bdr.lo_put ^^^^^^^^^^ Writes data into the large object starting at the given offset, extending the object if necessary. .. _synopsis-19: Synopsis ^^^^^^^^ .. code:: sql bdr.lo_put(lobjId oid, offset int64, data bytea) returns void .. _parameters-19: Parameters ^^^^^^^^^^ - ``lobjId`` — OID of the large object to write to. - ``offset`` — Byte offset within the large object to start writing at. - ``data`` — Data to write.