PolarDB:lo-interfaces

これらの関数を使用するすべての大きなオブジェクト操作は、SQLトランザクションブロック内で行われなければならない。

これらの関数のいずれか1つの実行中にエラーが発生した場合、関数は通常は0または-1の値を返します。 エラーを説明するメッセージは接続オブジェクトに格納され、PQerrorMessageで取得できます。

これらの関数を使用するクライアントアプリケーションには、ヘッダーファイルlibpq/libpq-fs.hを含め、thelibpqlibraryにリンクする必要があります。

大きなオブジェクトの作成

関数

Oid lo_creat(PGconn * conn、intモード);

は新しい大きなオブジェクトを作成します。 戻り値は、新しいラージオブジェクトに割り当てられたOID、または失敗時にInvalidOid (ゼロ) です。modeは未使用で、ofPostgreSQL8.1として無視されます。ただし、以前のリリースとの下位互換性については、INV_READ、INV_WRITE、またはINV_READ | INV_WRITEに設定することをお勧めします。 (これらのシンボリック定数は、ヘッダーファイルlibpq/libpq-fs.hで定義されています。)

例:

inv_oid = lo_creat(conn, INV_READ | INV_WRITE);

関数

Oid lo_create(PGconn * conn, Oid lobjId);

また、新しい大きなオブジェクトを作成します。 割り当てられるOIDは、lobjIdで指定できます。指定されている場合、そのOIDが何らかのラージオブジェクトですでに使用されている場合は失敗が発生します。 lobjIdがInvalidOid (ゼロ) の場合、lo_createは未使用のOIDを割り当てます (これはlo_creatと同じ動作です) 。 戻り値は、新しいラージオブジェクトに割り当てられたOID、または失敗時にInvalidOid (ゼロ) です。

lo_createはofPostgreSQL8.1として新しくなりました。この関数を古いサーバーバージョンに対して実行すると、失敗してInvalidOidを返します。

例:

inv_oid = lo_create(conn, desired_oid);

大きなオブジェクトのインポート

オペレーティングシステムファイルをラージオブジェクトとしてインポートするには、

Oid lo_import(PGconn * conn、const char * filename);

filenameは、ラージオブジェクトとしてインポートするファイルのオペレーティングシステム名を指定します。 戻り値は、新しいラージオブジェクトに割り当てられたOID、または失敗時にInvalidOid (ゼロ) です。 ファイルはサーバーではなくクライアントインターフェイスライブラリによって読み取られるため、クライアントファイルシステムに存在し、クライアントアプリケーションによって読み取り可能である必要があります。

関数

Oid lo_import_with_oid(PGconn * conn、const char * filename、Oid lobjId);

また、新しい大きなオブジェクトをインポートします。 割り当てられるOIDは、lobjIdで指定できます。指定されている場合、そのOIDが何らかのラージオブジェクトですでに使用されている場合は失敗が発生します。 lobjIdがInvalidOid (ゼロ) の場合、lo_import_with_oidは未使用のOIDを割り当てます (これはlo_importと同じ動作です) 。 戻り値は、新しいラージオブジェクトに割り当てられたOID、または失敗時にInvalidOid (ゼロ) です。

lo_import_with_oidはPostgreSQL 8.4の時点で新しく、内部的に新しいlo_createを使用します。この関数を8.0以前に対して実行すると、失敗してInvalidOidを返します。

大きなオブジェクトのエクスポートExporting a large object

大きなオブジェクトをオペレーティングシステムファイルにエクスポートするには、

int lo_export(PGconn * conn, Oid lobjId, const char * filename);

lobjId引数はエクスポートするラージオブジェクトのOIDを指定し、filename引数はファイルのオペレーティングシステム名を指定します。 ファイルは、サーバーではなく、クライアントインターフェイスライブラリによって書き込まれることに注意してください。 成功の場合は1、失敗の場合は-1を返します。

既存の大きなオブジェクトを開く

読み取りまたは書き込みのために既存のラージオブジェクトを開くには、

int lo_open(PGconn * conn, Oid lobjId, intモード);

lobjId引数は、開くラージオブジェクトのOIDを指定します。 modeビットは、オブジェクトが読み取り (INV_READ) 、書き込み (INV_WRITE) 、またはその両方のために開かれるかどうかを制御する。 (これらのシンボリック定数は、ヘッダーファイルlibpq/libpq-fs.hで定義されています。) lo_openは、後でlo_read、lo_write、lo_lseek、lo_lseek64、lo_tell、lo_tell64、lo_truncate、lo_truncate64、およびlo_closeで使用するための (非負の) 大きなオブジェクト記述子を返します。 記述子は、現在のトランザクションの期間中のみ有効です。 失敗すると、-1が返されます。

現在、サーバーはモードINV_WRITEとINV_READ | INV_WRITEを区別していません。どちらの場合も、記述子からの読み取りが許可されています。 ただし、これらのモードとINV_READのみには大きな違いがあります。INV_READでは記述子に書き込むことができず、そこから読み取られたデータは、lo_openが実行されたときにアクティブだったトランザクションスナップショットの時点でのラージオブジェクトの内容を反映します。 INV_WRITEで開かれた記述子からの読み取りは、他のコミットされたトランザクションのすべての書き込みと現在のトランザクションの書き込みを反映するデータを返します。 これは、通常のSQL SELECTコマンドのREPEATABLE READとREAD COMMITTEDトランザクションモードの動作に似ています。

ラージオブジェクトでSELECT特権が使用できない場合、またはINV_WRITEが指定されていてUPDATE特権が使用できない場合、lo_openは失敗します。 (PostgreSQL11以前は、これらの特権チェックは、記述子を使用した最初の実際の読み取りまたは書き込み呼び出しで実行されていました。) これらの特権チェックは、lo_compat_privilegesランタイムパラメーターで無効にできます。

例:

inv_fd = lo_open(conn, inv_oid, INV_READ | INV_WRITE);

ラージオブジェクトへのデータの書き込み

関数

int lo_write(PGconn * conn, int fd, const char * buf, size_t len);

は、buf (サイズはlenでなければなりません) からlenバイトをラージオブジェクト記述子fdに書き込みます。 fd引数は、前のlo_openによって返されている必要があります。 実際に書き込まれたバイト数が返されます (現在の実装では、エラーがない限り、これは常にlenに等しくなります) 。 エラーが発生した場合の戻り値は-1です。

lenパラメーターはsize_tとして宣言されていますが、この関数はINT_MAXより大きい長さの値を拒否します。 実際には、とにかく最大で数メガバイトのチャンクでデータを転送するのが最善です。

ラージオブジェクトからのデータの読み取り

関数

int lo_read(PGconn * conn, int fd, char * buf, size_t len);

は、ラージオブジェクト記述子fdから最大lenバイトをbufに読み込みます (サイズはlenでなければなりません) 。 fd引数は、前のlo_openによって返されている必要があります。 実際に読み取られたバイト数が返されます。ラージオブジェクトの末尾に最初に到達した場合、これはlen未満になります。 エラーが発生した場合の戻り値は-1です。

lenパラメーターはsize_tとして宣言されていますが、この関数はINT_MAXより大きい長さの値を拒否します。 実際には、とにかく最大で数メガバイトのチャンクでデータを転送するのが最善です。

シークin a large object

ラージオブジェクト記述子に関連付けられている現在の読み取りまたは書き込み位置を変更するには、

int lo_lseek(PGconn * conn, int fd, int offset, int whence);

この関数は、fdによって識別された大型オブジェクト記述子の現在位置ポインタを、offsetによって指定された新しい位置に移動させる。 whenceの有効な値は、SEEK_SET (オブジェクト開始からのシーク) 、seek_CUR (現在位置からのシーク) 、およびSEEK_END (オブジェクト終了からのシーク) です。 戻り値は、新しい位置ポインタ、またはエラーの場合は-1です。

サイズが2GBを超える可能性のある大きなオブジェクトを扱う場合は、代わりに

pg_int64 lo_lseek64(PGconn * conn、int fd、pg_int64オフセット、int whence);

この関数の動作はlo_lseekと同じですが、2GBを超えるオフセットを受け入れたり、2GBを超える結果を出力したりできます。 新しいロケーションポインタが2GBより大きい場合、lo_lseekは失敗することに注意してください。

lo_lseek64はPostgreSQL9.3として新しいものです。 この関数を古いサーバーバージョンに対して実行すると、失敗して-1が返されます。

ラージオブジェクトのシーク位置の取得

ラージオブジェクト記述子の現在の読み取り位置または書き込み位置を取得するには、

int lo_tell(PGconn * conn, int fd);

エラーがある場合、戻り値は-1です。

サイズが2GBを超える可能性のある大きなオブジェクトを扱う場合は、代わりに

pg_int64 lo_tell64(PGconn * conn, int fd);

この関数の動作はlo_tellと同じですが、2GBを超える結果が得られます。 現在の読み取り /書き込み場所が2GBを超えると、lo_tellは失敗することに注意してください。

lo_tell64はPostgreSQL9.3として新しいものです。 この関数を古いサーバーバージョンに対して実行すると、失敗して-1が返されます。

大きなオブジェクトの切り捨て

大きなオブジェクトを指定された長さに切り捨てるには、

int lo_truncate(PGcon * conn, int fd, size_t len);

この関数は、ラージオブジェクト記述子fdを長さlenに切り捨てます。 fd引数は、前のlo_openによって返されている必要があります。 lenがラージオブジェクトの現在の長さより大きい場合、ラージオブジェクトはnullバイト ('\0') で指定された長さに拡張されます。 成功すると、lo_truncateはゼロを返します。 エラーの場合、戻り値は-1です。

記述子fdに関連する読み出し /書き込み位置は変更されない。

lenパラメーターはsize_tとして宣言されていますが、lo_truncateはINT_MAXより大きい長さの値を拒否します。

サイズが2GBを超える可能性のある大きなオブジェクトを扱う場合は、代わりに

int lo_truncate64(PGcon * conn, int fd, pg_int64 len);

この関数の動作はlo_truncateと同じですが、2GBを超えるlen値を受け入れることができます。

lo_truncateはofPostgreSQL8.3として新しくなりました。この関数を古いサーバーバージョンに対して実行すると、失敗して-1が返されます。

lo_truncate64はofPostgreSQL9.3として新しくなりました。この関数を古いサーバーバージョンに対して実行すると、失敗して-1が返されます。

大きなオブジェクト記述子を閉じる

を呼び出すと、大きなオブジェクト記述子を閉じることができます。

int lo_close(PGconn * conn, int fd);

ここで、fdはlo_openによって返される大きなオブジェクト記述子です。 成功すると、lo_closeはゼロを返します。 エラーの場合、戻り値は-1です。

トランザクションの最後に開いたままの大きなオブジェクト記述子は、自動的に閉じられます。

大きなオブジェクトの削除

データベースから大きなオブジェクトを削除するには、

int lo_unlink(PGconn * conn, Oid lobjId);

lobjId引数は、削除するラージオブジェクトのOIDを指定します。 成功した場合は1、失敗した場合は-1を返します。