↑↓ 选择 ↵ 打开 ⌫ 改范围 完整检索页

pgsql.cc 提供对 postgresql.org 官网内容的中文翻译,由 Pigsty 团队维护。

受支持版本: 当前版本 (18) / 17 / 16 / 15 / 14
测试与开发版本: 19 / devel
不受支持的版本: 13 / 12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4 / 7.3 / 7.2
历史版本PostgreSQL 8.4 已于 2014 年 7 月结束社区维护,本页译文保留供仍在使用旧版本的读者参考。新系统请看当前版本。

第 41 章 PL/Python - Python 过程语言

PL/Python 过程语言允许用 Python 语言编写 PostgreSQL 函数。

要在某个特定数据库中安装 PL/Python,使用 createlang plpythonu dbname。

提示

如果把某种语言安装到template1中,之后创建的所有数据库都会自动安装该语言。

从 PostgreSQL 7.4 起,PL/Python 只能作为一种“不受信任的”语言使用(这意味着它不提供任何机制来限制用户能在其中做什么)。因此其名称被改为 plpythonu。如果将来能在 Python 中开发出新的安全执行机制,受信任的变体 plpython 可能会重新出现。

注意

源码包用户必须在安装过程中专门启用 PL/Python 的构建(更多信息请参阅安装说明)。二进制包用户则可能会在单独的子包中找到 PL/Python。

41.1. PL/Python 函数 #

PL/Python 中的函数通过标准的CREATE FUNCTION语法声明:

CREATE FUNCTION funcname (argument-list)
  RETURNS return-type
AS $$
  # PL/Python function body
$$ LANGUAGE plpythonu;

函数体就是一段 Python 脚本。调用函数时,参数作为列表 args[] 的元素传入;命名参数还会作为普通变量传给 Python 脚本。结果以通常的方式从 Python 代码中返回,使用 return 或(对于结果集语句)yield。

例如,一个返回两个整数中较大值的函数可以定义为:

CREATE FUNCTION pymax (a integer, b integer)
  RETURNS integer
AS $$
  if a > b:
    return a
  return b
$$ LANGUAGE plpythonu;

作为函数体给出的 Python 代码会被转换成一个 Python 函数。例如,上面的定义会得到:

def __plpython_procedure_pymax_23456():
  if a > b:
    return a
  return b

这里假定 PostgreSQL 给该函数分配的 OID 是 23456。

PostgreSQL 的函数参数可以在全局列表 args 中获得。在上面的 pymax 示例中,args[0] 包含作为第一个参数传入的内容,args[1] 包含第二个参数的值。或者,也可以像上面的示例那样使用命名参数。使用命名参数通常可读性更好。

如果把一个 SQL 空值传给函数,该参数值在 Python 中会表现为 None。上面的函数定义对空值输入会返回错误的答案。我们可以在函数定义中加上 STRICT,让 PostgreSQL 做更合理的事情:如果传入了空值,函数根本不会被调用,而是自动返回空结果。或者,我们也可以在函数体中检查空值输入:

CREATE FUNCTION pymax (a integer, b integer)
  RETURNS integer
AS $$
  if (a is None) or (b is None):
    return None
  if a > b:
    return a
  return b
$$ LANGUAGE plpythonu;

如上所示,要让 PL/Python 函数返回 SQL 空值,返回值 None 即可。无论函数是否为严格函数,都可以这样做。

复合类型的参数会作为 Python 映射传给函数。映射的元素名就是复合类型的属性名。如果传入行中的某个属性为空值,它在映射中的值就是 None。下面是一个例子:

CREATE TABLE employee (
  name text,
  salary integer,
  age integer
);

CREATE FUNCTION overpaid (e employee)
  RETURNS boolean
AS $$
  if e["salary"] > 200000:
    return True
  if (e["age"] < 30) and (e["salary"] > 100000):
    return True
  return False
$$ LANGUAGE plpythonu;

有多种方法可以从 Python 函数返回行类型或复合类型。以下示例假定我们有:

CREATE TYPE named_value AS (
  name   text,
  value  integer
);

复合结果可以作为以下形式返回:

序列类型(元组或列表,但不能是集合,因为集合不可索引)

返回的序列对象的项数必须与复合结果类型的字段数相同。索引为 0 的项赋给复合类型的第一个字段,1 赋给第二个,依此类推。例如:

CREATE FUNCTION make_pair (name text, value integer)
  RETURNS named_value
AS $$
  return [ name, value ]
  # or alternatively, as tuple: return ( name, value )
$$ LANGUAGE plpythonu;

要让某一列返回 SQL 空值,在相应位置插入 None。

映射(字典)

结果类型中每一列的值,都使用列名作为键从映射中取得。例如:

CREATE FUNCTION make_pair (name text, value integer)
  RETURNS named_value
AS $$
  return { "name": name, "value": value }
$$ LANGUAGE plpythonu;

多余的字典键/值对会被忽略。缺失的键被视为错误。 要让某一列返回 SQL 空值,以相应的列名作为键插入 None。

对象(任何提供 __getattr__ 方法的对象)

其工作方式与映射相同。 例如:

CREATE FUNCTION make_pair (name text, value integer)
  RETURNS named_value
AS $$
  class named_value:
    def __init__ (self, n, v):
      self.name = n
      self.value = v
  return named_value(name, value)

  # or simply
  class nv: pass
  nv.name = name
  nv.value = value
  return nv
$$ LANGUAGE plpythonu;

如果你不提供返回值,Python 会返回默认的 None。PL/Python 会把 Python 的 None 转换为 SQL 空值。

PL/Python 函数也可以返回标量类型或复合类型的集合。实现方式有多种,因为返回的对象在内部会被转换成一个迭代器。以下示例假定我们有复合类型:

CREATE TYPE greeting AS (
  how text,
  who text
);

集合结果可以作为以下形式返回:

序列类型(元组、列表、集合)
CREATE FUNCTION greet (how text)
  RETURNS SETOF greeting
AS $$
  # return tuple containing lists as composite types
  # all other combinations work also
  return ( [ how, "World" ], [ how, "PostgreSQL" ], [ how, "PL/Python" ] )
$$ LANGUAGE plpythonu;
迭代器(任何提供 __iter__ 和 next 方法的对象)
CREATE FUNCTION greet (how text)
  RETURNS SETOF greeting
AS $$
  class producer:
    def __init__ (self, how, who):
      self.how = how
      self.who = who
      self.ndx = -1

    def __iter__ (self):
      return self

    def next (self):
      self.ndx += 1
      if self.ndx == len(self.who):
        raise StopIteration
      return ( self.how, self.who[self.ndx] )

  return producer(how, [ "World", "PostgreSQL", "PL/Python" ] )
$$ LANGUAGE plpythonu;
生成器(yield)
CREATE FUNCTION greet (how text)
  RETURNS SETOF greeting
AS $$
  for who in [ "World", "PostgreSQL", "PL/Python" ]:
    yield ( how, who )
$$ LANGUAGE plpythonu;

警告

目前,由于 Python 的 缺陷 #1483133, 某些调试版本的 Python 2.4(配置并编译时使用了 --with-pydebug 选项) 在使用迭代器返回集合结果时会导致 PostgreSQL 服务器崩溃。 未打补丁的 Fedora 4 版本包含此缺陷。在正式版本的 Python 或打过补丁的 Fedora 4 上不会发生。

全局字典 SD 可用于在函数调用之间存储数据。这个变量是私有的静态数据。全局字典 GD 是公开数据,对一次会话中的所有 Python 函数可用。请谨慎使用。

每个函数在 Python 解释器中得到自己的执行环境,因此 myfunc 的全局数据和函数参数对 myfunc2 不可用。例外是上面提到的 GD 字典中的数据。

提交更正

译文有误、术语不当或页面显示问题,请到译文仓库 pgsty/pgdoc 报告译文问题。 英文原文本身的问题,请在当前版本的对应页面向上游反馈;上游不再修订已结束维护的版本。