diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile index e1ba2796c33..42551d24074 100644 --- a/doc/src/sgml/Makefile +++ b/doc/src/sgml/Makefile @@ -2,7 +2,7 @@ # # PostgreSQL documentation makefile # -# $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.56 2003/03/25 16:15:35 petere Exp $ +# $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.57 2003/04/10 01:22:44 petere Exp $ # #---------------------------------------------------------------------------- @@ -77,7 +77,7 @@ all: html .PHONY: html -html: postgres.sgml $(ALLSGML) stylesheet.dsl catalogs.gif connections.gif +html: postgres.sgml $(ALLSGML) stylesheet.dsl @rm -f *.html $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -i output-html -t sgml $< @@ -114,8 +114,6 @@ features-unsupported.sgml: $(top_srcdir)/src/backend/catalog/sql_feature_package %.rtf: %.sgml $(ALLSGML) stylesheet.dsl $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t rtf -V rtf-backend -i output-print $< -postgres.rtf: catalogs.gif connections.gif - # TeX # Regular TeX and pdfTeX have slightly differing requirements, so we # need to distinguish the path we're taking. @@ -123,13 +121,9 @@ postgres.rtf: catalogs.gif connections.gif %.tex-ps: %.sgml $(ALLSGML) stylesheet.dsl $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t tex -V tex-backend -i output-print -V texdvi-output -o $@ $< -postgres.tex-ps: catalogs.eps connections.eps - %.tex-pdf: %.sgml $(ALLSGML) stylesheet.dsl $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t tex -V tex-backend -i output-print -V texpdf-output -o $@ $< -postgres.tex-pdf: catalogs.pdf connections.pdf - %.dvi: %.tex-ps @rm -f $*.aux $*.log jadetex $< diff --git a/doc/src/sgml/arch-pg.sgml b/doc/src/sgml/arch-pg.sgml deleted file mode 100644 index 21dbf58685e..00000000000 --- a/doc/src/sgml/arch-pg.sgml +++ /dev/null @@ -1,116 +0,0 @@ - - Architecture - - -<ProductName>PostgreSQL</ProductName> Architectural Concepts - - - Before we begin, you should understand the basic - PostgreSQL system architecture. Understanding how the - parts of PostgreSQL interact will make the next chapter - somewhat clearer. - In database jargon, PostgreSQL uses a simple "process - per-user" client/server model. A PostgreSQL session - consists of the following cooperating Unix processes (programs): - - - - - A supervisory daemon process (the postmaster), - - - - - the user's frontend application (e.g., the psql program), and - - - - - one or more backend database servers (the postgres process itself). - - - - - - A single postmaster manages a given collection of - databases on a single host. Such a collection of - databases is called a cluster (of databases). A frontend - application that wishes to access a given database - within a cluster makes calls to an interface library (e.g., libpq) - that is linked into the application. - The library sends user requests over the network to the - postmaster -((a)), -which in turn starts a new backend server process -((b)) - -
- How a connection is established - - - - - - -
- - and connects the frontend process to the new server -((c)). -From that point on, the frontend process and the backend - server communicate without intervention by the - postmaster. Hence, the postmaster is always running, waiting - for connection requests, whereas frontend and backend processes - come and go. The libpq library allows a single - frontend to make multiple connections to backend processes. - However, each backend process is a single-threaded process that can - only execute one query at a time; so the communication over any one - frontend-to-backend connection is single-threaded. - - - - One implication of this architecture is that the - postmaster and the backend always run on the - same machine (the database server), while the frontend - application may run anywhere. You should keep this - in mind, - because the files that can be accessed on a client - machine may not be accessible (or may only be accessed - using a different path name) on the database server - machine. - - - - You should also be aware that the postmaster and - postgres servers run with the user ID of the PostgreSQL - superuser. -Note that the PostgreSQL superuser does not -have to be any particular user (e.g., a user named -postgres), although many systems are installed that way. -Furthermore, the PostgreSQL superuser should -definitely not be the Unix superuser, root! -It is safest if the PostgreSQL superuser is an -ordinary, unprivileged user so far as the surrounding Unix system is -concerned. - In any case, all files relating to a database should belong to - this Postgres superuser. - - - - - diff --git a/doc/src/sgml/dfunc.sgml b/doc/src/sgml/dfunc.sgml index ae30dd1fa96..3898a2bc176 100644 --- a/doc/src/sgml/dfunc.sgml +++ b/doc/src/sgml/dfunc.sgml @@ -1,5 +1,5 @@ @@ -14,7 +14,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/dfunc.sgml,v 1.24 2003/03/25 16:15:35 peter - For more information you should read the documentation of your + For information beyond what is contained in this section + you should read the documentation of your operating system, in particular the manual pages for the C compiler, cc, and the link editor, ld. In addition, the PostgreSQL source code @@ -47,13 +48,10 @@ $Header: /cvsroot/pgsql/doc/src/sgml/dfunc.sgml,v 1.24 2003/03/25 16:15:35 peter here. - - @@ -160,7 +158,7 @@ cc -shared -o foo.so foo.o MacOS X - Here is a sample. It assumes the developer tools are installed. + Here is an example. It assumes the developer tools are installed. cc -c foo.c cc -bundle -flat_namespace -undefined suppress -o foo.so foo.o @@ -271,17 +269,13 @@ gcc -shared -o foo.so foo.o - - If you want to package your extension modules for wide distribution - you should consider using GNU - Libtool for building shared libraries. It - encapsulates the platform differences into a general and powerful - interface. Serious packaging also requires considerations about - library versioning, symbol resolution methods, and other issues. + If this is too complicated for you, you should consider using + GNU + Libtool, which hides the platform differences + behind a uniform interface. diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml index 1367f16d784..60ea4acb469 100644 --- a/doc/src/sgml/extend.sgml +++ b/doc/src/sgml/extend.sgml @@ -1,9 +1,9 @@ - Extending <acronym>SQL</acronym>: An Overview + Extending <acronym>SQL</acronym> extending SQL @@ -17,22 +17,22 @@ $Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.20 2003/03/25 16:15:36 pete - functions + functions (starting in ) - data types + data types (starting in ) - operators + operators (starting in ) - aggregates + aggregates (starting in ) @@ -44,30 +44,29 @@ $Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.20 2003/03/25 16:15:36 pete PostgreSQL is extensible because its operation is catalog-driven. If you are familiar with standard - relational systems, you know that they store information + relational database systems, you know that they store information about databases, tables, columns, etc., in what are commonly known as system catalogs. (Some systems call this the data dictionary). The catalogs appear to the user as tables like any other, but the DBMS stores its internal bookkeeping in them. One key difference - between PostgreSQL and standard relational systems is + between PostgreSQL and standard relational database systems is that PostgreSQL stores much more information in its - catalogs -- not only information about tables and columns, - but also information about its types, functions, access + catalogs: not only information about tables and columns, + but also information about data types, functions, access methods, and so on. These tables can be modified by - the user, and since PostgreSQL bases its internal operation + the user, and since PostgreSQL bases its operation on these tables, this means that PostgreSQL can be extended by users. By comparison, conventional database systems can only be extended by changing hardcoded - procedures within the DBMS or by loading modules + procedures in the source code or by loading modules specially written by the DBMS vendor. - PostgreSQL is also unlike most other data managers in - that the server can incorporate user-written code into + The PostgreSQL server can moreover incorporate user-written code into itself through dynamic loading. That is, the user can - specify an object code file (e.g., a shared library) that implements a new type or function + specify an object code file (e.g., a shared library) that implements a new type or function, and PostgreSQL will load it as required. Code written in SQL is even more trivial to add to the server. This ability to modify its operation on the fly makes @@ -89,195 +88,25 @@ $Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.20 2003/03/25 16:15:36 pete - The PostgreSQL type system - can be broken down in several ways. - Types are divided into base types and composite types. + Data types are divided into base types and composite types. Base types are those, like int4, that are implemented in a language such as C. They generally correspond to - what are often known as abstract data types; PostgreSQL + what are often known as abstract data types. PostgreSQL can only operate on such types through methods provided by the user and only understands the behavior of such types to the extent that the user describes them. Composite types are created whenever the user creates a - table. - - - - PostgreSQL stores these types - in only one way (within the - file that stores all rows of a table) but the + table. The user can look inside at the attributes of these types - from the query language and optimize their retrieval by - (for example) defining indexes on the attributes. - PostgreSQL base types are further - divided into built-in - types and user-defined types. Built-in types (like - int4) are those that are compiled - into the system. - User-defined types are those created by the user in the - manner to be described later. + from the query language. - - About the <productname>PostgreSQL</productname> System Catalogs + &xfunc; + &xtypes; + &xoper; + &xaggr; - - catalogs - - - - Having introduced the basic extensibility concepts, we - can now take a look at how the catalogs are actually - laid out. You can skip this section for now, but some - later sections will be incomprehensible without the - information given here, so mark this page for later - reference. - All system catalogs have names that begin with - pg_. - The following tables contain information that may be - useful to the end user. (There are many other system - catalogs, but there should rarely be a reason to query - them directly.) - - - PostgreSQL System Catalogs - Catalogs - - - - Catalog Name - Description - - - - - pg_database - databases - - - pg_class - tables - - - pg_attribute - table columns - - - pg_index - indexes - - - pg_proc - procedures/functions - - - pg_type - data types (both base and complex) - - - pg_operator - operators - - - pg_aggregate - aggregate functions - - - pg_am - access methods - - - pg_amop - access method operators - - - pg_amproc - access method support functions - - - pg_opclass - access method operator classes - - - -
- - - -
- The major <productname>PostgreSQL</productname> system catalogs - - - - - -
- - gives a more detailed explanation of these - catalogs and their columns. However, - - shows the major entities and their relationships - in the system catalogs. (Columns that do not refer - to other entities are not shown unless they are part of - a primary key.) - This diagram is more or less incomprehensible until you - actually start looking at the contents of the catalogs - and see how they relate to each other. For now, the - main things to take away from this diagram are as follows: - - - - - In several of the sections that follow, we will - present various join queries on the system - catalogs that display information we need to extend - the system. Looking at this diagram should make - some of these join queries (which are often - three- or four-way joins) more understandable, - because you will be able to see that the - columns used in the queries form foreign keys - in other tables. - - - - - Many different features (tables, columns, - functions, types, access methods, etc.) are - tightly integrated in this schema. A simple - create command may modify many of these catalogs. - - - - - Types and procedures - are central to the schema. - - - - We use the words procedure - and function more or less interchangeably. - - - - Nearly every catalog contains some reference to - rows in one or both of these tables. For - example, PostgreSQL frequently uses type - signatures (e.g., of functions and operators) to - identify unique rows of other catalogs. - - - - - There are many columns and relationships that - have obvious meanings, but there are many - (particularly those that have to do with access - methods) that do not. - - - - - + @@ -57,7 +57,6 @@ - diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index 30849fb9e3c..e207cdacc4e 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -1,5 +1,5 @@ - &arch-pg; &extend; - &xfunc; - &xtypes; - &xoper; - &xaggr; - &rules; &xindex; &indexcost; + &rules; &trigger; &spi; diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml index 1c6c1f4ae39..04029f529b4 100644 --- a/doc/src/sgml/queries.sgml +++ b/doc/src/sgml/queries.sgml @@ -1,4 +1,4 @@ - + Queries @@ -550,6 +550,78 @@ FROM (SELECT * FROM table1) AS alias_name grouping or aggregation. + + + Table Functions + + table function + + + Table functions are functions that produce a set of rows, made up + of either base data types (scalar types) or composite data types + (table rows). They are used like a table, view, or subquery in + the FROM clause of a query. Columns returned by table + functions may be included in SELECT, + JOIN, or WHERE clauses in the same manner + as a table, view, or subquery column. + + + + If a table function returns a base data type, the single result + column is named like the function. If the function returns a + composite type, the result columns get the same names as the + individual attributes of the type. + + + + A table function may be aliased in the FROM clause, + but it also may be left unaliased. If a function is used in the + FROM clause with no alias, the function name is used + as the resulting table name. + + + + Some examples: + +CREATE TABLE foo (fooid int, foosubid int, fooname text); + +CREATE FUNCTION getfoo(int) RETURNS SETOF foo AS ' + SELECT * FROM foo WHERE fooid = $1; +' LANGUAGE SQL; + +SELECT * FROM getfoo(1) AS t1; + +SELECT * FROM foo + WHERE foosubid IN (select foosubid from getfoo(foo.fooid) z + where z.fooid = foo.fooid); + +CREATE VIEW vw_getfoo AS SELECT * FROM getfoo(1); +SELECT * FROM vw_getfoo; + + + + + In some cases it is useful to define table functions that can + return different column sets depending on how they are invoked. + To support this, the table function can be declared as returning + the pseudotype record. When such a function is used in + a query, the expected row structure must be specified in the + query itself, so that the system can know how to parse and plan + the query. Consider this example: + +SELECT * + FROM dblink('dbname=mydb', 'select proname, prosrc from pg_proc') + AS t1(proname name, prosrc text) + WHERE proname LIKE 'bytea%'; + + The dblink function executes a remote query (see + contrib/dblink). It is declared to return + record since it might be used for any kind of query. + The actual column set must be specified in the calling query so + that the parser knows, for example, what * should + expand to. + + @@ -951,7 +1023,7 @@ SELECT DISTINCT ON (expression , DISTINCT ON clause is not part of the SQL standard and is sometimes considered bad style because of the potentially indeterminate nature of its results. With judicious use of - GROUP BY and subselects in FROM the + GROUP BY and subqueries in FROM the construct can be avoided, but it is often the most convenient alternative. diff --git a/doc/src/sgml/xaggr.sgml b/doc/src/sgml/xaggr.sgml index 33bfd962299..101067e1756 100644 --- a/doc/src/sgml/xaggr.sgml +++ b/doc/src/sgml/xaggr.sgml @@ -1,9 +1,9 @@ - - Extending <acronym>SQL</acronym>: Aggregates + + User-Defined Aggregates aggregate functions @@ -22,38 +22,36 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xaggr.sgml,v 1.19 2003/03/25 16:15:38 peter function. The state transition function is just an ordinary function that could also be used outside the context of the aggregate. A final function - can also be specified, in case the desired output of the aggregate + can also be specified, in case the desired result of the aggregate is different from the data that needs to be kept in the running state value. - Thus, in addition to the input and result data types seen by a user + Thus, in addition to the argument and result data types seen by a user of the aggregate, there is an internal state-value data type that - may be different from both the input and result types. + may be different from both the argument and result types. If we define an aggregate that does not use a final function, we have an aggregate that computes a running function of - the column values from each row. Sum is an - example of this kind of aggregate. Sum starts at + the column values from each row. sum is an + example of this kind of aggregate. sum starts at zero and always adds the current row's value to its running total. For example, if we want to make a sum aggregate to work on a data type for complex numbers, we only need the addition function for that data type. - The aggregate definition is: + The aggregate definition would be: - + CREATE AGGREGATE complex_sum ( sfunc = complex_add, basetype = complex, stype = complex, initcond = '(0,0)' ); - - SELECT complex_sum(a) FROM test_complex; complex_sum @@ -61,43 +59,43 @@ SELECT complex_sum(a) FROM test_complex; (34,53.9) - (In practice, we'd just name the aggregate sum, and rely on + (In practice, we'd just name the aggregate sum and rely on PostgreSQL to figure out which kind of sum to apply to a column of type complex.) The above definition of sum will return zero (the initial - state condition) if there are no non-null input values. - Perhaps we want to return NULL in that case instead --- the SQL standard + state condition) if there are no nonnull input values. + Perhaps we want to return null in that case instead --- the SQL standard expects sum to behave that way. We can do this simply by omitting the initcond phrase, so that the initial state - condition is NULL. Ordinarily this would mean that the sfunc - would need to check for a NULL state-condition input, but for + condition is null. Ordinarily this would mean that the sfunc + would need to check for a null state-condition input, but for sum and some other simple aggregates like max and min, - it's sufficient to insert the first non-null input value into + it would be sufficient to insert the first nonnull input value into the state variable and then start applying the transition function - at the second non-null input value. PostgreSQL - will do that automatically if the initial condition is NULL and + at the second nonnull input value. PostgreSQL + will do that automatically if the initial condition is null and the transition function is marked strict (i.e., not to be called - for NULL inputs). + for null inputs). Another bit of default behavior for a strict transition function is that the previous state value is retained unchanged whenever a - NULL input value is encountered. Thus, null values are ignored. If you - need some other behavior for NULL inputs, just define your transition - function as non-strict, and code it to test for NULL inputs and do + null input value is encountered. Thus, null values are ignored. If you + need some other behavior for null inputs, just do not define your transition + function as strict, and code it to test for null inputs and do whatever is needed. - Avg (average) is a more complex example of an aggregate. It requires + avg (average) is a more complex example of an aggregate. It requires two pieces of running state: the sum of the inputs and the count of the number of inputs. The final result is obtained by dividing these quantities. Average is typically implemented by using a - two-element array as the transition state value. For example, + two-element array as the state value. For example, the built-in implementation of avg(float8) looks like: @@ -116,7 +114,7 @@ CREATE AGGREGATE avg ( For further details see the description of the CREATE AGGREGATE command in . - + - - Extending <acronym>SQL</acronym>: Functions + + User-Defined Functions function - - Introduction - PostgreSQL provides four kinds of functions: @@ -17,24 +14,25 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v 1.66 2003/03/25 16:15:38 peter - query language functions - (functions written in SQL) + query language functions (functions written in + SQL) () - procedural language - functions (functions written in, for example, PL/Tcl or PL/pgSQL) + procedural language functions (functions written in, for + example, PL/Tcl or PL/pgSQL) + () - internal functions + internal functions () - C language functions + C-language functions () @@ -42,10 +40,14 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v 1.66 2003/03/25 16:15:38 peter Every kind - of function can take a base type, a composite type, or + of function can take base types, composite types, or some combination as arguments (parameters). In addition, every kind of function can return a base type or - a composite type. It's easiest to define SQL + a composite type. + + + + It's easiest to define SQL functions, so we'll start with those. Examples in this section can also be found in funcs.sql and funcs.c in the tutorial directory. @@ -72,14 +74,14 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v 1.66 2003/03/25 16:15:38 peter (Bear in mind that the first row of a multirow result is not well-defined unless you use ORDER BY.) If the last query happens - to return no rows at all, NULL will be returned. + to return no rows at all, the null value will be returned. SETOFfunction Alternatively, an SQL function may be declared to return a set, by specifying the function's return type - as SETOF sometype. In this case + as SETOF sometype. In this case all rows of the last query's result are returned. Further details appear below. @@ -97,22 +99,65 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v 1.66 2003/03/25 16:15:38 peter Arguments to the SQL function may be referenced in the function - body using the syntax $n: $1 refers to - the first argument, $2 to the second, and so on. If an argument - is of a composite type, then the dot notation, - e.g., $1.emp, may be used to access attributes + body using the syntax $n: $1 refers to + the first argument, $2 to the second, and so on. If an argument + is of a composite type, then the dot notation, + e.g., $1.name, may be used to access attributes of the argument. - Examples + <acronym>SQL</acronym> Functions on Base Types - To illustrate a simple SQL function, consider the following, - which might be used to debit a bank account: + The simplest possible SQL function has no arguments and + simply returns a base type, such as integer: + + +CREATE FUNCTION one() RETURNS integer AS ' + SELECT 1 AS result; +' LANGUAGE SQL; + +SELECT one(); + + one +----- + 1 + + + + + Notice that we defined a column alias within the function body for the result of the function + (with the name result), but this column alias is not visible + outside the function. Hence, the result is labeled one + instead of result. + + + + It is almost as easy to define SQL functions + that take base types as arguments. In the example below, notice + how we refer to the arguments within the function as $1 + and $2. + + +CREATE FUNCTION add_em(integer, integer) RETURNS integer AS ' + SELECT $1 + $2; +' LANGUAGE SQL; + +SELECT add_em(1, 2) AS answer; + + answer +-------- + 3 + + + + + Here is a more useful function, which might be used to debit a + bank account: -CREATE FUNCTION tp1 (integer, numeric) RETURNS integer AS ' +CREATE FUNCTION tf1 (integer, numeric) RETURNS integer AS ' UPDATE bank SET balance = balance - $2 WHERE accountno = $1; @@ -124,17 +169,17 @@ CREATE FUNCTION tp1 (integer, numeric) RETURNS integer AS ' follows: -SELECT tp1(17, 100.0); +SELECT tf1(17, 100.0); In practice one would probably like a more useful result from the - function than a constant 1, so a more likely definition + function than a constant 1, so a more likely definition is -CREATE FUNCTION tp1 (integer, numeric) RETURNS numeric AS ' +CREATE FUNCTION tf1 (integer, numeric) RETURNS numeric AS ' UPDATE bank SET balance = balance - $2 WHERE accountno = $1; @@ -148,83 +193,29 @@ CREATE FUNCTION tp1 (integer, numeric) RETURNS numeric AS ' Any collection of commands in the SQL language can be packaged together and defined as a function. - The commands can include data modification (i.e., + Besides SELECT queries, + the commands can include data modification (i.e., INSERT, UPDATE, and - DELETE) as well - as SELECT queries. However, the final command + DELETE). However, the final command must be a SELECT that returns whatever is specified as the function's return type. Alternatively, if you want to define a SQL function that performs actions but has no useful value to return, you can define it as returning void. - In that case it must not end with a SELECT. + In that case, the function body must not end with a SELECT. For example: - -CREATE FUNCTION clean_EMP () RETURNS void AS ' - DELETE FROM EMP - WHERE EMP.salary <= 0; + +CREATE FUNCTION clean_emp() RETURNS void AS ' + DELETE FROM emp + WHERE salary <= 0; ' LANGUAGE SQL; -SELECT clean_EMP(); - +SELECT clean_emp(); - clean_emp ----------- (1 row) - - - - - - - <acronym>SQL</acronym> Functions on Base Types - - - The simplest possible SQL function has no arguments and - simply returns a base type, such as integer: - - -CREATE FUNCTION one() RETURNS integer AS ' - SELECT 1 as RESULT; -' LANGUAGE SQL; - -SELECT one(); - - - - one ------ - 1 - - - - - Notice that we defined a column alias within the function body for the result of the function - (with the name RESULT), but this column alias is not visible - outside the function. Hence, the result is labeled one - instead of RESULT. - - - - It is almost as easy to define SQL functions - that take base types as arguments. In the example below, notice - how we refer to the arguments within the function as $1 - and $2: - - -CREATE FUNCTION add_em(integer, integer) RETURNS integer AS ' - SELECT $1 + $2; -' LANGUAGE SQL; - -SELECT add_em(1, 2) AS answer; - - - - answer --------- - 3 @@ -237,22 +228,27 @@ SELECT add_em(1, 2) AS answer; types, we must not only specify which argument we want (as we did above with $1 and $2) but also the attributes of that argument. For example, suppose that - EMP is a table containing employee data, and therefore + emp is a table containing employee data, and therefore also the name of the composite type of each row of the table. Here - is a function double_salary that computes what your + is a function double_salary that computes what someone's salary would be if it were doubled: - -CREATE FUNCTION double_salary(EMP) RETURNS integer AS ' + +CREATE TABLE emp ( + name text, + salary integer, + age integer, + cubicle point +); + +CREATE FUNCTION double_salary(emp) RETURNS integer AS ' SELECT $1.salary * 2 AS salary; ' LANGUAGE SQL; -SELECT name, double_salary(EMP) AS dream - FROM EMP - WHERE EMP.cubicle ~= point '(2,1)'; - +SELECT name, double_salary(emp) AS dream + FROM emp + WHERE emp.cubicle ~= point '(2,1)'; - name | dream ------+------- Sam | 2400 @@ -269,28 +265,29 @@ SELECT name, double_salary(EMP) AS dream It is also possible to build a function that returns a composite type. This is an example of a function - that returns a single EMP row: + that returns a single emp row: -CREATE FUNCTION new_emp() RETURNS EMP AS ' +CREATE FUNCTION new_emp() RETURNS emp AS ' SELECT text ''None'' AS name, 1000 AS salary, 25 AS age, point ''(2,2)'' AS cubicle; ' LANGUAGE SQL; + + In this case we have specified each of the attributes + with a constant value, but any computation + could have been substituted for these constants. - In this case we have specified each of the attributes - with a constant value, but any computation or expression - could have been substituted for these constants. Note two important things about defining the function: - The target list order must be exactly the same as + The select list order in the query must be exactly the same as that in which the columns appear in the table associated with the composite type. (Naming the columns, as we did above, is irrelevant to the system.) @@ -315,13 +312,15 @@ ERROR: function declared to return emp returns varchar instead of text at colum function, as described below. It can also be called in the context of an SQL expression, but only when you extract a single attribute out of the row or pass the entire row into - another function that accepts the same composite type. For example, + another function that accepts the same composite type. + - -SELECT (new_emp()).name; - + + This is an example for how to extract an attribute out of a row type: +SELECT (new_emp()).name; + name ------ None @@ -340,29 +339,24 @@ ERROR: parser: parse error at or near "." functional notation for extracting an attribute. The simple way to explain this is that we can use the notations attribute(table) and table.attribute - interchangeably: - - -SELECT name(new_emp()); - + interchangeably. +SELECT name(new_emp()); + name ------ None - --- --- this is the same as: --- SELECT EMP.name AS youngster FROM EMP WHERE EMP.age < 30 --- -SELECT name(EMP) AS youngster - FROM EMP - WHERE age(EMP) < 30; - - +-- This is the same as: +-- SELECT emp.name AS youngster FROM emp WHERE emp.age < 30 + +SELECT name(emp) AS youngster + FROM emp + WHERE age(emp) < 30; + youngster ----------- Sam @@ -370,17 +364,15 @@ SELECT name(EMP) AS youngster - Another way to use a function returning a row result is to declare a - second function accepting a row type parameter, and pass the function - result to it: + The other way to use a function returning a row result is to declare a + second function accepting a row type argument and pass the + result of the first function to it: - + CREATE FUNCTION getname(emp) RETURNS text AS 'SELECT $1.name;' LANGUAGE SQL; - - SELECT getname(new_emp()); getname --------- @@ -391,35 +383,32 @@ SELECT getname(new_emp()); - <acronym>SQL</acronym> Table Functions + <acronym>SQL</acronym> Functions as Table Sources - A table function is one that may be used in the FROM - clause of a query. All SQL language functions may be used in this manner, + All SQL functions may be used in the FROM clause of a query, but it is particularly useful for functions returning composite types. If the function is defined to return a base type, the table function produces a one-column table. If the function is defined to return - a composite type, the table function produces a column for each column + a composite type, the table function produces a column for each attribute of the composite type. Here is an example: - + CREATE TABLE foo (fooid int, foosubid int, fooname text); -INSERT INTO foo VALUES(1,1,'Joe'); -INSERT INTO foo VALUES(1,2,'Ed'); -INSERT INTO foo VALUES(2,1,'Mary'); +INSERT INTO foo VALUES (1, 1, 'Joe'); +INSERT INTO foo VALUES (1, 2, 'Ed'); +INSERT INTO foo VALUES (2, 1, 'Mary'); CREATE FUNCTION getfoo(int) RETURNS foo AS ' SELECT * FROM foo WHERE fooid = $1; ' LANGUAGE SQL; SELECT *, upper(fooname) FROM getfoo(1) AS t1; - - fooid | foosubid | fooname | upper -------+----------+---------+------- 1 | 1 | Joe | JOE @@ -432,35 +421,35 @@ SELECT *, upper(fooname) FROM getfoo(1) AS t1; Note that we only got one row out of the function. This is because - we did not say SETOF. + we did not use SETOF. This is described in the next section. - <acronym>SQL</acronym> Functions Returning Sets - When an SQL function is declared as returning SETOF - sometype, the function's final + When an SQL function is declared as returning SETOF + sometype, the function's final SELECT query is executed to completion, and each row it - outputs is returned as an element of the set. + outputs is returned as an element of the result set. - This feature is normally used by calling the function as a table - function. In this case each row returned by the function becomes + This feature is normally used when calling the function in the FROM + clause. In this case each row returned by the function becomes a row of the table seen by the query. For example, assume that table foo has the same contents as above, and we say: -CREATE FUNCTION getfoo(int) RETURNS setof foo AS ' +CREATE FUNCTION getfoo(int) RETURNS SETOF foo AS ' SELECT * FROM foo WHERE fooid = $1; ' LANGUAGE SQL; SELECT * FROM getfoo(1) AS t1; + Then we would get: fooid | foosubid | fooname -------+----------+--------- @@ -471,21 +460,19 @@ SELECT * FROM getfoo(1) AS t1; - Currently, functions returning sets may also be called in the target list - of a SELECT query. For each row that the SELECT + Currently, functions returning sets may also be called in the select list + of a query. For each row that the query generates by itself, the function returning set is invoked, and an output row is generated for each element of the function's result set. Note, however, that this capability is deprecated and may be removed in future releases. The following is an example function returning a set from the - target list: + select list: - + CREATE FUNCTION listchildren(text) RETURNS SETOF text AS 'SELECT name FROM nodes WHERE parent = $1' LANGUAGE SQL; - - SELECT * FROM nodes; name | parent -----------+-------- @@ -519,7 +506,7 @@ SELECT name, listchildren(name) FROM nodes; In the last SELECT, notice that no output row appears for Child2, Child3, etc. This happens because listchildren returns an empty set - for those inputs, so no output rows are generated. + for those arguments, so no result rows are generated. @@ -562,7 +549,7 @@ SELECT name, listchildren(name) FROM nodes; Normally, all internal functions present in the - backend are declared during the initialization of the database cluster (initdb), + server are declared during the initialization of the database cluster (initdb), but a user could use CREATE FUNCTION to create additional alias names for an internal function. Internal functions are declared in CREATE FUNCTION @@ -571,8 +558,8 @@ SELECT name, listchildren(name) FROM nodes; CREATE FUNCTION square_root(double precision) RETURNS double precision AS 'dsqrt' - LANGUAGE INTERNAL - WITH (isStrict); + LANGUAGE internal + STRICT; (Most internal functions expect to be declared strict.) @@ -587,7 +574,7 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision - C Language Functions + C-Language Functions User-defined functions can be written in C (or a language that can @@ -617,7 +604,7 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision The first time a user-defined function in a particular - loadable object file is called in a backend session, + loadable object file is called in a session, the dynamic loader loads that object file into memory so that the function can be called. The CREATE FUNCTION for a user-defined C function must therefore specify two pieces of @@ -736,9 +723,140 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision Base Types in C-Language Functions - gives the C type required for - parameters in the C functions that will be loaded into - PostgreSQL. + To know how to write C-language functions, you need to know how + PostgreSQL internally represents base data types and how they can + be passed to and from functions. + Internally, PostgreSQL regards a + base type as a blob of memory. The user-defined + functions that you define over a type in turn define the + way that PostgreSQL can operate + on it. That is, PostgreSQL will + only store and retrieve the data from disk and use your + user-defined functions to input, process, and output the data. + + + + Base types can have one of three internal formats: + + + + + pass by value, fixed-length + + + + + pass by reference, fixed-length + + + + + pass by reference, variable-length + + + + + + + By-value types can only be 1, 2, or 4 bytes in length + (also 8 bytes, if sizeof(Datum) is 8 on your machine). + You should be careful + to define your types such that they will be the same + size (in bytes) on all architectures. For example, the + long type is dangerous because it + is 4 bytes on some machines and 8 bytes on others, whereas + int type is 4 bytes on most + Unix machines. A reasonable implementation of + the int4 type on Unix + machines might be: + + +/* 4-byte integer, passed by value */ +typedef int int4; + + + + + On the other hand, fixed-length types of any size may + be passed by-reference. For example, here is a sample + implementation of a PostgreSQL type: + + +/* 16-byte structure, passed by reference */ +typedef struct +{ + double x, y; +} Point; + + + Only pointers to such types can be used when passing + them in and out of PostgreSQL functions. + To return a value of such a type, allocate the right amount of + memory with palloc, fill in the allocated memory, + and return a pointer to it. (You can also return an input value + that has the same type as the return value directly by returning + the pointer to the input value. Never modify the + contents of a pass-by-reference input value, however.) + + + + Finally, all variable-length types must also be passed + by reference. All variable-length types must begin + with a length field of exactly 4 bytes, and all data to + be stored within that type must be located in the memory + immediately following that length field. The + length field contains the total length of the structure, + that is, it includes the size of the length field + itself. + + + + As an example, we can define the type text as + follows: + + +typedef struct { + int4 length; + char data[1]; +} text; + + + Obviously, the data field declared here is not long enough to hold + all possible strings. Since it's impossible to declare a variable-size + structure in C, we rely on the knowledge that the + C compiler won't range-check array subscripts. We + just allocate the necessary amount of space and then access the array as + if it were declared the right length. (This is a common trick, which + you can read about in many textbooks about C.) + + + + When manipulating + variable-length types, we must be careful to allocate + the correct amount of memory and set the length field correctly. + For example, if we wanted to store 40 bytes in a text + structure, we might use a code fragment like this: + + +#include "postgres.h" +... +char buffer[40]; /* our source data */ +... +text *destination = (text *) palloc(VARHDRSZ + 40); +destination->length = VARHDRSZ + 40; +memcpy(destination->data, buffer, 40); +... + + + VARHDRSZ is the same as sizeof(int4), but + it's considered good style to use the macro VARHDRSZ + to refer to the size of the overhead for a variable-length type. + + + + specifies which C type + corresponds to which SQL type when writing a C-language function + that uses a built-in type of PostgreSQL. The Defined In column gives the header file that needs to be included to get the type definition. (The actual definition may be in a different file that is included by the @@ -749,9 +867,7 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision - Equivalent C Types - for Built-In <productname>PostgreSQL</productname> Types - Equivalent C Types + Equivalent C Types for Built-In SQL Types @@ -921,132 +1037,6 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision
- - Internally, PostgreSQL regards a - base type as a blob of memory. The user-defined - functions that you define over a type in turn define the - way that PostgreSQL can operate - on it. That is, PostgreSQL will - only store and retrieve the data from disk and use your - user-defined functions to input, process, and output the data. - Base types can have one of three internal formats: - - - - - pass by value, fixed-length - - - - - pass by reference, fixed-length - - - - - pass by reference, variable-length - - - - - - - By-value types can only be 1, 2 or 4 bytes in length - (also 8 bytes, if sizeof(Datum) is 8 on your machine). - You should be careful - to define your types such that they will be the same - size (in bytes) on all architectures. For example, the - long type is dangerous because it - is 4 bytes on some machines and 8 bytes on others, whereas - int type is 4 bytes on most - Unix machines. A reasonable implementation of - the int4 type on Unix - machines might be: - - -/* 4-byte integer, passed by value */ -typedef int int4; - - - PostgreSQL automatically figures - things out so that the integer types really have the size they - advertise. - - - - On the other hand, fixed-length types of any size may - be passed by-reference. For example, here is a sample - implementation of a PostgreSQL type: - - -/* 16-byte structure, passed by reference */ -typedef struct -{ - double x, y; -} Point; - - - - - Only pointers to such types can be used when passing - them in and out of PostgreSQL functions. - To return a value of such a type, allocate the right amount of - memory with palloc(), fill in the allocated memory, - and return a pointer to it. (Alternatively, you can return an input - value of the same type by returning its pointer. Never - modify the contents of a pass-by-reference input value, however.) - - - - Finally, all variable-length types must also be passed - by reference. All variable-length types must begin - with a length field of exactly 4 bytes, and all data to - be stored within that type must be located in the memory - immediately following that length field. The - length field is the total length of the structure - (i.e., it includes the size of the length field - itself). We can define the text type as follows: - - -typedef struct { - int4 length; - char data[1]; -} text; - - - - - Obviously, the data field declared here is not long enough to hold - all possible strings. Since it's impossible to declare a variable-size - structure in C, we rely on the knowledge that the - C compiler won't range-check array subscripts. We - just allocate the necessary amount of space and then access the array as - if it were declared the right length. (If this isn't a familiar trick to - you, you may wish to spend some time with an introductory - C programming textbook before delving deeper into - PostgreSQL server programming.) - When manipulating - variable-length types, we must be careful to allocate - the correct amount of memory and set the length field correctly. - For example, if we wanted to store 40 bytes in a text - structure, we might use a code fragment like this: - - -#include "postgres.h" -... -char buffer[40]; /* our source data */ -... -text *destination = (text *) palloc(VARHDRSZ + 40); -destination->length = VARHDRSZ + 40; -memcpy(destination->data, buffer, 40); -... - - - VARHDRSZ is the same as sizeof(int4), but - it's considered good style to use the macro VARHDRSZ - to refer to the size of the overhead for a variable-length type. - - Now that we've gone over all of the possible structures for base types, we can show some examples of real functions. @@ -1054,7 +1044,7 @@ memcpy(destination->data, buffer, 40); - Version-0 Calling Conventions for C-Language Functions + Calling Conventions Version 0 for C-Language Functions We present the old style calling convention first --- although @@ -1072,7 +1062,7 @@ memcpy(destination->data, buffer, 40); #include "postgres.h" #include <string.h> -/* By Value */ +/* by value */ int add_one(int arg) @@ -1080,7 +1070,7 @@ add_one(int arg) return arg + 1; } -/* By Reference, Fixed Length */ +/* by reference, fixed length */ float8 * add_one_float8(float8 *arg) @@ -1103,7 +1093,7 @@ makepoint(Point *pointx, Point *pointy) return new_point; } -/* By Reference, Variable Length */ +/* by reference, variable length */ text * copytext(text *t) @@ -1144,47 +1134,48 @@ concat_text(text *arg1, text *arg2) with commands like this: -CREATE FUNCTION add_one(int4) RETURNS int4 - AS 'PGROOT/tutorial/funcs' LANGUAGE C - WITH (isStrict); +CREATE FUNCTION add_one(integer) RETURNS integer + AS 'DIRECTORY/funcs', 'add_one' + LANGUAGE C STRICT; --- note overloading of SQL function name add_one() -CREATE FUNCTION add_one(float8) RETURNS float8 - AS 'PGROOT/tutorial/funcs', - 'add_one_float8' - LANGUAGE C WITH (isStrict); +-- note overloading of SQL function name "add_one" +CREATE FUNCTION add_one(double precision) RETURNS double precision + AS 'DIRECTORY/funcs', 'add_one_float8' + LANGUAGE C STRICT; CREATE FUNCTION makepoint(point, point) RETURNS point - AS 'PGROOT/tutorial/funcs' LANGUAGE C - WITH (isStrict); + AS 'DIRECTORY/funcs', 'makepoint' + LANGUAGE C STRICT; CREATE FUNCTION copytext(text) RETURNS text - AS 'PGROOT/tutorial/funcs' LANGUAGE C - WITH (isStrict); + AS 'DIRECTORY/funcs', 'copytext' + LANGUAGE C STRICT; CREATE FUNCTION concat_text(text, text) RETURNS text - AS 'PGROOT/tutorial/funcs' LANGUAGE C - WITH (isStrict); + AS 'DIRECTORY/funcs', 'concat_text', + LANGUAGE C STRICT; - Here PGROOT stands for the full path to - the PostgreSQL source tree. (Better style would - be to use just 'funcs' in the AS clause, - after having added PGROOT/tutorial - to the search path. In any case, we may omit the system-specific - extension for a shared library, commonly .so or + Here, DIRECTORY stands for the + directory of the shared library file (for instance the PostgreSQL + tutorial directory, which contains the code for the examples used + in this section). (Better style would be to use just + 'funcs' in the AS clause, after having + added DIRECTORY to the search path. + In any case, we may omit the system-specific extension for a + shared library, commonly .so or .sl.) Notice that we have specified the functions as strict, meaning that - the system should automatically assume a NULL result if any input - value is NULL. By doing this, we avoid having to check for NULL inputs + the system should automatically assume a null result if any input + value is null. By doing this, we avoid having to check for null inputs in the function code. Without this, we'd have to check for null values - explicitly, for example by checking for a null pointer for each + explicitly, by checking for a null pointer for each pass-by-reference argument. (For pass-by-value arguments, we don't even have a way to check!) @@ -1192,15 +1183,15 @@ CREATE FUNCTION concat_text(text, text) RETURNS text Although this calling convention is simple to use, it is not very portable; on some architectures there are problems - with passing smaller-than-int data types this way. Also, there is - no simple way to return a NULL result, nor to cope with NULL arguments + with passing data types that are smaller than int this way. Also, there is + no simple way to return a null result, nor to cope with null arguments in any way other than making the function strict. The version-1 convention, presented next, overcomes these objections. - Version-1 Calling Conventions for C-Language Functions + Calling Conventions Version 1 for C-Language Functions The version-1 calling convention relies on macros to suppress most @@ -1213,21 +1204,26 @@ Datum funcname(PG_FUNCTION_ARGS) PG_FUNCTION_INFO_V1(funcname); - must appear in the same source file (conventionally it's written - just before the function itself). This macro call is not needed - for internal-language functions, since - PostgreSQL currently - assumes all internal functions are version-1. However, it is - required for dynamically-loaded functions. + must appear in the same source file. (Conventionally. it's + written just before the function itself.) This macro call is not + needed for internal-language functions, since + PostgreSQL assumes that all internal functions + use the version-1 convention. It is, however, required for + dynamically-loaded functions. In a version-1 function, each actual argument is fetched using a PG_GETARG_xxx() - macro that corresponds to the argument's data type, and the result - is returned using a + macro that corresponds to the argument's data type, and the + result is returned using a PG_RETURN_xxx() macro for the return type. + PG_GETARG_xxx() + takes as its argument the number of the function argument to + fetch, where the count starts at 0. + PG_RETURN_xxx() + takes as its argument the actual value to return. @@ -1238,7 +1234,7 @@ PG_FUNCTION_INFO_V1(funcname); #include <string.h> #include "fmgr.h" -/* By Value */ +/* by value */ PG_FUNCTION_INFO_V1(add_one); @@ -1250,14 +1246,14 @@ add_one(PG_FUNCTION_ARGS) PG_RETURN_INT32(arg + 1); } -/* By Reference, Fixed Length */ +/* b reference, fixed length */ PG_FUNCTION_INFO_V1(add_one_float8); Datum add_one_float8(PG_FUNCTION_ARGS) { - /* The macros for FLOAT8 hide its pass-by-reference nature */ + /* The macros for FLOAT8 hide its pass-by-reference nature. */ float8 arg = PG_GETARG_FLOAT8(0); PG_RETURN_FLOAT8(arg + 1.0); @@ -1268,7 +1264,7 @@ PG_FUNCTION_INFO_V1(makepoint); Datum makepoint(PG_FUNCTION_ARGS) { - /* Here, the pass-by-reference nature of Point is not hidden */ + /* Here, the pass-by-reference nature of Point is not hidden. */ Point *pointx = PG_GETARG_POINT_P(0); Point *pointy = PG_GETARG_POINT_P(1); Point *new_point = (Point *) palloc(sizeof(Point)); @@ -1279,7 +1275,7 @@ makepoint(PG_FUNCTION_ARGS) PG_RETURN_POINT_P(new_point); } -/* By Reference, Variable Length */ +/* by reference, variable length */ PG_FUNCTION_INFO_V1(copytext); @@ -1327,80 +1323,178 @@ concat_text(PG_FUNCTION_ARGS) At first glance, the version-1 coding conventions may appear to - be just pointless obscurantism. However, they do offer a number + be just pointless obscurantism. They do, however, offer a number of improvements, because the macros can hide unnecessary detail. An example is that in coding add_one_float8, we no longer need to be aware that float8 is a pass-by-reference type. Another - example is that the GETARG macros for variable-length types hide - the need to deal with fetching toasted (compressed or - out-of-line) values. The old-style copytext - and concat_text functions shown above are - actually wrong in the presence of toasted values, because they - don't call pg_detoast_datum() on their - inputs. (The handler for old-style dynamically-loaded functions - currently takes care of this detail, but it does so less - efficiently than is possible for a version-1 function.) + example is that the GETARG macros for variable-length types allow + for more efficient fetching of toasted (compressed or + out-of-line) values. - One big improvement in version-1 functions is better handling of NULL + One big improvement in version-1 functions is better handling of null inputs and results. The macro PG_ARGISNULL(n) - allows a function to test whether each input is NULL (of course, doing - this is only necessary in functions not declared strict). + allows a function to test whether each input is null. (Of course, doing + this is only necessary in functions not declared strict.) As with the PG_GETARG_xxx() macros, the input arguments are counted beginning at zero. Note that one should refrain from executing PG_GETARG_xxx() until - one has verified that the argument isn't NULL. - To return a NULL result, execute PG_RETURN_NULL(); + one has verified that the argument isn't null. + To return a null result, execute PG_RETURN_NULL(); this works in both strict and nonstrict functions. - Other options provided in the new-style interface are two + Other options provided in the new-style interface are two variants of the PG_GETARG_xxx() macros. The first of these, - PG_GETARG_xxx_COPY() - guarantees to return a copy of the specified parameter which is + PG_GETARG_xxx_COPY(), + guarantees to return a copy of the specified argument that is safe for writing into. (The normal macros will sometimes return a - pointer to a value that is physically stored in a table, and so + pointer to a value that is physically stored in a table, which must not be written to. Using the PG_GETARG_xxx_COPY() macros guarantees a writable result.) - - - The second variant consists of the PG_GETARG_xxx_SLICE() - macros which take three parameters. The first is the number of the - parameter (as above). The second and third are the offset and + macros which take three arguments. The first is the number of the + function argument (as above). The second and third are the offset and length of the segment to be returned. Offsets are counted from zero, and a negative length requests that the remainder of the - value be returned. These routines provide more efficient access to + value be returned. These macros provide more efficient access to parts of large values in the case where they have storage type external. (The storage type of a column can be specified using ALTER TABLE tablename ALTER COLUMN colname SET STORAGE - storagetype. Storage type is one of + storagetype. storagetype is one of plain, external, extended, or main.) - The version-1 function call conventions make it possible to - return set results and implement trigger functions and - procedural-language call handlers. Version-1 code is also more - portable than version-0, because it does not break ANSI C restrictions - on function call protocol. For more details see - src/backend/utils/fmgr/README in the source - distribution. + Finally, the version-1 function call conventions make it possible + to return set results () and + implement trigger functions () and + procedural-language call handlers (). Version-1 code is also more + portable than version-0, because it does not break restrictions + on function call protocol in the C standard. For more details + see src/backend/utils/fmgr/README in the + source distribution. - Composite Types in C-Language Functions + Writing Code + + + Before we turn to the more advanced topics, we should discuss + some coding rules for PostgreSQL C-language functions. While it + may be possible to load functions written in languages other than + C into PostgreSQL, this is usually + difficult (when it is possible at all) because other languages, + such as C++, FORTRAN, or Pascal often do not follow the same + calling convention as C. That is, other languages do not pass + argument and return values between functions in the same way. + For this reason, we will assume that your C-language functions + are actually written in C. + + + + The basic rules for writing and building C functions are as follows: + + + + + Use pg_config + --includedir-serverpg_config + to find out where the PostgreSQL server header + files are installed on your system (or the system that your + users will be running on). This option is new with + PostgreSQL 7.2. For + PostgreSQL 7.1 you should use the option + . (pg_config + will exit with a non-zero status if it encounters an unknown + option.) For releases prior to 7.1 you will have to guess, + but since that was before the current calling conventions were + introduced, it is unlikely that you want to support those + releases. + + + + + + When allocating memory, use the + PostgreSQL functions + palloc and pfree + instead of the corresponding C library functions + malloc and free. + The memory allocated by palloc will be + freed automatically at the end of each transaction, preventing + memory leaks. + + + + + + Always zero the bytes of your structures using + memset or bzero. + Several routines (such as the hash access method, hash joins, + and the sort algorithm) compute functions of the raw bits + contained in your structure. Even if you initialize all + fields of your structure, there may be several bytes of + alignment padding (holes in the structure) that may contain + garbage values. + + + + + + Most of the internal PostgreSQL + types are declared in postgres.h, while + the function manager interfaces + (PG_FUNCTION_ARGS, etc.) are in + fmgr.h, so you will need to include at + least these two files. For portability reasons it's best to + include postgres.h first, + before any other system or user header files. Including + postgres.h will also include + elog.h and palloc.h + for you. + + + + + + Symbol names defined within object files must not conflict + with each other or with symbols defined in the + PostgreSQL server executable. You + will have to rename your functions or variables if you get + error messages to this effect. + + + + + + Compiling and linking your code so that it can be dynamically + loaded into PostgreSQL always + requires special flags. See for a + detailed explanation of how to do it for your particular + operating system. + + + + + + +&dfunc; + + + Composite-Type Arguments in C-Language Functions Composite types do not have a fixed layout like C @@ -1409,26 +1503,28 @@ concat_text(PG_FUNCTION_ARGS) part of an inheritance hierarchy may have different fields than other members of the same inheritance hierarchy. Therefore, PostgreSQL provides - a procedural interface for accessing fields of composite types - from C. As PostgreSQL processes - a set of rows, each row will be passed into your - function as an opaque structure of type TUPLE. + a function interface for accessing fields of composite types + from C. + + + Suppose we want to write a function to answer the query SELECT name, c_overpaid(emp, 1500) AS overpaid -FROM emp -WHERE name = 'Bill' OR name = 'Sam'; + FROM emp + WHERE name = 'Bill' OR name = 'Sam'; - In the query above, we can define c_overpaid as: + Using call conventions version 0, we can define + c_overpaid as: #include "postgres.h" #include "executor/executor.h" /* for GetAttributeByName() */ bool -c_overpaid(TupleTableSlot *t, /* the current row of EMP */ +c_overpaid(TupleTableSlot *t, /* the current row of emp */ int32 limit) { bool isnull; @@ -1436,11 +1532,16 @@ c_overpaid(TupleTableSlot *t, /* the current row of EMP */ salary = DatumGetInt32(GetAttributeByName(t, "salary", &isnull)); if (isnull) - return (false); + return false; return salary > limit; } + -/* In version-1 coding, the above would look like this: */ + In version-1 coding, the above would look like this: + + +#include "postgres.h" +#include "executor/executor.h" /* for GetAttributeByName() */ PG_FUNCTION_INFO_V1(c_overpaid); @@ -1455,7 +1556,7 @@ c_overpaid(PG_FUNCTION_ARGS) salary = DatumGetInt32(GetAttributeByName(t, "salary", &isnull)); if (isnull) PG_RETURN_BOOL(false); - /* Alternatively, we might prefer to do PG_RETURN_NULL() for null salary */ + /* Alternatively, we might prefer to do PG_RETURN_NULL() for null salary. */ PG_RETURN_BOOL(salary > limit); } @@ -1465,7 +1566,7 @@ c_overpaid(PG_FUNCTION_ARGS) GetAttributeByName is the PostgreSQL system function that - returns attributes out of the current row. It has + returns attributes out of the specified row. It has three arguments: the argument of type TupleTableSlot* passed into the function, the name of the desired attribute, and a return parameter that tells whether the attribute @@ -1475,55 +1576,43 @@ c_overpaid(PG_FUNCTION_ARGS) - The following command lets PostgreSQL - know about the c_overpaid function: + The following command declares the function + c_overpaid in SQL: -CREATE FUNCTION c_overpaid(emp, int4) -RETURNS bool -AS 'PGROOT/tutorial/funcs' -LANGUAGE C; +CREATE FUNCTION c_overpaid(emp, integer) + RETURNS boolean + AS 'DIRECTORY/funcs', 'c_overpaid' + LANGUAGE C; - Table Function API + Returning Rows (Composite Types) from C-Language Functions - The Table Function API assists in the creation of user-defined - C language table functions (). - Table functions are functions that produce a set of rows, made up of - either base (scalar) data types, or composite (multi-column) data types. - The API is split into two main components: support for returning - composite data types, and support for returning multiple rows - (set-returning functions or SRFs). - - - - The Table Function API relies on macros and functions to suppress most - of the complexity of building composite data types and returning multiple - results. A table function must follow the version-1 calling convention - described above. In addition, the source file must include: + To return a row or composite-type value from a C-language + function, you can use a special API that provides macros and + functions to hide most of the complexity of building composite + data types. To use this API, the source file must include: #include "funcapi.h" - - Returning Rows (Composite Types) - - The Table Function API support for returning composite data types - (or rows) starts with the AttInMetadata - structure. This structure holds arrays of individual attribute - information needed to create a row from raw C strings. It also - saves a pointer to the TupleDesc. The information - carried here is derived from the TupleDesc, but it - is stored here to avoid redundant CPU cycles on each call to a - table function. In the case of a function returning a set, the - AttInMetadata structure should be computed - once during the first call and saved for re-use in later calls. + The support for returning composite data types (or rows) starts + with the AttInMetadata structure. This structure + holds arrays of individual attribute information needed to create + a row from raw C strings. The information contained in the + structure is derived from a TupleDesc structure, + but it is stored to avoid redundant computations on each call to + a set-returning function (see next section). In the case of a + function returning a set, the AttInMetadata + structure should be computed once during the first call and saved + for reuse in later calls. AttInMetadata also + saves a pointer to the original TupleDesc. typedef struct AttInMetadata { @@ -1548,13 +1637,13 @@ typedef struct AttInMetadata TupleDesc RelationNameGetTupleDesc(const char *relname) - to get a TupleDesc based on a specified relation, or + to get a TupleDesc for a named relation, or TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases) to get a TupleDesc based on a type OID. This can - be used to get a TupleDesc for a base (scalar) or - composite (relation) type. Then + be used to get a TupleDesc for a base or + composite type. Then AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc) @@ -1562,8 +1651,7 @@ AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc) initialized based on the given TupleDesc. AttInMetadata can be used in conjunction with C strings to produce a properly formed - tuple. The metadata is stored here to avoid redundant work across - multiple calls. + row value (internally called tuple). @@ -1574,7 +1662,7 @@ TupleTableSlot *TupleDescGetSlot(TupleDesc tupdesc) to initialize this tuple slot, or obtain one through other (user provided) means. The tuple slot is needed to create a Datum for return by the - function. The same slot can (and should) be re-used on each call. + function. The same slot can (and should) be reused on each call. @@ -1583,13 +1671,13 @@ TupleTableSlot *TupleDescGetSlot(TupleDesc tupdesc) HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values) can be used to build a HeapTuple given user data - in C string form. values is an array of C strings, one for - each attribute of the return tuple. Each C string should be in + in C string form. values is an array of C strings, one for + each attribute of the return row. Each C string should be in the form expected by the input function of the attribute data type. In order to return a null value for one of the attributes, the corresponding pointer in the values array should be set to NULL. This function will need to - be called again for each tuple you return. + be called again for each row you return. @@ -1597,16 +1685,16 @@ HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values) BuildTupleFromCStrings is only convenient if your function naturally computes the values to be returned as text strings. If your code naturally computes the values as a set of - Datums, you should instead use the underlying - heap_formtuple routine to convert the - Datums directly into a tuple. You will still need + Datum values, you should instead use the underlying + function heap_formtuple to convert the + Datum values directly into a tuple. You will still need the TupleDesc and a TupleTableSlot, but not AttInMetadata. - Once you have built a tuple to return from your function, the tuple must - be converted into a Datum. Use + Once you have built a tuple to return from your function, it + must be converted into a Datum. Use TupleGetDatum(TupleTableSlot *slot, HeapTuple tuple) @@ -1617,28 +1705,36 @@ TupleGetDatum(TupleTableSlot *slot, HeapTuple tuple) - An example appears below. + An example appears in the next section. - + - - Returning Sets + + Returning Sets from C-Language Functions - A set-returning function (SRF) is normally called + There is also a special API that provides support for returning + sets (multiple rows) from a C-language function. A set-returning + function must follow the version-1 calling conventions. Also, + source files must include funcapi.h, as + above. + + + + A set-returning function (SRF) is called once for each item it returns. The SRF must therefore save enough state to remember what it was doing and - return the next item on each call. The Table Function API - provides the FuncCallContext structure to help - control this process. fcinfo->flinfo->fn_extra + return the next item on each call. + The structure FuncCallContext is provided to help + control this process. Within a function, fcinfo->flinfo->fn_extra is used to hold a pointer to FuncCallContext across calls. typedef struct { /* - * Number of times we've been called before. + * Number of times we've been called before * * call_cntr is initialized to 0 for you by SRF_FIRSTCALL_INIT(), and * incremented for you every time SRF_RETURN_NEXT() is called. @@ -1648,7 +1744,7 @@ typedef struct /* * OPTIONAL maximum number of calls * - * max_calls is here for convenience ONLY and setting it is OPTIONAL. + * max_calls is here for convenience only and setting it is optional. * If not set, you must provide alternative means to know when the * function is done. */ @@ -1657,41 +1753,43 @@ typedef struct /* * OPTIONAL pointer to result slot * - * slot is for use when returning tuples (i.e. composite data types) - * and is not needed when returning base (i.e. scalar) data types. + * slot is for use when returning tuples (i.e., composite data types) + * and is not needed when returning base data types. */ TupleTableSlot *slot; /* - * OPTIONAL pointer to misc user provided context info + * OPTIONAL pointer to miscellaneous user-provided context information * - * user_fctx is for use as a pointer to your own struct to retain - * arbitrary context information between calls for your function. + * user_fctx is for use as a pointer to your own data to retain + * arbitrary context information between calls of your function. */ void *user_fctx; /* - * OPTIONAL pointer to struct containing arrays of attribute type input - * metainfo + * OPTIONAL pointer to struct containing attribute type input metadata * - * attinmeta is for use when returning tuples (i.e. composite data types) - * and is not needed when returning base (i.e. scalar) data types. It - * is ONLY needed if you intend to use BuildTupleFromCStrings() to create + * attinmeta is for use when returning tuples (i.e., composite data types) + * and is not needed when returning base data types. It + * is only needed if you intend to use BuildTupleFromCStrings() to create * the return tuple. */ AttInMetadata *attinmeta; /* - * memory context used for structures which must live for multiple calls + * memory context used for structures that must live for multiple calls * * multi_call_memory_ctx is set by SRF_FIRSTCALL_INIT() for you, and used * by SRF_RETURN_DONE() for cleanup. It is the most appropriate memory - * context for any memory that is to be re-used across multiple calls + * context for any memory that is to be reused across multiple calls * of the SRF. */ MemoryContext multi_call_memory_ctx; } FuncCallContext; + + + An SRF uses several functions and macros that automatically manipulate the FuncCallContext structure (and expect to find it via fn_extra). Use @@ -1718,9 +1816,9 @@ SRF_PERCALL_SETUP() SRF_RETURN_NEXT(funcctx, result) - to return it to the caller. (The result must be a + to return it to the caller. (result must be of type Datum, either a single value or a tuple prepared as - described earlier.) Finally, when your function is finished + described above.) Finally, when your function is finished returning data, use SRF_RETURN_DONE(funcctx) @@ -1731,8 +1829,8 @@ SRF_RETURN_DONE(funcctx) The memory context that is current when the SRF is called is a transient context that will be cleared between calls. This means - that you do not need to pfree everything - you palloc; it will go away anyway. However, if you want to allocate + that you do not need to call pfree on everything + you allocated using palloc; it will go away anyway. However, if you want to allocate any data structures to live across calls, you need to put them somewhere else. The memory context referenced by multi_call_memory_ctx is a suitable location for any @@ -1745,45 +1843,45 @@ SRF_RETURN_DONE(funcctx) A complete pseudo-code example looks like the following: Datum -my_Set_Returning_Function(PG_FUNCTION_ARGS) +my_set_returning_function(PG_FUNCTION_ARGS) { FuncCallContext *funcctx; Datum result; MemoryContext oldcontext; - [user defined declarations] + further declarations as needed if (SRF_IS_FIRSTCALL()) { funcctx = SRF_FIRSTCALL_INIT(); oldcontext = MemoryContextSwitchTo(funcctx->multi_call_memory_ctx); - /* one-time setup code appears here: */ - [user defined code] - [if returning composite] - [build TupleDesc, and perhaps AttInMetadata] - [obtain slot] + /* One-time setup code appears here: */ + user code + if returning composite + build TupleDesc, and perhaps AttInMetadata + obtain slot funcctx->slot = slot; - [endif returning composite] - [user defined code] + endif returning composite + user code MemoryContextSwitchTo(oldcontext); } - /* each-time setup code appears here: */ - [user defined code] + /* Each-time setup code appears here: */ + user code funcctx = SRF_PERCALL_SETUP(); - [user defined code] + user code /* this is just one way we might test whether we are done: */ if (funcctx->call_cntr < funcctx->max_calls) { - /* here we want to return another item: */ - [user defined code] - [obtain result Datum] + /* Here we want to return another item: */ + user code + obtain result Datum SRF_RETURN_NEXT(funcctx, result); } else { - /* here we are done returning items, and just need to clean up: */ - [user defined code] + /* Here we are done returning items and just need to clean up: */ + user code SRF_RETURN_DONE(funcctx); } } @@ -1794,6 +1892,7 @@ my_Set_Returning_Function(PG_FUNCTION_ARGS) A complete example of a simple SRF returning a composite type looks like: PG_FUNCTION_INFO_V1(testpassbyval); + Datum testpassbyval(PG_FUNCTION_ARGS) { @@ -1801,7 +1900,7 @@ testpassbyval(PG_FUNCTION_ARGS) int call_cntr; int max_calls; TupleDesc tupdesc; - TupleTableSlot *slot; + TupleTableSlot *slot; AttInMetadata *attinmeta; /* stuff done only on the first call of the function */ @@ -1818,9 +1917,7 @@ testpassbyval(PG_FUNCTION_ARGS) /* total number of tuples to be returned */ funcctx->max_calls = PG_GETARG_UINT32(0); - /* - * Build a tuple description for a __testpassbyval tuple - */ + /* Build a tuple description for a __testpassbyval tuple */ tupdesc = RelationNameGetTupleDesc("__testpassbyval"); /* allocate a slot for a tuple with this tupdesc */ @@ -1830,7 +1927,7 @@ testpassbyval(PG_FUNCTION_ARGS) funcctx->slot = slot; /* - * Generate attribute metadata needed later to produce tuples from raw + * generate attribute metadata needed later to produce tuples from raw * C strings */ attinmeta = TupleDescGetAttInMetadata(tupdesc); @@ -1856,7 +1953,7 @@ testpassbyval(PG_FUNCTION_ARGS) /* * Prepare a values array for storage in our slot. * This should be an array of C strings which will - * be processed later by the appropriate "in" functions. + * be processed later by the type input functions. */ values = (char **) palloc(3 * sizeof(char *)); values[0] = (char *) palloc(16 * sizeof(char)); @@ -1873,150 +1970,36 @@ testpassbyval(PG_FUNCTION_ARGS) /* make the tuple into a datum */ result = TupleGetDatum(slot, tuple); - /* Clean up (this is not actually necessary) */ + /* clean up (this is not really necessary) */ pfree(values[0]); pfree(values[1]); pfree(values[2]); pfree(values); - SRF_RETURN_NEXT(funcctx, result); + SRF_RETURN_NEXT(funcctx, result); } else /* do when there is no more left */ { - SRF_RETURN_DONE(funcctx); + SRF_RETURN_DONE(funcctx); } } - with supporting SQL code of - -CREATE TYPE __testpassbyval AS (f1 int4, f2 int4, f3 int4); -CREATE OR REPLACE FUNCTION testpassbyval(int4, int4) RETURNS setof __testpassbyval - AS 'MODULE_PATHNAME','testpassbyval' LANGUAGE 'c' IMMUTABLE STRICT; + The SQL code to declare this function is: + +CREATE TYPE __testpassbyval AS (f1 integer, f2 integer, f3 integer); + +CREATE OR REPLACE FUNCTION testpassbyval(integer, integer) RETURNS SETOF __testpassbyval + AS 'filename', 'testpassbyval' + LANGUAGE C IMMUTABLE STRICT; - See contrib/tablefunc for more examples of table functions. - - - - - - - - Writing Code - - - We now turn to the more difficult task of writing - programming language functions. Be warned: this section - of the manual will not make you a programmer. You must - have a good understanding of C - (including the use of pointers) - before trying to write C functions for - use with PostgreSQL. While it may - be possible to load functions written in languages other - than C into PostgreSQL, - this is often difficult (when it is possible at all) - because other languages, such as FORTRAN - and Pascal often do not follow the same - calling convention - as C. That is, other - languages do not pass argument and return values - between functions in the same way. For this reason, we - will assume that your programming language functions - are written in C. - - - - The basic rules for building C functions - are as follows: - - - - - Use pg_config --includedir-serverpg_config to find - out where the PostgreSQL server header files are installed on - your system (or the system that your users will be running - on). This option is new with PostgreSQL 7.2. - For PostgreSQL - 7.1 you should use the option . - (pg_config will exit with a non-zero status - if it encounters an unknown option.) For releases prior to - 7.1 you will have to guess, but since that was before the - current calling conventions were introduced, it is unlikely - that you want to support those releases. - - - - - - When allocating memory, use the - PostgreSQL routines - palloc and pfree - instead of the corresponding C library - routines malloc and - free. The memory allocated by - palloc will be freed automatically at the - end of each transaction, preventing memory leaks. - - - - - - Always zero the bytes of your structures using - memset or bzero. - Several routines (such as the hash access method, hash join - and the sort algorithm) compute functions of the raw bits - contained in your structure. Even if you initialize all - fields of your structure, there may be several bytes of - alignment padding (holes in the structure) that may contain - garbage values. - - - - - - Most of the internal PostgreSQL types - are declared in postgres.h, while the function - manager interfaces (PG_FUNCTION_ARGS, etc.) - are in fmgr.h, so you will need to - include at least these two files. For portability reasons it's best - to include postgres.h first, - before any other system or user header files. - Including postgres.h will also include - elog.h and palloc.h - for you. - - - - - - Symbol names defined within object files must not conflict - with each other or with symbols defined in the - PostgreSQL server executable. You - will have to rename your functions or variables if you get - error messages to this effect. - - - - - - Compiling and linking your object code so that - it can be dynamically loaded into - PostgreSQL - always requires special flags. - See - for a detailed explanation of how to do it for - your particular operating system. - - - + The directory contrib/tablefunc in the source + distribution contains more examples of set-returning functions. - -&dfunc; - @@ -2035,9 +2018,11 @@ CREATE OR REPLACE FUNCTION testpassbyval(int4, int4) RETURNS setof __testpassbyv - A function may also have the same name as an attribute. In the case - that there is an ambiguity between a function on a complex type and - an attribute of the complex type, the attribute will always be used. + A function may also have the same name as an attribute. (Recall + that attribute(table) is equivalent to + table.attribute.) In the case that there is an + ambiguity between a function on a complex type and an attribute of + the complex type, the attribute will always be used. @@ -2056,7 +2041,7 @@ CREATE FUNCTION test(smallint, double precision) RETURNS ... - When overloading C language functions, there is an additional + When overloading C-language functions, there is an additional constraint: The C name of each function in the family of overloaded functions must be different from the C names of all other functions, either internal or dynamically loaded. If this @@ -2076,85 +2061,6 @@ CREATE FUNCTION test(int, int) RETURNS int The names of the C functions here reflect one of many possible conventions. - - - Prior to PostgreSQL 7.0, this - alternative syntax did not exist. There is a trick to get around - the problem, by defining a set of C functions with different names - and then define a set of identically-named SQL function wrappers - that take the appropriate argument types and call the matching C - function. - - - - - Table Functions - - function - - - Table functions are functions that produce a set of rows, made up of - either base (scalar) data types, or composite (multi-column) data types. - They are used like a table, view, or subselect in the FROM - clause of a query. Columns returned by table functions may be included in - SELECT, JOIN, or WHERE clauses in the - same manner as a table, view, or subselect column. - - - - If a table function returns a base data type, the single result column - is named for the function. If the function returns a composite type, the - result columns get the same names as the individual attributes of the type. - - - - A table function may be aliased in the FROM clause, but it also - may be left unaliased. If a function is used in the FROM clause with no - alias, the function name is used as the relation name. - - - - Table functions work wherever tables do in SELECT statements. - For example - -CREATE TABLE foo (fooid int, foosubid int, fooname text); - -CREATE FUNCTION getfoo(int) RETURNS setof foo AS ' - SELECT * FROM foo WHERE fooid = $1; -' LANGUAGE SQL; - -SELECT * FROM getfoo(1) AS t1; - -SELECT * FROM foo -WHERE foosubid in (select foosubid from getfoo(foo.fooid) z - where z.fooid = foo.fooid); - -CREATE VIEW vw_getfoo AS SELECT * FROM getfoo(1); -SELECT * FROM vw_getfoo; - - are all valid statements. - - - - In some cases it is useful to define table functions that can return - different column sets depending on how they are invoked. To support this, - the table function can be declared as returning the pseudo-type - record. When such a function is used in a query, the expected - row structure must be specified in the query itself, so that the system - can know how to parse and plan the query. Consider this example: - -SELECT * -FROM dblink('dbname=template1', 'select proname, prosrc from pg_proc') - AS t1(proname name, prosrc text) -WHERE proname LIKE 'bytea%'; - - The dblink function executes a remote query (see - contrib/dblink). It is declared to return record - since it might be used for any kind of query. The actual column set - must be specified in the calling query so that the parser knows, for - example, what * should expand to. - - @@ -2179,22 +2085,14 @@ WHERE proname LIKE 'bytea%'; The call handler for a procedural language is a - normal function, which must be written in a - compiled language such as C and registered with - PostgreSQL as taking no arguments and - returning the language_handler type. - This special pseudo-type identifies the handler as a call handler - and prevents it from being called directly in queries. + normal function that must be written in a compiled + language such as C, using the version-1 interface, and registered + with PostgreSQL as taking no arguments + and returning the type language_handler. This + special pseudotype identifies the function as a call handler and + prevents it from being called directly in SQL commands. - - - In PostgreSQL 7.1 and later, call - handlers must adhere to the version 1 function - manager interface, not the old-style interface. - - - The call handler is called in the same way as any other function: It receives a pointer to a @@ -2203,7 +2101,7 @@ WHERE proname LIKE 'bytea%'; is expected to return a Datum result (and possibly set the isnull field of the FunctionCallInfoData structure, if it wishes - to return an SQL NULL result). The difference between a call + to return an SQL null result). The difference between a call handler and an ordinary callee function is that the flinfo->fn_oid field of the FunctionCallInfoData structure will contain @@ -2215,12 +2113,12 @@ WHERE proname LIKE 'bytea%'; - It's up to the call handler to fetch the - pg_proc entry and to analyze the argument - and return types of the called procedure. The AS clause from the - CREATE FUNCTION of the procedure will be found - in the prosrc attribute of the - pg_proc table entry. This may be the source + It's up to the call handler to fetch the entry of the function from the system table + pg_proc and to analyze the argument + and return types of the called function. The AS clause from the + CREATE FUNCTION of the function will be found + in the prosrc column of the + pg_proc row. This may be the source text in the procedural language itself (like for PL/Tcl), a path name to a file, or anything else that tells the call handler what to do in detail. @@ -2231,11 +2129,11 @@ WHERE proname LIKE 'bytea%'; A call handler can avoid repeated lookups of information about the called function by using the flinfo->fn_extra field. This will - initially be NULL, but can be set by the call handler to point at - information about the PL function. On subsequent calls, if - flinfo->fn_extra is already non-NULL + initially be NULL, but can be set by the call handler to point at + information about the called function. On subsequent calls, if + flinfo->fn_extra is already non-NULL then it can be used and the information lookup step skipped. The - call handler must be careful that + call handler must make sure that flinfo->fn_extra is made to point at memory that will live at least until the end of the current query, since an FmgrInfo data structure could be @@ -2244,23 +2142,23 @@ WHERE proname LIKE 'bytea%'; flinfo->fn_mcxt; such data will normally have the same lifespan as the FmgrInfo itself. But the handler could - also choose to use a longer-lived context so that it can cache + also choose to use a longer-lived memory context so that it can cache function definition information across queries. - When a PL function is invoked as a trigger, no explicit arguments - are passed, but the + When a procedural-language function is invoked as a trigger, no arguments + are passed in the usual way, but the FunctionCallInfoData's context field points at a - TriggerData node, rather than being NULL + TriggerData structure, rather than being NULL as it is in a plain function call. A language handler should - provide mechanisms for PL functions to get at the trigger + provide mechanisms for procedural-language functions to get at the trigger information. - This is a template for a PL handler written in C: + This is a template for a procedural-language handler written in C: #include "postgres.h" #include "executor/spi.h" @@ -2288,7 +2186,8 @@ plsample_call_handler(PG_FUNCTION_ARGS) retval = ... } - else { + else + { /* * Called as a function */ @@ -2299,27 +2198,23 @@ plsample_call_handler(PG_FUNCTION_ARGS) return retval; } - - - Only a few thousand lines of code have to be added instead of the - dots to complete the call handler. See - for information on how to compile it into a loadable module. + dots to complete the call handler. - The following commands then register the sample procedural - language: + After having compiled the handler function into a loadable module + (see ), the following commands then + register the sample procedural language: -CREATE FUNCTION plsample_call_handler () RETURNS language_handler - AS '/usr/local/pgsql/lib/plsample' +CREATE FUNCTION plsample_call_handler() RETURNS language_handler + AS 'filename' LANGUAGE C; CREATE LANGUAGE plsample HANDLER plsample_call_handler; - - - Extending <Acronym>SQL</Acronym>: Operators - - - Introduction - - - PostgreSQL supports left unary, - right unary, and binary - operators. Operators can be overloaded; that is, - the same operator name can be used for different operators - that have different numbers and types of operands. If - there is an ambiguous situation and the system cannot - determine the correct operator to use, it will return - an error. You may have to type-cast the left and/or - right operands to help it understand which operator you - meant to use. - + + User-defined Operators Every operator is syntactic sugar for a call to an @@ -28,13 +12,18 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xoper.sgml,v 1.22 2003/01/15 19:35:35 tgl E the operator. However, an operator is not merely syntactic sugar, because it carries additional information that helps the query planner optimize queries that use the - operator. Much of this chapter will be devoted to explaining + operator. The next section will be devoted to explaining that additional information. - - - Example + + PostgreSQL supports left unary, right + unary, and binary operators. Operators can be overloaded; that is, + the same operator name can be used for different operators that + have different numbers and types of operands. When a query is + executed, the system determines the operator to call from the + number and types of the provided operands. + Here is an example of creating an operator for adding two complex @@ -45,7 +34,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xoper.sgml,v 1.22 2003/01/15 19:35:35 tgl E CREATE FUNCTION complex_add(complex, complex) RETURNS complex - AS 'PGROOT/tutorial/complex' + AS 'filename', 'complex_add' LANGUAGE C; CREATE OPERATOR + ( @@ -58,7 +47,7 @@ CREATE OPERATOR + ( - Now we can do: + Now we could execute a query like this: SELECT (a + b) AS c FROM test_complex; @@ -78,20 +67,13 @@ SELECT (a + b) AS c FROM test_complex; CREATE OPERATOR. The commutator clause shown in the example is an optional hint to the query optimizer. Further details about commutator and other - optimizer hints appear below. + optimizer hints appear in the next section. Operator Optimization Information - - Author - - Written by Tom Lane. - - - A PostgreSQL operator definition can include several optional clauses that tell the system useful things about how @@ -99,7 +81,7 @@ SELECT (a + b) AS c FROM test_complex; appropriate, because they can make for considerable speedups in execution of queries that use the operator. But if you provide them, you must be sure that they are right! Incorrect use of an optimization clause can - result in backend crashes, subtly wrong output, or other Bad Things. + result in server process crashes, subtly wrong output, or other Bad Things. You can always leave out an optimization clause if you are not sure about it; the only consequence is that queries might run slower than they need to. @@ -112,7 +94,7 @@ SELECT (a + b) AS c FROM test_complex; - COMMUTATOR + <literal>COMMUTATOR</> The COMMUTATOR clause, if provided, names an operator that is the @@ -155,7 +137,7 @@ SELECT (a + b) AS c FROM test_complex; The other, more straightforward way is just to include COMMUTATOR clauses in both definitions. When PostgreSQL processes - the first definition and realizes that COMMUTATOR refers to a non-existent + the first definition and realizes that COMMUTATOR refers to a nonexistent operator, the system will make a dummy entry for that operator in the system catalog. This dummy entry will have valid data only for the operator name, left and right operand types, and result type, @@ -164,9 +146,7 @@ SELECT (a + b) AS c FROM test_complex; dummy entry. Later, when you define the second operator, the system updates the dummy entry with the additional information from the second definition. If you try to use the dummy operator before it's been filled - in, you'll just get an error message. (Note: This procedure did not work - reliably in PostgreSQL versions before 6.5, - but it is now the recommended way to do things.) + in, you'll just get an error message. @@ -174,7 +154,7 @@ SELECT (a + b) AS c FROM test_complex; - NEGATOR + <literal>NEGATOR</> The NEGATOR clause, if provided, names an operator that is the @@ -194,14 +174,14 @@ SELECT (a + b) AS c FROM test_complex; An operator's negator must have the same left and/or right operand types - as the operator itself, so just as with COMMUTATOR, only the operator + as the operator to be defined, so just as with COMMUTATOR, only the operator name need be given in the NEGATOR clause. Providing a negator is very helpful to the query optimizer since it allows expressions like NOT (x = y) to be simplified into - x <> y. This comes up more often than you might think, because + x <> y. This comes up more often than you might think, because NOT operations can be inserted as a consequence of other rearrangements. @@ -213,12 +193,12 @@ SELECT (a + b) AS c FROM test_complex; - RESTRICT + <literal>RESTRICT</> The RESTRICT clause, if provided, names a restriction selectivity - estimation function for the operator (note that this is a function - name, not an operator name). RESTRICT clauses only make sense for + estimation function for the operator. (Note that this is a function + name, not an operator name.) RESTRICT clauses only make sense for binary operators that return boolean. The idea behind a restriction selectivity estimator is to guess what fraction of the rows in a table will satisfy a WHERE-clause condition of the form @@ -269,15 +249,15 @@ column OP constant You can use scalarltsel and scalargtsel for comparisons on data types that have some sensible means of being converted into numeric scalars for range comparisons. If possible, add the data type to those understood - by the routine convert_to_scalar() in src/backend/utils/adt/selfuncs.c. - (Eventually, this routine should be replaced by per-data-type functions + by the function convert_to_scalar() in src/backend/utils/adt/selfuncs.c. + (Eventually, this function should be replaced by per-data-type functions identified through a column of the pg_type system catalog; but that hasn't happened yet.) If you do not do this, things will still work, but the optimizer's estimates won't be as good as they could be. - There are additional selectivity functions designed for geometric + There are additional selectivity estimation functions designed for geometric operators in src/backend/utils/adt/geo_selfuncs.c: areasel, positionsel, and contsel. At this writing these are just stubs, but you may want to use them (or even better, improve them) anyway. @@ -285,12 +265,12 @@ column OP constant - JOIN + <literal>JOIN</> The JOIN clause, if provided, names a join selectivity - estimation function for the operator (note that this is a function - name, not an operator name). JOIN clauses only make sense for + estimation function for the operator. (Note that this is a function + name, not an operator name.) JOIN clauses only make sense for binary operators that return boolean. The idea behind a join selectivity estimator is to guess what fraction of the rows in a pair of tables will satisfy a WHERE-clause condition of the form @@ -319,13 +299,13 @@ table1.column1 OP table2.column2 - HASHES + <literal>HASHES</> The HASHES clause, if present, tells the system that it is permissible to use the hash join method for a join based on this - operator. HASHES only makes sense for binary operators that - return boolean, and in practice the operator had better be + operator. HASHES only makes sense for a binary operator that + returns boolean, and in practice the operator had better be equality for some data type. @@ -340,33 +320,35 @@ table1.column1 OP table2.column2 In fact, logical equality is not good enough either; the operator - had better represent pure bitwise equality, because the hash function - will be computed on the memory representation of the values regardless - of what the bits mean. For example, equality of - time intervals is not bitwise equality; the interval equality operator - considers two time intervals equal if they have the same - duration, whether or not their endpoints are identical. What this means - is that a join using = between interval fields would yield different - results if implemented as a hash join than if implemented another way, - because a large fraction of the pairs that should match will hash to - different values and will never be compared by the hash join. But - if the optimizer chose to use a different kind of join, all the pairs - that the equality operator says are equal will be found. - We don't want that kind of inconsistency, so we don't mark interval - equality as hashable. + had better represent pure bitwise equality, because the hash + function will be computed on the memory representation of the + values regardless of what the bits mean. For example, the + polygon operator ~=, which checks whether two + polygons are the same, is not bitwise equality, because two + polygons can be considered the same even if their vertices are + specified in a different order. What this means is that a join + using ~= between polygon fields would yield + different results if implemented as a hash join than if + implemented another way, because a large fraction of the pairs + that should match will hash to different values and will never be + compared by the hash join. But if the optimizer chooses to use a + different kind of join, all the pairs that the operator + ~= says are the same will be found. We don't + want that kind of inconsistency, so we don't mark the polygon + operator ~= as hashable. There are also machine-dependent ways in which a hash join might fail to do the right thing. For example, if your data type is a structure in which there may be uninteresting pad bits, it's unsafe - to mark the equality operator HASHES. (Unless, perhaps, you write - your other operators to ensure that the unused bits are always zero.) + to mark the equality operator HASHES. (Unless you write + your other operators and functions to ensure that the unused bits are always zero, which is the recommended strategy.) Another example is that the floating-point data types are unsafe for hash - joins. On machines that meet the IEEE floating-point standard, minus - zero and plus zero are different values (different bit patterns) but + joins. On machines that meet the IEEE floating-point standard, negative + zero and positive zero are different values (different bit patterns) but they are defined to compare equal. So, if the equality operator on floating-point data types were marked - HASHES, a minus zero and a plus zero would probably not be matched up + HASHES, a negative zero and a positive zero would probably not be matched up by a hash join, but they would be matched up by any other join process. @@ -403,9 +385,9 @@ table1.column1 OP table2.column2 The MERGES clause, if present, tells the system that - it is permissible to use the merge join method for a join based on this - operator. MERGES only makes sense for binary operators that - return boolean, and in practice the operator must represent + it is permissible to use the merge-join method for a join based on this + operator. MERGES only makes sense for a binary operator that + returns boolean, and in practice the operator must represent equality for some data type or pair of data types. @@ -420,7 +402,7 @@ table1.column1 OP table2.column2 data types had better be the same (or at least bitwise equivalent), it is possible to merge-join two distinct data types so long as they are logically compatible. For - example, the int2-versus-int4 equality operator + example, the smallint-versus-integer equality operator is merge-joinable. We only need sorting operators that will bring both data types into a logically compatible sequence. @@ -429,11 +411,11 @@ table1.column1 OP table2.column2 Execution of a merge join requires that the system be able to identify four operators related to the merge-join equality operator: less-than - comparison for the left input data type, less-than comparison for the - right input data type, less-than comparison between the two data types, and + comparison for the left operand data type, less-than comparison for the + right operand data type, less-than comparison between the two data types, and greater-than comparison between the two data types. (These are actually four distinct operators if the merge-joinable operator has two different - input data types; but when the input types are the same the three + operand data types; but when the operand types are the same the three less-than operators are all the same operator.) It is possible to specify these operators individually by name, as the SORT1, @@ -447,8 +429,8 @@ table1.column1 OP table2.column2 - The input data types of the four comparison operators can be deduced - from the input types of the merge-joinable operator, so just as with + The operand data types of the four comparison operators can be deduced + from the operand types of the merge-joinable operator, so just as with COMMUTATOR, only the operator names need be given in these clauses. Unless you are using peculiar choices of operator names, it's sufficient to write MERGES and let the system fill in @@ -469,7 +451,7 @@ table1.column1 OP table2.column2 A merge-joinable equality operator must have a merge-joinable - commutator (itself if the two data types are the same, or a related + commutator (itself if the two operand data types are the same, or a related equality operator if they are different). @@ -523,11 +505,8 @@ table1.column1 OP table2.column2 < and > respectively. - - - + + + User-Defined Types data types @@ -7,22 +11,20 @@ - This chapter needs to be updated for the version-1 function manager + This section needs to be updated for the version-1 function manager interface. - As previously mentioned, there are two kinds of types in - PostgreSQL: base types (defined in a - programming language) and composite types. This chapter describes - how to define new base types. + As described above, there are two kinds of data types in + PostgreSQL: base types and composite + types. This section describes how to define new base types. The examples in this section can be found in complex.sql and complex.c - in the tutorial directory. Composite examples are in - funcs.sql. + in the tutorial directory. @@ -36,15 +38,15 @@ These functions determine how the type appears in strings (for input by the user and output to the user) and how the type is organized in memory. The input function takes a null-terminated character string - as its input and returns the internal (in memory) representation of + as its argument and returns the internal (in memory) representation of the type. The output function takes the internal representation of - the type and returns a null-terminated character string. + the type as argument and returns a null-terminated character string. - Suppose we want to define a complex type which represents complex - numbers. Naturally, we would choose to represent a complex in memory - as the following C structure: + Suppose we want to define a type complex that represents + complex numbers. A natural way to to represent a complex number in + memory would be the following C structure: typedef struct Complex { @@ -53,24 +55,16 @@ typedef struct Complex { } Complex; - and a string of the form (x,y) as the external string - representation. + As the external string representation of the type, we choose a + string of the form (x,y). - The functions are usually not hard to write, especially the output - function. However, there are a number of points to remember: - - - - - When defining your external (string) representation, remember - that you must eventually write a complete and robust parser for - that representation as your input function! - - - - For instance: + The input and output functions are usually not hard to write, + especially the output function. But when defining the external + string representation of the type, remember that you must eventually + write a complete and robust parser for that representation as your + input function. For instance: Complex * @@ -78,48 +72,42 @@ complex_in(char *str) { double x, y; Complex *result; - if (sscanf(str, " ( %lf , %lf )", &x, &y) != 2) { + + if (sscanf(str, " ( %lf , %lf )", &x, &y) != 2) + { elog(ERROR, "complex_in: error in parsing %s", str); return NULL; } - result = (Complex *)palloc(sizeof(Complex)); + result = (Complex *) palloc(sizeof(Complex)); result->x = x; result->y = y; - return (result); + return result; } - - - The output function can simply be: + The output function can simply be: char * complex_out(Complex *complex) { char *result; + if (complex == NULL) return(NULL); result = (char *) palloc(60); sprintf(result, "(%g,%g)", complex->x, complex->y); - return(result); + return result; } + - - - - - - You should try to make the input and output functions inverses of - each other. If you do not, you will have severe problems when - you need to dump your data into a file and then read it back in - (say, into someone else's database on another computer). This is - a particularly common problem when floating-point numbers are - involved. - - - + + You should try to make the input and output functions inverses of + each other. If you do not, you will have severe problems when you + need to dump your data into a file and then read it back in. This + is a particularly common problem when floating-point numbers are + involved. @@ -130,14 +118,18 @@ complex_out(Complex *complex) CREATE FUNCTION complex_in(cstring) RETURNS complex - AS 'PGROOT/tutorial/complex' + AS 'filename' LANGUAGE C; CREATE FUNCTION complex_out(complex) RETURNS cstring - AS 'PGROOT/tutorial/complex' + AS 'filename' LANGUAGE C; + + Notice that the declarations of the input and output functions must + reference the not-yet-defined type. This is allowed, but will draw + warning messages that may be ignored. @@ -149,49 +141,36 @@ CREATE TYPE complex ( output = complex_out ); - - Notice that the declarations of the input and output functions must - reference the not-yet-defined type. This is allowed, but will draw - warning messages that may be ignored. - - arrays - - As discussed earlier, PostgreSQL fully - supports arrays of base types. Additionally, - PostgreSQL supports arrays of - user-defined types as well. When you define a type, + When you define a new base type, PostgreSQL automatically provides support - for arrays of that type. For historical reasons, the array type has - the same name as the user-defined type with the underscore character - _ prepended. + for arrays of that + type.arrayof user-defined + type For historical reasons, the array type + has the same name as the base type with the underscore character + (_) prepended. - Composite types do not need any function defined on them, since the - system already understands what they look like inside. - - - - - TOAST - and user-defined types - If the values of your data type might exceed a few hundred bytes in - size (in internal form), you should be careful to mark them - TOAST-able. To do this, the internal representation must follow the - standard layout for variable-length data: the first four bytes must - be an int32 containing the total length in bytes of the - datum (including itself). Then, all your functions that accept - values of the type must be careful to call - pg_detoast_datum() on the supplied values --- - after checking that the value is not NULL, if your function is not - strict. Finally, select the appropriate storage option when giving - the CREATE TYPE command. + size (in internal form), you should mark them + TOAST-able.TOASTand + user-defined types To do this, the internal + representation must follow the standard layout for variable-length + data: the first four bytes must be an int32 containing + the total length in bytes of the datum (including itself). Also, + when running the CREATE TYPE command, specify the + internal length as variable and select the appropriate + storage option. - + + + For further details see the description of the CREATE + TYPE command in . + +