create_language(7)

1CREATE LANGUAGE(7)               SQL Commands               CREATE LANGUAGE(7)
2
3
4

NAME

6       CREATE LANGUAGE - define a new procedural language
7
8

SYNOPSIS

10       CREATE [ PROCEDURAL ] LANGUAGE name
11       CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE name
12           HANDLER call_handler [ VALIDATOR valfunction ]
13
14

DESCRIPTION

16       Using  CREATE LANGUAGE, a PostgreSQL user can register a new procedural
17       language with a PostgreSQL database. Subsequently, functions and  trig‐
18       ger procedures can be defined in this new language.
19
20       CREATE  LANGUAGE  effectively  associates the language name with a call
21       handler that is responsible for executing functions written in the lan‐
22       guage.  Refer  to  in the documentation for more information about lan‐
23       guage call handlers.
24
25       There are two forms of the CREATE LANGUAGE command.  In the first form,
26       the  user supplies just the name of the desired language, and the Post‐
27       greSQL server consults the pg_pltemplate system  catalog  to  determine
28       the  correct parameters. In the second form, the user supplies the lan‐
29       guage parameters along with the language name.  The second form can  be
30       used  to  create  a  language that is not defined in pg_pltemplate, but
31       this approach is considered obsolescent.
32
33       When the server finds an entry in the  pg_pltemplate  catalog  for  the
34       given  language  name, it will use the catalog data even if the command
35       includes language parameters. This behavior simplifies loading  of  old
36       dump  files,  which are likely to contain out-of-date information about
37       language support functions.
38
39       Ordinarily, the user must have the PostgreSQL  superuser  privilege  to
40       register  a new language. However, the owner of a database can register
41       a new language within that database if the language is  listed  in  the
42       pg_pltemplate  catalog  and is marked as allowed to be created by data‐
43       base owners (tmpldbacreate is true). The default is that  trusted  lan‐
44       guages  can  be created by database owners, but this can be adjusted by
45       superusers by modifying the contents of pg_pltemplate.  The creator  of
46       a  language  becomes  its  owner  and  can later drop it, rename it, or
47       assign it to a new owner.
48

PARAMETERS

50       TRUSTED
51              TRUSTED specifies that the call  handler  for  the  language  is
52              safe,  that is, it does not offer an unprivileged user any func‐
53              tionality to bypass access restrictions. If  this  key  word  is
54              omitted when registering the language, only users with the Post‐
55              greSQL superuser privilege can use this language to  create  new
56              functions.
57
58       PROCEDURAL
59              This is a noise word.
60
61       name   The  name  of  the new procedural language. The language name is
62              case insensitive. The name must be unique among the languages in
63              the database.
64
65              For  backward  compatibility, the name can be enclosed by single
66              quotes.
67
68       HANDLER call_handler
69              call_handler is the name of  a  previously  registered  function
70              that  will  be  called  to execute the procedural language func‐
71              tions. The call handler for a procedural language must be  writ‐
72              ten in a compiled language such as C with version 1 call conven‐
73              tion and registered with PostgreSQL  as  a  function  taking  no
74              arguments and returning the language_handler type, a placeholder
75              type that is simply used to identify the function as a call han‐
76              dler.
77
78       VALIDATOR valfunction
79              valfunction is the name of a previously registered function that
80              will be called when a new function in the language  is  created,
81              to validate the new function.  If no validator function is spec‐
82              ified, then a new function will not be checked when it  is  cre‐
83              ated.   The  validator  function  must take one argument of type
84              oid, which will be the OID of the  to-be-created  function,  and
85              will typically return void.
86
87              A  validator  function would typically inspect the function body
88              for syntactical correctness, but it can also look at other prop‐
89              erties  of the function, for example if the language cannot han‐
90              dle certain argument types. To signal an  error,  the  validator
91              function  should use the ereport() function. The return value of
92              the function is ignored.
93
94       The TRUSTED option and the support function name(s) are ignored if  the
95       server has an entry for the specified language name in pg_pltemplate.
96

NOTES

98       The  createlang(1)  program  is a simple wrapper around the CREATE LAN‐
99       GUAGE command. It eases installation of procedural languages  from  the
100       shell command line.
101
102       Use  DROP  LANGUAGE  [drop_language(7)],  or better yet the droplang(1)
103       program, to drop procedural languages.
104
105       The system catalog  pg_language  (see  in  the  documentation)  records
106       information  about  the currently installed languages. Also, createlang
107       has an option to list the installed languages.
108
109       To create functions in a procedural language,  a  user  must  have  the
110       USAGE  privilege for the language. By default, USAGE is granted to PUB‐
111       LIC (i.e., everyone) for trusted languages.  This  can  be  revoked  if
112       desired.
113
114       Procedural  languages  are  local  to individual databases.  However, a
115       language can be installed into the template1 database, which will cause
116       it to be available automatically in all subsequently-created databases.
117
118       The  call  handler  function  and  the validator function (if any) must
119       already exist if the server does not have an entry for the language  in
120       pg_pltemplate.  But  when  there  is  an  entry, the functions need not
121       already exist; they will be automatically defined if not present in the
122       database.  (This might result in CREATE LANGUAGE failing, if the shared
123       library that implements the language is not available in the  installa‐
124       tion.)
125
126       In  PostgreSQL versions before 7.3, it was necessary to declare handler
127       functions as returning the placeholder type opaque,  rather  than  lan‐
128       guage_handler.   To  support loading of old dump files, CREATE LANGUAGE
129       will accept a function declared as returning opaque, but it will  issue
130       a  notice  and  change  the  function's  declared  return  type to lan‐
131       guage_handler.
132

EXAMPLES

134       The preferred way of creating any of the standard procedural  languages
135       is just:
136
137       CREATE LANGUAGE plpgsql;
138
139
140       For  a language not known in the pg_pltemplate catalog, a sequence such
141       as this is needed:
142
143       CREATE FUNCTION plsample_call_handler() RETURNS language_handler
144           AS '$libdir/plsample'
145           LANGUAGE C;
146       CREATE LANGUAGE plsample
147           HANDLER plsample_call_handler;
148
149

COMPATIBILITY

151       CREATE LANGUAGE is a PostgreSQL extension.
152