begriffs open source - ai-pg/blob - full-docs/txt/lo-funcs.txt

   1
   2 33.4. Server-Side Functions #
   3
   4    Server-side functions tailored for manipulating large objects from SQL
   5    are listed in Table 33.1.
   6
   7    Table 33.1. SQL-Oriented Large Object Functions
   8
   9    Function
  10
  11    Description
  12
  13    Example(s)
  14
  15    lo_from_bytea ( loid oid, data bytea ) → oid
  16
  17    Creates a large object and stores data in it. If loid is zero then the
  18    system will choose a free OID, otherwise that OID is used (with an
  19    error if some large object already has that OID). On success, the large
  20    object's OID is returned.
  21
  22    lo_from_bytea(0, '\xffffff00') → 24528
  23
  24    lo_put ( loid oid, offset bigint, data bytea ) → void
  25
  26    Writes data starting at the given offset within the large object; the
  27    large object is enlarged if necessary.
  28
  29    lo_put(24528, 1, '\xaa') →
  30
  31    lo_get ( loid oid [, offset bigint, length integer ] ) → bytea
  32
  33    Extracts the large object's contents, or a substring thereof.
  34
  35    lo_get(24528, 0, 3) → \xffaaff
  36
  37    There are additional server-side functions corresponding to each of the
  38    client-side functions described earlier; indeed, for the most part the
  39    client-side functions are simply interfaces to the equivalent
  40    server-side functions. The ones just as convenient to call via SQL
  41    commands are lo_creat, lo_create, lo_unlink, lo_import, and lo_export.
  42    Here are examples of their use:
  43 CREATE TABLE image (
  44     name            text,
  45     raster          oid
  46 );
  47
  48 SELECT lo_creat(-1);       -- returns OID of new, empty large object
  49
  50 SELECT lo_create(43213);   -- attempts to create large object with OID 43213
  51
  52 SELECT lo_unlink(173454);  -- deletes large object with OID 173454
  53
  54 INSERT INTO image (name, raster)
  55     VALUES ('beautiful image', lo_import('/etc/motd'));
  56
  57 INSERT INTO image (name, raster)  -- same as above, but specify OID to use
  58     VALUES ('beautiful image', lo_import('/etc/motd', 68583));
  59
  60 SELECT lo_export(image.raster, '/tmp/motd') FROM image
  61     WHERE name = 'beautiful image';
  62
  63    The server-side lo_import and lo_export functions behave considerably
  64    differently from their client-side analogs. These two functions read
  65    and write files in the server's file system, using the permissions of
  66    the database's owning user. Therefore, by default their use is
  67    restricted to superusers. In contrast, the client-side import and
  68    export functions read and write files in the client's file system,
  69    using the permissions of the client program. The client-side functions
  70    do not require any database privileges, except the privilege to read or
  71    write the large object in question.
  72
  73 Caution
  74
  75    It is possible to GRANT use of the server-side lo_import and lo_export
  76    functions to non-superusers, but careful consideration of the security
  77    implications is required. A malicious user of such privileges could
  78    easily parlay them into becoming superuser (for example by rewriting
  79    server configuration files), or could attack the rest of the server's
  80    file system without bothering to obtain database superuser privileges
  81    as such. Access to roles having such privilege must therefore be
  82    guarded just as carefully as access to superuser roles. Nonetheless, if
  83    use of server-side lo_import or lo_export is needed for some routine
  84    task, it's safer to use a role with such privileges than one with full
  85    superuser privileges, as that helps to reduce the risk of damage from
  86    accidental errors.
  87
  88    The functionality of lo_read and lo_write is also available via
  89    server-side calls, but the names of the server-side functions differ
  90    from the client side interfaces in that they do not contain
  91    underscores. You must call these functions as loread and lowrite.