2. 首页 > PostgreSQL教程 > 正文

PostgreSQL教程FG181-PG自定义索引访问方法：基础开发

教程整理：风哥教程  |  更新时间：2026-01-22  |  教程分类：PostgreSQL教程  |  文档学习：18

内容大纲

内容简介

本篇文章介绍PostgreSQL自定义索引访问方法的基础开发，包括索引访问方法概述、API介绍、开发环境搭建、实现步骤、注册与测试、打包与部署等内容，风哥教程参考PostgreSQL官方文档Indexes、Index Access Methods等相关内容。通过本文的学习，读者将能够掌握自定义索引访问方法的开发流程，为特定数据类型或查询需求创建高效的索引访问方法。

Part01-基础概念与理论知识

1.1 索引访问方法概述

索引访问方法是PostgreSQL中用于实现不同类型索引的核心组件，主要特点：

  • 可扩展性：
    • PostgreSQL允许开发者创建自定义索引访问方法
    • 支持为特定数据类型创建专用索引
    • 灵活的索引访问方法API
  • 内置索引访问方法：
    • btree：B树索引，默认索引类型
    • hash：哈希索引，用于等值查询
    • gist：通用搜索树，支持复杂数据类型
    • gin：通用倒排索引，用于全文检索和数组
    • spgist：空间分区GiST，用于空间数据
    • brin：块范围索引，用于大型数据集
  • 索引访问方法的功能：
    • 索引构建
    • 索引扫描
    • 索引插入
    • 索引删除
    • 索引更新
    • 索引一致性检查

1.2 索引访问方法API

索引访问方法的核心API：

  • ambuild：构建新索引
  • ambuildempty：构建空索引
  • aminsert：向索引插入新项
  • ambulkdelete：批量删除索引项
  • amvacuumcleanup：VACUUM后的清理
  • amcostestimate：估算索引扫描成本
  • amoptions：处理索引选项
  • amproperty：返回索引属性
  • ambeginscan：开始索引扫描
  • amrescan：重新开始索引扫描
  • amgettuple：获取下一个元组
  • amgetbitmap：获取位图
  • amendscan：结束索引扫描
  • ammarkpos：标记扫描位置
  • amrestrpos：恢复扫描位置

1.3 内置索引访问方法

内置索引访问方法的比较：

Part02-生产环境规划与建议

2.1 自定义索引需求分析

自定义索引访问方法的需求分析：

  • 数据类型：
    • 是否有特殊的数据类型需要索引
    • 内置索引访问方法是否满足需求
    • 数据的访问模式是什么
  • 查询模式：
    • 主要的查询类型是什么
    • 是否需要特殊的操作符
    • 查询的性能要求是什么
  • 性能要求：
    • 索引构建时间要求
    • 查询响应时间要求
    • 索引维护开销
  • 维护需求：
    • 索引的维护复杂度
    • 与PostgreSQL版本的兼容性
    • 长期维护的可行性

2.2 性能考虑

自定义索引访问方法的性能考虑：

  • 索引构建性能：
    • 索引构建的时间复杂度
    • 内存使用情况
    • 磁盘I/O开销
  • 查询性能：
    • 索引扫描的效率
    • 成本估算的准确性
    • 缓存利用情况
  • 维护性能：
    • 插入、更新、删除操作的开销
    • VACUUM的效率
    • 索引重建的频率
  • 存储效率：
    • 索引的大小
    • 压缩率
    • 页填充率

2.3 兼容性规划

自定义索引访问方法的兼容性规划：

  • PostgreSQL版本：
    • 支持的PostgreSQL版本范围
    • 版本间的API变化
    • 版本升级策略
  • 操作系统：
    • 支持的操作系统
    • 编译器兼容性
    • 系统调用的使用
  • 数据类型兼容性：
    • 与内置数据类型的兼容性
    • 与自定义数据类型的兼容性
    • 类型转换的处理
  • 扩展兼容性：
    • 与其他扩展的兼容性
    • 依赖关系
    • 命名空间管理

Part03-生产环境项目实施方案

3.1 开发环境搭建

开发环境搭建的步骤：

# 安装PostgreSQL开发包

— Ubuntu/Debian
apt update
apt install -y postgresql-server-dev-18 build-essential

— RHEL/CentOS
yum install -y postgresql18-devel gcc make

— 验证安装
pg_config –version
pg_config –includedir
pg_config –libdir

# 获取PostgreSQL源码

— 下载PostgreSQL源码
wget https://ftp.postgresql.org/pub/source/v18.0/postgresql-18.0.tar.gz
tar xvfz postgresql-18.0.tar.gz
cd postgresql-18.0

— 查看索引访问方法示例
ls -la src/backend/access/
ls -la src/backend/access/btree/
ls -la src/backend/access/hash/

3.2 索引访问方法实现

简单索引访问方法的实现：

# 简单索引访问方法示例

— simpleidx.c – 简单索引访问方法实现
#include “postgres.h”
#include “fmgr.h”
#include “access/genam.h”
#include “access/heapam.h”
#include “access/htup_details.h”
#include “access/simpleidx.h”
#include “catalog/index.h”
#include “storage/bufmgr.h”
#include “utils/rel.h”
#include “utils/relcache.h”

PG_MODULE_MAGIC;

— 索引构建函数
Datum
simpleidxbuild(PG_FUNCTION_ARGS)
{
Relation heapRel = (Relation) PG_GETARG_POINTER(0);
Relation indexRel = (Relation) PG_GETARG_POINTER(1);
IndexInfo *indexInfo = (IndexInfo *) PG_GETARG_POINTER(2);

elog(INFO, “Building simple index”);

— 实现索引构建逻辑
— …

PG_RETURN_VOID();
}

— 索引插入函数
Datum
simpleidxinsert(PG_FUNCTION_ARGS)
{
Relation indexRel = (Relation) PG_GETARG_POINTER(0);
Datum *values = (Datum *) PG_GETARG_POINTER(1);
bool *isnull = (bool *) PG_GETARG_POINTER(2);
ItemPointer heap_tid = (ItemPointer) PG_GETARG_POINTER(3);
Relation heapRel = (Relation) PG_GETARG_POINTER(4);
IndexUniqueCheck checkUnique = (IndexUniqueCheck) PG_GETARG_INT32(5);
bool indexUnchanged = (bool) PG_GETARG_BOOL(6);

elog(INFO, “Inserting into simple index”);

— 实现索引插入逻辑
— …

PG_RETURN_BOOL(false);
}

— 索引扫描开始函数
Datum
simpleidxbeginscan(PG_FUNCTION_ARGS)
{
Relation indexRel = (Relation) PG_GETARG_POINTER(0);
int nkeys = PG_GETARG_INT32(1);
int norderbys = PG_GETARG_INT32(2);
IndexScanDesc scan;

elog(INFO, “Beginning simple index scan”);

scan = RelationGetIndexScan(indexRel, nkeys, norderbys);

PG_RETURN_POINTER(scan);
}

— 索引扫描获取元组函数
Datum
simpleidxgettuple(PG_FUNCTION_ARGS)
{
IndexScanDesc scan = (IndexScanDesc) PG_GETARG_POINTER(0);
ScanDirection direction = (ScanDirection) PG_GETARG_INT32(1);

elog(INFO, “Getting tuple from simple index”);

— 实现索引扫描逻辑
— …

PG_RETURN_BOOL(false);
}

— 索引扫描结束函数
Datum
simpleidxendscan(PG_FUNCTION_ARGS)
{
IndexScanDesc scan = (IndexScanDesc) PG_GETARG_POINTER(0);

elog(INFO, “Ending simple index scan”);

if (scan)
RelationCloseIndexScan(scan);

PG_RETURN_VOID();
}

— 注册函数
PG_FUNCTION_INFO_V1(simpleidxbuild);
PG_FUNCTION_INFO_V1(simpleidxinsert);
PG_FUNCTION_INFO_V1(simpleidxbeginscan);
PG_FUNCTION_INFO_V1(simpleidxgettuple);
PG_FUNCTION_INFO_V1(simpleidxendscan);

# Makefile

MODULES = simpleidx
EXTENSION = simpleidx
DATA = simpleidx–1.0.sql
PGFILEDESC = “Simple Index Access Method”

PG_CONFIG = pg_config
PGXS := $(shell $(PG_CONFIG) –pgxs)
include $(PGXS)

# simpleidx.control

comment = ‘Simple Index Access Method’
default_version = ‘1.0’
module_pathname = ‘$libdir/simpleidx’
relocatable = true
# simpleidx–1.0.sql

— 注册索引访问方法
CREATE FUNCTION simpleidxbuild(internal, internal, internal)
RETURNS void
AS ‘MODULE_PATHNAME’, ‘simpleidxbuild’
LANGUAGE C STRICT;

CREATE FUNCTION simpleidxinsert(internal, internal, internal, internal, internal, integer, boolean)
RETURNS boolean
AS ‘MODULE_PATHNAME’, ‘simpleidxinsert’
LANGUAGE C STRICT;

CREATE FUNCTION simpleidxbeginscan(internal, integer, integer)
RETURNS internal
AS ‘MODULE_PATHNAME’, ‘simpleidxbeginscan’
LANGUAGE C STRICT;

CREATE FUNCTION simpleidxgettuple(internal, integer)
RETURNS boolean
AS ‘MODULE_PATHNAME’, ‘simpleidxgettuple’
LANGUAGE C STRICT;

CREATE FUNCTION simpleidxendscan(internal)
RETURNS void
AS ‘MODULE_PATHNAME’, ‘simpleidxendscan’
LANGUAGE C STRICT;

— 创建索引访问方法
CREATE INDEX METHOD simpleidx (
BUFFER,
BUILD = simpleidxbuild,
INSERT = simpleidxinsert,
BEGINSCAN = simpleidxbeginscan,
GETTUPLE = simpleidxgettuple,
ENDSCAN = simpleidxendscan
);

3.3 注册与测试

索引访问方法的注册与测试：

# 编译和安装

— 编译
make

— 安装
sudo make install

— 验证安装
ls -la $(pg_config –pkglibdir)/simpleidx.so
ls -la $(pg_config –sharedir)/extension/simpleidx*

— 在PostgreSQL中创建扩展
psql -U pgsql -c “CREATE EXTENSION simpleidx;”

— 验证索引访问方法
psql -U pgsql -c “\dAm”

— 测试索引访问方法
psql -U pgsql -c “CREATE TABLE fgedu_test_table (id int, data text);”
psql -U pgsql -c “CREATE INDEX test_idx ON test_table USING simpleidx (id);”
psql -U pgsql -c “INSERT INTO test_table VALUES (1, ‘fgfgfgtest1’), (2, ‘test2’), (3, ‘test3’);”
psql -U pgsql -c “SELECT * FROM test_table WHERE id = 2;”

3.4 打包与部署

索引访问方法的打包与部署：

# 打包扩展

— 创建打包目录
mkdir -p simpleidx-1.0
cp simpleidx.c Makefile simpleidx.control simpleidx–1.0.sql README.md simpleidx-1.0/

— 创建压缩包
tar czvf simpleidx-1.0.tar.gz simpleidx-1.0/

— 部署到其他服务器
# 复制压缩包到目标服务器
scp simpleidx-1.0.tar.gz fgedu@remote-server:/tmp/

# 在目标服务器上安装
ssh fgedu@remote-server
cd /tmp
tar xzvf simpleidx-1.0.tar.gz
cd simpleidx-1.0
make
sudo make install
psql -U pgsql -c “CREATE EXTENSION simpleidx;”

Part04-生产案例与实战讲解

4.1 简单索引访问方法

简单索引访问方法的实战案例：

# 数组反转索引访问方法

— reverseidx.c – 数组反转索引访问方法
#include “postgres.h”
#include “fmgr.h”
#include “access/genam.h”
#include “access/heapam.h”
#include “access/htup_details.h”
#include “access/reverseidx.h”
#include “catalog/index.h”
#include “storage/bufmgr.h”
#include “utils/array.h”
#include “utils/rel.h”
#include “utils/relcache.h”

PG_MODULE_MAGIC;

— 数组反转函数
static Datum
reverse_array(Datum array_datum)
{
ArrayType *array = DatumGetArrayTypeP(array_datum);
int ndim = ARR_NDIM(array);
int *dims = ARR_DIMS(array);
int *lbs = ARR_LBOUND(array);
int nelems = ArrayGetNItems(ndim, dims);
Oid elem_type = ARR_ELEMTYPE(array);
int16 elem_len;
bool elem_byval;
char elem_align;
Datum *elems;
bool *nulls;
int i;
Datum *reversed_elems;
ArrayType *result;

— 获取元素类型信息
get_typlenbyvalalign(elem_type, &elem_len, &elem_byval, &elem_align);

— 解构数组
deconstruct_array(array, elem_type, elem_len, elem_byval, elem_align,
&elems, &nulls, &nelems);

— 反转数组元素
reversed_elems = (Datum *) palloc(nelems * sizeof(Datum));
for (i = 0; i < nelems; i++) reversed_elems[i] = elems[nelems - 1 - i]; -- 构建新数组 result = construct_array(reversed_elems, nulls, nelems, elem_type, elem_len, elem_byval, elem_align); -- 清理内存 pfree(elems); pfree(nulls); pfree(reversed_elems); return PointerGetDatum(result); } -- 索引构建函数 Datum reverseidxbuild(PG_FUNCTION_ARGS) { Relation heapRel = (Relation) PG_GETARG_POINTER(0); Relation indexRel = (Relation) PG_GETARG_POINTER(1); IndexInfo *indexInfo = (IndexInfo *) PG_GETARG_POINTER(2); HeapScanDesc scan; HeapTuple tuple; Datum values[INDEX_MAX_KEYS]; bool isnull[INDEX_MAX_KEYS]; elog(INFO, "Building reverse index"); -- 开始扫描堆表 scan = heap_beginscan(heapRel, SnapshotNow, 0, NULL); -- 遍历所有元组 while ((tuple = heap_getnext(scan, ForwardScanDirection)) != NULL) { -- 获取索引键值 IndexBuildHeapScan(indexRel, heapRel, indexInfo, false, values, isnull, tuple); -- 如果键值是数组，反转它 if (!isnull[0]) { Oid key_type = indexRel->rd_att->attrs[0]->atttypid;

if (key_type == INT4ARRAYOID || key_type == TEXTARRAYOID)
values[0] = reverse_array(values[0]);
}

— 插入到索引（这里简化处理）
— …
}

— 结束扫描
heap_endscan(scan);

PG_RETURN_VOID();
}

— 其他函数实现类似…
— …

PG_FUNCTION_INFO_V1(reverseidxbuild);
— 注册其他函数…

4.2 复杂索引访问方法

复杂索引访问方法的实战案例：

# 位图索引访问方法

— bitmapidx.c – 位图索引访问方法
#include “postgres.h”
#include “fmgr.h”
#include “access/genam.h”
#include “access/heapam.h”
#include “access/htup_details.h”
#include “access/bitmapidx.h”
#include “catalog/index.h”
#include “storage/bufmgr.h”
#include “utils/bitmapset.h”
#include “utils/rel.h”
#include “utils/relcache.h”

PG_MODULE_MAGIC;

— 位图索引结构
typedef struct BitmapIndexPage
{
BlockNumber next;
Bitmapset *bitmap;
} BitmapIndexPage;

— 索引构建函数
Datum
bitmapidxbuild(PG_FUNCTION_ARGS)
{
Relation heapRel = (Relation) PG_GETARG_POINTER(0);
Relation indexRel = (Relation) PG_GETARG_POINTER(1);
IndexInfo *indexInfo = (IndexInfo *) PG_GETARG_POINTER(2);
HeapScanDesc scan;
HeapTuple tuple;
Datum values[INDEX_MAX_KEYS];
bool isnull[INDEX_MAX_KEYS];
Bitmapset *bitmaps[256];
int i;
BlockNumber blkno;
Buffer buf;
BitmapIndexPage *page;

elog(INFO, “Building bitmap index”);

— 初始化位图数组
for (i = 0; i < 256; i++) bitmaps[i] = NULL; -- 开始扫描堆表 scan = heap_beginscan(heapRel, SnapshotNow, 0, NULL); -- 遍历所有元组 while ((tuple = heap_getnext(scan, ForwardScanDirection)) != NULL) { ItemPointerData tid = tuple->t_self;
int key_byte;

— 获取索引键值
IndexBuildHeapScan(indexRel, heapRel, indexInfo, false,
values, isnull, tuple);

if (!isnull[0])
{
— 简化处理：只处理字节类型的键
key_byte = DatumGetUInt8(values[0]);

— 设置位图位
bitmaps[key_byte] = bms_add_member(bitmaps[key_byte],
ItemPointerGetBlockNumber(&tid));
}
}

— 结束扫描
heap_endscan(scan);

— 存储位图到索引页面
for (i = 0; i < 256; i++) { if (bitmaps[i] != NULL) { -- 创建新页面 buf = ReadBuffer(indexRel, P_NEW); LockBuffer(buf, BUFFER_LOCK_EXCLUSIVE); blkno = BufferGetBlockNumber(buf); page = (BitmapIndexPage *) BufferGetPage(buf); -- 初始化页面 page->next = InvalidBlockNumber;
page->bitmap = bitmaps[i];

— 写页面
MarkBufferDirty(buf);
UnlockReleaseBuffer(buf);

— 这里需要更复杂的页面管理逻辑
// …
}
}

PG_RETURN_VOID();
}

— 其他函数实现…
— …

PG_FUNCTION_INFO_V1(bitmapidxbuild);
— 注册其他函数…

4.3 索引访问方法优化

索引访问方法的优化：

# 索引访问方法优化

— 优化1：添加成本估算函数
Datum
simpleidxcostestimate(PG_FUNCTION_ARGS)
{
PlannerInfo *root = (PlannerInfo *) PG_GETARG_POINTER(0);
IndexPath *path = (IndexPath *) PG_GETARG_POINTER(1);
double loop_count = PG_GETARG_FLOAT8(2);
Cost *indexStartupCost = (Cost *) PG_GETARG_POINTER(3);
Cost *indexTotalCost = (Cost *) PG_GETARG_POINTER(4);
Selectivity *indexSelectivity = (Selectivity *) PG_GETARG_POINTER(5);
double *indexCorrelation = (double *) PG_GETARG_POINTER(6);

— 估算索引扫描成本
*indexStartupCost = 0.0;
*indexTotalCost = 1.0 * loop_count;
*indexSelectivity = 0.1;
*indexCorrelation = 0.5;

PG_RETURN_VOID();
}

PG_FUNCTION_INFO_V1(simpleidxcostestimate);

— 优化2：添加位图扫描支持
Datum
simpleidxgetbitmap(PG_FUNCTION_ARGS)
{
IndexScanDesc scan = (IndexScanDesc) PG_GETARG_POINTER(0);
TIDBitmap *tbm = (TIDBitmap *) PG_GETARG_POINTER(1);

elog(INFO, “Getting bitmap from simple index”);

— 实现位图扫描逻辑
// …

PG_RETURN_INT64(0);
}

PG_FUNCTION_INFO_V1(simpleidxgetbitmap);

— 优化3：添加批量删除支持
Datum
simpleidxbulkdelete(PG_FUNCTION_ARGS)
{
IndexVacuumInfo *info = (IndexVacuumInfo *) PG_GETARG_POINTER(0);
IndexBulkDeleteResult *stats = (IndexBulkDeleteResult *) PG_GETARG_POINTER(1);
IndexBulkDeleteCallback callback = (IndexBulkDeleteCallback) PG_GETARG_POINTER(2);
void *callback_state = (void *) PG_GETARG_POINTER(3);

elog(INFO, “Bulk deleting from simple index”);

— 实现批量删除逻辑
// …

PG_RETURN_POINTER(stats);
}

PG_FUNCTION_INFO_V1(simpleidxbulkdelete);

— 更新索引访问方法注册
— 在simpleidx–1.0.sql中添加：
CREATE FUNCTION simpleidxcostestimate(internal, internal, float8, internal, internal, internal, internal)
RETURNS void
AS ‘MODULE_PATHNAME’, ‘simpleidxcostestimate’
LANGUAGE C STRICT;

CREATE FUNCTION simpleidxgetbitmap(internal, internal)
RETURNS int8
AS ‘MODULE_PATHNAME’, ‘simpleidxgetbitmap’
LANGUAGE C STRICT;

CREATE FUNCTION simpleidxbulkdelete(internal, internal, internal, internal)
RETURNS internal
AS ‘MODULE_PATHNAME’, ‘simpleidxbulkdelete’
LANGUAGE C STRICT;

— 更新索引访问方法定义
CREATE OR REPLACE INDEX METHOD simpleidx (
BUFFER,
BUILD = simpleidxbuild,
INSERT = simpleidxinsert,
BULKDELETE = simpleidxbulkdelete,
COSTESTIMATE = simpleidxcostestimate,
BEGINSCAN = simpleidxbeginscan,
GETTUPLE = simpleidxgettuple,
GETBITMAP = simpleidxgetbitmap,
ENDSCAN = simpleidxendscan
);

Part05-风哥经验总结与分享

5.1 开发最佳实践

自定义索引访问方法的开发最佳实践：

  • 代码组织：
    • 遵循PostgreSQL编码规范
    • 合理划分函数职责
    • 添加详细的注释
    • 使用有意义的变量名
  • 性能优化：
    • 优化索引扫描算法
    • 合理使用缓存
    • 减少磁盘I/O
    • 优化成本估算
  • 错误处理：
    • 完善的错误检查
    • 合理的错误报告
    • 资源清理
    • 事务处理
  • 测试：
    • 单元测试
    • 集成测试
    • 性能测试
    • 回归测试

5.2 常见问题与解决方案

自定义索引访问方法的常见问题与解决方案：

  • 问题：编译错误
    解决方案：检查PostgreSQL版本兼容性，确保头文件路径正确
  • 问题：运行时崩溃
    解决方案：添加错误检查，使用调试工具，检查内存管理
  • 问题：性能差
    解决方案：优化算法，检查缓存使用，优化I/O
  • 问题：查询计划不好
    解决方案：优化成本估算函数，提供准确的选择性
  • 问题：索引损坏
    解决方案：添加一致性检查，实现vacuumcleanup函数

5.3 企业级应用建议

企业级自定义索引访问方法的应用建议：

  • 需求评估：
    • 充分评估是否真的需要自定义索引
    • 考虑内置索引访问方法的扩展性
    • 评估开发和维护成本
  • 开发流程：
    • 先从简单的原型开始
    • 逐步完善功能
    • 充分测试后再上线
  • 维护：
    • 定期更新以兼容新的PostgreSQL版本
    • 收集使用反馈持续优化
    • 建立文档和知识库
  • 风险控制：
    • 在测试环境充分验证
    • 准备回滚方案
    • 监控使用情况和性能

更多视频教程www.fgedu.net.cn

学习交流加群风哥微信: itpux-com

学习交流加群风哥QQ113257174

风哥提示：自定义索引访问方法是PostgreSQL强大扩展性的体现，但开发复杂度高，需要充分评估必要性，建议优先考虑使用或扩展内置索引访问方法。

更多学习教程公众号风哥教程itpux_com

from PostgreSQL视频:www.itpux.com

本文由风哥教程整理发布,仅用于学习测试使用,转载注明出处:http://www.fgedu.net.cn/10327.html

相关推荐

联系我们

在线咨询：点击这里给我发消息

微信号：itpux-com

工作日：9:30-18:30，节假日休息