PostgreSQL 10.1 手册_部分 IV. 客户端接口_第 34 章 大对象_34.3. 客户端接口

本文涉及的产品
云原生数据库 PolarDB MySQL 版,通用型 2核4GB 50GB
云原生数据库 PolarDB PostgreSQL 版,标准版 2核4GB 50GB
简介: 34.3. 客户端接口 34.3.1. 创建一个大对象 34.3.2. 导入一个大对象 34.3.3. 导出一个大对象 34.3.4. 打开一个现有的大对象 34.3.5. 向一个大对象写入数据 34.3.6. 从一个大对象读取数据 34.3.7. 在一个大对象中查找 34.3.8. 获取一个大对象的查找位置 34.3.9. 截断一个大对象 34.3.10. 关闭一个大对象描述符 34.3.11. 移除一个大对象 本节描述PostgreSQL的libpq客户端接口为访问大对象所提供的功能。

34.3. 客户端接口

本节描述PostgreSQLlibpq客户端接口为访问大对象所提供的功能。PostgreSQL的大对象接口按照Unix文件系统的接口建模,也有相似的openreadwritelseek等。

所有使用这些函数对大对象的操作都必须发生在一个SQL事务块中,因为大对象文件描述符只在事务期间有效。

在执行任何一个这种函数期间如果发生一个错误,该函数将会返回一个其他的不可能值,典型的是0或-1。一个关于该错误的消息亦会被保存在连接对象中,可以通过PQerrorMessage检索到。

使用这些函数的客户端应用应该包括头文件libpq/libpq-fs.h并链接libpq库。

34.3.1. 创建一个大对象

函数

Oid lo_creat(PGconn *conn, int mode);

创建一个新的大对象。其返回值是分配给这个新大对象的OID或者InvalidOid(0)表示失败。 modePostgreSQL 8.1就不再使用且会被忽略。但是,为了和以前的发行兼容,它最好被设置为INV_READINV_WRITEINV_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已经被某个大对象使用时会产生错误。如果lobjIdInvalidOid(0),则lo_create会分配一个未使用的OID(这时和lo_creat的行为相同)。返回值是分配给新大对象的OID或InvalidOid(0)表示发生错误。

lo_create在从PostgreSQL 8.1开始的版本中是新的,如果该函数在旧服务器版本上运行,它将失败并返回InvalidOid

一个例子:

inv_oid = lo_create(conn, desired_oid);

34.3.2. 导入一个大对象

要将一个操作系统文件导入成一个大对象,调用:

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

filename指定了要导入为大对象的操作系统文件名。返回值是分配给新大对象的OID或InvalidOid(0)表示发生错误。注意该文件是被客户端接口库而不是服务器所读取,因此它必须存在于客户端文件系统中并且对于客户端应用是可读的。

函数

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

也可以导入一个新大对象。分配给新大对象的OID可以用lobjId指定,如果这样做,该OID已经被某个大对象使用时会产生错误。如果lobjIdInvalidOid(0),则lo_import_with_oid会分配一个未使用的OID(这和lo_import的行为相同)。返回值是分配给新大对象的OID或InvalidOid(0)表示发生错误。

lo_import_with_oid在从PostgreSQL 8.1开始的版本中是新的并且在内部使用了lo_create(在8.1中也是新的),如果该函数在旧服务器版本上运行,它将失败并返回InvalidOid

34.3.3. 导出一个大对象

要把一个大对象导出到一个操作系统文件,调用:

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

lobjId参数指定要导出的大对象的OID,filename参数指定操作系统文件名。注意该文件是被客户端接口库而不是服务器写入。成功返回1,错误返回-1。

34.3.4. 打开一个现有的大对象

要打开一个现有的大对象进行读写,调用:

int lo_open(PGconn *conn, Oid lobjId, int mode);

lobjId参数指定要打开的大对象的OID。mode位控制着打开对象是为了只读(INV_READ)、只写(INV_WRITE)或者读写(这些符号常量定义在头文件libpq/libpq-fs.h中)。lo_open返回一个(非负)大对象描述符以便后面用于lo_readlo_writelo_lseeklo_lseek64lo_telllo_tell64lo_truncatelo_truncate64以及lo_close。该描述符只在当前事务期间有效。如果打开错误将会返回-1。

服务器目前并不区分模式INV_WRITEINV_READ |INV_WRITE:在两种情况中都允许从描述符读取。但是在这些模式和单独的INV_READ之间有明显的区别:使用INV_READ我们不能向描述符写入,从中读取的数据则反映了该大对象在活动事务快照时刻的内容(该快照在lo_open被执行时创建),而不管之后被该事务或其他事务写入的内容。从一个以INV_WRITE模式打开的描述符读取的数据所有其他已提交事务以及当前事务所作的写入。这与普通SQL命令 SELECTREPEATABLE READREAD COMMITTED事务模式之间的区别相似。

一个例子:

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

34.3.5. 向一个大对象写入数据

函数

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的长度值。在实际中,被传送的数据最好是每块最多数兆字节。

34.3.6. 从一个大对象读取数据

函数

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的长度值。在实际中,被传送的数据最好是每块最多数兆字节。

34.3.7. 在一个大对象中查找

要改变一个大对象描述符的当前读或写位置,调用:

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 offset, int whence);

该函数的行为和lo_lseek相同,但是它能接受一个超过2GB的offset并/或传送一个超过2GB的结果。注意如果新位置的指针超过2GB,lo_lseek会失败。

lo_lseek64是从 PostgreSQL 9.3开始增加的新函数。如果该函数在一个旧服务器版本上执行,将会失败并返回-1。

34.3.8. 获取一个大对象的查找位置

要得到一个大对象描述符的当前读或写位置,调用:

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是从PostgreSQL 9.3开始新增的函数。如果该函数在旧服务器版本上运行,将会失败并返回-1。

34.3.9. 截断一个大对象

要将一个大对象截断成一个给定长度,调用:

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

该函数将大对象描述符fd截断为长度len。参数fd必须是已经由前面的lo_open返回的大对象描述符。如果len超过了大对象的当前长度,大对象将会被使用空字节('\0')扩展到指定长度。成功时lo_truncate返回0,失败时返回值为-1。

描述fd的读/写位置不变。

尽管参数len被声明为类型size_tlo_truncate会拒绝超过INT_MAX的长度值。

在处理可能超过2GB大小的大对象时,换用:

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

该函数和lo_truncate的行为相同,但它能够接受超过2GB的len值。

lo_truncate是从PostgreSQL 8.3开始新的函数,如果该函数运行在一个旧服务器版本上,它将失败并返回-1。

lo_truncate64是从PostgreSQL 9.3开始新的函数,如果该函数运行在一个旧服务器版本上,它将失败并返回-1。

34.3.10. 关闭一个大对象描述符

要关闭一个大对象描述符,调用:

int lo_close(PGconn *conn, int fd);

其中fd是由lo_open返回的大对象描述符。成功时,lo_close返回0,失败时返回-1。

在事务末尾仍然保持打开的任何大对象描述符都会自动被关闭。

34.3.11. 移除一个大对象

要从数据库中移除一个大对象,调用:

int lo_unlink(PGconn *conn, Oid lobjId);

lobjId参数指定要移除的大对象的OID。成功时返回1,失败时返回-1。

本文转自PostgreSQL中文社区,原文链接:34.3. 客户端接口

相关实践学习
使用PolarDB和ECS搭建门户网站
本场景主要介绍基于PolarDB和ECS实现搭建门户网站。
阿里云数据库产品家族及特性
阿里云智能数据库产品团队一直致力于不断健全产品体系,提升产品性能,打磨产品功能,从而帮助客户实现更加极致的弹性能力、具备更强的扩展能力、并利用云设施进一步降低企业成本。以云原生+分布式为核心技术抓手,打造以自研的在线事务型(OLTP)数据库Polar DB和在线分析型(OLAP)数据库Analytic DB为代表的新一代企业级云原生数据库产品体系, 结合NoSQL数据库、数据库生态工具、云原生智能化数据库管控平台,为阿里巴巴经济体以及各个行业的企业客户和开发者提供从公共云到混合云再到私有云的完整解决方案,提供基于云基础设施进行数据从处理、到存储、再到计算与分析的一体化解决方案。本节课带你了解阿里云数据库产品家族及特性。
相关文章
|
6月前
|
SQL 关系型数据库 数据库
nacos 2.2.3版本 查看配置文件的历史版本的接口 是针对MySQL数据库的sql 改成postgresql后 sql语句报错 该怎么解决
在Nacos 2.2.3中切换到PostgreSQL后,执行配置文件历史版本分页查询出错,因`LIMIT 0, 10`语法不被PostgreSQL支持,需改为`LIMIT 10 OFFSET 0`。仅当存在历史版本时报错。解决方案是调整查询SQL以兼容PostgreSQL语法。
|
7月前
|
SQL 存储 缓存
PostgreSQL函数管理接口
学习PostgreSQL服务端开发必须要对函数管理接口有比较深入的了解
|
7月前
|
存储 SQL 关系型数据库
Mysql学习手册(第一部分)
【5月更文挑战第17天】Mysql学习手册(第一部分)
74 0
|
7月前
|
存储 SQL 关系型数据库
MySQL学习手册(第一部分)
mysql日常使用记录
150 0
|
7月前
|
关系型数据库 分布式数据库 PolarDB
PolarDB for PostgreSQL下载问题之客户端 X-Paxos下载失败如何解决
PolarDB for PostgreSQL是基于PostgreSQL开发的一款云原生关系型数据库服务,它提供了高性能、高可用性和弹性扩展的特性;本合集将围绕PolarDB(pg)的部署、管理和优化提供指导,以及常见问题的排查和解决办法。
|
关系型数据库 MySQL 数据库
史上最全的MySQL性能手册(优化+SQL+并发+数据库)
史上最全的MySQL性能手册(优化+SQL+并发+数据库)
|
存储 关系型数据库 MySQL
MySQL手册 2
MySQL手册
110 1
|
JSON 安全 关系型数据库
MySQL 8.0 参考手册— 内置函数和运算符参考
MySQL 8.0 参考手册— 内置函数和运算符参考
109 0
|
存储 关系型数据库 MySQL
MySQL手册 3
MySQL手册
|
SQL 存储 关系型数据库
5 分钟上手 Flink MySQL 连接器实验手册|Flink-Learning 实战营
加入 Flink-Learning 实战营,动手体验真实有趣的实战场景。只需 2 小时,让您变身 Flink 实战派。实战营采取了 Flink 专家在线授课,专属社群答疑,小松鼠助教全程陪伴的学习模式。
2216 2
5 分钟上手 Flink MySQL 连接器实验手册|Flink-Learning 实战营
下一篇
DataWorks