- url="https://www.python.org/dev/peps/pep-0394/">PEP 394 regarding the
- naming and transitioning of the python command.
-
-
- It depends on the build configuration or the installed packages
- whether PL/Python for Python 2 or Python 3 or both are available.
-
-
-
- The built variant depends on which Python version was found during
- the installation or which version was explicitly set using
- the PYTHON environment variable;
- see . To make both variants of
- PL/Python available in one installation, the source tree has to be
- configured and built twice.
-
-
-
- This results in the following usage and migration strategy:
-
-
-
- Existing users and users who are currently not interested in
- Python 3 use the language name plpythonu and
- don't have to change anything for the foreseeable future. It is
- recommended to gradually future-proof
the code
- via migration to Python 2.6/2.7 to simplify the eventual
- migration to Python 3.
-
-
- In practice, many PL/Python functions will migrate to Python 3
- with few or no changes.
-
-
-
-
- Users who know that they have heavily Python 2 dependent code
- and don't plan to ever change it can make use of
- the plpython2u language name. This will
- continue to work into the very distant future, until Python 2
- support might be completely dropped by PostgreSQL.
-
-
-
-
- Users who want to dive into Python 3 can use
- the plpython3u language name, which will keep
- working forever by today's standards. In the distant future,
- when Python 3 might become the default, they might like to
- remove the 3
for aesthetic reasons.
-
-
-
-
- Daredevils, who want to build a Python-3-only operating system
- environment, can change the contents of
- plpythonu's extension control and script files
- to make plpythonu be equivalent
- to plpython3u, keeping in mind that this
- would make their installation incompatible with most of the rest
- of the world.
-
-
-
-
-
- See also the
- New In Python 3.0 for more information about porting to
- Python 3.
-
-
- It is not allowed to use PL/Python based on Python 2 and PL/Python
- based on Python 3 in the same session, because the symbols in the
- dynamic modules would clash, which could result in crashes of the
- PostgreSQL server process. There is a check that prevents mixing
- Python major versions in a session, which will abort the session if
- a mismatch is detected. It is possible, however, to use both
- PL/Python variants in the same database, from separate sessions.
-
-
-
PL/Python Functions
RETURNS return-type
AS $$
# PL/Python function body
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
if a > b:
return a
return b
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
The Python code that is given as the body of the function definition
AS $$
x = x.strip() # error
return x
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
because assigning to x
makes x a local variable for the entire block,
global x
x = x.strip() # ok now
return x
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
But it is advisable not to rely on this implementation detail of
PL/Python. It is better to treat the function parameters as
- PostgreSQL smallint and int are
- converted to Python int.
- PostgreSQL bigint and oid are converted
- to long in Python 2 and to int in
- Python 3.
+ PostgreSQL smallint, int, bigint
+ and oid are converted to Python int.
- PostgreSQL bytea is converted to
- Python str in Python 2 and to bytes
- in Python 3. In Python 2, the string should be treated as a
- byte sequence without any character encoding.
+ PostgreSQL bytea is converted to Python bytes.
- All other data types, including the PostgreSQL character string
- types, are converted to a Python str. In Python
- 2, this string will be in the PostgreSQL server encoding; in
- Python 3, it will be a Unicode string like all strings.
+ All other data types, including the PostgreSQL character string types,
+ are converted to a Python str (in Unicode like all Python
+ strings).
- When the PostgreSQL return type is bytea, the
- return value will be converted to a string (Python 2) or bytes
- (Python 3) using the respective Python built-ins, with the
- result being converted to bytea.
+ When the PostgreSQL return type is bytea, the return value
+ will be converted to Python bytes using the respective
+ Python built-ins, with the result being converted to
+ bytea.
- Strings in Python 2 are required to be in the PostgreSQL server
- encoding when they are passed to PostgreSQL. Strings that are
- not valid in the current server encoding will raise an error,
- but not all encoding mismatches can be detected, so garbage
- data can still result when this is not done correctly. Unicode
- strings are converted to the correct encoding automatically, so
- it can be safer and more convenient to use those. In Python 3,
- all strings are Unicode strings.
+ Strings are automatically converted to the PostgreSQL server encoding
+ when they are passed to PostgreSQL.
if a > b:
return a
return b
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
As shown above, to return an SQL null value from a PL/Python
RETURNS int[]
AS $$
return [1, 2, 3, 4, 5]
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
SELECT return_arr();
- return_arr
+ return_arr
-------------
{1,2,3,4,5}
(1 row)
CREATE FUNCTION test_type_conversion_array_int4(x int4[]) RETURNS int4[] AS $$
plpy.info(x, type(x))
return x
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
SELECT * FROM test_type_conversion_array_int4(ARRAY[[1,2,3],[4,5,6]]);
INFO: ([[1, 2, 3], [4, 5, 6]], <type 'list'>)
- test_type_conversion_array_int4
+ test_type_conversion_array_int4
---------------------------------
{{1,2,3},{4,5,6}}
(1 row)
RETURNS varchar[]
AS $$
return "hello"
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
SELECT return_str_arr();
return_str_arr
if (e["age"] < 30) and (e["salary"] > 100000):
return True
return False
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
AS $$
return ( name, value )
# or alternatively, as list: return [ name, value ]
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
To return an SQL null for any column, insert None at
RETURNS named_value
AS $$
return { "name": name, "value": value }
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
Any extra dictionary key/value pairs are ignored. Missing keys are
nv.name = name
nv.value = value
return nv
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
CREATE FUNCTION multiout_simple(OUT i integer, OUT j integer) AS $$
return (1, 2)
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
SELECT * FROM multiout_simple();
CREATE PROCEDURE python_triple(INOUT a integer, INOUT b integer) AS $$
return (a * 3, b * 3)
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
CALL python_triple(5, 10);
# return tuple containing lists as composite types
# all other combinations work also
return ( [ how, "World" ], [ how, "PostgreSQL" ], [ how, "PL/Python" ] )
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
return ( self.how, self.who[self.ndx] )
return producer(how, [ "World", "PostgreSQL", "PL/Python" ])
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
AS $$
for who in [ "World", "PostgreSQL", "PL/Python" ]:
yield ( how, who )
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
CREATE FUNCTION multiout_simple_setof(n integer, OUT integer, OUT integer) RETURNS SETOF record AS $$
return [(1, 2)] * n
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
SELECT * FROM multiout_simple_setof(3);
DO $$
# PL/Python code
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
An anonymous code block receives no arguments, and whatever value it
plan = plpy.prepare("SELECT 1")
SD["plan"] = plan
# rest of function
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
if row['num'] % 2:
odd += 1
return odd
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
CREATE FUNCTION count_odd_fetch(batch_size integer) RETURNS integer AS $$
odd = 0
if row['num'] % 2:
odd += 1
return odd
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
CREATE FUNCTION count_odd_prepared() RETURNS integer AS $$
odd = 0
rows = list(plpy.cursor(plan, [2])) # or: = list(plan.cursor([2]))
return len(rows)
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
return "something went wrong"
else:
return "Joe added"
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
return "other error, SQLSTATE %s" % e.sqlstate
else:
return "fraction inserted"
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
Note that because all exceptions from
the plpy.spiexceptions module inherit
result = "funds transferred correctly"
plan = plpy.prepare("INSERT INTO operations (result) VALUES ($1)", ["text"])
plpy.execute(plan, [result])
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
If the second UPDATE statement results in an
exception being raised, this function will report the error, but
result = "funds transferred correctly"
plan = plpy.prepare("INSERT INTO operations (result) VALUES ($1)", ["text"])
plpy.execute(plan, [result])
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
Note that the use of try/catch is still
required. Otherwise the exception would propagate to the top of
to be rolled back.
-
-
-
Older Python Versions
-
- Context managers syntax using the with keyword
- is available by default in Python 2.6. For compatibility with
- older Python versions, you can call the
- subtransaction manager's __enter__ and
- __exit__ functions using the
- enter and exit convenience
- aliases. The example function that transfers funds could be
- written as:
-CREATE FUNCTION transfer_funds_old() RETURNS void AS $$
-try:
- subxact = plpy.subtransaction()
- subxact.enter()
- try:
- plpy.execute("UPDATE accounts SET balance = balance - 100 WHERE account_name = 'joe'")
- plpy.execute("UPDATE accounts SET balance = balance + 100 WHERE account_name = 'mary'")
- except:
- import sys
- subxact.exit(*sys.exc_info())
- raise
- else:
- subxact.exit(None, None, None)
-except plpy.SPIError as e:
- result = "error transferring funds: %s" % e.args
-else:
- result = "funds transferred correctly"
-
-plan = plpy.prepare("INSERT INTO operations (result) VALUES ($1)", ["text"])
-plpy.execute(plan, [result])
-$$ LANGUAGE plpythonu;
-
-
-
Here is an example:
CREATE PROCEDURE transaction_test1()
-LANGUAGE plpythonu
+LANGUAGE plpython3u
AS $$
for i in range(0, 10):
plpy.execute("INSERT INTO test1 (a) VALUES (%d)" % i)
plpy.error("custom exception message",
detail="some info about exception",
hint="hint for users")
-$$ LANGUAGE plpythonu;
+$$ LANGUAGE plpython3u;
=# SELECT raise_custom_exception();
ERROR: plpy.Error: custom exception message
+
+
Python 2 vs. Python 3
+
+ PL/Python supports only Python 3. Past versions of
+
PostgreSQL supported Python 2, using the
+ plpythonu and plpython2u language
+ names.
+
+
+
Environment Variables
projects / postgresql.git / commitdiff