begriffs open source - ai-pg/blob - full-docs/src/sgml/man7/CREATE_LANGUAGE.7

   1 '\" t
   2 .\"     Title: CREATE LANGUAGE
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "CREATE LANGUAGE" "7" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 CREATE_LANGUAGE \- define a new procedural language
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE \fIname\fR
  36     HANDLER \fIcall_handler\fR [ INLINE \fIinline_handler\fR ] [ VALIDATOR \fIvalfunction\fR ]
  37 CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE \fIname\fR
  38 .fi
  39 .SH "DESCRIPTION"
  40 .PP
  41 \fBCREATE LANGUAGE\fR
  42 registers a new procedural language with a
  43 PostgreSQL
  44 database\&. Subsequently, functions and procedures can be defined in this new language\&.
  45 .PP
  46 \fBCREATE LANGUAGE\fR
  47 effectively associates the language name with handler function(s) that are responsible for executing functions written in the language\&. Refer to
  48 Chapter\ \&57
  49 for more information about language handlers\&.
  50 .PP
  51 \fBCREATE OR REPLACE LANGUAGE\fR
  52 will either create a new language, or replace an existing definition\&. If the language already exists, its parameters are updated according to the command, but the language\*(Aqs ownership and permissions settings do not change, and any existing functions written in the language are assumed to still be valid\&.
  53 .PP
  54 One must have the
  55 PostgreSQL
  56 superuser privilege to register a new language or change an existing language\*(Aqs parameters\&. However, once the language is created it is valid to assign ownership of it to a non\-superuser, who may then drop it, change its permissions, rename it, or assign it to a new owner\&. (Do not, however, assign ownership of the underlying C functions to a non\-superuser; that would create a privilege escalation path for that user\&.)
  57 .PP
  58 The form of
  59 \fBCREATE LANGUAGE\fR
  60 that does not supply any handler function is obsolete\&. For backwards compatibility with old dump files, it is interpreted as
  61 \fBCREATE EXTENSION\fR\&. That will work if the language has been packaged into an extension of the same name, which is the conventional way to set up procedural languages\&.
  62 .SH "PARAMETERS"
  63 .PP
  64 TRUSTED
  65 .RS 4
  66 TRUSTED
  67 specifies that the language does not grant access to data that the user would not otherwise have\&. If this key word is omitted when registering the language, only users with the
  68 PostgreSQL
  69 superuser privilege can use this language to create new functions\&.
  70 .RE
  71 .PP
  72 PROCEDURAL
  73 .RS 4
  74 This is a noise word\&.
  75 .RE
  76 .PP
  77 \fIname\fR
  78 .RS 4
  79 The name of the new procedural language\&. The name must be unique among the languages in the database\&.
  80 .RE
  81 .PP
  82 HANDLER \fIcall_handler\fR
  83 .RS 4
  84 \fIcall_handler\fR
  85 is the name of a previously registered function that will be called to execute the procedural language\*(Aqs functions\&. The call handler for a procedural language must be written in a compiled language such as C with version 1 call convention and registered with
  86 PostgreSQL
  87 as a function taking no arguments and returning the
  88 language_handler
  89 type, a placeholder type that is simply used to identify the function as a call handler\&.
  90 .RE
  91 .PP
  92 INLINE \fIinline_handler\fR
  93 .RS 4
  94 \fIinline_handler\fR
  95 is the name of a previously registered function that will be called to execute an anonymous code block (\fBDO\fR
  96 command) in this language\&. If no
  97 \fIinline_handler\fR
  98 function is specified, the language does not support anonymous code blocks\&. The handler function must take one argument of type
  99 internal, which will be the
 100 \fBDO\fR
 101 command\*(Aqs internal representation, and it will typically return
 102 void\&. The return value of the handler is ignored\&.
 103 .RE
 104 .PP
 105 VALIDATOR \fIvalfunction\fR
 106 .RS 4
 107 \fIvalfunction\fR
 108 is the name of a previously registered function that will be called when a new function in the language is created, to validate the new function\&. If no validator function is specified, then a new function will not be checked when it is created\&. The validator function must take one argument of type
 109 oid, which will be the OID of the to\-be\-created function, and will typically return
 110 void\&.
 111 .sp
 112 A validator function would typically inspect the function body for syntactical correctness, but it can also look at other properties of the function, for example if the language cannot handle certain argument types\&. To signal an error, the validator function should use the
 113 \fBereport()\fR
 114 function\&. The return value of the function is ignored\&.
 115 .RE
 116 .SH "NOTES"
 117 .PP
 118 Use
 119 \fBDROP LANGUAGE\fR
 120 to drop procedural languages\&.
 121 .PP
 122 The system catalog
 123 pg_language
 124 (see
 125 Section\ \&52.29) records information about the currently installed languages\&. Also, the
 126 psql
 127 command
 128 \fB\edL\fR
 129 lists the installed languages\&.
 130 .PP
 131 To create functions in a procedural language, a user must have the
 132 USAGE
 133 privilege for the language\&. By default,
 134 USAGE
 135 is granted to
 136 PUBLIC
 137 (i\&.e\&., everyone) for trusted languages\&. This can be revoked if desired\&.
 138 .PP
 139 Procedural languages are local to individual databases\&. However, a language can be installed into the
 140 template1
 141 database, which will cause it to be available automatically in all subsequently\-created databases\&.
 142 .SH "EXAMPLES"
 143 .PP
 144 A minimal sequence for creating a new procedural language is:
 145 .sp
 146 .if n \{\
 147 .RS 4
 148 .\}
 149 .nf
 150 CREATE FUNCTION plsample_call_handler() RETURNS language_handler
 151     AS \*(Aq$libdir/plsample\*(Aq
 152     LANGUAGE C;
 153 CREATE LANGUAGE plsample
 154     HANDLER plsample_call_handler;
 155 .fi
 156 .if n \{\
 157 .RE
 158 .\}
 159 .sp
 160 Typically that would be written in an extension\*(Aqs creation script, and users would do this to install the extension:
 161 .sp
 162 .if n \{\
 163 .RS 4
 164 .\}
 165 .nf
 166 CREATE EXTENSION plsample;
 167 .fi
 168 .if n \{\
 169 .RE
 170 .\}
 171 .SH "COMPATIBILITY"
 172 .PP
 173 \fBCREATE LANGUAGE\fR
 174 is a
 175 PostgreSQL
 176 extension\&.
 177 .SH "SEE ALSO"
 178 ALTER LANGUAGE (\fBALTER_LANGUAGE\fR(7)), CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7)), DROP LANGUAGE (\fBDROP_LANGUAGE\fR(7)), \fBGRANT\fR(7), \fBREVOKE\fR(7)