From: Pavan Deolasee Date: Tue, 28 Jul 2015 06:43:48 +0000 (+0530) Subject: Remove doc-xc directory and supporting infrastructure to build XC docs X-Git-Tag: XL9_5_R1BETA1~172 X-Git-Url: http://git.postgresql.org/gitweb/static/gitweb.js?a=commitdiff_plain;h=ff1010e0aa3b94815ed71657c8c3d0bba7aa42ae;p=postgres-xl.git Remove doc-xc directory and supporting infrastructure to build XC docs We now change the documentation in-place and hence don't need this additional copy of the docs. The doc changes are already rebased on the original 9.5 docs per previous commit --- diff --git a/GNUmakefile.in b/GNUmakefile.in index 8bbd1cb83d..15fba9fce0 100644 --- a/GNUmakefile.in +++ b/GNUmakefile.in @@ -14,9 +14,9 @@ all: +@echo "All of PostgreSQL successfully made. Ready to install." docs: - $(MAKE) -C doc-xc all + $(MAKE) -C doc all -$(call recurse,world,doc-xc src config contrib,all) +$(call recurse,world,doc src config contrib,all) world: +@echo "PostgreSQL, contrib, and documentation successfully made. Ready to install." @@ -24,28 +24,28 @@ world: world-contrib-recurse: world-src-recurse html man: - $(MAKE) -C doc-xc $@ + $(MAKE) -C doc $@ install: +@echo "PostgreSQL installation complete." install-docs: - $(MAKE) -C doc-xc install + $(MAKE) -C doc install -$(call recurse,install-world,doc-xc src config contrib,install) +$(call recurse,install-world,doc src config contrib,install) install-world: +@echo "PostgreSQL, contrib, and documentation installation complete." # build src/ before contrib/ install-world-contrib-recurse: install-world-src-recurse -$(call recurse,installdirs uninstall coverage init-po update-po,doc-xc src config) +$(call recurse,installdirs uninstall coverage init-po update-po,doc src config) -$(call recurse,distprep,doc-xc src config contrib) +$(call recurse,distprep,doc src config contrib) # clean, distclean, etc should apply to contrib too, even though # it's not built by default -$(call recurse,clean,doc-xc contrib src config) +$(call recurse,clean,doc contrib src config) clean: rm -rf tmp_install/ # Garbage from autoconf: @@ -54,7 +54,7 @@ clean: # Important: distclean `src' last, otherwise Makefile.global # will be gone too soon. distclean maintainer-clean: - $(MAKE) -C doc-xc $@ + $(MAKE) -C doc $@ $(MAKE) -C contrib $@ $(MAKE) -C config $@ $(MAKE) -C src $@ diff --git a/doc-xc/KNOWN_BUGS b/doc-xc/KNOWN_BUGS deleted file mode 100644 index 44dd8812b7..0000000000 --- a/doc-xc/KNOWN_BUGS +++ /dev/null @@ -1,3 +0,0 @@ -PostgreSQL has a single combined bugs, missing features, and todo list -simply called TODO, in this directory. A current copy is always -available on our web site. diff --git a/doc-xc/MISSING_FEATURES b/doc-xc/MISSING_FEATURES deleted file mode 100644 index 44dd8812b7..0000000000 --- a/doc-xc/MISSING_FEATURES +++ /dev/null @@ -1,3 +0,0 @@ -PostgreSQL has a single combined bugs, missing features, and todo list -simply called TODO, in this directory. A current copy is always -available on our web site. diff --git a/doc-xc/Makefile b/doc-xc/Makefile deleted file mode 100644 index 2e5e09ef88..0000000000 --- a/doc-xc/Makefile +++ /dev/null @@ -1,16 +0,0 @@ -#---------------------------------------------------------------------------- -# -# PostgreSQL documentation top-level makefile -# -# Copyright (c) 1994, Regents of the University of California -# -# doc/Makefile -# -#---------------------------------------------------------------------------- - -subdir = doc -top_builddir = .. -include $(top_builddir)/src/Makefile.global - -all distprep html man install installdirs uninstall clean distclean maintainer-clean maintainer-check: - $(MAKE) -C src $@ diff --git a/doc-xc/README.mb.big5 b/doc-xc/README.mb.big5 deleted file mode 100644 index 529af95591..0000000000 --- a/doc-xc/README.mb.big5 +++ /dev/null @@ -1,326 +0,0 @@ -PostgreSQL 7.0.1 multi-byte (MB) support README May 20 2000 - - Tatsuo Ishii - ishii@postgresql.org - http://www.sra.co.jp/people/t-ishii/PostgreSQL/ - -[µù] 1. ·PÁÂ¥Û¤«¹F¤Ò (Tatsuo Ishii) ¥ý¥Í! - 2. µùÄÀ³¡¥÷­ì¤å©ÒµL, ¤¤Ä¶­Y¦³¿ù»~, ½ÐÁpµ¸ cch@cc.kmu.edu.tw - - -0. ²¤¶ - -MB ¤ä´©¬O¬°¤FÅý PostgreSQL ¯à³B²z¦h¦ì¤¸²Õ¦r¤¸ (multi-byte character), -¨Ò¦p: EUC (Extended Unix Code), Unicode (²Î¤@½X) ©M Mule internal code -(¦h°ê»y¨¥¤º½X). ¦b MB ªº¤ä´©¤U, §A¥i¥H¦b¥¿³Wªí¥Ü¦¡ (regexp), LIKE ¤Î -¨ä¥L¤@¨Ç¨ç¦¡¤¤¨Ï¥Î¦h¦ì¤¸²Õ¦r¤¸. ¹w³]ªº½s½X¨t²Î¥i¨ú¨M©ó§A¦w¸Ë PostgreSQL -®Éªº initdb(1) ©R¥O, ¥ç¥i¥Ñ createdb(1) ©R¥O©Î«Ø¥ß¸ê®Æ®wªº SQL ©R¥O¨M©w. -©Ò¥H§A¥i¥H¦³¦h­Ó¤£¦P½s½X¨t²Îªº¸ê®Æ®w. - -MB ¤ä´©¤]¸Ñ¨M¤F¤@¨Ç 8 ¦ì¤¸³æ¦ì¤¸²Õ¦r¤¸¶° (¥]§t ISO-8859-1) ªº¬ÛÃö°ÝÃD, -(§Ú¨Ã¨S¦³»¡©Ò¦³ªº¬ÛÃö°ÝÃD³£¸Ñ¨M¤F, §Ú¥u¬O½T»{¤F°jÂk´ú¸Õ°õ¦æ¦¨¥\, -¦Ó¤@¨Çªk»y¦r¤¸¦b MB ­×¸É¤U¥i¥H¨Ï¥Î. ¦pªG§A¦b¨Ï¥Î 8 ¦ì¤¸¦r¤¸®Éµo²{¤F -¥ô¦ó°ÝÃD, ½Ð³qª¾§Ú) - -1. ¦p¦ó¨Ï¥Î - -½sĶ PostgreSQL «e, °õ¦æ configure ®É¨Ï¥Î multibyte ªº¿ï¶µ - - % ./configure --enable-multibyte[=encoding_system] - % ./configure --enable-multibyte[=½s½X¨t²Î] - -¨ä¤¤ªº½s½X¨t²Î¥i¥H«ü©w¬°¤U­±¨ä¤¤¤§¤@: - - SQL_ASCII ASCII - EUC_JP Japanese EUC - EUC_CN Chinese EUC - EUC_KR Korean EUC - EUC_TW Taiwan EUC - UNICODE Unicode(UTF-8) - MULE_INTERNAL Mule internal - LATIN1 ISO 8859-1 English and some European languages - LATIN2 ISO 8859-2 English and some European languages - LATIN3 ISO 8859-3 English and some European languages - LATIN4 ISO 8859-4 English and some European languages - LATIN5 ISO 8859-5 English and some European languages - KOI8 KOI8-R - WIN Windows CP1251 - ALT Windows CP866 - -¨Ò¦p: - - % ./configure --enable-multibyte=EUC_JP - -¦pªG¬Ù²¤«ü©w½s½X¨t²Î, ¨º»ò¹w³]­È´N¬O SQL_ASCII. - -2. ¦p¦ó³]©w½s½X - -initdb ©R¥O©w¸q PostgresSQL ¦w¸Ë«áªº¹w³]½s½X, ¨Ò¦p: - - % initdb -E EUC_JP - -±N¹w³]ªº½s½X³]©w¬° EUC_JP (Extended Unix Code for Japanese), ¦pªG§A³ßÅw -¸ûªøªº¦r¦ê, §A¤]¥i¥H¥Î "--encoding" ¦Ó¤£¥Î "-E". ¦pªG¨S¦³¨Ï¥Î -E ©Î ---encoding ªº¿ï¶µ, ¨º»ò½sö®Éªº³]©w·|¦¨¬°¹w³]­È. - -§A¥i¥H«Ø¥ß¨Ï¥Î¤£¦P½s½Xªº¸ê®Æ®w: - - % createdb -E EUC_KR korean - -³o­Ó©R¥O·|«Ø¥ß¤@­Ó¥s°µ "korean" ªº¸ê®Æ®w, ¦Ó¨ä±Ä¥Î EUC_KR ½s½X. -¥t¥~¦³¤@­Ó¤èªk, ¬O¨Ï¥Î SQL ©R¥O, ¤]¥i¥H¹F¨ì¦P¼Ëªº¥Øªº: - - CREATE DATABASE korean WITH ENCODING = 'EUC_KR'; - -¦b pg_database ¨t²Î³W®æªí (system catalog) ¤¤¦³¤@­Ó "encoding" ªºÄæ¦ì, -´N¬O¥Î¨Ó¬ö¿ý¤@­Ó¸ê®Æ®wªº½s½X. §A¥i¥H¥Î psql -l ©Î¶i¤J psql «á¥Î \l ªº -©R¥O¨Ó¬d¬Ý¸ê®Æ®w±Ä¥Î¦óºØ½s½X: - -$ psql -l - List of databases - Database | Owner | Encoding ----------------+---------+--------------- - euc_cn | t-ishii | EUC_CN - euc_jp | t-ishii | EUC_JP - euc_kr | t-ishii | EUC_KR - euc_tw | t-ishii | EUC_TW - mule_internal | t-ishii | MULE_INTERNAL - regression | t-ishii | SQL_ASCII - template1 | t-ishii | EUC_JP - test | t-ishii | EUC_JP - unicode | t-ishii | UNICODE -(9 rows) - -3. «eºÝ»P«áºÝ½s½Xªº¦Û°ÊÂà´« - -[µù: «eºÝªx«ü«È¤áºÝªºµ{¦¡, ¥i¯à¬O psql ©R¥O¸ÑĶ¾¹, ©Î±Ä¥Î libpq ªº C -µ{¦¡, Perl µ{¦¡, ©ÎªÌ¬O³z¹L ODBC ªºµøµ¡À³¥Îµ{¦¡. ¦Ó«áºÝ´N¬O«ü PostgreSQL -¸ê®Æ®wªº¦øªAµ{¦¡] - -PostgreSQL ¤ä´©¬Y¨Ç½s½X¦b«eºÝ»P«áºÝ¶¡°µ¦Û°ÊÂà´«: [µù: ³o¸Ì©Ò¿×ªº¦Û°Ê -Âà´«¬O«ü§A¦b«eºÝ¤Î«áºÝ©Ò«Å§i±Ä¥Îªº½s½X¤£¦P, ¦ý¥u­n PostgreSQL ¤ä´©³o -¨âºØ½s½X¶¡ªºÂà´«, ¨º»ò¥¦·|À°§A¦b¦s¨ú«e°µÂà´«] - - encoding of backend available encoding of frontend - -------------------------------------------------------------------- - EUC_JP EUC_JP, SJIS - - EUC_TW EUC_TW, BIG5 - - LATIN2 LATIN2, WIN1250 - - LATIN5 LATIN5, WIN, ALT - - MULE_INTERNAL EUC_JP, SJIS, EUC_KR, EUC_CN, - EUC_TW, BIG5, LATIN1 to LATIN5, - WIN, ALT, WIN1250 - -¦b±Ò°Ê¦Û°Ê½s½XÂà´«¤§«e, §A¥²¶·§i¶D PostgreSQL §A­n¦b«eºÝ±Ä¥Î¦óºØ½s½X. -¦³¦n´X­Ó¤èªk¥i¥H¹F¨ì³o­Ó¥Øªº: - -o ¦b psql ©R¥O¸ÑĶ¾¹¤¤¨Ï¥Î \encoding ³o­Ó©R¥O - -\encoding ³o­Ó©R¥O¥i¥HÅý§A°¨¤W¤Á´««eºÝ½s½X, ¨Ò¦p, §A­n±N«eºÝ½s½X¤Á´«¬° SJIS, -¨º»ò½Ð¥´: - - \encoding SJIS - -o ¨Ï¥Î libpq [µù: PostgreSQL ¸ê®Æ®wªº C API µ{¦¡®w] ªº¨ç¦¡ - -psql ªº \encoding ©R¥O¨ä¹ê¥u¬O¥h©I¥s PQsetClientEncoding() ³o­Ó¨ç¦¡¨Ó¹F¨ì¥Øªº. - - int PQsetClientEncoding(PGconn *conn, const char *encoding) - -¤W¦¡¤¤ conn ³o­Ó°Ñ¼Æ¥Nªí¤@­Ó¹ï«áºÝªº³s½u, encoding ³o­Ó°Ñ¼Æ­n©ñ§A·Q¥Îªº½s½X, -°²¦p¥¦¦¨¥\¦a³]©w¤F½s½X, «K·|¶Ç¦^ 0 ­È, ¥¢±Ñªº¸Ü¶Ç¦^ -1. ¦Ü©ó¥Ø«e³s½uªº½s½X¥i -§Q¥Î¥H¤U¨ç¦¡¬dª¾: - - int PQclientEncoding(const PGconn *conn) - -³o¸Ì­nª`·Nªº¬O: ³o­Ó¨ç¦¡¶Ç¦^ªº¬O½s½Xªº¥N¸¹ (encoding id, ¬O­Ó¾ã¼Æ­È), -¦Ó¤£¬O½s½Xªº¦WºÙ¦r¦ê (¦p "EUC_JP"), ¦pªG§A­n¥Ñ½s½X¥N¸¹±oª¾½s½X¦WºÙ, -¥²¶·©I¥s: - -char *pg_encoding_to_char(int encoding_id) - -o ¨Ï¥Î PGCLIENTENCODING ³o­ÓÀô¹ÒÅÜ¼Æ - -¦pªG«eºÝ©³³]©w¤F PGCLIENTENCODING ³o¤@­ÓÀô¹ÒÅܼÆ, ¨º»ò«áºÝ·|°µ½s½X¦Û°ÊÂà´«. - -[µù] PostgreSQL 7.0.0 ~ 7.0.3 ¦³­Ó bug -- ¤£»{³o­ÓÀô¹ÒÅÜ¼Æ - -o ¨Ï¥Î SET CLIENT_ENCODING TO ³o­Ó SQL ªº©R¥O - -­n³]©w«eºÝªº½s½X¥i¥H¥Î¥H¤U³o­Ó SQL ©R¥O: - - SET CLIENT_ENCODING TO 'encoding'; - -§A¤]¥i¥H¨Ï¥Î SQL92 ªº»yªk "SET NAMES" ¹F¨ì¦P¼Ëªº¥Øªº: - - SET NAMES 'encoding'; - -¬d¸ß¥Ø«eªº«eºÝ½s½X¥i¥H¥Î¥H¤U³o­Ó SQL ©R¥O: - - SHOW CLIENT_ENCODING; - -¤Á´«¬°­ì¨Ó¹w³]ªº½s½X, ¥Î¥H¤U³o­Ó SQL ©R¥O: - - RESET CLIENT_ENCODING; - -[µù] ¨Ï¥Î psql ©R¥O¸ÑĶ¾¹®É, «Øij¤£­n¥Î³o­Ó¤èªk, ½Ð¥Î \encoding - -4. Ãö©ó Unicode (²Î¤@½X) - -²Î¤@½X©M¨ä¥L½s½X¶¡ªºÂà´«¥i¯à­n¦b 7.1 ª©«á¤~·|¹ê²{. - -5. ¦pªGµLªkÂà´«·|µo¥Í¤°»ò¨Æ? - -°²³]§A¦b«áºÝ¿ï¾Ü¤F EUC_JP ³o­Ó½s½X, «eºÝ¨Ï¥Î LATIN1, (¬Y¨Ç¤é¤å¦r¤¸µLªkÂà´«¦¨ -LATIN1) ¦b³o­Óª¬ªp¤U, ¬Y­Ó¦r¤¸­Y¤£¯àÂন LATIN1 ¦r¤¸¶°, ´N·|³QÂন¥H¤Uªº«¬¦¡: - - (¤Q¤»¶i¦ì­È) - -6. °Ñ¦Ò¸ê®Æ - -These are good sources to start learning various kind of encoding -systems. - -ftp://ftp.ora.com/pub/examples/nutshell/ujip/doc/cjk.inf - Detailed explanations of EUC_JP, EUC_CN, EUC_KR, EUC_TW - appear in section 3.2. - -Unicode: http://www.unicode.org/ - The homepage of UNICODE. - - RFC 3629 - UTF-8 is defined here. - -5. History - -May 20, 2000 - * SJIS UDC (NEC selection IBM kanji) support contributed - by Eiji Tokuya - * Changes above will appear in 7.0.1 - -Mar 22, 2000 - * Add new libpq functions PQsetClientEncoding, PQclientEncoding - * ./configure --with-mb=EUC_JP - now deprecated. use - ./configure --enable-multibyte=EUC_JP - instead - * Add SQL_ASCII regression test case - * Add SJIS User Defined Character (UDC) support - * All of above will appear in 7.0 - -July 11, 1999 - * Add support for WIN1250 (Windows Czech) as a client encoding - (contributed by Pavel Behal) - * fix some compiler warnings (contributed by Tomoaki Nishiyama) - -Mar 23, 1999 - * Add support for KOI8(KOI8-R), WIN(CP1251), ALT(CP866) - (thanks Oleg Broytmann for testing) - * Fix problem with MB and locale - -Jan 26, 1999 - * Add support for Big5 for fronend encoding - (you need to create a database with EUC_TW to use Big5) - * Add regression test case for EUC_TW - (contributed by Jonah Kuo ) - -Dec 15, 1998 - * Bugs related to SQL_ASCII support fixed - -Nov 5, 1998 - * 6.4 release. In this version, pg_database has "encoding" - column that represents the database encoding - -Jul 22, 1998 - * determine encoding at initdb/createdb rather than compile time - * support for PGCLIENTENCODING when issuing COPY command - * support for SQL92 syntax "SET NAMES" - * support for LATIN2-5 - * add UNICODE regression test case - * new test suite for MB - * clean up source files - -Jun 5, 1998 - * add support for the encoding translation between the backend - and the frontend - * new command SET CLIENT_ENCODING etc. added - * add support for LATIN1 character set - * enhance 8 bit cleaness - -April 21, 1998 some enhancements/fixes - * character_length(), position(), substring() are now aware of - multi-byte characters - * add octet_length() - * add --with-mb option to configure - * new regression tests for EUC_KR - (contributed by "Soonmyung. Hong" ) - * add some test cases to the EUC_JP regression test - * fix problem in regress/regress.sh in case of System V - * fix toupper(), tolower() to handle 8bit chars - -Mar 25, 1998 MB PL2 is incorporated into PostgreSQL 6.3.1 - -Mar 10, 1998 PL2 released - * add regression test for EUC_JP, EUC_CN and MULE_INTERNAL - * add an English document (this file) - * fix problems concerning 8-bit single byte characters - -Mar 1, 1998 PL1 released - -Appendix: - -[Here is a good documentation explaining how to use WIN1250 on -Windows/ODBC from Pavel Behal. Please note that Installation step 1) -is not necceary in 6.5.1 -- Tatsuo] - -Version: 0.91 for PgSQL 6.5 -Author: Pavel Behal -Revised by: Tatsuo Ishii -Email: behal@opf.slu.cz -Licence: The Same as PostgreSQL - -Sorry for my Eglish and C code, I'm not native :-) - -!!!!!!!!!!!!!!!!!!!!!!!!! NO WARRANTY !!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Instalation: ------------- -1) Change three affected files in source directories - (I don't have time to create proper patch diffs, I don't know how) -2) Compile with enabled locale and multibyte set to LATIN2 -3) Setup properly your instalation, do not forget to create locale - variables in your profile (environment). Ex. (may not be exactly true): - LC_ALL=cs_CZ.ISO8859-2 - LC_COLLATE=cs_CZ.ISO8859-2 - LC_CTYPE=cs_CZ.ISO8859-2 - LC_MONETARY=cs_CZ.ISO8859-2 - LC_NUMERIC=cs_CZ.ISO8859-2 - LC_TIME=cs_CZ.ISO8859-2 -4) You have to start the postmaster with locales set! -5) Try it with Czech language, it have to sort -5) Install ODBC driver for PgSQL into your M$ Windows -6) Setup properly your data source. Include this line in your ODBC - configuration dialog in field "Connect Settings:" : - SET CLIENT_ENCODING = 'WIN1250'; -7) Now try it again, but in Windows with ODBC. - -Description: ------------- -- Depends on proper system locales, tested with RH6.0 and Slackware 3.6, - with cs_CZ.iso8859-2 loacle -- Never try to set-up server multibyte database encoding to WIN1250, - always use LATIN2 instead. There is not WIN1250 locale in Unix -- WIN1250 encoding is useable only for M$W ODBC clients. The characters are - on thy fly re-coded, to be displayed and stored back properly - -Important: ----------- -- it reorders your sort order depending on your LC_... setting, so don't be - confused with regression tests, they don't use locale -- "ch" is corectly sorted only in some newer locales (Ex. RH6.0) -- you have to insert money as '162,50' (with comma in aphostrophes!) -- not tested properly diff --git a/doc-xc/README.mb.jp b/doc-xc/README.mb.jp deleted file mode 100644 index 7cafb2426e..0000000000 --- a/doc-xc/README.mb.jp +++ /dev/null @@ -1,814 +0,0 @@ -PostgreSQL 7.3 multi-byte (MB) support README 2002/10/21 $B:n@.(B - - $B@P0fC#IW(B - ishii@postgresql.org - -$B"#$O$8$a$K(B - - PostgreSQL $B$K$*$1$k%^%k%A%P%$%H%5%]!<%H$O0J2<$N$h$&$JFCD'$r;}$C$F$$$^$9!%(B - - 1. $B%^%k%A%P%$%HJ8;z$H$7$F!$F|K\8l!$Cf9q8l$J$I$N3F9q$N(B EUC$B!$(BUnicode$B!$(B - mule internal code, ISO-8859-* $B$,%G!<%?%Y!<%9:n@.;~$KA*Br2DG=!%(B - $B%G!<%?%Y!<%9$K$O$3$N%(%s%3!<%G%#%s%0$N$^$^3JG<$5$l$^$9!%(B - 2. $B%F!<%V%kL>$K%^%k%A%P%$%HJ8;z$,;HMQ2DG=(B - 3. $B%+%i%`L>$K%^%k%A%P%$%HJ8;z$,;HMQ2DG=(B - 4. $B%G!<%?$=$N$b$N$K$b%^%k%A%P%$%HJ8;z$,;HMQ2DG=(B - 5. $B%^%k%A%P%$%HJ8;z$N@55,I=8=8!:w$,;HMQ2DG=(B - 6. $B%^%k%A%P%$%HJ8;z$N(B LIKE $B8!:w$,;HMQ2DG=(B - 7. character_length(), position(), substring() $B$J$I$NJ8;zNs4X?t$G(B - $B$N%^%k%A%P%$%H%5%]!<%H(B - 8. $B%U%m%s%H%(%s%IB&$N%(%s%3!<%G%#%s%0$,%P%C%/%(%s%IB&$H0[$k>l9g$K!$(B - $B<+F0E*$K%(%s%3!<%G%#%s%0JQ49$r9T$J$$$^$9!%(B - 9. $B%f!<%6Dj5A$N%(%s%3!<%G%#%s%0JQ49$r:n@.2DG=!%(B - - $B%^%k%A%P%$%H%5%]!<%H$,07$&$3$H$N$G$-$k%(%s%3!<%G%#%s%0$O0J2<$K$J$j$^(B - $B$9!%(B - - SQL_ASCII ASCII - EUC_JP $BF|K\8l(B EUC - EUC_CN GB $B$r%Y!<%9$K$7$?CfJ8(BEUC$B!%(Bcode set 2 $B$O(B - SS2+2$B%P%$%H%3!<%I(B = 3$B%P%$%HI=8=$G$9!%(B - EUC_KR $B4Z9q8l(B EUC$B!%(B - JOHAB $B%O%s%0%k%Y!<%9$N4Z9q8l(BEUC. - EUC_TW $BBfOQ$N(B EUC$B!%(Bcode set 2 $B$O(B - SS2+$BLLHV9f(B+2$B%P%$%H%3!<%I(B = 4$B%P%$%HI=8=$G$9!%(B - UNICODE UTF-8$B!%$?$@$7%5%]!<%H$9$k$N$O(B UCS-2 $B$NHO0O!$(B - $B$9$J$o$A(B 0xffff $B$^$G$G$9!%(B - MULE_INTERNAL mule $B$NFbIt%3!<%I!%$?$@$7!$(BType N $B$NITDjD9J8;z$O(B - $B%5%]!<%H$7$F$$$^$;$s!%(B - LATIN1 $B$+$i(B LATIN10$B$^$G(B - ISO_8859_1 $B$+$i(B 16$B$^$G(B - $B%-%j%kJ8;z(B KOI8(KOI8-R), WIN(CP1251), ALT(CP866)$B$r%5%]!<%H(B - $B$7$F$$$^$9!%$b$A$m$s(B ISO 8859-5 $B$b;HMQ2DG=$G$9!%(B - $B$3$N>l9g!$(B"LATIN5" $B$H$7$F;XDj$7$F2<$5$$!%(B - WIN1256 $B%"%i%V=t9q8l(BWindows$BMQ%(%s%3!<%G%#%s%0(B. - TCVN $B%Y%H%J%`8l(B."ABC"$B$d(B"VSCII"$B$b;HMQ2DG=(B. - WIN874 $B%?%$8l(B. - - $B%U%m%s%H%(%s%IB&$G$O$5$i$K0J2<$N%(%s%3!<%G%#%s%0$,;HMQ$G$-$^$9!%(B - - SJIS $B%7%U%H(BJIS(MS932$B$H$[$\8_49(B) - BIG5 $BBfOQ$d9a9A$G;HMQ$5$l$F$$$kCf9q8l!%(BEUC_TW$B$H8_49(B - $B@-$,$"$j$^$9!%(B - GBK Windows-936 - UHC Windows-949 - WIN1250 Windows-1250 - GB18030 GB18030 - -$B"#F|K\8l$r;HMQ$9$k$3$H$N$G$-$k%(%s%3!<%G%#%s%0(B - - $BA*Br$NL\0B$H$7$F$O!$1Q8l$HF|K\8l$7$+;H$o$J$$>l9g$O(B EUC_JP($BF1MM$K!$Cf(B - $B9q8l$7$+;H$o$J$$>l9g$O(B EUC_CN... $B$J$I$H$J$j$^$9(B)$B!$$=$NB>$N8@8l$b;H$$$?(B - $B$$>l9g$O(B UNICODE $B$b$7$/$O(B MULE_INTERNAL $B$H$J$k$G$7$g$&!%(B - - $BCm0U!'(BMULE_INTERNAL $B$rA*$V$H!$$?$/$5$s$NJ8;z=89g$KBP1~$G$-$FJXMx$G$9(B - $B$,!$@55,I=8=$GJ#?t$NJ8;z=89g$K$^$?$,$k$h$&$JHO0O;XDj(B($B$?$H$($P!$(B[a-$BHO(B] - $B$H$+!$(B[abc$BHO0O(B]$B$N$h$&$J(B)$B$O;H$($^$;$s!%J#?t$NHO0O;XDj$G0[$J$kJ8;z=89g(B - $B$r;H$&$N$O9=$$$^$;$s(B($B$?$H$($P(B [abc][$BHO(B-$B0O(B])$B!%$^$?!$(B[^a] $B$N$h$&$JI=8=(B - $B$O!$(B"a" $B$NB0$9$kJ8;z=89g(B($B$3$N>l9g!$(BUS-ASCII)$B$K$*$$$F(B "a" $B0J30$G$"$k(B - $B$3$H$rI=$7$^$9!%7h$7$F4A;z$dJ?2>L>$J$I(B "a" $B0J30$r$9$Y$FI=$9$o$1$G$O(B - $B$J$$$3$H$KCm0U$7$F2<$5$$!%(B - -$B"#%$%s%9%H!<%k(B - - PostgreSQL 7.3$B$+$i$O(Bconfigure$B$N%*%W%7%g%s;XDj$NM-L5$K4X$o$i$:!$%^%k(B - $B%A%P%$%H%5%]!<%H$,M-8z$K$J$C$F$$$^$9$N$G!$FC$K(Bconifgure$B;~$K%^%k%A%P(B - $B%$%HMQ$NFCJL$J%*%W%7%g%s$r;XDj$9$kI,MW$O$"$j$^$;$s!%(B - -$B"#(Binitdb/createdb/create database $B$K$*$1$k%(%s%3!<%G%#%s%0$N;XDj$K$D$$$F(B - - initdb $B$G$O0J2<$N%*%W%7%g%s$G%(%s%3!<%G%#%s%0$,;XDj$G$-$^$9!%(B - - -E $B%(%s%3!<%G%#%s%0(B - --encoding=$B%(%s%3!<%G%#%s%0(B - - $B$3$3$G;XDj$7$?%(%s%3!<%G%#%s%0$O!$0J8e(B createdb/create database $B$G%((B - $B%s%3!<%G%#%s%0$r>JN,$7$?>l9g$K@_Dj$5$l$k%(%s%3!<%G%#%s%0$K$J$j$^$9!%(B - -E $B$^$?$O(B --encoding $B%*%W%7%g%s$r>JN,$7$?>l9g$O!$%(%s%3!<%G%#%s%0$H(B - $B$7$F(BSQL_ASCII$B$,:NMQ$5$l$F$7$^$&$N$G!$F|K\8l$r%G%U%)%k%H$G;HMQ$9$k>l(B - $B9g$O!$(B - - -E EUC_JP - - $B$"$k$$$O(B - - --encoding=EUC_JP - - $B$H$7$FI,$:L@<(E*$K%(%s%3!<%G%#%s%0$r;XDj$7$F$/$@$5$$!%(B - - $B$J$*!$(BPostgreSQL 7.3$B0J9_%m%1!<%k%5%]!<%H$,I,$:M-8z$K$J$C$F$$$^$9$,!$(B - $B$3$l$OF|K\8l$J$I$r;HMQ$9$k:]$K$O2?$N%a%C%j%H$b$J$$$P$+$j$G$J$/!$>c32(B - $B$N860x$K$J$C$?$j!$(BLIKE$B8!:w$d@55,I=8=8!:w$G%$%s%G%C%/%9$,M-8z$K$J$i$J(B - $B$$$J$I$NLdBj$r0z$-5/$3$9$N$G!$L58z$K$7$F$*$/$3$H$r$*$9$9$a$7$^$9!%%m(B - $B%1!<%k%5%]!<%H$rL58z$K$9$k$?$a$K$O!$(B - - --no-locale - - $B%*%W%7%g%s$r;XDj$7$^$9!%(B - - createdb $B$G$O0J2<$N%*%W%7%g%s$G%(%s%3!<%G%#%s%0$,;XDj$G$-$^$9!%(B - - -E $B%(%s%3!<%G%#%s%0(B - --encoding=$B%(%s%3!<%G%#%s%0(B - - create database $B$G$O0J2<$N%*%W%7%g%s$G%(%s%3!<%G%#%s%0$,;XDj$G$-$^$9!%(B - - CREATE DATABASE dbanme WITH ENCODING = '$B%(%s%3!<%G%#%s%0(B'; - - LOCATION $B$rF1;~$K;XDj$9$k>l9g$O0J2<$N$h$&$K$J$j$^$9!%(B - - CREATE DATABASE dbanme WITH LOCATION = 'path' ENCODING = '$B%(%s%3!<%G%#%s%0(B'; - - createdb/create database $B$G$O!$%(%s%3!<%G%#%s%0;XDj$r>JN,$7$?>l9g$O!$(Binitdb - $B$G;XDj$7$?%(%s%3!<%G%#%s%0$,:NMQ$5$l$^$9!%$3$l$O!$(Binitdb $B$,:n@.$9$k(B - $B%F%s%W%l!<%H%G!<%?%Y!<%9(B(template1)$B$N(B encoding $B%"%H%j%S%e!<%H$r7Q>5(B - $B$9$k$+$i$G$9!%(B - - $B%G!<%?%Y!<%9$N%(%s%3!<%G%#%s%0$O!$(Bpsql -l$B!$(Bpsql $B$N(B \l $B$G;2>H$G$-$^$9!%(B - -$ psql -l - List of databases - Database | Owner | Encoding ----------------+---------+--------------- - euc_cn | t-ishii | EUC_CN - euc_jp | t-ishii | EUC_JP - euc_kr | t-ishii | EUC_KR - euc_tw | t-ishii | EUC_TW - mule_internal | t-ishii | MULE_INTERNAL - regression | t-ishii | SQL_ASCII - template1 | t-ishii | EUC_JP - test | t-ishii | EUC_JP - unicode | t-ishii | UNICODE -(9 rows) - -$B"#J8;z7?$N%G!<%?7?$K$D$$$F(B - - 7.2$B$G$O!$(BCHAR(n)$B$H(BVARCHAR(n)$B$N(B n $B$OJ8;z?t$r0UL#$7$^$9!%(Bn $B$,%P%$%H?t$r(B - $B0UL#$9$k(B 7.1 $B0JA0$H$O0[$J$j$^$9$N$G$4Cm0U2<$5$$!%(B - - $BNc$r<($7$^$9!%(B - - 7.2$B$G$O!$(BCHAR(1)$B$K(B"$B$"(B"$B$r3JG<$G$-$^$9$,!$(B7.1$B0JA0$G$O3JG<$G$-$^$;$s$3(B - $B$l$O!$(B"$B$"(B"$B$r3JG<$9$k$?$a$K>/$J$/$H$b(B2$B%P%$%H0J>e$rMW$9$k$+$i$G$9!%(B - $B5U$K!$(B"a" $B$O(B1$B%P%$%H$7$+>CHq$7$J$$$?$a!$(B7.1$B$G$b(B CHAR(1) $B$K3JG<$G$-$^(B - $B$9!%(B - - $B$J$*!$(B7.2$B$G$O!$(B7.1$B$^$G$H0[$J$j!$(BCHAR(n)$B$K3JG<$G$-$J$$(B n $BJ8;z$h$jBg$-(B - $B$$J8;zNs$O(B n $BJ8;z$G@Z$jl9g!$<+F0E*$K%P%C%/%(%s%I$G%(%s%3!<%G%#%s%0JQ49$,9T$o$l$^$9!%(B - - $B%P%C%/%(%s%I$N%(%s%3!<%G%#%s%0(B $B5vMF$5$l$k%U%m%s%H%(%s%I$N(B - $B%(%s%3!<%G%#%s%0(B - ---------------------------------------------------------------- - EUC_JP EUC_JP, SJIS, UNICODE - - EUC_TW EUC_TW, BIG5, UNICODE - - EUC_CN EUC_CN, UNICODE - - EUC_KR EUC_KR, UNICODE - - JOHAB JOHAB, UNICODE - - LATIN1,3,4 LATIN1,3,4, UNICODE - - LATIN2 LATIN2, WIN1250, UNICODE - - LATIN5 LATIN5, WIN, ALT, UNICODE - - LATIN6,7,8,9,10 LATIN6,7,8,9,10, UNICODE - - ISO_8859_5,6,7,8 ISO_8859_5,6,7,8, UNICODE - - WIN1256 WIN1256, UNICODE - - TCVN TCVN, UNICODE - - WIN874 WIN874, UNICODE - - MULE_INTERNAL EUC_JP, SJIS, EUC_KR, EUC_CN, - EUC_TW, BIG5, LATIN1$B$+$i(B5, - WIN, ALT, WIN1250 - - UNICODE EUC_JP, SJIS, EUC_KR, UHC, - EUC_CN, GBK, EUC_TW, BIG5, - LATIN1$B$+$i(B10, ISO_8859_5$B$+$i(B8, - WIN, ALT, WIN1250, WIN1256, - TCVN, WIN874, JOHAB - ---------------------------------------------------------------- - - $B%P%C%/%(%s%I$H%U%m%s%H%(%s%I$N%(%s%3!<%G%#%s%0$,0[$J$k>l9g!$$=$N$3$H(B - $B$r%P%C%/%(%s%I$KEA$($kI,MW$,$"$j$^$9!%$=$N$?$a$NJ}K!$,$$$/$D$+$"$j$^(B - $B$9!%(B - -o psql $B$N(B \encoding $B%3%^%s%I$r;H$&J}K!(B - - psql$B$G$O!$(B\encoding$B%3%^%s%I$r;H$C$FF0E*$K%U%m%s%H%(%s%IB&$NJ8;z%3!<(B - $B%I$r@ZBX$($k$3$H$,$G$-$^$9!%Nc(B: - - \encoding SJIS - -o libpq $B$N4X?t(B PQsetClientEncoding $B$r;H$&J}K!(B - - 7.0 $B$+$i?7$7$$(B libpq $B4X?t(B PQsetClientEncoding $B$,DI2C$5$l$F$$$^$9!%(B - - PQsetClientEncoding(PGconn *conn, const char *encoding) - - $B$3$N4X?t$r;H$($P!$%3%M%/%7%g%sKh$K%(%s%3!<%G%#%s%0$r@ZBX$($k$3$H$,$G(B - $B$-$^$9!%8=:_$N%(%s%3!<%G%#%s%0$NLd$$9g$o$;$O(B - - int PQclientEncoding(const PGconn *conn) - - $B$G$9!%(B - -o postgresql.conf $B$G@_Dj$9$kJ}K!(B - - $B%U%m%s%H%(%s%I$N%G%U%)%k%H%(%s%3!<%G%#%s%0$r;XDj$9$k$K$O!$(B - postgresql.conf $B$N(B client_encoding $B$r;XDj$7$^$9!%;XDjNc(B: - - client_encoding = SJIS - -o $B4D6-JQ?t(B PGCLIENTENCODING $B$r;H$&J}K!(B - - (1) postmaster $B5/F0;~$K4D6-JQ?t$r@_Dj$9$kJ}K!(B - - $B4D6-JQ?t(B PGCLIENTENCODING $B$r@_Dj$9$k$3$H$K$h$j!$(B postgresql.conf $B$G(B - $B%(%s%3!<%G%#%s%0$r;XDj$9$k$N$HF1$88z2L$,F@$i$l$^$9!%$?$@$7!$$3$l$ONr(B - $B;KE*7P0^$+$i;D$5$l$F$$$k5!G=$G!$:#8e$O$3$N5!G=$rMxMQ$7$J$$$3$H$r$*$9(B - $B$9$a$7$^$9!%@_DjNc(B: - - export PGCLIENTENCODING=SJIS postmaster -S - - (2) $B%/%i%$%"%s%H!$%U%m%s%H%(%s%IKh$K%(%s%3!<%G%#%s%0$r@_Dj$7$?$$>l9g(B - - $B$=$N%U%m%s%H%(%s%I(B($B$?$H$($P(B psql)$B$r5/F0$9$kA0$K4D6-JQ?t(B - PGCLIENTENCODING $B$r@_Dj$7$^$9!%(B - -o set client_encoding $B%3%^%s%I$r;H$&J}K!(B - - SET CLIENT_ENCODING SQL$B%3%^%s%I$r;H$C$FF0E*$K%U%m%s%H%(%s%I$N%(%s%3!<(B - $B%G%#%s%0$rJQ99$G$-$^$9!%Nc(B: - - SET CLIENT_ENCODING TO SJIS; - -$B"#8=:_@_Dj$5$l$F$$$k%U%m%s%H%(%s%IB&$N%(%s%3!<%G%#%s%0$rD4$Y$k(B - - $B8=:_@_Dj$5$l$F$$$k%U%m%s%H%(%s%IB&$N%(%s%3!<%G%#%s%0$O(B - - show client_encoding; - - $B$G;2>H$G$-$^$9(B($B>.J8;z$GI=<($5$l$^$9(B)$B!%(B - -$B"#%G%U%)%k%H$N%(%s%3!<%G%#%s%0$X$NI|5"(B - - SQL$B%3%^%s%I(B: - - RESET CLIENT_ENCODING; - - $B$O!$%G%U%)%k%H$N%U%m%s%H%(%s%I%(%s%3!<%G%#%s%0@_Dj$KI|5"$5$;$^$9!%(B - postmaster$B$rN)$A>e$2$k$H$-$K(B postgresql.conf $B$N(B client_encoding $B$d4D(B - $B6-JQ?t(B PGCLIENTENCODING $B$,@_Dj$5$l$F$$$k$H$=$N%(%s%3!<%G%#%s%0$K!$$=(B - $B$&$G$J$1$l$P%G!<%?%Y!<%9$N%(%s%3!<%G%#%s%0$HF1$8$K$J$j$^$9!%(B - -$B"#L@<(E*$J%(%s%3!<%G%#%s%0JQ49(B - - 7.2$B$G$O!$(Bconvert$B$H$$$&4X?t$r;H$$!$L@<(E*$J%(%s%3!<%G%#%s%0JQ49$,$G$-(B - $B$^$9!%(B - - convert(string text, [src_encoding name,] dest_encoding name) - - $B$3$3$G(Bsrc_encoding$B$O(Btext$B$N%(%s%3!<%G%#%s%0L>$G$9!%>JN,$9$k$H!$%G!<%?(B - $B%Y!<%9%(%s%3!<%G%#%s%0L>$HF1$8$G$"$k$H8+$J$5$l$^$9!%(Bdest_encoding$B$O!$(B - $BJQ498e$N%(%s%3!<%G%#%s%0L>$G$9!%(B - - $BNc$r<($7$^$9!%(B - - SELECT convert(text, EUC_JP) FROM unicode_tbl; - - $B$O!$(BUnicode$B$N%F!<%V%k(Bunicode_tbl$B$N(Btext$BNs$r(BEUC_JP$B$KJQ49$7$FJV$7$^$9!%(B - - 7.3$B$G$O$5$i$K(BSQL$BI8=`$N(BCONVERT$B4X?t$,;H$($^$9!%(BSQL$BI8=`$N(BCONVERT$B$O(B - PostgreSQL$B$N(BCONVERT$B$H5!G=$O$[$H$s$IF1$8$G$9$,!$8F$S=P$77A<0$,0[$j$^(B - $B$9!%(B - - SELECT convert(text using euc_jp_to_utf8) FROM unicode_tbl; - - "using" $B$N8e$N0z?t$O!V%3%s%P!<%8%g%sL>!W$G$9!%$3$NNc$G$O!$(BEUC_JP $B$+(B - $B$i(B UTF-8 $B$KJQ49$9$k%3%s%P!<%8%g%s$r;XDj$7$F$$$^$9!%Dj5A:Q$N%3%s%P!<(B - $B%8%g%s$K$D$$$F$O!$%f!<%6!<%:%,%$%I$N(B "String Functions and - Operators" $B$NI=(B"Built-in Conversions" $B$r8+$F$/$@$5$$!%(B - -$B"#%(%s%3!<%G%#%s%0JQ49ITG=$N>l9g$N=hM}(B - - $B%P%C%/%(%s%IB&$N%(%s%3!<%G%#%s%0$H%U%m%s%H%(%s%IB&$N%(%s%3!<%G%#%s%0(B - $B$,$$$D$bAj8_JQ49$G$-$k$H$O8B$j$^$;$s!%6KC<$JOC!$%P%C%/%(%s%IB&$,(B - EUC_JP $B$J$N$K!$%U%m%s%H%(%s%IB&$,(B EUC_KR $B$@$C$?$i$I$&$J$k$G$7$g$&!%(B - $B$3$N>l9g(B PostgreSQL $B$OJQ49$G$-$J$$%3!<%I$r(B 16$B?JI=8=$KJQ49$7$^$9!%(B - $B$?$H$($P!$(B"(bdae)" $B$N$h$&$K!%$J$*!$$3$N(B 16$B?JI=8=$O(B mule - internal code $B$N%3!<%I$G$"$k$3$H$KCm0U$7$F2<$5$$!%$3$l$O!$D>@\%U%m%s(B - $B%H%(%s%I(B <--> $B%P%C%/%(%s%I$N%(%s%3!<%G%#%s%0$rJQ49$9$k$N$G$O$J$/!$0l(B - $BEYFbItI=8=$G$"$k(B mule internal code $B$r7PM3$7$F$$$k$?$a$G$9!%(B - - $B$J$*!$(BUnicode$B$H$=$l0J30$N%(%s%3!<%G%#%s%0$NJQ49$@$1$ONc30$G!$(BNOTICE - $B%a%C%;!<%8$,I=<($5$l!$JQ49ITG=$NJ8;z$OL5;k$5$l$^$9!%(B - -$B"#%G%U%)%k%H%3%s%P!<%8%g%s(B - - $B%G%U%)%k%H%3%s%P!<%8%g%s$O!$%P%C%/%(%s%I$H%U%m%s%H%(%s%I$H$N4V$N%(%s(B - $B%3!<%G%#%s%0$N<+F0JQ49$K;H$o$l$kFCJL$J%3%s%P!<%8%g%s$G$9!%%G%U%)%k%H(B - $B%3%s%P!<%8%g%s$O3F!9$N(B{$B%9%-!<%^!$%=!<%9%(%s%3!<%G%#%s%0!$%G%9%F%#%M!<(B - $B%7%g%s%(%s%3!<%G%#%s%0(B}$B$NAH$_9g$o$;$K$*$$$F!$$?$@0l8D$@$1B8:_$7$^$9!%(B - $B>e5-$G@bL@$7$?AH$_9~$_:Q$N%3%s%P!<%8%g%s$O!$(Bpg_catalog$B%9%-!<%^$K$*$$(B - $B$FDj5A$5$l$F$*$j!$%9%-!<%^%5!<%A%Q%9$N@_Dj$K4X$o$i$:I,$:MxMQ$G$-$k%3(B - $B%s%P!<%8%g%s$K$J$C$F$$$^$9!%(B - - $B5U$K8@$&$H!$(B pg_catalog $B0J30$N%9%-!<%^$K%G%U%)%k%H%3%s%P!<%8%g%s$r:n(B - $B@.$9$k$3$H$K$h$j!$%G%U%)%k%H%3%s%P!<%8%g%s$r<+M3$KA*Br$9$k$3$H$b$G$-(B - $B$k$o$1$G$9!%$?$H$($P(B SJIS $B$H$NJQ49$K$*$$$F!$(BPostgreSQL $B$,MQ0U$7$F$$(B - $B$k(B MS932$B8_49(B $B$NJQ49$G$O$J$/!$(BJIS $B5,3J$N%7%U%H%8%9$KAjEv$9$kJQ49$r9T(B - $B$&$h$&$J%3%s%P!<%8%g%s$r:n@.$9$k$3$H$b2DG=$G$9!%(B - -$B"#%f!<%6Dj5A%3%s%P!<%8%g%s$N:n@.(B - - PostgreSQL 7.3$B0J9_!$%f!<%6Dj5A$N%3%s%P!<%8%g%s$r:n@.$G$-$k$h$&$K$J$C(B - $B$F$$$^$9!%%3%s%P!<%8%g%s$NDj5A$O(B CREATE CONVERSION $B$H$$$&(B SQL $B%3%^%s(B - $B%I$r;H$C$F9T$$$^$9!%(B - - CREATE [DEFAULT] CONVERSION conversion_name - FOR source_encoding - TO dest_encoding FROM funcname - - $B>\:Y$O%j%U%!%l%s%9%^%K%e%"%k$r$4Mw2<$5$$!%(B - -$B"#(BSJIS$B%f!<%6Dj5AJ8;z$X$NBP1~(B - - 7.0 $B$+$i(B SJIS$B%f!<%6Dj5AJ8;z(B (UDC) $B$KBP1~$7$F$$$^$9!%(BUDC $B$r$I$&07$&$+(B - $B$H8@$&$3$H$K$D$$$FCf>r$5$s(B(nak@email.com)$B$+$iLdBjDs5/$H>\:Y$J2r@b$r(B - $BD:$-$^$7$?$N$G!$;29M$N$?$a$K$3$N%I%-%e%a%s%H$N:G8e$KIU$1$F$*$-$^$9!%(B - $B$^$?!$$3$NLdBj$K$D$$$F$O!$(BPostgreSQL$BF|K\8l%a!<%j%s%0%j%9%H$N(B - [pgsql-jp 12288] (1999/12/17$BIU(B)$B$H(B [pgsql-jp 12486] (2000/1/5$BIU(B) $B$+$i(B - $B;O$^$k%9%l%C%I$G5DO@$r8+$k$3$H$,$G$-$^$9(B($B%a!<%k$N%"!<%+%$%V$O(B - http://www.sra.co.jp/people/t-ishii/PostgreSQL/ $B$G;2>H$G$-$^$9(B)$B!%(B - - $B$3$3$G$O!$$=$l$i$N5DO@$r$U$^$(!$4JC1$K2r@b$7$^$9!%(B - - PostgreSQL$B$G$O!$F|K\8l$r;HMQ$9$k:]$K%P%C%/%(%s%IB&$N%(%s%3!<%G%#%s%0(B - $B$r(B EUC_JP $B$^$?$O(B MULE_INTERNAL or Unicode $B$K$9$kI,MW$,$"$j$^$9!%(B - MULE_INTERNAL $B$O(B EUC_JP $B$KJ8;z=89g$rI=$9%3!<%I$rIU$1$?$b$N$J$N$G!$K\(B - $B SJIS $BJQ49$O8=:_$N$H$3$m%5%]!<%H(B - $B$5$l$F$$$^$;$s$N$GL5;k$7$^$9!%$7$?$,$C$F!$$3$3$G$O(B EUC_JP $B$H(B SJIS $B$N(B - $BAj8_JQ49$N$_$r9M$($^$9!%(B - - $BM=HwCN<1(B - - $B0l8}$K(B EUC_JP $B$H$$$C$F$b!$e5-(B JIS $B5,3J$GDj5A$5$l$F$$(B - $B$J$$J8;z%3!<%I$,0lItMxMQ$5$l$F$*$j!$$3$NItJ,(B (UDC) $B$O=>Mh(B PostgreSQL - $B$G$OA4$/9MN8$5$l$F$$$^$;$s$G$7$?!%>N(B) - 95$B!A(B104 $B6h(B $B"+"*(B $BF|K\8l(B EUC / G1 (JIS X 0208) 85$B!A(B95 $B6h(B - - - SJIS $B%f!<%6Dj5AJ8;zNN0h(B B ($B2>>N(B) - 105$B!A(B114 $B6h(B $B"+"*(B $BF|K\8l(B EUC / G3 (JIS X 0212) 85$B!A(B95 $B6h(B - - (2) IBM $B3HD%J8;zNN0h(B (SJIS 115$B!A(B120 $B6h(B) - - $BJQ49%F!<%V%k$K$h$C$F(B G1 (JIS X 0208)$B$H!$(BG3 (JIS X 0212)$B$KJQ49$5$l$^(B - $B$9!%$J$*!$$3$NJQ49$K$*$$$F$O!$(BSJIS --> EUC_JP $B$GJQ49$7!$:F$S(B EUC_JP -- - > SJIS $B$KJQ49$9$k$H85$N(B SJIS $B$KLa$i$J$$$3$H$,$"$j$^$9!%$^$?!$(BEUC_JP -- - > SJIS $B$NJQ49$G$O!$$9$Y$F$NJ8;z$rJQ49$G$-$k$o$1$G$O$J$$$N$G!$$=$N>l(B - $B9g$OJQ49ITG=J8;z$H$7$F!V".!W$KCV$-49$($^$9!%(B - - *$B6H3&CDBN$Nr$5$s(B - (nak@email.com)$B$+$iLdBjDs5/$H>\:Y$J2r@b$rD:$-$^$7$?!%(B - -$B"#(BUnicode$B$H$=$l0J30$N%(%s%3!<%G%#%s%0$H$NAj8_JQ49$K$D$$$F(B - - PostgreSQL 7.1$B$+$i(BUnicode$B$H$=$l0J30$N%(%s%3!<%G%#%s%0$H$NAj8_JQ49$,(B - $B2DG=$K$J$j$^$7$?!%$3$NJQ49$O$4$/0lIt$NJ8;z%3!<%I(B(ISO 8859-1)$B$r$N$>$-!$(B - $B%m%8%C%/$K$h$kJQ49$,$G$-$J$$$?$a!$JQ49$N:]$K$O%F!<%V%k$,I,MW$K$J$j$^(B - $B$9!%(BPostgreSQL$B$Ne!$MxMQ$7$F$$$^$9(B)$B!%(BUnicode - organization$B$NDs6!$9$kJQ49%F!<%V%k$O:FG[I[$,5v2D$5$l$F$$$J$$$?$a!$(B - PostgreSQL$B$N%=!<%9%3!<%I$K$O4^$^$l$F$$$^$;$s!%0J2r$5$s(B - (nak@email.com)$B$+$i$$$?$@$$$?LdBjDs5/$H2r@b$G$9!%(B - --------------------------- $B0zMQ3+;O(B ---------------------------------- ---- -1. SJIS $B%3!<%I$NHO0O(B - - 1 $B%P%$%HL\(B 0x81 - 0x9F$B!$(B0xE0 - 0xFC - 2 $B%P%$%HL\(B 0x40 - 0x7E$B!$(B0x80 - 0xFC - - $B$$$o$f$k!V30;zNN0h!W$NHO0O(B: - - - X0208 $B6&DL<+M3NN0h(B - - |-------------------- - | 85 $B6h(B 0xEB40 $B!A(B - |... - |-------------------- - | 89 $B6h(B 0xED40 $B!A(B ; 89$B!A(B92 $B6h$O(B - |... ; $B!V(BNEC $BA*Dj(B IBM $B3HD%J8;zNN0h!W(B - |-------------------- ; $B$H8F$P$l$k(B - | 93 $B6h(B 0xEF40 $B!A(B - | 94 $B6h(B 0xEF9F $B!A(B 0xEFFC - - - $B%f!<%6Dj5AJ8;zNN0h(B - - |-------------------- - | 95 $B6h(B 0xF040 $B!A(B ; 95$B!A(B104 $B6h(B - |... ; $B!V%f!<%6Dj5AJ8;zNN0h(B A$B!W(B($B2>>N(B) - |-------------------- - |105 $B6h(B 0xF540 $B!A(B ; 105$B!A(B114 $B6h(B - |... ; $B!V%f!<%6Dj5AJ8;zNN0h(B B$B!W(B($B2>>N(B) - |-------------------- - |115 $B6h(B 0xFA40 $B!A(B ; 115$B!A(B120 $B6h$O0lHL$K(B - |... ; $B!V(BIBM $B3HD%J8;zNN0h!W(B - |120 $B6h(B ... ; $B$H8F$P$l$k(B - |-------------------- - ---- -2. i-mode $BC\:Y$O(B -$B8e=R$N;29M;qNA$r$4Mw$$$?$@$/$H$7$F!$$3$3$G$O$=$N%k!<%k$r(B -$B4JC1$K$4@bL@$$$?$7$^$9!%(B - - - SJIS $B%f!<%6Dj5AJ8;zNN0h(B A ($B2>>N(B) - 95$B!A(B104 $B6h(B $B"+"*(B $BF|K\8l(B EUC / G1 85$B!A(B95 $B6h(B - - $B$?$H$($P(B SJIS $B$N(B (95, 1) = 0xF040 $B$O(B - EUC $B$N(B 0xF5A1 $B$K$J$j$^$9!%(B - - - SJIS $B%f!<%6Dj5AJ8;zNN0h(B B ($B2>>N(B) - 105$B!A(B114 $B6h(B $B"+"*(B $BF|K\8l(B EUC / G3 85$B!A(B95 $B6h(B - - $B$?$H$($P(B SJIS $B$N(B (105, 1) = 0xF540 $B$O(B - EUC $B$N(B 0x8FF5A1 $B$K$J$j$^$9!%(B - - - IBM $B3HD%J8;zNN0h(B - 115$B!A(B120 $B6h(B - - JIS X 0208 ($BF|K\8l(B EUC / G1)$B!$(BJIS X 0212 - ($BF|K\8l(B EUC / G3) $B$K3:Ev$9$kJ8;z$,$"$k>l9g(B - $B$O$=$NJ8;z$K%^%C%T%s%0!%$=$&$G$J$$>l9g$O(B - $BF|K\8l(B EUC / G3 83$B!A(B84 $B6h$r!$6hE@%3!<%I$N>e0L(B - $B$+$i=g$K3d$jEv$F$F$$$/(B ($BJQ49%F!<%V%kJ}<0(B) - -$B$3$N;EMM$O!$9-$/;H$o$l$F$$$k(B SJIS $B$H(B EUC $B$N%^%C%T%s%0$,%Y%s%@$K(B -$B$h$C$F0[$J$k$?$a!$Aj8_1?MQ$N:]$KLdBj$K$J$C$F$$$k$3$H$+$i!$(B1996 -$BG/$K(B OSF $BF|K\%Y%s%@6(5D2q$,8!F$:n@.$7$?Js9p=q$,%Y!<%9$K$J$C$F$$(B -$B$k$h$&$G$9!%(B - -Solaris $B$N%I%-%e%a%s%H$K$O!V(BTOG $BF|K\%Y%s%@6(5D2q?d>)(B EUC$B!&%7%U%H(B -JIS $B%3!<%IJQ49;EMM!W$K$b$H$E$/$H=q$$$F$"$j!$(BSolaris 2.6 $B$+$iF3F~(B -$B$7$F$$$k$N$@$=$&$G!$;d$+$i8+$l$P;ve$NI8=`$H9M$($F$bIT<+A3$G$O(B -$B$J$$$H46$8$^$9!%(B - -$B$J$*!$>/$J$/$H$b(B 1996 $BG/Ev;~$K$*$$$F$O!$(BOracle $B$d(B Sybase $B$O(B -SJIS $B$N%f!<%6Dj5A(B/$B%Y%s%@Dj5AJ8;zNN0h$r(B EUC $B$KJQ49$9$k:]!$H=JLIT(B -$B2DG=J8;z$H$7$F07$C$F$$$k$i$7$$$H$$$&$3$H$bJdB-$7$F$*$-$^$9!%(B - ---- -[$B;29M;qNA(B] - -// URL $B$,D9$$$N$G!$ESCf$G@Z$l$J$$$H$$$$$N$G$9$,(B... - --$B!VF|K\8l(B EUC$B!&%7%U%H(B JIS $B%3!<%IJQ49;EMM$H%3!<%I7O.$5$/$J$C$F$$$^$9!%$^$?!$(B - SQL$BI8=`$N(BCONVERT$B4X?t$rDI2C$7$^$7$?!%(B - * $B$$$/$D$+%(%s%3!<%G%#%s%0$,DI2C$5$l$F$$$^$9!%(B - * $B0J>e!$(B7.3$B$KH?1G$5$l$^$9!%(B - - 2001/10/01 - * CONVERT$B$NDI2C!%(Blpad/rpad/trim/btrim/ltrim/rtrim/translate$B$N(B - $B%^%k%A%P%$%HBP1~DI2C!%(Bchar/varchar$B$G%P%$%H?t$G$O$J$/!$J8;z?t(B - $B$G%5%$%:$rDj5A$9$k$h$&$KJQ99!%0J>e!$(B7.2$B$KH?1G$5$l$^$9!%(B - - 2001/2/15 - * $BFA2H(B@$B;06(1?M"%5!<%S%9$5$s$+$i!$(BCP932.TXT$B$h$j@8@.$7$?(BSJIS$BMQ$N(B - $BJQ49%F!<%V%k$rDs6!$7$F$$$?$@$-$^$7$?!%(B7.1$B$KH?1G$5$l$^$9!%(B - - 2001/1/6 - * UNICODE$B$HB>$N%(%s%3!<%G%#%s%0$H$NAj8_JQ495!G=$rDI2C!%(B - * 7.1$B$KH?1G$5$l$^$9!%(B - - 2000/5/20 - * NEC $BA*Dj(B IBM $B4A;zBP1~$rDI2C$7$^$7$?!%$3$l$O(B $BFA2H(B@$B;06(1?M"%5!<%S%9(B - $B$5$s$+$i$N(B contribute $B$G$9!%(B - * $B$3$l$i$O!$(B7.0.1 $B$KH?1G$5$l$^$9!%(B - - 2000/3/22 - * PQsetClientEncoding, PQclientEncoding $B$r(Blibpq $B4X?t$KDI2C!$(B - $B%3%M%/%7%g%sKh$K%(%s%3!<%G%#%s%0$rJQ992DG=$K!%(B - * SJIS $B%f!<%6Dj5AJ8;z(B (UDC) $B$X$NBP1~(B - * ./configure --with-mb=EUC_JP $B$+$i(B - ./configure --enable-multibyte=EUC_JP $B$KJQ99(B - * SQL_ASCII $B$N(B regression test $BDI2C(B - * $B$3$l$i$O(B 7.0 $B$KH?1G$5$l$^$9!%(B - - 1999/7/11 WIN1250(Windows$BMQ$N%A%'%38l(B)$B%5%]!<%H$rDI2C$7$^$7$?!%(B - * WIN1250 $B$,%U%m%s%H%(%s%IB&$N%(%s%3!<%G%#%s%0$H$7$FMxMQ$G$-$k$h(B - $B$&$K$J$j$^$7$?!%$3$N>l9g!$%P%C%/%(%s%IB&$N%(%s%3!<%G%#%s%0$O(B - LATIN2 $B$^$?$O(B MULE_INTERNAL $B$H$7$^$9!%(B - (contributed by Pavel Behal) - * backend/utils/mb/conv.c$B$K$*$1$k7?$NIT@09g$r=$@5$7$^$7$?!%(B - (contributed by Tomoaki Nishiyama) - * $B$3$l$i$O(B6.5.1$B$KH?1G$5$l$^$9!%(B - - 1999/3/23 $B%-%j%kJ8;z%5%]!<%HDI2CB>(B(6.5 $B$KH?1G:Q(B) - * $B%(%s%3!<%G%#%s%0$H$7$F(B KOI8(KOI8-R), WIN(CP1251), ALT(CP866) $B$r(B - $B%5%]!<%H$7$F$$$^$9!%$3$l$i$O!$%U%m%s%H%(%s%I!$%P%C%/%(%s%I!$(B - $B$I$A$i$N%(%s%3!<%G%#%s%0$H$7$F$b;HMQ2DG=$G$"$j!$%(%s%3!<%G%#%s%0$N(B - $BAj8_JQ49$,2DG=$G$9!%$^$?!$=>Mh$+$i%5%]!<%H$7$F$$$k(B ISO 8859-5 $B$b(B - $BF1MM$K;HMQ2DG=$G$9!%(B - $B%-%j%kJ8;z%5%]!<%H$O!$(BOleg Broytmann $B;a$N(B - $B%j%/%(%9%H5Z$S6(NO$K$h$jMh$+$i$"$k(B - RCODE $B%5%]!<%H$N5!G=$rl9g$KBgJ8;z!?>.J8;z$rL5;k$7$?(B - $B@55,I=8=8!:w$,@5>o$KF0:n$7$J$$%P%0$r=$@5(B - - 1999/1/26 Big5 $B%5%]!<%HDI2C(B(6.4.2-patched/6.5 $B$KH?1G:Q(B) - * Big5 $B$,%U%m%s%H%(%s%IB&$N%(%s%3!<%G%#%s%0$H$7$FMxMQ$G$-$k$h(B - $B$&$K$J$j$^$7$?!%$3$N>l9g!$%P%C%/%(%s%IB&$N%(%s%3!<%G%#%s%0$O(B - EUC_TW $B$^$?$O(B MULE_INTERNAL $B$H$7$^$9!%(B - * EUC_TW $B$N(B regression test $B%1!<%9$rDI2C(B - (contributed by Jonah Kuo ) - - 1998/12/16 $BK\%I%-%e%a%s%H=$@5(B(6.4.2 $B$KH?1G:Q(B)$B!%(B - * Makefile.custom $B$G(B MB=EUC_JP $B$J$I$H@_Dj$9$kJ}K!$O(B 6.4 $B0J9_(B - $B%5%]!<%H$5$l$F$$$J$$$N$G:o=|$7$?!%(B - * $BJ8;z%3!<%I(B $B"*(B $B%(%s%3!<%G%#%s%0!$%/%i%$%"%s%H"*%U%m%s%H%(%s%I(B - $B%5!<%P"*%P%C%/%(%s%I(B $B$K$=$l$>$l8l6g$r=$@5!%(B - - 1998/12/15 6.4 $B8~$1%P%0=$@5%Q%C%A%j%j!<%9(B(6.4.2 $B$KH?1G:Q(B)$B!%(B - * SQL_ASCII $B%5%]!<%H$N%P%0=$@5(B - - 1998/11/21 6.4 $B8~$1%P%0=$@5%Q%C%A%j%j!<%9(B(6.4.2 $B$KH?1G:Q(B)$B!%(B - * BINARY CURSOR $B$NLdBj$r=$@5(B - * pg_dumpall $B$N%P%0=$@5(B - - 1998/11/5 6.4 $B%j%j!<%9!%(B - * pg_database $B$N(B encoding $B%+%i%`$,(B MB $B$,M-8z$G$J$$$H$-$K$b(B - $BDI2C$5$l$k$h$&$K$J$C$?!%$=$N$?$a!$(BMB $B$,M-8z$G$J$$$H$-$K$O!$(B - ASCII $B$N%(%s%3!<%G%#%s%0$rI=$9(B SQL_ASCII $B$r?7$7$$%(%s%3!<%G%#%s%0(B - $B$H$7$FDI2C$7$?!%$3$l$K$H$b$J$$!$%(%s%3!<%G%#%s%0L>$KBP1~$9$k(B - $B%(%s%3!<%G%#%s%0(BID$B$,(B SQL_ASCII $B$r(B 0 $B$H$9$kHV9f$KJQ99$K$J$C$?!%(B - - 1998/7/22 6.4 $B&A8~$1$K%Q%C%A$r%j%j!<%9!%(B - * initdb/createdb/create database $B$G%P%C%/%(%s%IB&$N(B - $B%(%s%3!<%G%#%s%0$r@_Dj$-$k5!G=l=j$rBgI}8+D>$7!%(BMB $B4X78$O(B - include/mb, backend/utils/mb $B$KCV$/$h$&$K$7$?(B - - 1998/5/25 $B%P%0=$@5(B(mb_b3.patch $B$H$7$F(B pgsql-jp ML $B$K%j%j!<%9!$(B - $BK\2H$G$O(B 6.4 snapshot $B$K$7I,MW(B - * configure $B$N%*%W%7%g%s$K(B MB $B%5%]!<%HDI2C(B - (ex. configure --with-mb=EUC_JP) - * EUC_KR $B$N(B regression test $BDI2C(B - ("Soonmyung. Hong" $B$5$sDs6!(B) - * EUC_JP $B$N(B regression test $B$K(B character_length(), position(), - substring(), octet_length() $BDI2C(B - * regress.sh $B$N(B SystemV $B$K$*$1$kHs8_49@-=$@5(B - * toupper(), tolower() $B$K(B 8bit $BJ8;z$,EO$k$HMn$A$k$3$H$,(B - $B$"$k$N$r=$@5(B - - 1998/3/25 PostgreSQL 6.3.1 $B%j%j!<%9!$(BMB PL2 $B$,l9g$KH/@8$9$k%P%0$r=$@5(B - - 1998/3/1 PL1 $B$r%j%j!<%9(B - -$B0J>e!%(B diff --git a/doc-xc/TODO b/doc-xc/TODO deleted file mode 100644 index 4b7b3da476..0000000000 --- a/doc-xc/TODO +++ /dev/null @@ -1,3 +0,0 @@ -The TODO list is now maintained at: - - http://wiki.postgresql.org/wiki/Todo diff --git a/doc-xc/bug.template b/doc-xc/bug.template deleted file mode 100644 index 392394fed8..0000000000 --- a/doc-xc/bug.template +++ /dev/null @@ -1,53 +0,0 @@ -If PostgreSQL failed to compile on your computer or you found a bug, -please fill out this form and e-mail it to postgres-xl-bugs@lists.sourceforge.net. - -If your bug report has security implications and you'd prefer that it not -become immediately visible in public archives, don't send it to postgres-xl-bugs. -Security issues can be reported privately to security@postgresql.org. - -If you not only found the problem but solved it and generated a patch -then e-mail it to postgres-xl-bugs@lists.sourceforge.net instead. Please use the -command "diff -c" to generate the patch. - -You may also enter a bug report at http://sourceforge.net/projects/postgres-xl/ -instead of e-mailing this form. - -============================================================================ - POSTGRES-XL BUG REPORT TEMPLATE -============================================================================ - - -Your name : -Your email address : - - -System Configuration: ---------------------- - Architecture (example: Intel Pentium) : - - Operating System (example: Linux 2.4.18) : - - Postgres-XL version (example: Postgres-XL 9.2): Postgres-XL 9.2 - - Compiler used (example: gcc 3.3.5) : - - -Please enter a FULL description of your problem: ------------------------------------------------- - - - - - -Please describe a way to repeat the problem. Please try to provide a -concise reproducible example, if at all possible: ----------------------------------------------------------------------- - - - - - -If you know how this problem might be fixed, list the solution below: ---------------------------------------------------------------------- - - diff --git a/doc-xc/src/Makefile b/doc-xc/src/Makefile deleted file mode 100644 index b0d4f1f506..0000000000 --- a/doc-xc/src/Makefile +++ /dev/null @@ -1,8 +0,0 @@ -# doc/src/Makefile - -subdir = doc/src -top_builddir = ../.. -include $(top_builddir)/src/Makefile.global - -all distprep html man install installdirs uninstall clean distclean maintainer-clean maintainer-check: - $(MAKE) -C sgml $@ diff --git a/doc-xc/src/sgml/.gitignore b/doc-xc/src/sgml/.gitignore deleted file mode 100644 index e1b84b490f..0000000000 --- a/doc-xc/src/sgml/.gitignore +++ /dev/null @@ -1,33 +0,0 @@ -# Stuff shipped in tarballs -/html/ -/html-stamp -/man1/ -/man3/ -/man7/ -/man-stamp -# Other popular build targets -/HISTORY -/INSTALL -/regress_README -/postgres-US.pdf -/postgres-A4.pdf -/postgres.html -/postgres.txt -# GENERATED_SGML -/features-supported.sgml -/features-unsupported.sgml -/errcodes-table.sgml -/version.sgml -/bookindex.sgml -/HTML.index -# Assorted byproducts from building the above -/postgres.xml -/HISTORY.html -/INSTALL.html -/regress_README.html -/postgres-US.aux -/postgres-US.log -/postgres-US.out -/postgres-A4.aux -/postgres-A4.log -/postgres-A4.out diff --git a/doc-xc/src/sgml/Makefile b/doc-xc/src/sgml/Makefile deleted file mode 100644 index 9c69b15f21..0000000000 --- a/doc-xc/src/sgml/Makefile +++ /dev/null @@ -1,421 +0,0 @@ -#---------------------------------------------------------------------------- -# -# PostgreSQL documentation makefile -# -# doc/src/sgml/Makefile -# -#---------------------------------------------------------------------------- - -# This makefile is for building and installing the documentation. -# When a release tarball is created, the documentation files are -# prepared using the distprep target. In Git-based trees these files -# don't exist, unless explicitly built, so we skip the installation in -# that case. - - -# Make "html" the default target, since that is what most people tend -# to want to use. -html: - -subdir = doc-xc/src/sgml -top_builddir = ../../.. -include $(top_builddir)/src/Makefile.global - -MAKESGMLDIR = $(top_builddir)/src/pgxc/tools/makesgml -MAKESGML = $(MAKESGMLDIR)/makesgml - - -all: html man - -distprep: html distprep-man - - -ifndef COLLATEINDEX -COLLATEINDEX = $(DOCBOOKSTYLE)/bin/collateindex.pl -endif - -ifndef JADE -JADE = jade -endif -SGMLINCLUDE = -D . -D $(srcdir) - -ifndef NSGMLS -NSGMLS = nsgmls -endif - -ifndef OSX -OSX = osx -endif - -ifndef XSLTPROC -XSLTPROC = xsltproc -endif - -VERSION = 9.2 - -override XSLTPROCFLAGS += --stringparam pg.version '$(VERSION)' - - -GENERATED_SGML = bookindex.sgml version.sgml \ - features-supported.sgml features-unsupported.sgml errcodes-table.sgml - -ALLSGMLIN := $(wildcard $(srcdir)/*.sgmlin $(srcdir)/ref/*.sgmlin) - -#ALLSGML := $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml) $(GENERATED_SGML) -ALLSGML := $(ALLSGMLIN:%sgmlin=%sgml) $(GENERATED_SGML) - -ALLSGMLTOREMOVE := $(ALLSGMLIN:%sgmlin=%sgml) - - -# Sometimes we don't want this one. -ALMOSTALLSGML := $(filter-out %bookindex.sgml,$(ALLSGML)) - -ifdef DOCBOOKSTYLE -CATALOG = -c $(DOCBOOKSTYLE)/catalog -endif - -# Enable some extra warnings -# -wfully-tagged needed to throw a warning on missing tags -# for older tool chains, 2007-08-31 -# Note: try "make SPFLAGS=-wxml" to catch a lot of other dubious constructs, -# in particular < and & that haven't been made into entities. It's far too -# noisy to turn on by default, unfortunately. -override SPFLAGS += -wall -wno-unused-param -wno-empty -wfully-tagged - -## -## SGML files -## - -sgml-files: $(ALLSGMLIN:%sgmlin=%sgml) - -## -## Man pages -## - -man distprep-man: man-stamp - -man-stamp: stylesheet-man.xsl postgres.xml - $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_MAN_FLAGS) $^ - touch $@ - - -## -## HTML -## - -.PHONY: draft - -JADE.html.call = $(JADE) $(JADEFLAGS) $(SPFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t sgml -i output-html - -# The draft target creates HTML output in draft mode, without index (for faster build). -draft: postgres.sgml $(ALMOSTALLSGML) stylesheet.dsl - $(MKDIR_P) html - $(JADE.html.call) -V draft-mode $< - cp $(srcdir)/stylesheet.css html/ - -html: html-stamp - -html-stamp: postgres.sgml $(ALLSGML) stylesheet.dsl - $(MKDIR_P) html - $(JADE.html.call) -i include-index $< - cp $(srcdir)/stylesheet.css html/ - touch $@ - -# single-page HTML -postgres.html: postgres.sgml $(ALLSGML) stylesheet.dsl - $(JADE.html.call) -V nochunks -V rootchunk -V '(define %root-filename% #f)' -V '(define use-output-dir #f)' -i include-index $< - -# single-page text -postgres.txt: postgres.html - $(LYNX) -force_html -dump -nolist $< > $@ - -HTML.index: postgres.sgml $(ALMOSTALLSGML) stylesheet.dsl - @$(MKDIR_P) html - $(JADE.html.call) -V html-index $< - -bookindex.sgml: HTML.index - LC_ALL=C $(PERL) $(COLLATEINDEX) -f -g -i 'bookindex' -o $@ $< - -# Technically, this should depend on Makefile.global, but then -# version.sgml would need to be rebuilt after every configure run, -# even in distribution tarballs. So this is cheating a bit, but it -# will achieve the goal of updating the version number when it -# changes. -version.sgml: $(top_srcdir)/configure - { \ - echo ""; \ - echo ""; \ - } > $@ - -features-supported.sgml: $(top_srcdir)/src/backend/catalog/sql_feature_packages.txt $(top_srcdir)/src/backend/catalog/sql_features.txt - $(PERL) $(srcdir)/mk_feature_tables.pl YES $^ > $@ - -features-unsupported.sgml: $(top_srcdir)/src/backend/catalog/sql_feature_packages.txt $(top_srcdir)/src/backend/catalog/sql_features.txt - $(PERL) $(srcdir)/mk_feature_tables.pl NO $^ > $@ - -errcodes-table.sgml: $(top_srcdir)/src/backend/utils/errcodes.txt generate-errcodes-table.pl - $(PERL) $(srcdir)/generate-errcodes-table.pl $< > $@ - -## -## Print -## - - -# RTF to allow minor editing for hardcopy -%.rtf: %.sgml $(ALLSGML) - $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t rtf -V rtf-backend -i output-print -i include-index postgres.sgml - -# TeX -# Regular TeX and pdfTeX have slightly differing requirements, so we -# need to distinguish the path we're taking. - -JADE.tex.call = $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d $(srcdir)/stylesheet.dsl -t tex -V tex-backend -i output-print -i include-index - -%-A4.tex-ps: %.sgml $(ALLSGML) - $(JADE.tex.call) -V texdvi-output -V '%paper-type%'=A4 -o $@ $< - -%-US.tex-ps: %.sgml $(ALLSGML) - $(JADE.tex.call) -V texdvi-output -V '%paper-type%'=USletter -o $@ $< - -%-A4.tex-pdf: %.sgml $(ALLSGML) - $(JADE.tex.call) -V texpdf-output -V '%paper-type%'=A4 -o $@ $< - -%-US.tex-pdf: %.sgml $(ALLSGML) - $(JADE.tex.call) -V texpdf-output -V '%paper-type%'=USletter -o $@ $< - -%.dvi: %.tex-ps - @rm -f $*.aux $*.log -# multiple runs are necessary to create proper intra-document links - jadetex $< - jadetex $< - jadetex $< - -# PostScript from TeX -postgres.ps: - $(error Invalid target; use postgres-A4.ps or postgres-US.ps as targets) - -%.ps: %.dvi - dvips -o $@ $< - -postgres.pdf: - $(error Invalid target; use postgres-A4.pdf or postgres-US.pdf as targets) - -%.pdf: %.tex-pdf - @rm -f $*.aux $*.log $*.out -# multiple runs are necessary to create proper intra-document links - pdfjadetex $< - pdfjadetex $< - pdfjadetex $< - -# Cancel built-in suffix rules, interfering with PS building -.SUFFIXES: -.SUFFIXES: .sgml .sgmlin - -INC_LIST = -I PG -I EN -#INC_LIST = -I PGXC -I EN - -.sgmlin.sgml: - $(MAKE) -C $(MAKESGMLDIR) - $(MAKESGML) -i $< -o $@ $(INC_LIST) $(EXC_LIST) - - -# This generates an XML version of the flow-object tree. It's useful -# for debugging DSSSL code, and possibly to interface to some other -# tools that can make use of this. -%.fot: %.sgml $(ALLSGML) - $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t fot -i output-print -i include-index -o $@ $< - - -## -## Semi-automatic generation of some text files. -## - -JADE.text = $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -i output-text -t sgml -LYNX = lynx - -INSTALL HISTORY regress_README: % : %.html - $(PERL) -p -e 's/ $@ - -INSTALL.html: standalone-install.sgml installation.sgml version.sgml - $(JADE.text) -V nochunks standalone-install.sgml installation.sgml > $@ - -HISTORY.html: generate_history.pl $(wildcard $(srcdir)/release*.sgml) - $(PERL) $< "$(srcdir)" release.sgml >tempfile_HISTORY.sgml - $(JADE.text) -V nochunks tempfile_HISTORY.sgml > $@ - rm tempfile_HISTORY.sgml - -regress_README.html: regress.sgml - ( echo ''; \ - echo ' ]>'; \ - cat $< ) >tempfile_regress_README.sgml - $(JADE.text) -V nochunks tempfile_regress_README.sgml > $@ - rm tempfile_regress_README.sgml - - -## -## XSLT processing -## - -# For obscure reasons, gmake 3.81 complains about circular dependencies -# if we try to do "make all" in a VPATH build without the explicit -# $(srcdir) on the postgres.sgml dependency in this rule. gmake bug? -postgres.xml: $(srcdir)/postgres.sgml $(ALMOSTALLSGML) - $(OSX) -D. -x lower $< >postgres.xmltmp - $(PERL) -p -e 's/\[(amp|copy|egrave|gt|lt|mdash|nbsp|ouml|pi|quot|uuml) *\]/\&\1;/g;' \ - -e '$$_ .= qq{\n} if $$. == 1;' \ - $@ - rm postgres.xmltmp -# ' hello Emacs - -xslthtml: stylesheet.xsl postgres.xml - $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $^ - -htmlhelp: stylesheet-hh.xsl postgres.xml - $(XSLTPROC) $(XSLTPROCFLAGS) $^ - -%-A4.fo: stylesheet-fo.xsl %.xml - $(XSLTPROC) $(XSLTPROCFLAGS) --stringparam paper.type A4 -o $@ $^ - -%-US.fo: stylesheet-fo.xsl %.xml - $(XSLTPROC) $(XSLTPROCFLAGS) --stringparam paper.type USletter -o $@ $^ - - -## -## Experimental Texinfo targets -## - -DB2X_TEXIXML = db2x_texixml -DB2X_XSLTPROC = db2x_xsltproc -MAKEINFO = makeinfo - -%.texixml: %.xml - $(DB2X_XSLTPROC) -s texi -g output-file=$(basename $@) $< -o $@ - -%.texi: %.texixml - $(DB2X_TEXIXML) --encoding=iso-8859-1//TRANSLIT $< --to-stdout > $@ - -%.info: %.texi - $(MAKEINFO) --enable-encoding --no-split --no-validate $< -o $@ - - -## -## Check -## - -# Quick syntax check without style processing -check maintainer-check: postgres.sgml $(ALMOSTALLSGML) check-tabs - $(NSGMLS) $(SPFLAGS) $(SGMLINCLUDE) -s $< - - -## -## Install -## - -install: install-html - -ifneq ($(PORTNAME), sco) -install: install-man -endif - -installdirs: - $(MKDIR_P) '$(DESTDIR)$(htmldir)'/html $(addprefix '$(DESTDIR)$(mandir)'/man, 1 3 $(sqlmansectnum)) - -uninstall: - rm -f '$(DESTDIR)$(htmldir)/html/'* $(addprefix '$(DESTDIR)$(mandir)'/man, 1/* 3/* $(sqlmansectnum)/*) - - -## Install html - -install-html: html installdirs - cp -R $(call vpathsearch,html) '$(DESTDIR)$(htmldir)' - - -## Install man - -install-man: man installdirs - -sqlmansect ?= 7 -sqlmansectnum = $(shell expr X'$(sqlmansect)' : X'\([0-9]\)') - -# Before we install the man pages, we massage the section numbers to -# follow the local conventions. -# -ifeq ($(sqlmansectnum),7) -install-man: - cp -R $(foreach dir,man1 man3 man7,$(call vpathsearch,$(dir))) '$(DESTDIR)$(mandir)' - -else # sqlmansectnum != 7 -fix_sqlmansectnum = sed -e '/^\.TH/s/"7"/"$(sqlmansect)"/' \ - -e 's/\\fR(7)/\\fR($(sqlmansectnum))/g' \ - -e '1s/^\.so man7/.so man$(sqlmansectnum)/g;1s/^\(\.so.*\)\.7$$/\1.$(sqlmansect)/g' - -man: fixed-man-stamp - -fixed-man-stamp: man-stamp - @$(MKDIR_P) $(addprefix fixedman/,man1 man3 man$(sqlmansectnum)) - for file in $(call vpathsearch,man1)/*.1; do $(fix_sqlmansectnum) $$file >fixedman/man1/`basename $$file` || exit; done - for file in $(call vpathsearch,man3)/*.3; do $(fix_sqlmansectnum) $$file >fixedman/man3/`basename $$file` || exit; done - for file in $(call vpathsearch,man7)/*.7; do $(fix_sqlmansectnum) $$file >fixedman/man$(sqlmansectnum)/`basename $$file | sed s/\.7$$/.$(sqlmansect)/` || exit; done - -install-man: - cp -R $(foreach dir,man1 man3 man$(sqlmansectnum),fixedman/$(dir)) '$(DESTDIR)$(mandir)' - -clean: clean-man clean-sgml - -.PHONY: clean-man -clean-man: - rm -rf fixedman/ fixed-man-stamp - -.PHONY: clean-sgml: -clean-sgml: - rm -rf $(ALLSGML) - -endif # sqlmansectnum != 7 - -# tabs are harmless, but it is best to avoid them in SGML files -check-tabs: - @( ! grep ' ' $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml) ) || (echo "Tabs appear in SGML files"; exit 1) - -## -## Clean -## - -# This allows removing some files from the distribution tarballs while -# keeping the dependencies satisfied. -.SECONDARY: postgres.xml $(GENERATED_SGML) HTML.index -.SECONDARY: INSTALL.html HISTORY.html regress_README.html -.SECONDARY: %-A4.tex-ps %-US.tex-ps %-A4.tex-pdf %-US.tex-pdf - -clean: -# text --- these are shipped, but not in this directory - rm -f INSTALL HISTORY regress_README - rm -f INSTALL.html HISTORY.html regress_README.html -# single-page output - rm -f postgres.html postgres.txt -# print - rm -f *.rtf *.tex-ps *.tex-pdf *.dvi *.aux *.log *.ps *.pdf *.out *.fot -# index - rm -f HTML.index $(GENERATED_SGML) -# XSLT - rm -f postgres.xml postgres.xmltmp htmlhelp.hhp toc.hhc index.hhk *.fo -# Texinfo - rm -f *.texixml *.texi *.info db2texi.refs -# sgml - rm -f $(ALLSGMLTOREMOVE) - -distclean: clean - -maintainer-clean: distclean -# HTML - rm -fr html/ html-stamp -# man - rm -rf man1/ man3/ man7/ man-stamp - -.PHONY: sgmlfiles - -INC_LIST = -I XL -I EN -EXC_LIST = -E PG -E JP - -sgmlfiles: - ./makesgmlfiles $(INC_LIST) $(EXC_LIST) diff --git a/doc-xc/src/sgml/Makefile.xc.wk b/doc-xc/src/sgml/Makefile.xc.wk deleted file mode 100644 index 5bf5fce8b9..0000000000 --- a/doc-xc/src/sgml/Makefile.xc.wk +++ /dev/null @@ -1,407 +0,0 @@ -#---------------------------------------------------------------------------- -# -# PostgreSQL documentation makefile -# -# $PostgreSQL: pgsql/doc/src/sgml/Makefile,v 1.148 2010/06/12 21:40:31 tgl Exp $ -# -#---------------------------------------------------------------------------- - -# This makefile is for building and installing the documentation. -# When a release tarball is created, the documentation files are -# prepared using the distprep target. In Git-based trees these files -# don't exist, unless explicitly built, so we skip the installation in -# that case. - - -# Make "html" the default target, since that is what most people tend -# to want to use. -html: - -subdir = doc/src/sgml -top_builddir = ../../.. -include $(top_builddir)/src/Makefile.global - - -all: html man - -distprep: html distprep-man - - -ifndef COLLATEINDEX -COLLATEINDEX = $(DOCBOOKSTYLE)/bin/collateindex.pl -endif - -ifndef JADE -JADE = jade -endif -SGMLINCLUDE = -D . -D $(srcdir) - -ifndef NSGMLS -NSGMLS = nsgmls -endif - -ifndef OSX -OSX = osx -endif - -ifndef XSLTPROC -XSLTPROC = xsltproc -endif - -override XSLTPROCFLAGS += --stringparam pg.version '$(VERSION)' - - -GENERATED_SGML = bookindex.sgml version.sgml \ - features-supported.sgml features-unsupported.sgml - -ALLSGMLIN := $(wildcard $(srcdir)/*.sgmlin $(srcdir)/ref/*.sgmlin) - -#ALLSGML := $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml) $(GENERATED_SGML) -ALLSGML := $(ALLSGMLIN:%sgmlin=%sgml) $(GENERATED_SGML) - -ALLSGMLTOREMOVE := $(ALLSGMLIN:%sgmlin=%sgml) - - -# Sometimes we don't want this one. -ALMOSTALLSGML := $(filter-out %bookindex.sgml,$(ALLSGML)) - -ifdef DOCBOOKSTYLE -CATALOG = -c $(DOCBOOKSTYLE)/catalog -endif - -# Enable some extra warnings -# -wfully-tagged needed to throw a warning on missing tags -# for older tool chains, 2007-08-31 -# Note: try "make SPFLAGS=-wxml" to catch a lot of other dubious constructs, -# in particular < and & that haven't been made into entities. It's far too -# noisy to turn on by default, unfortunately. -override SPFLAGS += -wall -wno-unused-param -wno-empty -wfully-tagged - -## -## Man pages -## - -man distprep-man: man-stamp - -man-stamp: stylesheet-man.xsl postgres.xml - $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_MAN_FLAGS) $^ - touch $@ - - -## -## HTML -## - -.PHONY: draft - -JADE.html.call = $(JADE) $(JADEFLAGS) $(SPFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t sgml -i output-html - -# The draft target creates HTML output in draft mode, without index (for faster build). -draft: postgres.sgml $(ALMOSTALLSGML) stylesheet.dsl - $(MKDIR_P) html - $(JADE.html.call) -V draft-mode $< - cp $(srcdir)/stylesheet.css html/ - -html: html-stamp - -html-stamp: postgres.sgml $(ALLSGML) stylesheet.dsl - $(MKDIR_P) html - $(JADE.html.call) -i include-index $< - cp $(srcdir)/stylesheet.css html/ - touch $@ - -# single-page HTML -postgres.html: postgres.sgml $(ALLSGML) stylesheet.dsl - $(JADE.html.call) -V nochunks -V rootchunk -V '(define %root-filename% #f)' -V '(define use-output-dir #f)' -i include-index $< - -# single-page text -postgres.txt: postgres.html - $(LYNX) -force_html -dump -nolist $< > $@ - -HTML.index: postgres.sgml $(ALMOSTALLSGML) stylesheet.dsl - @$(MKDIR_P) html - $(JADE.html.call) -V html-index $< - -bookindex.sgml: HTML.index - LC_ALL=C $(PERL) $(COLLATEINDEX) -f -g -i 'bookindex' -o $@ $< - -# Technically, this should depend on Makefile.global, but then -# version.sgml would need to be rebuilt after every configure run, -# even in distribution tarballs. So this is cheating a bit, but it -# will achieve the goal of updating the version number when it -# changes. -version.sgml: $(top_srcdir)/configure - { \ - echo ""; \ - echo ""; \ - } > $@ - -features-supported.sgml: $(top_srcdir)/src/backend/catalog/sql_feature_packages.txt $(top_srcdir)/src/backend/catalog/sql_features.txt - $(PERL) $(srcdir)/mk_feature_tables.pl YES $^ > $@ - -features-unsupported.sgml: $(top_srcdir)/src/backend/catalog/sql_feature_packages.txt $(top_srcdir)/src/backend/catalog/sql_features.txt - $(PERL) $(srcdir)/mk_feature_tables.pl NO $^ > $@ - - -## -## Print -## - - -# RTF to allow minor editing for hardcopy -%.rtf: %.sgml $(ALLSGML) - $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t rtf -V rtf-backend -i output-print -i include-index postgres.sgml - -# TeX -# Regular TeX and pdfTeX have slightly differing requirements, so we -# need to distinguish the path we're taking. - -JADE.tex.call = $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d $(srcdir)/stylesheet.dsl -t tex -V tex-backend -i output-print -i include-index - -%-A4.tex-ps: %.sgml $(ALLSGML) - $(JADE.tex.call) -V texdvi-output -V '%paper-type%'=A4 -o $@ $< - -%-US.tex-ps: %.sgml $(ALLSGML) - $(JADE.tex.call) -V texdvi-output -V '%paper-type%'=USletter -o $@ $< - -%-A4.tex-pdf: %.sgml $(ALLSGML) - $(JADE.tex.call) -V texpdf-output -V '%paper-type%'=A4 -o $@ $< - -%-US.tex-pdf: %.sgml $(ALLSGML) - $(JADE.tex.call) -V texpdf-output -V '%paper-type%'=USletter -o $@ $< - -%.dvi: %.tex-ps - @rm -f $*.aux $*.log -# multiple runs are necessary to create proper intra-document links - jadetex $< - jadetex $< - jadetex $< - -# PostScript from TeX -postgres.ps: - $(error Invalid target; use postgres-A4.ps or postgres-US.ps as targets) - -%.ps: %.dvi - dvips -o $@ $< - -postgres.pdf: - $(error Invalid target; use postgres-A4.pdf or postgres-US.pdf as targets) - -%.pdf: %.tex-pdf - @rm -f $*.aux $*.log $*.out -# multiple runs are necessary to create proper intra-document links - pdfjadetex $< - pdfjadetex $< - pdfjadetex $< - -# Cancel built-in suffix rules, interfering with PS building -.SUFFIXES: -.SUFFIXES: .sgml .sgmlin - -INC_LIST = -I PG -I EN -#INC_LIST = -I PGXC -I EN - -.sgmlin.sgml: - makesgml -i $< -o $@ $(INC_LIST) $(EXC_LIST) - - -# This generates an XML version of the flow-object tree. It's useful -# for debugging DSSSL code, and possibly to interface to some other -# tools that can make use of this. -%.fot: %.sgml $(ALLSGML) - $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -t fot -i output-print -i include-index -o $@ $< - - -## -## Semi-automatic generation of some text files. -## - -JADE.text = $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) $(CATALOG) -d stylesheet.dsl -i output-text -t sgml -LYNX = lynx - -INSTALL HISTORY regress_README: % : %.html - $(PERL) -p -e 's/ $@ - -INSTALL.html: standalone-install.sgml installation.sgml version.sgml - $(JADE.text) -V nochunks standalone-install.sgml installation.sgml > $@ - -HISTORY.html: generate_history.pl $(wildcard $(srcdir)/release*.sgml) - $(PERL) $< "$(srcdir)" release.sgml >tempfile_HISTORY.sgml - $(JADE.text) -V nochunks tempfile_HISTORY.sgml > $@ - rm tempfile_HISTORY.sgml - -regress_README.html: regress.sgml - ( echo ''; \ - echo ' ]>'; \ - cat $< ) >tempfile_regress_README.sgml - $(JADE.text) -V nochunks tempfile_regress_README.sgml > $@ - rm tempfile_regress_README.sgml - - -## -## XSLT processing -## - -# For obscure reasons, gmake 3.81 complains about circular dependencies -# if we try to do "make all" in a VPATH build without the explicit -# $(srcdir) on the postgres.sgml dependency in this rule. gmake bug? -postgres.xml: $(srcdir)/postgres.sgml $(ALMOSTALLSGML) - $(OSX) -D. -x lower $< >postgres.xmltmp - $(PERL) -p -e 's/\[(amp|copy|egrave|gt|lt|mdash|nbsp|ouml|pi|quot|uuml) *\]/\&\1;/g;' \ - -e '$$_ .= qq{\n} if $$. == 1;' \ - $@ - rm postgres.xmltmp -# ' hello Emacs - -xslthtml: stylesheet.xsl postgres.xml - $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $^ - -htmlhelp: stylesheet-hh.xsl postgres.xml - $(XSLTPROC) $(XSLTPROCFLAGS) $^ - -%-A4.fo: stylesheet-fo.xsl %.xml - $(XSLTPROC) $(XSLTPROCFLAGS) --stringparam paper.type A4 -o $@ $^ - -%-US.fo: stylesheet-fo.xsl %.xml - $(XSLTPROC) $(XSLTPROCFLAGS) --stringparam paper.type USletter -o $@ $^ - - -## -## Experimental Texinfo targets -## - -DB2X_TEXIXML = db2x_texixml -DB2X_XSLTPROC = db2x_xsltproc -MAKEINFO = makeinfo - -%.texixml: %.xml - $(DB2X_XSLTPROC) -s texi -g output-file=$(basename $@) $< -o $@ - -%.texi: %.texixml - $(DB2X_TEXIXML) --encoding=iso-8859-1//TRANSLIT $< --to-stdout > $@ - -%.info: %.texi - $(MAKEINFO) --enable-encoding --no-split --no-validate $< -o $@ - - -## -## Check -## - -# Quick syntax check without style processing -check: postgres.sgml $(ALMOSTALLSGML) check-tabs - $(NSGMLS) $(SPFLAGS) $(SGMLINCLUDE) -s $< - - -## -## Install -## - -install: install-html - -ifneq ($(PORTNAME), sco) -install: install-man -endif - -installdirs: - $(MKDIR_P) '$(DESTDIR)$(htmldir)'/html $(addprefix '$(DESTDIR)$(mandir)'/man, 1 3 $(sqlmansectnum)) - -uninstall: - rm -f '$(DESTDIR)$(htmldir)/html/'* $(addprefix '$(DESTDIR)$(mandir)'/man, 1/* 3/* $(sqlmansectnum)/*) - - -## Install html - -install-html: html installdirs - cp -R $(call vpathsearch,html) '$(DESTDIR)$(htmldir)' - - -## Install man - -install-man: man installdirs - -sqlmansect ?= 7 -sqlmansectnum = $(shell expr X'$(sqlmansect)' : X'\([0-9]\)') - -# Before we install the man pages, we massage the section numbers to -# follow the local conventions. -# -ifeq ($(sqlmansectnum),7) -install-man: - cp -R $(foreach dir,man1 man3 man7,$(call vpathsearch,$(dir))) '$(DESTDIR)$(mandir)' - -else # sqlmansectnum != 7 -fix_sqlmansectnum = sed -e '/^\.TH/s/"7"/"$(sqlmansect)"/' \ - -e 's/\\fR(7)/\\fR($(sqlmansectnum))/g' \ - -e '1s/^\.so man7/.so man$(sqlmansectnum)/g;1s/^\(\.so.*\)\.7$$/\1.$(sqlmansect)/g' - -man: fixed-man-stamp - -fixed-man-stamp: man-stamp - @$(MKDIR_P) $(addprefix fixedman/,man1 man3 man$(sqlmansectnum)) - for file in $(call vpathsearch,man1)/*.1; do $(fix_sqlmansectnum) $$file >fixedman/man1/`basename $$file` || exit; done - for file in $(call vpathsearch,man3)/*.3; do $(fix_sqlmansectnum) $$file >fixedman/man3/`basename $$file` || exit; done - for file in $(call vpathsearch,man7)/*.7; do $(fix_sqlmansectnum) $$file >fixedman/man$(sqlmansectnum)/`basename $$file | sed s/\.7$$/.$(sqlmansect)/` || exit; done - -install-man: - cp -R $(foreach dir,man1 man3 man$(sqlmansectnum),fixedman/$(dir)) '$(DESTDIR)$(mandir)' - -clean: clean-man clean-sgml - -.PHONY: clean-man -clean-man: - rm -rf fixedman/ fixed-man-stamp - -.PHONY: clean-sgml: -clean-sgml: - rm -rf $(ALLSGML) - -endif # sqlmansectnum != 7 - -# tabs are harmless, but it is best to avoid them in SGML files -check-tabs: - @( ! grep ' ' $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml) ) || (echo "Tabs appear in SGML files"; exit 1) - -## -## Clean -## - -# This allows removing some files from the distribution tarballs while -# keeping the dependencies satisfied. -.SECONDARY: postgres.xml $(GENERATED_SGML) HTML.index -.SECONDARY: INSTALL.html HISTORY.html regress_README.html -.SECONDARY: %-A4.tex-ps %-US.tex-ps %-A4.tex-pdf %-US.tex-pdf - -clean: -# text --- these are shipped, but not in this directory - rm -f INSTALL HISTORY regress_README - rm -f INSTALL.html HISTORY.html regress_README.html -# single-page output - rm -f postgres.html postgres.txt -# print - rm -f *.rtf *.tex-ps *.tex-pdf *.dvi *.aux *.log *.ps *.pdf *.out *.fot -# index - rm -f HTML.index $(GENERATED_SGML) -# XSLT - rm -f postgres.xml postgres.xmltmp htmlhelp.hhp toc.hhc index.hhk *.fo -# Texinfo - rm -f *.texixml *.texi *.info db2texi.refs -# sgml - rm -f $(ALLSGMLTOREMOVE) - -distclean: clean - -maintainer-clean: distclean -# HTML - rm -fr html/ html-stamp -# man - rm -rf man1/ man3/ man7/ man-stamp - -.PHONY: sgmlfiles - -INC_LIST = -I XC -I EN -EXC_LIST = -E PG -E JP - -sgmlfiles: - ./makesgmlfiles $(INC_LIST) $(EXC_LIST) diff --git a/doc-xc/src/sgml/README.links b/doc-xc/src/sgml/README.links deleted file mode 100644 index 2668b00d7f..0000000000 --- a/doc-xc/src/sgml/README.links +++ /dev/null @@ -1,45 +0,0 @@ - - -Linking within SGML documents can be confusing, so here is a summary: - - -Intra-document Linking ----------------------- - - - use to get chapter/section # from the title of the target - link, or xreflabel if defined at the target; has no close tag - http://www.oasis-open.org/docbook/documentation/reference/html/xref.html - - - use to supply text for the link, requires - http://www.oasis-open.org/docbook/documentation/reference/html/link.html - -linkend= - controls the target of the link/xref, required - -endterm= - for , allows the text of the link/xref to be taken from a - different link target title - - -External Linking ----------------- - - - like , but uses a URL (not a document target); requires - ; if no text is specified, the URL appears as the link - text - http://www.oasis-open.org/docbook/documentation/reference/html/ulink.html - -url= - used by to specify the URL, required - - -Guidelines ----------- - -o If you want to supply text, use , else -o Do not use text with so the URL appears in printed output -o Specific nouns like GUC variables, SQL commands, and contrib modules - usually have xreflabels diff --git a/doc-xc/src/sgml/acronyms.sgmlin b/doc-xc/src/sgml/acronyms.sgmlin deleted file mode 100644 index f61d477b35..0000000000 --- a/doc-xc/src/sgml/acronyms.sgmlin +++ /dev/null @@ -1,832 +0,0 @@ - - - - Acronyms - - - - This is a list of acronyms commonly used in the PostgreSQL - documentation and in discussions about PostgreSQL. - - - This is a list of acronyms commonly used in the Postgres-XC - documentation and in discussions about Postgres-XC. - - - This is a list of acronyms commonly used in the Postgres-XL - documentation and in discussions about Postgres-XL. - - - - - - ANSI - - - - American National Standards Institute - - - - - - API - - - Application Programming Interface - - - - - - ASCII - - - American Standard - Code for Information Interchange - - - - - - BKI - - - Backend Interface - - - - - - CA - - - Certificate Authority - - - - - - CIDR - - - Classless - Inter-Domain Routing - - - - - - CPAN - - - Comprehensive Perl Archive Network - - - - - - CRL - - - Certificate - Revocation List - - - - - - CSV - - - Comma - Separated Values - - - - - - CTE - - - Common Table Expression - - - - - - CVE - - - Common Vulnerabilities and Exposures - - - - - - DBA - - - Database - Administrator - - - - - - DBI - - - Database Interface (Perl) - - - - - - DBMS - - - Database Management - System - - - - - - DDL - - - Data - Definition Language, SQL commands such as CREATE - TABLE, ALTER USER - - - - - - DML - - - Data - Manipulation Language, SQL commands such as INSERT, - UPDATE, DELETE - - - - - - DST - - - Daylight - Saving Time - - - - - - ECPG - - - - Embedded C for PostgreSQL - - - Embedded C for Postgres-XC - - - Embedded C for Postgres-XL - - - - - - - ESQL - - - Embedded - SQL - - - - - - FAQ - - - Frequently Asked - Questions - - - - - - FSM - - - Free Space Map - - - - - - GEQO - - - Genetic Query Optimizer - - - - - - GIN - - - Generalized Inverted Index - - - - - - GiST - - - Generalized Search Tree - - - - - - Git - - - Git - - - - - - GMT - - - Greenwich Mean Time - - - - - - - GTM - - - Global Transaction Manager - - - - - - - GTM - - - Global Transaction Manager - - - - - - - GSSAPI - - - Generic - Security Services Application Programming Interface - - - - - - GUC - - - Grand Unified Configuration, - - the PostgreSQL subsystem that handles server configuration - - - the Postgres-XC subsystem that handles server configuration - - - the Postgres-XL subsystem that handles server configuration - - - - - - - - GXID - - - Global Transaction Identifier - - - - - - - GXID - - - Global Transaction Identifier - - - - - - - HBA - - - Host-Based Authentication - - - - - - HOT - - - Heap-Only - Tuples - - - - - - IEC - - - International - Electrotechnical Commission - - - - - - IEEE - - - Institute of Electrical and - Electronics Engineers - - - - - - IPC - - - Inter-Process - Communication - - - - - - ISO - - - International Organization for - Standardization - - - - - - ISSN - - - International Standard - Serial Number - - - - - - JDBC - - - Java - Database Connectivity - - - - - - LDAP - - - Lightweight - Directory Access Protocol - - - - - - MSVC - - - Microsoft - Visual C - - - - - - MVCC - - - Multi-Version Concurrency Control - - - - - - NLS - - - National - Language Support - - - - - - ODBC - - - Open - Database Connectivity - - - - - - OID - - - Object Identifier - - - - - - OLAP - - - Online Analytical - Processing - - - - - - OLTP - - - Online Transaction - Processing - - - - - - ORDBMS - - - Object-Relational - Database Management System - - - - - - PAM - - - Pluggable - Authentication Modules - - - - - - PGSQL - - - - PostgreSQL - - - Postgres-XC - - - Postgres-XL - - - - - - - PGXS - - - - PostgreSQL Extension System - - - Postgres-XC Extension System - - - Postgres-XL Extension System - - - - - - - PID - - - Process Identifier - - - - - - PITR - - - Point-In-Time - Recovery (Continuous Archiving) - - - - - - PL - - - Procedural Languages (server-side) - - - - - - POSIX - - - Portable Operating - System Interface - - - - - - RDBMS - - - Relational - Database Management System - - - - - - RFC - - - Request For - Comments - - - - - - SGML - - - Standard Generalized - Markup Language - - - - - - SPI - - - Server Programming Interface - - - - - - SQL - - - Structured Query Language - - - - - - SRF - - - Set-Returning Function - - - - - - SSH - - - Secure - Shell - - - - - - SSL - - - Secure Sockets Layer - - - - - - SSPI - - - Security - Support Provider Interface - - - - - - SYSV - - - Unix System V - - - - - - TCP/IP - - - Transmission - Control Protocol (TCP) / Internet Protocol (IP) - - - - - - TID - - - Tuple Identifier - - - - - - TOAST - - - The Oversized-Attribute Storage Technique - - - - - - TPC - - - Transaction Processing - Performance Council - - - - - - URL - - - Uniform Resource - Locator - - - - - - UTC - - - Coordinated - Universal Time - - - - - - UTF - - - Unicode Transformation - Format - - - - - - UTF8 - - - Eight-Bit Unicode - Transformation Format - - - - - - UUID - - - Universally Unique Identifier - - - - - - WAL - - - Write-Ahead Log - - - - - - XID - - - Transaction Identifier - - - - - - XML - - - Extensible Markup - Language - - - - - - - - diff --git a/doc-xc/src/sgml/add-node.sgmlin b/doc-xc/src/sgml/add-node.sgmlin deleted file mode 100644 index b8bf1816f4..0000000000 --- a/doc-xc/src/sgml/add-node.sgmlin +++ /dev/null @@ -1,273 +0,0 @@ - - - - Adding a New Node - - - Add a new node - - -&xlonly; - - - This chapter outlines steps to add a new Coordinator or a Datanode to a running cluster. - Note that an easier way to do this is to make use of the pgxc_ctl utility. - - - - - - - - Adding a New Coordinator - - - Add a new coordinator - - - - The following steps should be performed to add a new coordinator to a running cluster: - - - - - - Initialize the new coordinator. The following example initilizes a coordinator named coord_3. - - /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data_cord3 --nodename coord_3 - - - - - - Make necessary changes in postgresql.conf of the new coordinator, - in particular specify new coordinator name and pooler port. - - - - - - Connect to any of the existing coordinators and lock the cluster for backup, do not close this session. - The following example assumes a coordinator is running on port 5432. Make sure the function call returns true. - The detailed description of the function pgxc_lock_for_backup can be found - in - - - ./psql postgres -p 5432 - select pgxc_lock_for_backup(); - - - - - - Connect to any of the existing coordinators and take backup of the database. - Please note that only schema (i.e. no data) is to be dumped. - Also note the use of - - ./pg_dumpall -p 5432 -s --include-nodes --dump-nodes --file=/some/valid/path/some_file_name.sql - - - - - - Start the new coordinator specifying - - ./postgres --restoremode -D ../data_cord3 -p 5455 - - - You can use pg_ctl with option. - - - ./pg_ctl start -Z restoremode -D ../data_coord3 -p 5455 - - - - - - Restore the backup (taken in step 4) by connecting to the new coordinator directly. - - - ./psql -d postgres -f /some/valid/path/some_file_name.sql -p 5455 - - - - - - Quit the new coordinator. - - - - - - Start the new coordinator specifying - - ./postgres --coordinator -D ../data_cord3 -p 5455 - - - - - - Create the new coordinator on rest of the coordinators and reload configuration. - The following example creates coord_3, with host localhost and port 5455. - - - CREATE NODE COORD_3 WITH (HOST = 'localhost', type = 'coordinator', PORT = 5455); - SELECT pgxc_pool_reload(); - - - - - - Quit the session of step 3, this will unlock the cluster. The new coordinator is now ready. - - - - - - - - - - Adding a New Datanode - - - Add a new Datanode - - - - Following steps should be performed to add a new datanode to a running cluster: - - - - - - - - Initialize the new datanode. The following example initializes a new datanode named data_node_3. - - - /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data3 --nodename data_node_3 - - - - - - Make the necessary changes in postgresql.conf of the new datanode, in particular specify new datanode name - - - - - - Connect to any of the existing coordinators and lock the cluster for backup, do not close this session. - The following example assumes a coordinator is running on port 5432. Make sure the function call returns true. - The detailed description of the function pgxc_lock_for_backup can be found - in - - - ./psql postgres -p 5432 - select pgxc_lock_for_backup(); - - - - - - Connect to any of the existing datanodes and take backup of the database. - Please note that only schema (i.e. no data) is to be dumped. - The following example assumes that a datanode is running on port 15432. - - - ./pg_dumpall -p 15432 -s --file=/some/valid/path/some_file_name.sql - - - - - - Start the new datanode specifying - - ./postgres --restoremode -D ../data3 -p 35432 - - - You can use pg_ctl with option. - - - ./pg_ctl start -Z restoremode -D ../data3 -p 5455 - - - - - - Restore the backup (taken in step 4) by connecting to the new datanode directly. - - - ./psql -d postgres -f /some/valid/path/some_file_name.sql -p 35432 - - - - - - Quit the new datanode. - - - - - - Start the new datanode specifying --datanode while starting. - - - ./postgres --datanode -D ../data3 -p 35432 - - - - - - Create the new datanode on all the coordinators and reload configuration. - The following example creates data_node_3, with host localhost and port 35432. - - - CREATE NODE DATA_NODE_3 WITH (HOST = 'localhost', type = 'datanode', PORT = 35432); - SELECT pgxc_pool_reload(); - - - - - - Create the new datanode on all the other datanodes too and reload configuration. - The following example creates data_node_3, with host localhost and port 35432. - - - EXECUTE DIRECT ON (DATA_NODE_1) 'CREATE NODE DATA_NODE_3 WITH (HOST = ''localhost'', type = ''datanode'', PORT = 35432)'; - EXECUTE DIRECT ON (DATA_NODE_2) 'CREATE NODE DATA_NODE_3 WITH (HOST = ''localhost'', type = ''datanode'', PORT = 35432)'; - EXECUTE DIRECT ON (DATA_NODE_3) 'ALTER NODE DATA_NODE_3 WITH (HOST = ''localhost'', type = ''datanode'', PORT = 35432)'; - EXECUTE DIRECT ON (DATA_NODE_1) 'SELECT pgxc_pool_reload()'; - EXECUTE DIRECT ON (DATA_NODE_2) 'SELECT pgxc_pool_reload()'; - EXECUTE DIRECT ON (DATA_NODE_3) 'SELECT pgxc_pool_reload()'; - - - - - - Quit the session of step 3, this will unlock the cluster. - - - - - The new datanode is now ready. - Redistribute existing data by using ALTER TABLE -my_table ADD NODE (DATA_NODE_3). - - - - - - - - - diff --git a/doc-xc/src/sgml/adminpack.sgmlin b/doc-xc/src/sgml/adminpack.sgmlin deleted file mode 100644 index fef740a815..0000000000 --- a/doc-xc/src/sgml/adminpack.sgmlin +++ /dev/null @@ -1,47 +0,0 @@ - - - - adminpack - - - adminpack - -&common; - - adminpack provides a number of support functions which - pgAdmin and other administration and management tools can - use to provide additional functionality, such as remote management - of server log files. - - - - Functions Implemented - -&common; - - The functions implemented by adminpack can only be run by a - superuser. Here's a list of these functions: - - -int8 pg_catalog.pg_file_write(fname text, data text, append bool) -bool pg_catalog.pg_file_rename(oldname text, newname text, archivename text) -bool pg_catalog.pg_file_rename(oldname text, newname text) -bool pg_catalog.pg_file_unlink(fname text) -setof record pg_catalog.pg_logdir_ls() - -/* Renaming of existing backend functions for pgAdmin compatibility */ -int8 pg_catalog.pg_file_read(fname text, data text, append bool) -bigint pg_catalog.pg_file_length(text) -int4 pg_catalog.pg_logfile_rotate() - - - - - - Functions of this module run only on the Coordinator you're connecting. - - - - - - diff --git a/doc-xc/src/sgml/advanced.sgmlin b/doc-xc/src/sgml/advanced.sgmlin deleted file mode 100644 index daae1dc8b2..0000000000 --- a/doc-xc/src/sgml/advanced.sgmlin +++ /dev/null @@ -1,929 +0,0 @@ - - - - Advanced Features - - - Introduction - -&common; - - - In the previous chapter we have covered the basics of using - SQL to store and access your data in - PostgreSQL. We will now discuss some - more advanced features of SQL that simplify - management and prevent loss or corruption of your data. Finally, - we will look at some PostgreSQL - extensions. - - - In the previous chapter we have covered the basics of using - SQL to store and access your data in - Postgres-XC. We will now discuss some - more advanced features of SQL that simplify - management and prevent loss or corruption of your data. Finally, - we will look at some Postgres-XC - extensions. - - - In the previous chapter we have covered the basics of using - SQL to store and access your data in - Postgres-XL. We will now discuss some - more advanced features of SQL that simplify - management and prevent loss or corruption of your data. Finally, - we will look at some Postgres-XL - extensions. - - - - - This chapter will on occasion refer to examples found in to change or improve them, so it will be - useful to have read that chapter. Some examples from - this chapter can also be found in - advanced.sql in the tutorial directory. This - file also contains some sample data to load, which is not - repeated here. (Refer to for - how to use the file.) - - - - - - Views - - - view - -&common; - - Refer back to the queries in . - Suppose the combined listing of weather records and city location - is of particular interest to your application, but you do not want - to type the query each time you need it. You can create a - view over the query, which gives a name to - the query that you can refer to like an ordinary table: - - -CREATE VIEW myview AS - SELECT city, temp_lo, temp_hi, prcp, date, location - FROM weather, cities - WHERE city = name; - -SELECT * FROM myview; - - - - - Making liberal use of views is a key aspect of good SQL database - design. Views allow you to encapsulate the details of the - structure of your tables, which might change as your application - evolves, behind consistent interfaces. - - - - Views can be used in almost any place a real table can be used. - Building views upon other views is not uncommon. - - - - - - Foreign Keys - - - foreign key - - - - referential integrity - -&common; - - Recall the weather and - cities tables from . Consider the following problem: You - want to make sure that no one can insert rows in the - weather table that do not have a matching - entry in the cities table. This is called - maintaining the referential integrity of - your data. In simplistic database systems this would be - implemented (if at all) by first looking at the - cities table to check if a matching record - exists, and then inserting or rejecting the new - weather records. This approach has a - number of problems and is very inconvenient, so - - PostgreSQL can do this for you. - - - Postgres-XC can do this for you. - - - Postgres-XL can do this for you. - - - - - The new declaration of the tables would look like this: - - -CREATE TABLE cities ( - city varchar(80) primary key, - location point -); - -CREATE TABLE weather ( - city varchar(80) references cities(city), - temp_lo int, - temp_hi int, - prcp real, - date date -); - - - Now try inserting an invalid record: - - -INSERT INTO weather VALUES ('Berkeley', 45, 53, 0.0, '1994-11-28'); - - - -ERROR: insert or update on table "weather" violates foreign key constraint "weather_city_fkey" -DETAIL: Key (city)=(Berkeley) is not present in table "cities". - - - - - The behavior of foreign keys can be finely tuned to your - application. We will not go beyond this simple example in this - tutorial, but just refer you to - for more information. Making correct use of - foreign keys will definitely improve the quality of your database - applications, so you are strongly encouraged to learn about them. - - - -&xconly; - - Please note that primary key and reference key are both allowed - only when these columns are distribution keys when tables are - distributed. As a default, Postgres-XC - distributes each row of tables based upon the value of the first - column of the table. You can choose any column as a basis of - table distribution, or you can have copies of a table in all the - Datanodes. - - - Please refer to for details. - - - - - - - Transactions - - - transaction - - -&common; - - Transactions are a fundamental concept of all database - systems. The essential point of a transaction is that it bundles - multiple steps into a single, all-or-nothing operation. The intermediate - states between the steps are not visible to other concurrent transactions, - and if some failure occurs that prevents the transaction from completing, - then none of the steps affect the database at all. - - - - For example, consider a bank database that contains balances for various - customer accounts, as well as total deposit balances for branches. - Suppose that we want to record a payment of $100.00 from Alice's account - to Bob's account. Simplifying outrageously, the SQL commands for this - might look like: - - -UPDATE accounts SET balance = balance - 100.00 - WHERE name = 'Alice'; -UPDATE branches SET balance = balance - 100.00 - WHERE name = (SELECT branch_name FROM accounts WHERE name = 'Alice'); -UPDATE accounts SET balance = balance + 100.00 - WHERE name = 'Bob'; -UPDATE branches SET balance = balance + 100.00 - WHERE name = (SELECT branch_name FROM accounts WHERE name = 'Bob'); - - - - - The details of these commands are not important here; the important - point is that there are several separate updates involved to accomplish - this rather simple operation. Our bank's officers will want to be - assured that either all these updates happen, or none of them happen. - It would certainly not do for a system failure to result in Bob - receiving $100.00 that was not debited from Alice. Nor would Alice long - remain a happy customer if she was debited without Bob being credited. - We need a guarantee that if something goes wrong partway through the - operation, none of the steps executed so far will take effect. Grouping - the updates into a transaction gives us this guarantee. - A transaction is said to be atomic: from the point of - view of other transactions, it either happens completely or not at all. - - - - We also want a - guarantee that once a transaction is completed and acknowledged by - the database system, it has indeed been permanently recorded - and won't be lost even if a crash ensues shortly thereafter. - For example, if we are recording a cash withdrawal by Bob, - we do not want any chance that the debit to his account will - disappear in a crash just after he walks out the bank door. - A transactional database guarantees that all the updates made by - a transaction are logged in permanent storage (i.e., on disk) before - the transaction is reported complete. - - - - Another important property of transactional databases is closely - related to the notion of atomic updates: when multiple transactions - are running concurrently, each one should not be able to see the - incomplete changes made by others. For example, if one transaction - is busy totalling all the branch balances, it would not do for it - to include the debit from Alice's branch but not the credit to - Bob's branch, nor vice versa. So transactions must be all-or-nothing - not only in terms of their permanent effect on the database, but - also in terms of their visibility as they happen. The updates made - so far by an open transaction are invisible to other transactions - until the transaction completes, whereupon all the updates become - visible simultaneously. - - - - - -&xlonly; - - Please note that primary key and reference key are both allowed - only when these columns are distribution keys when tables are - distributed. As a default, Postgres-XL - distributes each row of tables based upon the value of the first - column of the table. You can choose any column as a basis of - table distribution, or you can have copies of a table in all the - Datanodes by specifying that it should be distributed by replication. - - - Please refer to for details. - - - - - - - Transactions - - - transaction - - -&common; - - Transactions are a fundamental concept of all database - systems. The essential point of a transaction is that it bundles - multiple steps into a single, all-or-nothing operation. The intermediate - states between the steps are not visible to other concurrent transactions, - and if some failure occurs that prevents the transaction from completing, - then none of the steps affect the database at all. - - - - For example, consider a bank database that contains balances for various - customer accounts, as well as total deposit balances for branches. - Suppose that we want to record a payment of $100.00 from Alice's account - to Bob's account. Simplifying outrageously, the SQL commands for this - might look like: - - -UPDATE accounts SET balance = balance - 100.00 - WHERE name = 'Alice'; -UPDATE branches SET balance = balance - 100.00 - WHERE name = (SELECT branch_name FROM accounts WHERE name = 'Alice'); -UPDATE accounts SET balance = balance + 100.00 - WHERE name = 'Bob'; -UPDATE branches SET balance = balance + 100.00 - WHERE name = (SELECT branch_name FROM accounts WHERE name = 'Bob'); - - - - - The details of these commands are not important here; the important - point is that there are several separate updates involved to accomplish - this rather simple operation. Our bank's officers will want to be - assured that either all these updates happen, or none of them happen. - It would certainly not do for a system failure to result in Bob - receiving $100.00 that was not debited from Alice. Nor would Alice long - remain a happy customer if she was debited without Bob being credited. - We need a guarantee that if something goes wrong partway through the - operation, none of the steps executed so far will take effect. Grouping - the updates into a transaction gives us this guarantee. - A transaction is said to be atomic: from the point of - view of other transactions, it either happens completely or not at all. - - - - We also want a - guarantee that once a transaction is completed and acknowledged by - the database system, it has indeed been permanently recorded - and won't be lost even if a crash ensues shortly thereafter. - For example, if we are recording a cash withdrawal by Bob, - we do not want any chance that the debit to his account will - disappear in a crash just after he walks out the bank door. - A transactional database guarantees that all the updates made by - a transaction are logged in permanent storage (i.e., on disk) before - the transaction is reported complete. - - - - Another important property of transactional databases is closely - related to the notion of atomic updates: when multiple transactions - are running concurrently, each one should not be able to see the - incomplete changes made by others. For example, if one transaction - is busy totalling all the branch balances, it would not do for it - to include the debit from Alice's branch but not the credit to - Bob's branch, nor vice versa. So transactions must be all-or-nothing - not only in terms of their permanent effect on the database, but - also in terms of their visibility as they happen. The updates made - so far by an open transaction are invisible to other transactions - until the transaction completes, whereupon all the updates become - visible simultaneously. - - - - - - In PostgreSQL, a transaction is set up by surrounding - the SQL commands of the transaction with - BEGIN and COMMIT commands. So our banking - transaction would actually look like: - - - In Postgres-XC, a transaction is set up by surrounding - the SQL commands of the transaction with - BEGIN and COMMIT commands. So our banking - transaction would actually look like: - - - In Postgres-XL, a transaction is set up by surrounding - the SQL commands of the transaction with - BEGIN and COMMIT commands. So our banking - transaction would actually look like: - - - -BEGIN; -UPDATE accounts SET balance = balance - 100.00 - WHERE name = 'Alice'; --- etc etc -COMMIT; - - - - - If, partway through the transaction, we decide we do not want to - commit (perhaps we just noticed that Alice's balance went negative), - we can issue the command ROLLBACK instead of - COMMIT, and all our updates so far will be canceled. - - - - - PostgreSQL actually treats every SQL statement as being - - - Postgres-XC actually treats every SQL statement as being - - - Postgres-XL actually treats every SQL statement as being - - executed within a transaction. If you do not issue a BEGIN - command, - then each individual statement has an implicit BEGIN and - (if successful) COMMIT wrapped around it. A group of - statements surrounded by BEGIN and COMMIT - is sometimes called a transaction block. - - - - - Some client libraries issue BEGIN and COMMIT - commands automatically, so that you might get the effect of transaction - blocks without asking. Check the documentation for the interface - you are using. - - - - - - - It's possible to control the statements in a transaction in a more - granular fashion through the use of savepoints. Savepoints - allow you to selectively discard parts of the transaction, while - committing the rest. After defining a savepoint with - SAVEPOINT, you can if needed roll back to the savepoint - with ROLLBACK TO. All the transaction's database changes - between defining the savepoint and rolling back to it are discarded, but - changes earlier than the savepoint are kept. - - - - After rolling back to a savepoint, it continues to be defined, so you can - roll back to it several times. Conversely, if you are sure you won't need - to roll back to a particular savepoint again, it can be released, so the - system can free some resources. Keep in mind that either releasing or - rolling back to a savepoint - will automatically release all savepoints that were defined after it. - - - - - All this is happening within the transaction block, so none of it - is visible to other database sessions. When and if you commit the - transaction block, the committed actions become visible as a unit - to other sessions, while the rolled-back actions never become visible - at all. - - - - - - - Remembering the bank database, suppose we debit $100.00 from Alice's - account, and credit Bob's account, only to find later that we should - have credited Wally's account. We could do it using savepoints like - this: - - -BEGIN; -UPDATE accounts SET balance = balance - 100.00 - WHERE name = 'Alice'; -SAVEPOINT my_savepoint; -UPDATE accounts SET balance = balance + 100.00 - WHERE name = 'Bob'; --- oops ... forget that and use Wally's account -ROLLBACK TO my_savepoint; -UPDATE accounts SET balance = balance + 100.00 - WHERE name = 'Wally'; -COMMIT; - - - - - This example is, of course, oversimplified, but there's a lot of control - possible in a transaction block through the use of savepoints. - Moreover, ROLLBACK TO is the only way to regain control of a - transaction block that was put in aborted state by the - system due to an error, short of rolling it back completely and starting - again. - - - - - - - - - - Window Functions - - - window function - - - - A window function performs a calculation across a set of - table rows that are somehow related to the current row. This is comparable - to the type of calculation that can be done with an aggregate function. - But unlike regular aggregate functions, use of a window function does not - cause rows to become grouped into a single output row — the - rows retain their separate identities. Behind the scenes, the window - function is able to access more than just the current row of the query - result. - - - - Here is an example that shows how to compare each employee's salary - with the average salary in his or her department: - - -SELECT depname, empno, salary, avg(salary) OVER (PARTITION BY depname) FROM empsalary; - - - - depname | empno | salary | avg ------------+-------+--------+----------------------- - develop | 11 | 5200 | 5020.0000000000000000 - develop | 7 | 4200 | 5020.0000000000000000 - develop | 9 | 4500 | 5020.0000000000000000 - develop | 8 | 6000 | 5020.0000000000000000 - develop | 10 | 5200 | 5020.0000000000000000 - personnel | 5 | 3500 | 3700.0000000000000000 - personnel | 2 | 3900 | 3700.0000000000000000 - sales | 3 | 4800 | 4866.6666666666666667 - sales | 1 | 5000 | 4866.6666666666666667 - sales | 4 | 4800 | 4866.6666666666666667 -(10 rows) - - - The first three output columns come directly from the table - empsalary, and there is one output row for each row in the - table. The fourth column represents an average taken across all the table - rows that have the same depname value as the current row. - (This actually is the same function as the regular avg - aggregate function, but the OVER clause causes it to be - treated as a window function and computed across an appropriate set of - rows.) - - - - A window function call always contains an OVER clause - directly following the window function's name and argument(s). This is what - syntactically distinguishes it from a regular function or aggregate - function. The OVER clause determines exactly how the - rows of the query are split up for processing by the window function. - The PARTITION BY list within OVER specifies - dividing the rows into groups, or partitions, that share the same - values of the PARTITION BY expression(s). For each row, - the window function is computed across the rows that fall into the - same partition as the current row. - - - - You can also control the order in which rows are processed by - window functions using ORDER BY within OVER. - (The window ORDER BY does not even have to match the - order in which the rows are output.) Here is an example: - - -SELECT depname, empno, salary, rank() OVER (PARTITION BY depname ORDER BY salary DESC) FROM empsalary; - - - - depname | empno | salary | rank ------------+-------+--------+------ - develop | 8 | 6000 | 1 - develop | 10 | 5200 | 2 - develop | 11 | 5200 | 2 - develop | 9 | 4500 | 4 - develop | 7 | 4200 | 5 - personnel | 2 | 3900 | 1 - personnel | 5 | 3500 | 2 - sales | 1 | 5000 | 1 - sales | 4 | 4800 | 2 - sales | 3 | 4800 | 2 -(10 rows) - - - As shown here, the rank function produces a numerical rank - within the current row's partition for each distinct ORDER BY - value, in the order defined by the ORDER BY clause. - rank needs no explicit parameter, because its behavior - is entirely determined by the OVER clause. - - - - The rows considered by a window function are those of the virtual - table produced by the query's FROM clause as filtered by its - WHERE, GROUP BY, and HAVING clauses - if any. For example, a row removed because it does not meet the - WHERE condition is not seen by any window function. - A query can contain multiple window functions that slice up the data - in different ways by means of different OVER clauses, but - they all act on the same collection of rows defined by this virtual table. - - - - We already saw that ORDER BY can be omitted if the ordering - of rows is not important. It is also possible to omit PARTITION - BY, in which case there is just one partition containing all the rows. - - - - There is another important concept associated with window functions: - for each row, there is a set of rows within its partition called its - window frame. Many (but not all) window functions act only - on the rows of the window frame, rather than of the whole partition. - By default, if ORDER BY is supplied then the frame consists of - all rows from the start of the partition up through the current row, plus - any following rows that are equal to the current row according to the - ORDER BY clause. When ORDER BY is omitted the - default frame consists of all rows in the partition. - - - There are options to define the window frame in other ways, but - this tutorial does not cover them. See - for details. - - - Here is an example using sum: - - - -SELECT salary, sum(salary) OVER () FROM empsalary; - - - - salary | sum ---------+------- - 5200 | 47100 - 5000 | 47100 - 3500 | 47100 - 4800 | 47100 - 3900 | 47100 - 4200 | 47100 - 4500 | 47100 - 4800 | 47100 - 6000 | 47100 - 5200 | 47100 -(10 rows) - - - - Above, since there is no ORDER BY in the OVER - clause, the window frame is the same as the partition, which for lack of - PARTITION BY is the whole table; in other words each sum is - taken over the whole table and so we get the same result for each output - row. But if we add an ORDER BY clause, we get very different - results: - - - -SELECT salary, sum(salary) OVER (ORDER BY salary) FROM empsalary; - - - - salary | sum ---------+------- - 3500 | 3500 - 3900 | 7400 - 4200 | 11600 - 4500 | 16100 - 4800 | 25700 - 4800 | 25700 - 5000 | 30700 - 5200 | 41100 - 5200 | 41100 - 6000 | 47100 -(10 rows) - - - - Here the sum is taken from the first (lowest) salary up through the - current one, including any duplicates of the current one (notice the - results for the duplicated salaries). - - - - Window functions are permitted only in the SELECT list - and the ORDER BY clause of the query. They are forbidden - elsewhere, such as in GROUP BY, HAVING - and WHERE clauses. This is because they logically - execute after the processing of those clauses. Also, window functions - execute after regular aggregate functions. This means it is valid to - include an aggregate function call in the arguments of a window function, - but not vice versa. - - - - If there is a need to filter or group rows after the window calculations - are performed, you can use a sub-select. For example: - - -SELECT depname, empno, salary, enroll_date -FROM - (SELECT depname, empno, salary, enroll_date, - rank() OVER (PARTITION BY depname ORDER BY salary DESC, empno) AS pos - FROM empsalary - ) AS ss -WHERE pos < 3; - - - The above query only shows the rows from the inner query having - rank less than 3. - - - - When a query involves multiple window functions, it is possible to write - out each one with a separate OVER clause, but this is - duplicative and error-prone if the same windowing behavior is wanted - for several functions. Instead, each windowing behavior can be named - in a WINDOW clause and then referenced in OVER. - For example: - - -SELECT sum(salary) OVER w, avg(salary) OVER w - FROM empsalary - WINDOW w AS (PARTITION BY depname ORDER BY salary DESC); - - - - - More details about window functions can be found in - , - , - , and the - reference page. - - - - - - Inheritance - - - inheritance - - -&common; - - Inheritance is a concept from object-oriented databases. It opens - up interesting new possibilities of database design. - - - - Let's create two tables: A table cities - and a table capitals. Naturally, capitals - are also cities, so you want some way to show the capitals - implicitly when you list all cities. If you're really clever you - might invent some scheme like this: - - -CREATE TABLE capitals ( - name text, - population real, - altitude int, -- (in ft) - state char(2) -); - -CREATE TABLE non_capitals ( - name text, - population real, - altitude int -- (in ft) -); - -CREATE VIEW cities AS - SELECT name, population, altitude FROM capitals - UNION - SELECT name, population, altitude FROM non_capitals; - - - This works OK as far as querying goes, but it gets ugly when you - need to update several rows, for one thing. - - - - A better solution is this: - - -CREATE TABLE cities ( - name text, - population real, - altitude int -- (in ft) -); - -CREATE TABLE capitals ( - state char(2) -) SELECT name, altitude - FROM cities - WHERE altitude > 500;INHERITS (cities); - - - - - In this case, a row of capitals - inherits all columns (name, - population, and altitude) from its - parent, cities. The - type of the column name is - - text, a native PostgreSQL - - - text, a native Postgres-XC - - - text, a native Postgres-XL - - type for variable length character strings. State capitals have - an extra column, state, that shows their state. In - - PostgreSQL, a table can inherit from - - - Postgres-XC, a table can inherit from - - - Postgres-XL, a table can inherit from - - zero or more other tables. - - - - For example, the following query finds the names of all cities, - including state capitals, that are located at an altitude - over 500 feet: - - -SELECT name, altitude - FROM cities - WHERE altitude > 500; - - - which returns: - - - name | altitude ------------+---------- - Las Vegas | 2174 - Mariposa | 1953 - Madison | 845 -(3 rows) - - - - - On the other hand, the following query finds - all the cities that are not state capitals and - are situated at an altitude of 500 feet or higher: - - -SELECT name, altitude - FROM ONLY cities - WHERE altitude > 500; - - - - name | altitude ------------+---------- - Las Vegas | 2174 - Mariposa | 1953 -(2 rows) - - - - - Here the ONLY before cities - indicates that the query should be run over only the - cities table, and not tables below - cities in the inheritance hierarchy. Many - of the commands that we have already discussed — - SELECT, UPDATE, and - DELETE — support this ONLY - notation. - - - - - Although inheritance is frequently useful, it has not been integrated - with unique constraints or foreign keys, which limits its usefulness. - See for more detail. - - - - - - - - Conclusion - -&common; - - - PostgreSQL has many features not - - - Postgres-XC has many features not - - - Postgres-XL has many features not - - touched upon in this tutorial introduction, which has been - oriented toward newer users of SQL. These - features are discussed in more detail in the remainder of this - book. - - - - - If you feel you need more introductory material, please visit the PostgreSQL - web site - for links to more resources. - - - - diff --git a/doc-xc/src/sgml/arch-dev.sgmlin b/doc-xc/src/sgml/arch-dev.sgmlin deleted file mode 100644 index fe4ef807b8..0000000000 --- a/doc-xc/src/sgml/arch-dev.sgmlin +++ /dev/null @@ -1,1630 +0,0 @@ - - - - Overview of PostgreSQL Internals - - - Author - - This chapter originated as part of - , Stefan Simkovics' - Master's Thesis prepared at Vienna University of Technology under the direction - of O.Univ.Prof.Dr. Georg Gottlob and Univ.Ass. Mag. Katrin Seyr. - - - - - - This chapter describes internals - of PostgreSQL - which Postgres-XC inherited most of - features. - - - - - This chapter describes the internals - of PostgreSQL, - from which Postgres-XL inherited most of - features. - - -&common; - - - This chapter gives an overview of the internal structure of the - backend of PostgreSQL. After having - read the following sections you should have an idea of how a query - is processed. This chapter does not aim to provide a detailed - description of the internal operation of - PostgreSQL, as such a document would be - very extensive. Rather, this chapter is intended to help the reader - understand the general sequence of operations that occur within the - backend from the point at which a query is received, to the point - at which the results are returned to the client. - - - - The Path of a Query - -&common; - - Here we give a short overview of the stages a query has to pass in - order to obtain a result. - - - - - - A connection from an application program to the PostgreSQL - server has to be established. The application program transmits a - query to the server and waits to receive the results sent back by the - server. - - - - - - The parser stage checks the query - transmitted by the application - program for correct syntax and creates - a query tree. - - - - - - The rewrite system takes - the query tree created by the parser stage and looks for - any rules (stored in the - system catalogs) to apply to - the query tree. It performs the - transformations given in the rule bodies. - - - - One application of the rewrite system is in the realization of - views. - Whenever a query against a view - (i.e., a virtual table) is made, - the rewrite system rewrites the user's query to - a query that accesses the base tables given in - the view definition instead. - - - - - - The planner/optimizer takes - the (rewritten) query tree and creates a - query plan that will be the input to the - executor. - - - - It does so by first creating all possible paths - leading to the same result. For example if there is an index on a - relation to be scanned, there are two paths for the - scan. One possibility is a simple sequential scan and the other - possibility is to use the index. Next the cost for the execution of - each path is estimated and the cheapest path is chosen. The cheapest - path is expanded into a complete plan that the executor can use. - - - - - - The executor recursively steps through - the plan tree and - retrieves rows in the way represented by the plan. - The executor makes use of the - storage system while scanning - relations, performs sorts and joins, - evaluates qualifications and finally hands back the rows derived. - - - - - - In the following sections we will cover each of the above listed items - in more detail to give a better understanding of PostgreSQL's internal - control and data structures. - - - - - How Connections are Established - -&common; - - PostgreSQL is implemented using a - simple process per user client/server model. In this model - there is one client process connected to - exactly one server process. As we do not - know ahead of time how many connections will be made, we have to - use a master process that spawns a new - server process every time a connection is requested. This master - process is called postgres and listens at a - specified TCP/IP port for incoming connections. Whenever a request - for a connection is detected the postgres - process spawns a new server process. The server tasks - communicate with each other using semaphores and - shared memory to ensure data integrity - throughout concurrent data access. - - - - The client process can be any program that understands the - PostgreSQL protocol described in - . Many clients are based on the - C-language library libpq, but several independent - implementations of the protocol exist, such as the Java - JDBC driver. - - - - Once a connection is established the client process can send a query - to the backend (server). The query is transmitted using plain text, - i.e., there is no parsing done in the frontend (client). The - server parses the query, creates an execution plan, - executes the plan and returns the retrieved rows to the client - by transmitting them over the established connection. - - - - - The Parser Stage - -&common; - - The parser stage consists of two parts: - - - - - The parser defined in - gram.y and scan.l is - built using the Unix tools bison - and flex. - - - - - The transformation process does - modifications and augmentations to the data structures returned by the parser. - - - - - - - Parser - -&common; - - The parser has to check the query string (which arrives as plain - ASCII text) for valid syntax. If the syntax is correct a - parse tree is built up and handed back; - otherwise an error is returned. The parser and lexer are - implemented using the well-known Unix tools bison - and flex. - - - - The lexer is defined in the file - scan.l and is responsible - for recognizing identifiers, - the SQL key words etc. For - every key word or identifier that is found, a token - is generated and handed to the parser. - - - - The parser is defined in the file gram.y and - consists of a set of grammar rules and - actions that are executed whenever a rule - is fired. The code of the actions (which is actually C code) is - used to build up the parse tree. - - - - The file scan.l is transformed to the C - source file scan.c using the program - flex and gram.y is - transformed to gram.c using - bison. After these transformations - have taken place a normal C compiler can be used to create the - parser. Never make any changes to the generated C files as they - will be overwritten the next time flex - or bison is called. - - - - The mentioned transformations and compilations are normally done - automatically using the makefiles - shipped with the PostgreSQL - source distribution. - - - - - - A detailed description of bison or - the grammar rules given in gram.y would be - beyond the scope of this paper. There are many books and - documents dealing with flex and - bison. You should be familiar with - bison before you start to study the - grammar given in gram.y otherwise you won't - understand what happens there. - - - - - - Transformation Process - -&common; - - The parser stage creates a parse tree using only fixed rules about - the syntactic structure of SQL. It does not make any lookups in the - system catalogs, so there is no possibility to understand the detailed - semantics of the requested operations. After the parser completes, - the transformation process takes the tree handed - back by the parser as input and does the semantic interpretation needed - to understand which tables, functions, and operators are referenced by - the query. The data structure that is built to represent this - information is called the query tree. - - - - The reason for separating raw parsing from semantic analysis is that - system catalog lookups can only be done within a transaction, and we - do not wish to start a transaction immediately upon receiving a query - string. The raw parsing stage is sufficient to identify the transaction - control commands (BEGIN, ROLLBACK, etc), and - these can then be correctly executed without any further analysis. - Once we know that we are dealing with an actual query (such as - SELECT or UPDATE), it is okay to - start a transaction if we're not already in one. Only then can the - transformation process be invoked. - - - - The query tree created by the transformation process is structurally - similar to the raw parse tree in most places, but it has many differences - in detail. For example, a FuncCall node in the - parse tree represents something that looks syntactically like a function - call. This might be transformed to either a FuncExpr - or Aggref node depending on whether the referenced - name turns out to be an ordinary function or an aggregate function. - Also, information about the actual data types of columns and expression - results is added to the query tree. - - - - - - The <productname>PostgreSQL</productname> Rule System - -&common; - - PostgreSQL supports a powerful - rule system for the specification - of views and ambiguous view updates. - Originally the PostgreSQL - rule system consisted of two implementations: - - - - - The first one worked using row level processing and was - implemented deep in the executor. The rule system was - called whenever an individual row had been accessed. This - implementation was removed in 1995 when the last official release - of the Berkeley Postgres project was - transformed into Postgres95. - - - - - - The second implementation of the rule system is a technique - called query rewriting. - The rewrite system is a module - that exists between the parser stage and the - planner/optimizer. This technique is still implemented. - - - - - - - The query rewriter is discussed in some detail in - , so there is no need to cover it here. - We will only point out that both the input and the output of the - rewriter are query trees, that is, there is no change in the - representation or level of semantic detail in the trees. Rewriting - can be thought of as a form of macro expansion. - - - - - - Planner/Optimizer - -&common; - - The task of the planner/optimizer is to - create an optimal execution plan. A given SQL query (and hence, a - query tree) can be actually executed in a wide variety of - different ways, each of which will produce the same set of - results. If it is computationally feasible, the query optimizer - will examine each of these possible execution plans, ultimately - selecting the execution plan that is expected to run the fastest. - - - - - In some situations, examining each possible way in which a query - can be executed would take an excessive amount of time and memory - space. In particular, this occurs when executing queries - involving large numbers of join operations. In order to determine - a reasonable (not necessarily optimal) query plan in a reasonable amount - of time, PostgreSQL uses a Genetic - Query Optimizer (see ) when the number of joins - exceeds a threshold (see ). - - - - - The planner's search procedure actually works with data structures - called paths, which are simply cut-down representations of - plans containing only as much information as the planner needs to make - its decisions. After the cheapest path is determined, a full-fledged - plan tree is built to pass to the executor. This represents - the desired execution plan in sufficient detail for the executor to run it. - In the rest of this section we'll ignore the distinction between paths - and plans. - - - - Generating Possible Plans - -&common; - - The planner/optimizer starts by generating plans for scanning each - individual relation (table) used in the query. The possible plans - are determined by the available indexes on each relation. - There is always the possibility of performing a - sequential scan on a relation, so a sequential scan plan is always - created. Assume an index is defined on a - relation (for example a B-tree index) and a query contains the - restriction - relation.attribute OPR constant. If - relation.attribute happens to match the key of the B-tree - index and OPR is one of the operators listed in - the index's operator class, another plan is created using - the B-tree index to scan the relation. If there are further indexes - present and the restrictions in the query happen to match a key of an - index, further plans will be considered. Index scan plans are also - generated for indexes that have a sort ordering that can match the - query's ORDER BY clause (if any), or a sort ordering that - might be useful for merge joining (see below). - - - - If the query requires joining two or more relations, - plans for joining relations are considered - after all feasible plans have been found for scanning single relations. - The three available join strategies are: - - - - - nested loop join: The right relation is scanned - once for every row found in the left relation. This strategy - is easy to implement but can be very time consuming. (However, - if the right relation can be scanned with an index scan, this can - be a good strategy. It is possible to use values from the current - row of the left relation as keys for the index scan of the right.) - - - - - - merge join: Each relation is sorted on the join - attributes before the join starts. Then the two relations are - scanned in parallel, and matching rows are combined to form - join rows. This kind of join is more - attractive because each relation has to be scanned only once. - The required sorting might be achieved either by an explicit sort - step, or by scanning the relation in the proper order using an - index on the join key. - - - - - - hash join: the right relation is first scanned - and loaded into a hash table, using its join attributes as hash keys. - Next the left relation is scanned and the - appropriate values of every row found are used as hash keys to - locate the matching rows in the table. - - - - - - - When the query involves more than two relations, the final result - must be built up by a tree of join steps, each with two inputs. - The planner examines different possible join sequences to find the - cheapest one. - - - - If the query uses fewer than - relations, a near-exhaustive search is conducted to find the best - join sequence. The planner preferentially considers joins between any - two relations for which there exist a corresponding join clause in the - WHERE qualification (i.e., for - which a restriction like where rel1.attr1=rel2.attr2 - exists). Join pairs with no join clause are considered only when there - is no other choice, that is, a particular relation has no available - join clauses to any other relation. All possible plans are generated for - every join pair considered by the planner, and the one that is - (estimated to be) the cheapest is chosen. - - - - When geqo_threshold is exceeded, the join - sequences considered are determined by heuristics, as described - in . Otherwise the process is the same. - - - - The finished plan tree consists of sequential or index scans of - the base relations, plus nested-loop, merge, or hash join nodes as - needed, plus any auxiliary steps needed, such as sort nodes or - aggregate-function calculation nodes. Most of these plan node - types have the additional ability to do selection - (discarding rows that do not meet a specified Boolean condition) - and projection (computation of a derived column set - based on given column values, that is, evaluation of scalar - expressions where needed). One of the responsibilities of the - planner is to attach selection conditions from the - WHERE clause and computation of required - output expressions to the most appropriate nodes of the plan - tree. - - - - - - Executor - -&common; - - The executor takes the plan created by the - planner/optimizer and recursively processes it to extract the required set - of rows. This is essentially a demand-pull pipeline mechanism. - Each time a plan node is called, it must deliver one more row, or - report that it is done delivering rows. - - - - To provide a concrete example, assume that the top - node is a MergeJoin node. - Before any merge can be done two rows have to be fetched (one from - each subplan). So the executor recursively calls itself to - process the subplans (it starts with the subplan attached to - lefttree). The new top node (the top node of the left - subplan) is, let's say, a - Sort node and again recursion is needed to obtain - an input row. The child node of the Sort might - be a SeqScan node, representing actual reading of a table. - Execution of this node causes the executor to fetch a row from the - table and return it up to the calling node. The Sort - node will repeatedly call its child to obtain all the rows to be sorted. - When the input is exhausted (as indicated by the child node returning - a NULL instead of a row), the Sort code performs - the sort, and finally is able to return its first output row, namely - the first one in sorted order. It keeps the remaining rows stored so - that it can deliver them in sorted order in response to later demands. - - - - The MergeJoin node similarly demands the first row - from its right subplan. Then it compares the two rows to see if they - can be joined; if so, it returns a join row to its caller. On the next - call, or immediately if it cannot join the current pair of inputs, - it advances to the next row of one table - or the other (depending on how the comparison came out), and again - checks for a match. Eventually, one subplan or the other is exhausted, - and the MergeJoin node returns NULL to indicate that - no more join rows can be formed. - - - - Complex queries can involve many levels of plan nodes, but the general - approach is the same: each node computes and returns its next output - row each time it is called. Each node is also responsible for applying - any selection or projection expressions that were assigned to it by - the planner. - - - - The executor mechanism is used to evaluate all four basic SQL query types: - SELECT, INSERT, UPDATE, and - DELETE. For SELECT, the top-level executor - code only needs to send each row returned by the query plan tree off - to the client. For INSERT, each returned row is inserted - into the target table specified for the INSERT. This is - done in a special top-level plan node called ModifyTable. - (A simple - INSERT ... VALUES command creates a trivial plan tree - consisting of a single Result node, which computes just one - result row, and ModifyTable above it to perform the insertion. - But INSERT ... SELECT can demand the full power - of the executor mechanism.) For UPDATE, the planner arranges - that each computed row includes all the updated column values, plus - the TID (tuple ID, or row ID) of the original target row; - this data is fed into a ModifyTable node, which uses the - information to create a new updated row and mark the old row deleted. - For DELETE, the only column that is actually returned by the - plan is the TID, and the ModifyTable node simply uses the TID - to visit each target row and mark it deleted. - - - - - - - - - - Overview of <productname>Postgres-XC</productname> Internals - -&xconly; - - This chapter gives an overview of the internal structure - of Postgres-XC. - - - - <productname>Postgres-XC</productname> Components -&xconly; - - As described - in , Postgres-XC - is a database cluster which consists of multiple database servers - based - upon PostgreSQL. Postgres-XC - provides global transparent transaction management to all the - database servers involved and provide both read and write - scalability. - - - - To achieve these features, Postgres-XC - is composed of three major components as follows: - - - - GTM - - - GTM stands for global transaction manager. It provides global - transaction ID and snapshot to each transaction - in Postgres-XC database cluster. - It also provide several global value such as sequence and - global timestamp. - - - To improve scalability itself, each server hardware or virtual - machine may have GTM-Proxy. GTM-Proxy groups commands and - response from/to GTM to reduce number of interaction and the - amount of data which GTM reads and writes. - - - - - Coordinator - - - Coordinator is an entry point - to Postgres-XC from applications. - You can configure more than one Coordinators in the - same Postgres-XC. With the help - of GTM, they provide transparent concurrency and integrity of - transactions globally. Application can choose any - Coordinator to connect with. Any Coordinator provides the - same view of the database. - - - - - Datanode - - - Datanode stores user data. As described - in - and , more than one Datanodes - can be configured. Each table can be replicated or - distributed among Datanodes. A table is distributed, you can - choose a column as the distribute key, whose value is used to - determine which Datanode each row should be stored. - - - - - - - - - GTM and Global Transaction Management -&xconly; - - Review of <productname>PostgreSQL</productname> Transaction Management Internals -&common; - - In PostgreSQL, each transaction is given unique ID called - transaction ID (or XID). XID is given in ascending order to - distinguish which transaction is older/newer. - - - More precisely, XID is 32bit integer. When XID reaches the max - value, it wraps around to the lowest value (3, as to the latest - definition). PostgreSQL has a means to handle this, as well as - Postgres-XC. For simplicity, it will not be described in this - document. - - - When a transaction tries to read a tuple, - - - This description is somewhat simplified for explanation. You - will find the precise rule in tqual.c file - in PostgreSQL's source code. - - - each tuple has a set of XIDs to indicate transactions which - created and deleted the tuple. So if the target tuple is created - by an active transaction, it is not committed or aborted and the - transaction should ignore such tuple. In such way (in practice, - this is done by versup module in PostgreSQL core), if we give - each transaction a unique transaction Id throughout the system - and maintain snapshot what transaction is active, not only in a - single server but transaction in all the servers, we can maintain - global consistent visibility of each tuple even when a server - accepts new statement from other transactions running on the - other server. - - - These information is stored in "xmin" and - "xmax" fields of each row of table. When - we INSERT rows, XID of - inserting transaction is recorded at xmin field. When we update - rows of tables (with UPDATE - or DELETE statement), PostgreSQL does not - simply overwrite the old rows. Instead, PostgreSQL - "marks" the old rows as - "deleted" by writing updating - transaction's XID to xmax field. In the case - of UPDATE (just - like INSERT), new rows are created whose xmin - field is "marked" - with XIDs of the creating transaction. - - - These "xmin" and "xmax" are - used to determine which row is visible to a transaction. To do - this, PostgreSQL needs a data to indicate what transactions are - running, which is called the "snapshot". - - - If the creating transaction is not running, visibility of each - row depends upon the fact if the creating transaction was - committed or aborted. Suppose a row of a table which was created - by some transaction and is not deleted yet. If the creating - transaction is running, such row is visible to the transaction - which created the row, but not visible to other transactions. If - the creating transaction is not running and was committed the row - is visible. If the transaction was aborted, this row is not - visible. - - - Therefore, PostgreSQL needs two kinds of information to determine - "which transaction is running" and "if an old transaction was - committed or aborted." - - - The former information is obtained as - "snapshot." PostgreSQL maintains the latter - information as "CLOG." - - - PostgreSQL uses all these information to determine which row is - visible to a given transaction. - - - - - Making Transaction Management Global -&xconly; - - In Postgres-XC, the following features of transaction management - and visibility checking were picked up: - - - - - Assigning XID globally to transactions (GXID, Global - Transaction ID). This can be done globally to identify each - Transactions in the system. - - - - - Providing snapshot. GTM collects all the transaction's status - (running, committed, aborted etc.) to provide snapshot globally - (global snapshot). Please note that global snapshot - includes GXID initiated by other - Coordinators or Datanodes. This is needed because some older - transaction may visit new server after a while. In this case, - if GXID of such a transaction is not - included in the snapshot, this transaction may be regarded as - "old enough" and uncommitted rows may be - read. If GXID of such transaction is - included in the snapshot from the beginning, such inconsistency - does not take place. - - - - - To do this, Postgres-XC introduced a dedicated component called - GTM (Global Transaction Manager). GTM runs on one of the servers - and provide unique and ordered transaction id to each transaction - running on Postgres-XC servers. Because this is globally unique - ID, we call this GXID (Global Transaction Id). - - - GTM receives GXID request from transactions - and provide GXID. It also keep track of all - the transactions when it started and finished to generate - snapshot used to control each tuple visibility. Because snapshot - here is also global property, it is called Global - Snapshot. - - - As long as each transaction runs with GXID and - Global Snapshot, it can maintain consistent visibility throughout - the system and it is safe to run transactions in parallel in any - servers. On the other hand, a transaction, composed of multiple - statements, can be executed using multiple servers maintaining - database consistency. - - - GTM provides Global Transaction Id to each transaction and keeps - track of the status of all the transactions, whether it is - running, committed or aborted, to calculate global snapshot to - maintain tuple visibility. - - - For this purpose, each transaction reports when it starts and - ends, as well as when it issues PREPARE - command in two-phase commit protocol. - - - Each transaction requests snapshot according to the transaction - isolation level as done in PostgreSQL. If the transaction - isolation level is "read committed", then - transaction will request a snapshot for each statement. If it is - "serializable" transaction will request a - snapshot at the beginning of transaction and reuse it thought the - transaction. - - - - - Improving GTM Performance -&xconly; - - Because GTM can be regarded as "serializing" all the transaction - processing, people may think that GTM can be a performance - bottleneck. - - - - In fact, GTM can limit the whole scalability. GTM should not be - used in very slow network environment such as wide area - network. GTM architecture is intended to be used with Gigabit - local network. We encourage to install Postgres-XC with local - Gigabit network with minimum latency, that is, use as fewer - switches involved in the connection among GTM, Coordinator and - Datanodes. - - - - Primitive GTM Implementation - - - Primitive GTM implementation can be done as follows: - - - - - - Coordinator backend is provided with GTM client library to - obtain GXID and snapshot and to report the transaction status. - - - - - - GTM opens a port to accept connection from each Coordinator and - Datanode backend. When GTM accepts a connection, it creates a - thread (GTM Thread) to handle request to GTM from the connected - Coordinator backend. - - - - - - GTM Thread receives each request, record it and - sends GXID, snapshot - and other response to the Coordinator backend. - - - - - - They are repeated until the Coordinator backend requests - disconnect. - - - - - - - - GTM Proxy Implementation - - - You may have been noticed that each transaction is issuing - request to GTM so frequently and we can collect them into single - block of requests in each Coordinator to reduce the amount of - interaction, as GTM-Proxy. - - - - In this configuration, each Coordinator and Datanode backend - does not connect to GTM directly. Instead, we have GTM Proxy - between GTM and Coordinator backend to group multiple requests - and responses. GTM Proxy, like GTM explained in the previous - sections, accepts connection from the Coordinator - backend. However, it does not create new thread. The following - paragraphs explains how GTM Proxy is initialized and how it - handles requests from Coordinator backends. - - - - GTM Proxy, as well as GTM, is initialized as follows: - - - - - - GTM starts up normally, but now can accept connections from - GTM proxies. - - - - - - GTM Proxy starts up. GTM Proxy creates GTM Proxy Threads. Each - GTM Proxy Threads connect to the GTM in advance. The number of - GTM Proxy Threads can be specified at the startup. Typical - number of threads is one or two so it can save the number of - connections between GTM and Coordinators. - - - - - - GTM Main Thread waits for the request connection from each - backend. - - - - - - - When each Coordinator backend requests for connection, Proxy - Main Thread assigns a GTM Proxy Thread to handle - request. Therefore, one GTM Proxy Thread handles multiple - Coordinator backends. If a Coordinator has one hundred - Coordinator backends and one GTM Proxy Thread, this thread takes - care of one hundred Coordinator backend. - - - - Then GTM Proxy Thread scans all the requests from Coordinator - backend. If Coordinator is more busy, it is expected to capture - more requests in a single scan. Therefore, the proxy can group - many requests into single block of requests, to reduce the - number of interaction between GTM and the Coordinator. - - - - Furthermore, in a single scan, we may have multiple request for - snapshots. Because these requests can be regarded as received at - the same time, we can represent multiple snapshots with single - one. This will reduce the amount of data which GTM provides. - - - - - - - Coordinator -&xconly; - - Coordinator handles SQL statements from applications and - determine which Datanode should be involved and generates local - SQL statements for each Datanode. In the most simplest case, if - single Datanode is involved, the Coordinator simply proxies - incoming statement to the Datanode. In more complicated case, - for example, if the target Datanode cannot be determined, then - the Coordinator generates local statements for each Datanode, - collects the result to materialize at the Coordinator for further - handling. In this case, the Coordinator will try to optimize the - plan by - - - - Pushdown WHERE clause to Datanodes, - - - - - Pushdown joins to Datanodes, - - - - - Pushdown projection (column list in SELECT clause), - - - - - Pushdown ORDER BY clause, as well as other clauses. - - - - - If a transaction is involved by more than one Datanodes and/or - Coordinators, the Coordinator will handle the transaction with - two-phase commit protocol internally. - - - - In the case of aggregate - functions, Postgres-XC introduced new - function collection function between existing transition function - and finalize function. Collection function runs on the - Coordinator to collect all the intermediate results from involved - Datanodes. For details, see - and . - - - - In the case of reading replicated tables, Coordinator can choose - any Datanode to read. The most efficient way is to select one - running in the same hardware or virtual machine. This is - called preferred Datanode and can be - specified by a GUC local to each Coordinator. - - - - On the other hand, in the case of writing replicated tables, all - the Coordinators choose the same Datanode to begin with to avoid - update conflicts. This is called primary - Datanode. - - - - Coordinators also take care of DDL statements. Because DDL - statements handles system catalogs, which are replicated in all - the Coordinators and Datanodes, they are proxied to all the - Coordinators and Datanodes. To synchronize the catalog update in - all the nodes, the Coordinator handles DDL with two-phase commit - protocol internally. - - - - - - Datanode -&xconly; - - While Coordinators handle cluster-wide SQL statements, Datanodes - take care of just local issues. In this sense, Datanodes are - essentially PostgreSQL servers except - that transaction management information is obtained from GTM, as - well as other global value. - - - - - - - Coordinator And Datanode Connection - - - The number of connection between Coordinator and Datanode may - increase from time to time. This may leave unused connection and - waste system resources. Repeating real connect and disconnect - requires Datanode backend initialization which increases latency - and also wastes system resources. - - - - For example, as in the case of GTM, if each Coordinator has one - hundred connections to applications and we have ten Coordinators, - after a while, each Coordinator may have connection to each data - node. It means that each Coordinator backend has ten connections - to Coordinators and each Coordinator has one thousand (10 x 10) - connections to Coordinators. - - - - Because we consume much more resources for locks and other - control information per backend and only a few of such connection - is active at a given time, it is not a good idea to hold such - unused connection between Coordinator and Datanode. - - - - To improve this, Postgres-XC is equipped with connection pooler - between Coordinator and Datanode. When a Coordinator backend - requires connection to a Datanode, the pooler looks for - appropriate connection from the pool. If there's an available - one, the pooler assigns it to the Coordinator backend. When the - connection is no longer needed, the Coordinator backend returns - the connection to the pooler. Pooler does not disconnect the - connection. It keeps the connection to the pool for later reuse, - keeping Datanode backend running. - - - - - - - - - - Overview of <productname>Postgres-XL</productname> Internals - -&xlonly; - - This chapter gives an overview of the internal structure - of Postgres-XL. - - - - <productname>Postgres-XL</productname> Components -&xlonly; - - As described - in , Postgres-XL - is a database cluster which consists of multiple database servers - based - upon PostgreSQL. Postgres-XL - provides global transparent transaction management to all the - database servers involved and provide both read and write - scalability. - - - - To achieve these features, Postgres-XL - is composed of three major components as follows: - - - - GTM - - - GTM stands for Global Transaction Manager. It provides global - transaction IDs and snapshots for each transaction - in the Postgres-XL database cluster. - It also provide several global values such as sequences and - global timestamps. - - - To improve scalability itself, each server hardware or virtual - machine may have GTM-Proxy. GTM-Proxy groups commands and - response from/to GTM to reduce number of interaction and the - amount of data which GTM reads and writes. - - - - - Coordinator - - - Coordinator is an entry point - for Postgres-XL from applications. - You can configure more than one Coordinators in the - same Postgres-XL. With the help - of GTM, they provide transparent concurrency and integrity of - transactions globally. Applications can choose any - Coordinator to connect to. Any Coordinator provides the - same view of the database. - - - - - Datanode - - - Datanode stores user data. As described - in - and , more than one Datanodes - can be configured. Each table can be replicated or - distributed among Datanodes. A table is distributed, you can - choose a column as the distribute key, whose value is used to - determine which Datanode each row should be stored. - - - - - - - - - GTM and Global Transaction Management -&xlonly; - - Review of <productname>PostgreSQL</productname> Transaction Management Internals -&common; - - In PostgreSQL, each transaction is given unique ID called - transaction ID (or XID). XID is given in ascending order to - distinguish which transaction is older/newer. - - - More precisely, XID is 32bit integer. When XID reaches the max - value, it wraps around to the lowest value (3, as to the latest - definition). PostgreSQL has a means to handle this, as well as - Postgres-XL. For simplicity, it will not be described in this - document. - - - When a transaction tries to read a tuple, - - - This description is somewhat simplified for explanation. You - will find the precise rule in tqual.c file - in PostgreSQL's source code. - - - each tuple has a set of XIDs to indicate transactions which - created and deleted the tuple. So if the target tuple is created - by an active transaction, it is not committed or aborted and the - transaction should ignore such tuple. In such way (in practice, - this is done by versup module in PostgreSQL core), if we give - each transaction a unique transaction Id throughout the system - and maintain snapshot what transaction is active, not only in a - single server but transaction in all the servers, we can maintain - global consistent visibility of each tuple even when a server - accepts new statement from other transactions running on the - other server. - - - These information is stored in "xmin" and - "xmax" fields of each row of table. When - we INSERT rows, XID of - inserting transaction is recorded at xmin field. When we update - rows of tables (with UPDATE - or DELETE statement), PostgreSQL does not - simply overwrite the old rows. Instead, PostgreSQL - "marks" the old rows as - "deleted" by writing updating - transaction's XID to xmax field. In the case - of UPDATE (just - like INSERT), new rows are created whose xmin - field is "marked" - with XIDs of the creating transaction. - - - These "xmin" and "xmax" are - used to determine which row is visible to a transaction. To do - this, PostgreSQL needs a data to indicate what transactions are - running, which is called the "snapshot". - - - If the creating transaction is not running, visibility of each - row depends upon the fact if the creating transaction was - committed or aborted. Suppose a row of a table which was created - by some transaction and is not deleted yet. If the creating - transaction is running, such row is visible to the transaction - which created the row, but not visible to other transactions. If - the creating transaction is not running and was committed the row - is visible. If the transaction was aborted, this row is not - visible. - - - Therefore, PostgreSQL needs two kinds of information to determine - "which transaction is running" and "if an old transaction was - committed or aborted." - - - The former information is obtained as - "snapshot." PostgreSQL maintains the latter - information as "CLOG." - - - PostgreSQL uses all these information to determine which row is - visible to a given transaction. - - - - - Making Transaction Management Global -&xlonly; - - In Postgres-XL, the following features of transaction management - and visibility checking extracted out from the nodes and pulled - into the GTM. - - - - - Assigning XID globally to transactions (GXID, Global - Transaction ID). This can be done globally to identify each - Transactions in the system. - - - - - Providing snapshots. GTM collects all the transaction's status - (running, committed, aborted etc.) to provide snapshots globally - (global snapshot). Please note that each global snapshot - includes GXID initiated by other - Coordinators or Datanodes. This is needed because some older - transaction may visit new server after a while. In this case, - if GXID of such a transaction is not - included in the snapshot, this transaction may be regarded as - "old enough" and uncommitted rows may be - read. If GXID of such transaction is - included in the snapshot from the beginning, such inconsistency - does not take place. - - - - - To do this, Postgres-XL introduced a dedicated component called - GTM (Global Transaction Manager). GTM runs on one of the servers - and provides unique and ordered transaction id to each transaction - running on Postgres-XL servers. Because this is a globally unique - ID, we call this GXID (Global Transaction Id). - - - GTM receives GXID request from transactions - and provide GXID. It also keeps track of all - the transactions when it started and finished to generate - snapshots used to control each tuple visibility. Because snapshots - here is also a global property, it is called Global - Snapshot. - - - As long as each transaction runs with a GXID and - a Global Snapshot, it can maintain consistent visibility throughout - the system and it is safe to run transactions in parallel in any - servers. On the other hand, a transaction, composed of multiple - statements, can be executed using multiple servers maintaining - database consistency. - - - GTM provides Global Transaction Id to each transaction and keeps - track of the status of all the transactions, whether it is - running, committed or aborted, to calculate global snapshots to - maintain tuple visibility. - - - For this purpose, each transaction reports when it starts and - ends, as well as when it issues PREPARE - command in two-phase commit protocol. - - - Each transaction requests snapshots according to the transaction - isolation level as done in PostgreSQL. If the transaction - isolation level is "read committed", then - transaction will request a snapshot for each statement. If it is - "serializable" transaction will request a - snapshot at the beginning of transaction and reuse it thought the - transaction. - - - - - Improving GTM Performance -&xlonly; - - Because GTM can be regarded as "serializing" all the transaction - processing, people may think that GTM can be a performance - bottleneck. - - - - In fact, GTM can limit the whole scalability. GTM should not be - used in very slow network environment such as wide area - network. GTM architecture is intended to be used with Gigabit - local network. It is encouraged to install Postgres-XL with a local - Gigabit network with minimum latency, that is, use as few - switches involved in the connection among GTM, Coordinator and - Datanodes. - In addition, consider putting all components on their own subnet - if you have multiple network ports in the systems. - - - - Primitive GTM Implementation - - - Primitive GTM implementation can be done as follows: - - - - - - The Coordinator backend is provided with a GTM client library to - obtain GXID and snapshots and to report the transaction status. - - - - - - GTM opens a port to accept connections from each Coordinator and - Datanode backend. When GTM accepts a connection, it creates a - thread (GTM Thread) to handle requests to GTM from the connected - Coordinator backend. - - - - - - GTM Thread receives each request, records it and - sends GXID, snapshot - and other response to the Coordinator backend. - - - - - - They are repeated until the Coordinator backend requests - disconnect. - - - - - - - - GTM Proxy Implementation - - - Each transaction is issuing - requests to GTM frequently. We can collect them into single - block of requests in each Coordinator to reduce the amount of - interaction by using a GTM-Proxy. - - - - In this configuration, each Coordinator and Datanode backend - does not connect to GTM directly. Instead, we have GTM Proxy - between GTM and Coordinator backend to group multiple requests - and responses. GTM Proxy, like GTM explained in the previous - sections, accepts connections from the Coordinator - backend. However, it does not create new thread. The following - paragraphs explains how GTM Proxy is initialized and how it - handles requests from Coordinator backends. - - - - GTM Proxy, as well as GTM, is initialized as follows: - - - - - - GTM starts up normally, but now can accept connections from - GTM proxies. - - - - - - GTM Proxy starts up. GTM Proxy creates GTM Proxy Threads. Each - GTM Proxy Thread connects to the GTM in advance. The number of - GTM Proxy Threads can be specified at the startup. A typical - number of threads is one or two so it can save the number of - connections between GTM and Coordinators. - - - - - - GTM Main Thread waits for the request connection from each - backend. - - - - - - - When each Coordinator backend requests for connection, the Proxy - Main Thread assigns a GTM Proxy Thread to handle - request. Therefore, one GTM Proxy Thread handles multiple - Coordinator backends. If a Coordinator has one hundred - Coordinator backends and one GTM Proxy Thread, this thread takes - care of one hundred Coordinator backend. - - - - Then GTM Proxy Thread scans all the requests from Coordinator - backend. If Coordinator is busy, it is expected to capture - more requests in a single scan. Therefore, the proxy can group - many requests into single block of requests, to reduce the - number of interaction between GTM and the Coordinator. - - - - Furthermore, in a single scan, we may have multiple request for - snapshots. Because these requests can be regarded as received at - the same time, we can represent multiple snapshots with single - one. This will reduce the amount of data which GTM provides. - - - - - - - Coordinator -&xlonly; - - Coordinator handles SQL statements from applications and - determines which Datanode should be involved and generates local - SQL statements for each Datanode. In the most simplest case, if - a single Datanode is involved, the Coordinator simply proxies - incoming statements to the Datanode. In more complicated cases, - for example, if the target Datanode cannot be determined, then - the Coordinator generates local statements for each Datanode, - collects the result to materialize at the Coordinator for further - handling. In this case, the Coordinator will try to optimize the - plan by - - - - Pushdown WHERE clause to Datanodes, - - - - - Pushdown joins to Datanodes, - - - - - Pushdown projection (column list in SELECT clause), - - - - - Pushdown ORDER BY clause, as well as other clauses. - - - - - If a transaction is involved by more than one Datanodes and/or - Coordinators, the Coordinator will handle the transaction with - two-phase commit protocol internally. - - - - In the case of aggregate - functions, Postgres-XL introduced new - function collection function between existing transition function - and finalize function. Collection function runs on the - Coordinator to collect all the intermediate results from involved - Datanodes. For details, see - and . - - - - In the case of reading replicated tables, the Coordinator can choose - any Datanode to read. The most efficient way is to select one - running in the same hardware or virtual machine. This is - called preferred Datanode and can be - specified by a GUC local to each Coordinator. - - - - On the other hand, in the case of writing replicated tables, all - the Coordinators choose the same Datanode to begin with to avoid - update conflicts. This is called primary - Datanode. - - - - Coordinators also take care of DDL statements. Because DDL - statements handles system catalogs, which are replicated in all - the Coordinators and Datanodes, they are proxied to all the - Coordinators and Datanodes. To synchronize the catalog update in - all the nodes, the Coordinator handles DDL with two-phase commit - protocol internally. - - - - - - Datanode -&xlonly; - - While Coordinators handle cluster-wide SQL statements, Datanodes - take care of just local issues. In this sense, Datanodes are - essentially PostgreSQL servers except - that transaction management information is obtained from GTM, as - well as other global value. - - - - - - - Coordinator And Datanode Connection - - - The number of connections between Coordinators and Datanodes may - increase from time to time. This may leave unused connection and - waste system resources. Repeating real connect and disconnect - requires Datanode backend initialization which increases latency - and also wastes system resources. - - - - For example, as in the case of GTM, if each Coordinator has one - hundred connections to applications and we have ten Coordinators, - after a while, each Coordinator may have connection to each data - node. It means that each Coordinator backend has ten connections - to Coordinators and each Coordinator has one thousand (10 x 10) - connections to Coordinators. - - - - Because we consume much more resources for locks and other - control information per backend and only a few of such connection - is active at a given time, it is not a good idea to hold such - unused connections between Coordinator and Datanode. - - - - To improve this, Postgres-XL is equipped with connection pooler - between Coordinator and Datanode. When a Coordinator backend - requires connection to a Datanode, the pooler looks for - appropriate connection from the pool. If there's an available - one, the pooler assigns it to the Coordinator backend. When the - connection is no longer needed, the Coordinator backend returns - the connection to the pooler. The pooler does not disconnect the - connection. It keeps the connection to the pool for later reuse, - keeping Datanode backend running. - - - - - - - - diff --git a/doc-xc/src/sgml/array.sgmlin b/doc-xc/src/sgml/array.sgmlin deleted file mode 100644 index 2e7220426e..0000000000 --- a/doc-xc/src/sgml/array.sgmlin +++ /dev/null @@ -1,749 +0,0 @@ - - - - Arrays - - - array - -&common; - - - PostgreSQL allows columns of a table to be - - - Postgres-XC allows columns of a table to be - - - Postgres-XL allows columns of a table to be - - defined as variable-length multidimensional arrays. Arrays of any - built-in or user-defined base type, enum type, or composite type - can be created. - Arrays of domains are not yet supported. - - - - Declaration of Array Types - - - array - declaration - -&common; - - To illustrate the use of array types, we create this table: - -CREATE TABLE sal_emp ( - name text, - pay_by_quarter integer[], - schedule text[][] -); - - As shown, an array data type is named by appending square brackets - ([]) to the data type name of the array elements. The - above command will create a table named - sal_emp with a column of type - text (name), a - one-dimensional array of type integer - (pay_by_quarter), which represents the - employee's salary by quarter, and a two-dimensional array of - text (schedule), which - represents the employee's weekly schedule. - - - - The syntax for CREATE TABLE allows the exact size of - arrays to be specified, for example: - - -CREATE TABLE tictactoe ( - squares integer[3][3] -); - - - However, the current implementation ignores any supplied array size - limits, i.e., the behavior is the same as for arrays of unspecified - length. - - - - The current implementation does not enforce the declared - number of dimensions either. Arrays of a particular element type are - all considered to be of the same type, regardless of size or number - of dimensions. So, declaring the array size or number of dimensions in - CREATE TABLE is simply documentation; it does not - affect run-time behavior. - - - - An alternative syntax, which conforms to the SQL standard by using - the keyword ARRAY, can be used for one-dimensional arrays. - pay_by_quarter could have been defined - as: - - pay_by_quarter integer ARRAY[4], - - Or, if no array size is to be specified: - - pay_by_quarter integer ARRAY, - - - As before, however, PostgreSQL does not enforce the - - - As before, however, Postgres-XC does not enforce the - - - As before, however, Postgres-XL does not enforce the - - size restriction in any case. - - - - - Array Value Input - - - array - constant - -&common; - - To write an array value as a literal constant, enclose the element - values within curly braces and separate them by commas. (If you - know C, this is not unlike the C syntax for initializing - structures.) You can put double quotes around any element value, - and must do so if it contains commas or curly braces. (More - details appear below.) Thus, the general format of an array - constant is the following: - -'{ val1 delim val2 delim ... }' - - where delim is the delimiter character - for the type, as recorded in its pg_type entry. - Among the standard data types provided in the - - PostgreSQL distribution, all use a comma - - - Postgres-XC distribution, all use a comma - - - Postgres-XL distribution, all use a comma - - (,), except for type box which uses a semicolon - (;). Each val is - either a constant of the array element type, or a subarray. An example - of an array constant is: - -'{{1,2,3},{4,5,6},{7,8,9}}' - - This constant is a two-dimensional, 3-by-3 array consisting of - three subarrays of integers. - - - - To set an element of an array constant to NULL, write NULL - for the element value. (Any upper- or lower-case variant of - NULL will do.) If you want an actual string value - NULL, you must put double quotes around it. - - - - (These kinds of array constants are actually only a special case of - the generic type constants discussed in . The constant is initially - treated as a string and passed to the array input conversion - routine. An explicit type specification might be necessary.) - - - - Now we can show some INSERT statements: - - -INSERT INTO sal_emp - VALUES ('Bill', - '{10000, 10000, 10000, 10000}', - '{{"meeting", "lunch"}, {"training", "presentation"}}'); - -INSERT INTO sal_emp - VALUES ('Carol', - '{20000, 25000, 25000, 25000}', - '{{"breakfast", "consulting"}, {"meeting", "lunch"}}'); - - - - - The result of the previous two inserts looks like this: - - -SELECT * FROM sal_emp; - name | pay_by_quarter | schedule --------+---------------------------+------------------------------------------- - Bill | {10000,10000,10000,10000} | {{meeting,lunch},{training,presentation}} - Carol | {20000,25000,25000,25000} | {{breakfast,consulting},{meeting,lunch}} -(2 rows) - - - - - Multidimensional arrays must have matching extents for each - dimension. A mismatch causes an error, for example: - - -INSERT INTO sal_emp - VALUES ('Bill', - '{10000, 10000, 10000, 10000}', - '{{"meeting", "lunch"}, {"meeting"}}'); -ERROR: multidimensional arrays must have array expressions with matching dimensions - - - - - The ARRAY constructor syntax can also be used: - -INSERT INTO sal_emp - VALUES ('Bill', - ARRAY[10000, 10000, 10000, 10000], - ARRAY[['meeting', 'lunch'], ['training', 'presentation']]); - -INSERT INTO sal_emp - VALUES ('Carol', - ARRAY[20000, 25000, 25000, 25000], - ARRAY[['breakfast', 'consulting'], ['meeting', 'lunch']]); - - Notice that the array elements are ordinary SQL constants or - expressions; for instance, string literals are single quoted, instead of - double quoted as they would be in an array literal. The ARRAY - constructor syntax is discussed in more detail in - . - - - - - Accessing Arrays - - - array - accessing - -&common; - - Now, we can run some queries on the table. - First, we show how to access a single element of an array. - This query retrieves the names of the employees whose pay changed in - the second quarter: - - -SELECT name FROM sal_emp WHERE pay_by_quarter[1] <> pay_by_quarter[2]; - - name -------- - Carol -(1 row) - - - The array subscript numbers are written within square brackets. - - By default PostgreSQL uses a - - - By default Postgres-XC uses a - - - By default Postgres-XL uses a - - one-based numbering convention for arrays, that is, - an array of n elements starts with array[1] and - ends with array[n]. - - - - This query retrieves the third quarter pay of all employees: - - -SELECT pay_by_quarter[3] FROM sal_emp; - - pay_by_quarter ----------------- - 10000 - 25000 -(2 rows) - - - - - We can also access arbitrary rectangular slices of an array, or - subarrays. An array slice is denoted by writing - lower-bound:upper-bound - for one or more array dimensions. For example, this query retrieves the first - item on Bill's schedule for the first two days of the week: - - -SELECT schedule[1:2][1:1] FROM sal_emp WHERE name = 'Bill'; - - schedule ------------------------- - {{meeting},{training}} -(1 row) - - - If any dimension is written as a slice, i.e., contains a colon, then all - dimensions are treated as slices. Any dimension that has only a single - number (no colon) is treated as being from 1 - to the number specified. For example, [2] is treated as - [1:2], as in this example: - - -SELECT schedule[1:2][2] FROM sal_emp WHERE name = 'Bill'; - - schedule -------------------------------------------- - {{meeting,lunch},{training,presentation}} -(1 row) - - - To avoid confusion with the non-slice case, it's best to use slice syntax - for all dimensions, e.g., [1:2][1:1], not [2][1:1]. - - - - An array subscript expression will return null if either the array itself or - any of the subscript expressions are null. Also, null is returned if a - subscript is outside the array bounds (this case does not raise an error). - For example, if schedule - currently has the dimensions [1:3][1:2] then referencing - schedule[3][3] yields NULL. Similarly, an array reference - with the wrong number of subscripts yields a null rather than an error. - - - - An array slice expression likewise yields null if the array itself or - any of the subscript expressions are null. However, in other - cases such as selecting an array slice that - is completely outside the current array bounds, a slice expression - yields an empty (zero-dimensional) array instead of null. (This - does not match non-slice behavior and is done for historical reasons.) - If the requested slice partially overlaps the array bounds, then it - is silently reduced to just the overlapping region instead of - returning null. - - - - The current dimensions of any array value can be retrieved with the - array_dims function: - - -SELECT array_dims(schedule) FROM sal_emp WHERE name = 'Carol'; - - array_dims ------------- - [1:2][1:2] -(1 row) - - - array_dims produces a text result, - which is convenient for people to read but perhaps inconvenient - for programs. Dimensions can also be retrieved with - array_upper and array_lower, - which return the upper and lower bound of a - specified array dimension, respectively: - - -SELECT array_upper(schedule, 1) FROM sal_emp WHERE name = 'Carol'; - - array_upper -------------- - 2 -(1 row) - - - array_length will return the length of a specified - array dimension: - - -SELECT array_length(schedule, 1) FROM sal_emp WHERE name = 'Carol'; - - array_length --------------- - 2 -(1 row) - - - - - - Modifying Arrays - - - array - modifying - -&common; - - An array value can be replaced completely: - - -UPDATE sal_emp SET pay_by_quarter = '{25000,25000,27000,27000}' - WHERE name = 'Carol'; - - - or using the ARRAY expression syntax: - - -UPDATE sal_emp SET pay_by_quarter = ARRAY[25000,25000,27000,27000] - WHERE name = 'Carol'; - - - An array can also be updated at a single element: - - -UPDATE sal_emp SET pay_by_quarter[4] = 15000 - WHERE name = 'Bill'; - - - or updated in a slice: - - -UPDATE sal_emp SET pay_by_quarter[1:2] = '{27000,27000}' - WHERE name = 'Carol'; - - - - - - A stored array value can be enlarged by assigning to elements not already - present. Any positions between those previously present and the newly - assigned elements will be filled with nulls. For example, if array - myarray currently has 4 elements, it will have six - elements after an update that assigns to myarray[6]; - myarray[5] will contain null. - Currently, enlargement in this fashion is only allowed for one-dimensional - arrays, not multidimensional arrays. - - - - Subscripted assignment allows creation of arrays that do not use one-based - subscripts. For example one might assign to myarray[-2:7] to - create an array with subscript values from -2 to 7. - - - - New array values can also be constructed using the concatenation operator, - ||: - -SELECT ARRAY[1,2] || ARRAY[3,4]; - ?column? ------------ - {1,2,3,4} -(1 row) - -SELECT ARRAY[5,6] || ARRAY[[1,2],[3,4]]; - ?column? ---------------------- - {{5,6},{1,2},{3,4}} -(1 row) - - - - - The concatenation operator allows a single element to be pushed onto the - beginning or end of a one-dimensional array. It also accepts two - N-dimensional arrays, or an N-dimensional - and an N+1-dimensional array. - - - - When a single element is pushed onto either the beginning or end of a - one-dimensional array, the result is an array with the same lower bound - subscript as the array operand. For example: - -SELECT array_dims(1 || '[0:1]={2,3}'::int[]); - array_dims ------------- - [0:2] -(1 row) - -SELECT array_dims(ARRAY[1,2] || 3); - array_dims ------------- - [1:3] -(1 row) - - - - - When two arrays with an equal number of dimensions are concatenated, the - result retains the lower bound subscript of the left-hand operand's outer - dimension. The result is an array comprising every element of the left-hand - operand followed by every element of the right-hand operand. For example: - -SELECT array_dims(ARRAY[1,2] || ARRAY[3,4,5]); - array_dims ------------- - [1:5] -(1 row) - -SELECT array_dims(ARRAY[[1,2],[3,4]] || ARRAY[[5,6],[7,8],[9,0]]); - array_dims ------------- - [1:5][1:2] -(1 row) - - - - - When an N-dimensional array is pushed onto the beginning - or end of an N+1-dimensional array, the result is - analogous to the element-array case above. Each N-dimensional - sub-array is essentially an element of the N+1-dimensional - array's outer dimension. For example: - -SELECT array_dims(ARRAY[1,2] || ARRAY[[3,4],[5,6]]); - array_dims ------------- - [1:3][1:2] -(1 row) - - - - - An array can also be constructed by using the functions - array_prepend, array_append, - or array_cat. The first two only support one-dimensional - arrays, but array_cat supports multidimensional arrays. - - Note that the concatenation operator discussed above is preferred over - direct use of these functions. In fact, these functions primarily exist for use - in implementing the concatenation operator. However, they might be directly - useful in the creation of user-defined aggregates. Some examples: - - -SELECT array_prepend(1, ARRAY[2,3]); - array_prepend ---------------- - {1,2,3} -(1 row) - -SELECT array_append(ARRAY[1,2], 3); - array_append --------------- - {1,2,3} -(1 row) - -SELECT array_cat(ARRAY[1,2], ARRAY[3,4]); - array_cat ------------ - {1,2,3,4} -(1 row) - -SELECT array_cat(ARRAY[[1,2],[3,4]], ARRAY[5,6]); - array_cat ---------------------- - {{1,2},{3,4},{5,6}} -(1 row) - -SELECT array_cat(ARRAY[5,6], ARRAY[[1,2],[3,4]]); - array_cat ---------------------- - {{5,6},{1,2},{3,4}} - - - - - - Searching in Arrays - - - array - searching - -&common; - - To search for a value in an array, each value must be checked. - This can be done manually, if you know the size of the array. - For example: - - -SELECT * FROM sal_emp WHERE pay_by_quarter[1] = 10000 OR - pay_by_quarter[2] = 10000 OR - pay_by_quarter[3] = 10000 OR - pay_by_quarter[4] = 10000; - - - However, this quickly becomes tedious for large arrays, and is not - helpful if the size of the array is unknown. An alternative method is - described in . The above - query could be replaced by: - - -SELECT * FROM sal_emp WHERE 10000 = ANY (pay_by_quarter); - - - In addition, you can find rows where the array has all values - equal to 10000 with: - - -SELECT * FROM sal_emp WHERE 10000 = ALL (pay_by_quarter); - - - - - - Alternatively, the generate_subscripts function can be used. - For example: - - -SELECT * FROM - (SELECT pay_by_quarter, - generate_subscripts(pay_by_quarter, 1) AS s - FROM sal_emp) AS foo - WHERE pay_by_quarter[s] = 10000; - - - This function is described in . - - - - - Arrays are not sets; searching for specific array elements - can be a sign of database misdesign. Consider - using a separate table with a row for each item that would be an - array element. This will be easier to search, and is likely to - scale better for a large number of elements. - - - - - - Array Input and Output Syntax - - - array - I/O - -&common; - - The external text representation of an array value consists of items that - are interpreted according to the I/O conversion rules for the array's - element type, plus decoration that indicates the array structure. - The decoration consists of curly braces ({ and }) - around the array value plus delimiter characters between adjacent items. - The delimiter character is usually a comma (,) but can be - something else: it is determined by the typdelim setting - for the array's element type. Among the standard data types provided - - in the PostgreSQL distribution, all use a comma, - - - in the Postgres-XC distribution, all use a comma, - - - in the Postgres-XL distribution, all use a comma, - - except for type box, which uses a semicolon (;). - In a multidimensional array, each dimension (row, plane, - cube, etc.) gets its own level of curly braces, and delimiters - must be written between adjacent curly-braced entities of the same level. - - - - The array output routine will put double quotes around element values - if they are empty strings, contain curly braces, delimiter characters, - double quotes, backslashes, or white space, or match the word - NULL. Double quotes and backslashes - embedded in element values will be backslash-escaped. For numeric - data types it is safe to assume that double quotes will never appear, but - for textual data types one should be prepared to cope with either the presence - or absence of quotes. - - - - By default, the lower bound index value of an array's dimensions is - set to one. To represent arrays with other lower bounds, the array - subscript ranges can be specified explicitly before writing the - array contents. - This decoration consists of square brackets ([]) - around each array dimension's lower and upper bounds, with - a colon (:) delimiter character in between. The - array dimension decoration is followed by an equal sign (=). - For example: - -SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2 - FROM (SELECT '[1:1][-2:-1][3:5]={{{1,2,3},{4,5,6}}}'::int[] AS f1) AS ss; - - e1 | e2 -----+---- - 1 | 6 -(1 row) - - The array output routine will include explicit dimensions in its result - only when there are one or more lower bounds different from one. - - - - If the value written for an element is NULL (in any case - variant), the element is taken to be NULL. The presence of any quotes - or backslashes disables this and allows the literal string value - NULL to be entered. Also, for backward compatibility with - pre-8.2 versions of PostgreSQL, the configuration parameter can be turned - off to suppress recognition of NULL as a NULL. - - - - As shown previously, when writing an array value you can use double - quotes around any individual array element. You must do so - if the element value would otherwise confuse the array-value parser. - For example, elements containing curly braces, commas (or the data type's - delimiter character), double quotes, backslashes, or leading or trailing - whitespace must be double-quoted. Empty strings and strings matching the - word NULL must be quoted, too. To put a double quote or - backslash in a quoted array element value, use escape string syntax - and precede it with a backslash. Alternatively, you can avoid quotes and use - backslash-escaping to protect all data characters that would otherwise - be taken as array syntax. - - - - You can add whitespace before a left brace or after a right - brace. You can also add whitespace before or after any individual item - string. In all of these cases the whitespace will be ignored. However, - whitespace within double-quoted elements, or surrounded on both sides by - non-whitespace characters of an element, is not ignored. - - - - - Remember that what you write in an SQL command will first be interpreted - as a string literal, and then as an array. This doubles the number of - backslashes you need. For example, to insert a text array - value containing a backslash and a double quote, you'd need to write: - -INSERT ... VALUES (E'{"\\\\","\\""}'); - - The escape string processor removes one level of backslashes, so that - what arrives at the array-value parser looks like {"\\","\""}. - In turn, the strings fed to the text data type's input routine - become \ and " respectively. (If we were working - with a data type whose input routine also treated backslashes specially, - bytea for example, we might need as many as eight backslashes - in the command to get one backslash into the stored array element.) - Dollar quoting (see ) can be - used to avoid the need to double backslashes. - - - - - - The ARRAY constructor syntax (see - ) is often easier to work - with than the array-literal syntax when writing array values in SQL - commands. In ARRAY, individual element values are written the - same way they would be written when not members of an array. - - - - - diff --git a/doc-xc/src/sgml/auth-delay.sgmlin b/doc-xc/src/sgml/auth-delay.sgmlin deleted file mode 100644 index b91a7ecda7..0000000000 --- a/doc-xc/src/sgml/auth-delay.sgmlin +++ /dev/null @@ -1,67 +0,0 @@ - - - - auth_delay - - - auth_delay - - - - auth_delay causes the server to pause briefly before - reporting authentication failure, to make brute-force attacks on database - passwords more difficult. Note that it does nothing to prevent - denial-of-service attacks, and may even exacerbate them, since processes - that are waiting before reporting authentication failure will still consume - connection slots. - - - - In order to function, this module must be loaded via - in postgresql.conf. - - - - Configuration Parameters - - - - - auth_delay.milliseconds (int) - - - auth_delay.milliseconds configuration parameter - - - - The number of milliseconds to wait before reporting an authentication - failure. The default is 0. - - - - - - - In order to set these parameters in your postgresql.conf file, - you will need to add auth_delay to - . Typical usage might be: - - - -# postgresql.conf -shared_preload_libraries = 'auth_delay' - -custom_variable_classes = 'auth_delay' -auth_delay.milliseconds = '500' - - - - - Author - - - KaiGai Kohei kaigai@ak.jp.nec.com - - - - diff --git a/doc-xc/src/sgml/auto-explain.sgmlin b/doc-xc/src/sgml/auto-explain.sgmlin deleted file mode 100644 index 0188053118..0000000000 --- a/doc-xc/src/sgml/auto-explain.sgmlin +++ /dev/null @@ -1,239 +0,0 @@ - - - - auto_explain - - - auto_explain - - -&common; - - - The auto_explain module provides a means for - logging execution plans of slow statements automatically, without - having to run - by hand. This is especially helpful for tracking down un-optimized queries - in large applications. - - - - The module provides no SQL-accessible functions. To use it, simply - load it into the server. You can load it into an individual session: - - -LOAD 'auto_explain'; - - - (You must be superuser to do that.) More typical usage is to preload - it into all sessions by including auto_explain in - in - postgresql.conf. Then you can track unexpectedly slow queries - no matter when they happen. Of course there is a price in overhead for - that. - - - -&xconly; - - To log plans on Datanodes, you must preload this module in each - Datanode. This module will log local plans of each node. For - example, Coordinator log will include the plan for Coordinator only. - Corresponding plan in Datanodes will be found in each Datanode's - log. - - - - - To log plans on Datanodes, you must preload this module in each - Datanode. This module will log local plans of each node. For - example, a Coordinator log will include the plan for Coordinator only. - the Corresponding plan in Datanodes will be found in each Datanode's - log. - - - - - - Configuration Parameters - -&common; - - There are several configuration parameters that control the behavior of - auto_explain. Note that the default behavior is - to do nothing, so you must set at least - auto_explain.log_min_duration if you want any results. - - - - - - auto_explain.log_min_duration (integer) - - - auto_explain.log_min_duration configuration parameter - - - - auto_explain.log_min_duration is the minimum statement - execution time, in milliseconds, that will cause the statement's plan to - be logged. Setting this to zero logs all plans. Minus-one (the default) - disables logging of plans. For example, if you set it to - 250ms then all statements that run 250ms or longer - will be logged. Only superusers can change this setting. - - - - - - - auto_explain.log_analyze (boolean) - - - auto_explain.log_analyze configuration parameter - - - - auto_explain.log_analyze causes EXPLAIN ANALYZE - output, rather than just EXPLAIN output, to be printed - when an execution plan is logged. This parameter is off by default. - Only superusers can change this setting. - - - - When this parameter is on, per-plan-node timing occurs for all - statements executed, whether or not they run long enough to actually - get logged. This can have extremely negative impact on performance. - - - - - - - - auto_explain.log_verbose (boolean) - - - auto_explain.log_verbose configuration parameter - - - - auto_explain.log_verbose causes EXPLAIN VERBOSE - output, rather than just EXPLAIN output, to be printed - when an execution plan is logged. This parameter is off by default. - Only superusers can change this setting. - - - - - - - auto_explain.log_buffers (boolean) - - - auto_explain.log_buffers configuration parameter - - - - auto_explain.log_buffers causes EXPLAIN - (ANALYZE, BUFFERS) output, rather than just EXPLAIN - output, to be printed when an execution plan is logged. This parameter is - off by default. Only superusers can change this setting. This - parameter has no effect unless auto_explain.log_analyze - parameter is set. - - - - - - - auto_explain.log_format (enum) - - - auto_explain.log_format configuration parameter - - - - auto_explain.log_format selects the - EXPLAIN output format to be used. - The allowed values are text, xml, - json, and yaml. The default is text. - Only superusers can change this setting. - - - - - - - auto_explain.log_nested_statements (boolean) - - - auto_explain.log_nested_statements configuration parameter - - - - auto_explain.log_nested_statements causes nested - statements (statements executed inside a function) to be considered - for logging. When it is off, only top-level query plans are logged. This - parameter is off by default. Only superusers can change this setting. - - - - - - - In order to set these parameters in your postgresql.conf file, - you will need to add auto_explain to - . Typical usage might be: - - - -# postgresql.conf -shared_preload_libraries = 'auto_explain' - -custom_variable_classes = 'auto_explain' -auto_explain.log_min_duration = '3s' - - - - - Example - - -postgres=# LOAD 'auto_explain'; -postgres=# SET auto_explain.log_min_duration = 0; -postgres=# SELECT count(*) - FROM pg_class, pg_index - WHERE oid = indrelid AND indisunique; - - -&common; - - This might produce log output such as: - - - Hash Join (cost=4.17..16.55 rows=92 width=0) (actual time=3.349..3.594 rows=92 loops=1) - Hash Cond: (pg_class.oid = pg_index.indrelid) - -> Seq Scan on pg_class (cost=0.00..9.55 rows=255 width=4) (actual time=0.016..0.140 rows=255 loops=1) - -> Hash (cost=3.02..3.02 rows=92 width=4) (actual time=3.238..3.238 rows=92 loops=1) - Buckets: 1024 Batches: 1 Memory Usage: 4kB - -> Seq Scan on pg_index (cost=0.00..3.02 rows=92 width=4) (actual time=0.008..3.187 rows=92 loops=1) - Filter: indisunique -]]> - - - - Author - - - Takahiro Itagaki itagaki.takahiro@oss.ntt.co.jp - - - - diff --git a/doc-xc/src/sgml/backup.sgmlin b/doc-xc/src/sgml/backup.sgmlin deleted file mode 100644 index 30950986ee..0000000000 --- a/doc-xc/src/sgml/backup.sgmlin +++ /dev/null @@ -1,1487 +0,0 @@ - - - - Backup and Restore - - backup - -&common; - - As with everything that contains valuable data, PostgreSQL - databases should be backed up regularly. While the procedure is - essentially simple, it is important to have a clear understanding of - the underlying techniques and assumptions. - - - - There are three fundamentally different approaches to backing up - PostgreSQL data: - - SQL dump - File system level backup - Continuous archiving - - Each has its own strengths and weaknesses; each is discussed in turn - in the following sections. - - - - <acronym>SQL</> Dump - -&common; - - The idea behind this dump method is to generate a text file with SQL - commands that, when fed back to the server, will recreate the - database in the same state as it was at the time of the dump. - PostgreSQL provides the utility program - for this purpose. The basic usage of this - command is: - -pg_dump dbname > outfile - - As you see, pg_dump writes its result to the - standard output. We will see below how this can be useful. - - - - pg_dump is a regular PostgreSQL - client application (albeit a particularly clever one). This means - that you can perform this backup procedure from any remote host that has - access to the database. But remember that pg_dump - does not operate with special permissions. In particular, it must - have read access to all tables that you want to back up, so in - practice you almost always have to run it as a database superuser. - - - - To specify which database server pg_dump should - contact, use the command line options - - - Like any other PostgreSQL client application, - pg_dump will by default connect with the database - user name that is equal to the current operating system user name. To override - this, either specify the option or set the - environment variable PGUSER. Remember that - pg_dump connections are subject to the normal - client authentication mechanisms (which are described in ). - - - - An important advantage of pg_dump over the other backup - methods described later is that pg_dump's output can - generally be re-loaded into newer versions of PostgreSQL, - whereas file-level backups and continuous archiving are both extremely - server-version-specific. pg_dump is also the only method - that will work when transferring a database to a different machine - architecture, such as going from a 32-bit to a 64-bit server. - - - - Dumps created by pg_dump are internally consistent, - meaning, the dump represents a snapshot of the database at the time - pg_dump began running. pg_dump does not - block other operations on the database while it is working. - (Exceptions are those operations that need to operate with an - exclusive lock, such as most forms of ALTER TABLE.) - - - - - If your database schema relies on OIDs (for instance, as foreign - keys) you must instruct pg_dump to dump the OIDs - as well. To do this, use the command-line - option. - - - - -&xconly; - - - In Postgres-XC, pg_dump - and pg_dumpall backs up all the information stored - both in Coordinators and Datanodes. - - - - -&xlonly; - - - In Postgres-XL, pg_dump - and pg_dumpall backs up all the information stored - both in Coordinators and Datanodes. - That is, it dumps the entire database just like in regular PostgreSQL - and outputs similarly. The output will contain additional table - distribution information. - - - - - - - Restoring the Dump - -&common; - - The text files created by pg_dump are intended to - be read in by the psql program. The - general command form to restore a dump is - -psql dbname < infile - - where infile is the - file output by the pg_dump command. The database dbname will not be created by this - command, so you must create it yourself from template0 - before executing psql (e.g., with - createdb -T template0 dbname). psql - supports options similar to pg_dump for specifying - the database server to connect to and the user name to use. See - the reference page for more information. - - - - Before restoring an SQL dump, all the users who own objects or were - granted permissions on objects in the dumped database must already - exist. If they do not, the restore will fail to recreate the - objects with the original ownership and/or permissions. - (Sometimes this is what you want, but usually it is not.) - - - - By default, the psql script will continue to - execute after an SQL error is encountered. You might wish to run - psql with - the ON_ERROR_STOP variable set to alter that - behavior and have psql exit with an - exit status of 3 if an SQL error occurs: - -psql --set ON_ERROR_STOP=on dbname < infile - - Either way, you will only have a partially restored database. - Alternatively, you can specify that the whole dump should be - restored as a single transaction, so the restore is either fully - completed or fully rolled back. This mode can be specified by - passing the - - - The ability of pg_dump and psql to - write to or read from pipes makes it possible to dump a database - directly from one server to another, for example: - -pg_dump -h host1 dbname | psql -h host2 dbname - - - - - - The dumps produced by pg_dump are relative to - template0. This means that any languages, procedures, - etc. added via template1 will also be dumped by - pg_dump. As a result, when restoring, if you are - using a customized template1, you must create the - empty database from template0, as in the example - above. - - - - - After restoring a backup, it is wise to run on each - database so the query optimizer has useful statistics; - see - and for more information. - For more advice on how to load large amounts of data - into PostgreSQL efficiently, refer to . - - - - - Using <application>pg_dumpall</> - -&common; - - pg_dump dumps only a single database at a time, - and it does not dump information about roles or tablespaces - (because those are cluster-wide rather than per-database). - To support convenient dumping of the entire contents of a database - cluster, the program is provided. - pg_dumpall backs up each database in a given - cluster, and also preserves cluster-wide data such as role and - tablespace definitions. The basic usage of this command is: - -pg_dumpall > outfile - - The resulting dump can be restored with psql: - -psql -f infile postgres - - (Actually, you can specify any existing database name to start from, - but if you are loading into an empty cluster then postgres - should usually be used.) It is always necessary to have - database superuser access when restoring a pg_dumpall - dump, as that is required to restore the role and tablespace information. - If you use tablespaces, make sure that the tablespace paths in the - dump are appropriate for the new installation. - - - - pg_dumpall works by emitting commands to re-create - roles, tablespaces, and empty databases, then invoking - pg_dump for each database. This means that while - each database will be internally consistent, the snapshots of - different databases might not be exactly in-sync. - - - - - Handling Large Databases - -&common; - - Some operating systems have maximum file size limits that cause - problems when creating large pg_dump output files. - Fortunately, pg_dump can write to the standard - output, so you can use standard Unix tools to work around this - potential problem. There are several possible methods: - - - - Use compressed dumps. - - You can use your favorite compression program, for example - gzip: - - -pg_dump dbname | gzip > filename.gz - - - Reload with: - - -gunzip -c filename.gz | psql dbname - - - or: - - -cat filename.gz | gunzip | psql dbname - - - - - - Use <command>split</>. - - The split command - allows you to split the output into smaller files that are - acceptable in size to the underlying file system. For example, to - make chunks of 1 megabyte: - - -pg_dump dbname | split -b 1m - filename - - - Reload with: - - -cat filename* | psql dbname - - - - - - Use <application>pg_dump</>'s custom dump format. - - If PostgreSQL was built on a system with the - zlib compression library installed, the custom dump - format will compress data as it writes it to the output file. This will - produce dump file sizes similar to using gzip, but it - has the added advantage that tables can be restored selectively. The - following command dumps a database using the custom dump format: - - -pg_dump -Fc dbname > filename - - - A custom-format dump is not a script for psql, but - instead must be restored with pg_restore, for example: - - -pg_restore -d dbname filename - - - See the and reference pages for details. - - - - - For very large databases, you might need to combine split - with one of the other two approaches. - - - - - - - File System Level Backup - - -&xconly; - - File system level backup covers only each Coordinator or Datanode. - To make file system level backup, you should backup each - Coordinator and Datanode manually. - - - -&xlonly; - - File system level backup covers only each Coordinator or Datanode. - To make file system level backup, you should backup each - Coordinator and Datanode manually. - - - -&common; - - An alternative backup strategy is to directly copy the files that - PostgreSQL uses to store the data in the database; - explains where these files - are located. You can use whatever method you prefer - for doing file system backups; for example: - - -tar -cf backup.tar /usr/local/pgsql/data - - - - - There are two restrictions, however, which make this method - impractical, or at least inferior to the pg_dump - method: - - - - - The database server must be shut down in order to - get a usable backup. Half-way measures such as disallowing all - connections will not work - (in part because tar and similar tools do not take - an atomic snapshot of the state of the file system, - but also because of internal buffering within the server). - Information about stopping the server can be found in - . Needless to say, you - also need to shut down the server before restoring the data. - - - - - - If you have dug into the details of the file system layout of the - database, you might be tempted to try to back up or restore only certain - individual tables or databases from their respective files or - directories. This will not work because the - information contained in these files is not usable without - the commit log files, - pg_clog/*, which contain the commit status of - all transactions. A table file is only usable with this - information. Of course it is also impossible to restore only a - table and the associated pg_clog data - because that would render all other tables in the database - cluster useless. So file system backups only work for complete - backup and restoration of an entire database cluster. - - - - - - - An alternative file-system backup approach is to make a - consistent snapshot of the data directory, if the - file system supports that functionality (and you are willing to - trust that it is implemented correctly). The typical procedure is - to make a frozen snapshot of the volume containing the - database, then copy the whole data directory (not just parts, see - above) from the snapshot to a backup device, then release the frozen - snapshot. This will work even while the database server is running. - However, a backup created in this way saves - the database files in a state as if the database server was not - properly shut down; therefore, when you start the database server - on the backed-up data, it will think the previous server instance - crashed and will replay the WAL log. This is not a problem; just - be aware of it (and be sure to include the WAL files in your backup). - You can perform a CHECKPOINT before taking the - snapshot to reduce recovery time. - - - - If your database is spread across multiple file systems, there might not - be any way to obtain exactly-simultaneous frozen snapshots of all - the volumes. For example, if your data files and WAL log are on different - disks, or if tablespaces are on different file systems, it might - not be possible to use snapshot backup because the snapshots - must be simultaneous. - Read your file system documentation very carefully before trusting - the consistent-snapshot technique in such situations. - - - - If simultaneous snapshots are not possible, one option is to shut down - the database server long enough to establish all the frozen snapshots. - Another option is to perform a continuous archiving base backup () because such backups are immune to file - system changes during the backup. This requires enabling continuous - archiving just during the backup process; restore is done using - continuous archive recovery (). - - - - Another option is to use rsync to perform a file - system backup. This is done by first running rsync - while the database server is running, then shutting down the database - server just long enough to do a second rsync. The - second rsync will be much quicker than the first, - because it has relatively little data to transfer, and the end result - will be consistent because the server was down. This method - allows a file system backup to be performed with minimal downtime. - - - - Note that a file system backup will typically be larger - than an SQL dump. (pg_dump does not need to dump - the contents of indexes for example, just the commands to recreate - them.) However, taking a file system backup might be faster. - - - - - Continuous Archiving and Point-in-Time Recovery (PITR) - - - continuous archiving - - - - point-in-time recovery - - - - PITR - - - -&xconly; - - This section describes PITR for PostgreSQL. - Because Coordinator and Datanode of Postgres-XC are - essentially PostgreSQLserver, you can do - PITR for each Coordinator and Datanode manually. - - - - - At all times, PostgreSQL maintains a - write ahead log (WAL) in the pg_xlog/ - subdirectory of the cluster's data directory. The log records - every change made to the database's data files. This log exists - primarily for crash-safety purposes: if the system crashes, the - database can be restored to consistency by replaying the - log entries made since the last checkpoint. However, the existence - of the log makes it possible to use a third strategy for backing up - databases: we can combine a file-system-level backup with backup of - the WAL files. If recovery is needed, we restore the file system backup and - then replay from the backed-up WAL files to bring the system to a - current state. This approach is more complex to administer than - either of the previous approaches, but it has some significant - benefits: - - - - We do not need a perfectly consistent file system backup as the starting point. - Any internal inconsistency in the backup will be corrected by log - replay (this is not significantly different from what happens during - crash recovery). So we do not need a file system snapshot capability, - just tar or a similar archiving tool. - - - - - Since we can combine an indefinitely long sequence of WAL files - for replay, continuous backup can be achieved simply by continuing to archive - the WAL files. This is particularly valuable for large databases, where - it might not be convenient to take a full backup frequently. - - - - - It is not necessary to replay the WAL entries all the - way to the end. We could stop the replay at any point and have a - consistent snapshot of the database as it was at that time. Thus, - this technique supports point-in-time recovery: it is - possible to restore the database to its state at any time since your base - backup was taken. - - - - - If we continuously feed the series of WAL files to another - machine that has been loaded with the same base backup file, we - have a warm standby system: at any point we can bring up - the second machine and it will have a nearly-current copy of the - database. - - - - - - - - pg_dump and - pg_dumpall do not produce file-system-level - backups and cannot be used as part of a continuous-archiving solution. - Such dumps are logical and do not contain enough - information to be used by WAL replay. - - - - - As with the plain file-system-backup technique, this method can only - support restoration of an entire database cluster, not a subset. - Also, it requires a lot of archival storage: the base backup might be bulky, - and a busy system will generate many megabytes of WAL traffic that - have to be archived. Still, it is the preferred backup technique in - many situations where high reliability is needed. - - - - To recover successfully using continuous archiving (also called - online backup by many database vendors), you need a continuous - sequence of archived WAL files that extends back at least as far as the - start time of your backup. So to get started, you should set up and test - your procedure for archiving WAL files before you take your - first base backup. Accordingly, we first discuss the mechanics of - archiving WAL files. - - - - Setting Up WAL Archiving - - -&xconly; - - This section describes PITR for PostgreSQL. - Because Coordinator and Datanode of Postgres-XC are - essentially PostgreSQLserver, you can - set up WAL archiving for each Coordinator and Datanode manually. - - - - - In an abstract sense, a running PostgreSQL system - produces an indefinitely long sequence of WAL records. The system - physically divides this sequence into WAL segment - files, which are normally 16MB apiece (although the segment size - can be altered when building PostgreSQL). The segment - files are given numeric names that reflect their position in the - abstract WAL sequence. When not using WAL archiving, the system - normally creates just a few segment files and then - recycles them by renaming no-longer-needed segment files - to higher segment numbers. It's assumed that segment files whose - contents precede the checkpoint-before-last are no longer of - interest and can be recycled. - - - - When archiving WAL data, we need to capture the contents of each segment - file once it is filled, and save that data somewhere before the segment - file is recycled for reuse. Depending on the application and the - available hardware, there could be many different ways of saving - the data somewhere: we could copy the segment files to an NFS-mounted - directory on another machine, write them onto a tape drive (ensuring that - you have a way of identifying the original name of each file), or batch - them together and burn them onto CDs, or something else entirely. To - provide the database administrator with flexibility, - PostgreSQL tries not to make any assumptions about how - the archiving will be done. Instead, PostgreSQL lets - the administrator specify a shell command to be executed to copy a - completed segment file to wherever it needs to go. The command could be - as simple as a cp, or it could invoke a complex shell - script — it's all up to you. - - - - To enable WAL archiving, set the - configuration parameter to archive (or hot_standby), - to on, - and specify the shell command to use in the configuration parameter. In practice - these settings will always be placed in the - postgresql.conf file. - In archive_command, - %p is replaced by the path name of the file to - archive, while %f is replaced by only the file name. - (The path name is relative to the current working directory, - i.e., the cluster's data directory.) - Use %% if you need to embed an actual % - characterin the command. The simplest useful command is something - like: - -archive_command = 'cp -i %p /mnt/server/archivedir/%f </dev/null' # Unix -archive_command = 'copy "%p" "C:\\server\\archivedir\\%f"' # Windows - - which will copy archivable WAL segments to the directory - /mnt/server/archivedir. (This is an example, not a - recommendation, and might not work on all platforms.) After the - %p and %f parameters have been replaced, - the actual command executed might look like this: - -cp -i pg_xlog/00000001000000A900000065 /mnt/server/archivedir/00000001000000A900000065 </dev/null - - A similar command will be generated for each new file to be archived. - - - - The archive command will be executed under the ownership of the same - user that the PostgreSQL server is running as. Since - the series of WAL files being archived contains effectively everything - in your database, you will want to be sure that the archived data is - protected from prying eyes; for example, archive into a directory that - does not have group or world read access. - - - - It is important that the archive command return zero exit status if and - only if it succeeds. Upon getting a zero result, - PostgreSQL will assume that the file has been - successfully archived, and will remove or recycle it. However, a nonzero - status tells PostgreSQL that the file was not archived; - it will try again periodically until it succeeds. - - - - The archive command should generally be designed to refuse to overwrite - any pre-existing archive file. This is an important safety feature to - preserve the integrity of your archive in case of administrator error - (such as sending the output of two different servers to the same archive - directory). - It is advisable to test your proposed archive command to ensure that it - indeed does not overwrite an existing file, and that it returns - nonzero status in this case. On many Unix platforms, cp - -i causes copy to prompt before overwriting a file, and - < /dev/null causes the prompt (and overwriting) to - fail. If your platform does not support this behavior, you should - add a command to test for the existence of the archive file. For - example, something like: - -archive_command = 'test ! -f /mnt/server/archivedir/%f && cp %p /mnt/server/archivedir/%f' - - works correctly on most Unix variants. - - - - While designing your archiving setup, consider what will happen if - the archive command fails repeatedly because some aspect requires - operator intervention or the archive runs out of space. For example, this - could occur if you write to tape without an autochanger; when the tape - fills, nothing further can be archived until the tape is swapped. - You should ensure that any error condition or request to a human operator - is reported appropriately so that the situation can be - resolved reasonably quickly. The pg_xlog/ directory will - continue to fill with WAL segment files until the situation is resolved. - (If the file system containing pg_xlog/ fills up, - PostgreSQL will do a PANIC shutdown. No committed - transactions will be lost, but the database will remain offline until - you free some space.) - - - - The speed of the archiving command is unimportant as long as it can keep up - with the average rate at which your server generates WAL data. Normal - operation continues even if the archiving process falls a little behind. - If archiving falls significantly behind, this will increase the amount of - data that would be lost in the event of a disaster. It will also mean that - the pg_xlog/ directory will contain large numbers of - not-yet-archived segment files, which could eventually exceed available - disk space. You are advised to monitor the archiving process to ensure that - it is working as you intend. - - - - In writing your archive command, you should assume that the file names to - be archived can be up to 64 characters long and can contain any - combination of ASCII letters, digits, and dots. It is not necessary to - preserve the original relative path (%p) but it is necessary to - preserve the file name (%f). - - - - Note that although WAL archiving will allow you to restore any - modifications made to the data in your PostgreSQL database, - it will not restore changes made to configuration files (that is, - postgresql.conf, pg_hba.conf and - pg_ident.conf), since those are edited manually rather - than through SQL operations. - You might wish to keep the configuration files in a location that will - be backed up by your regular file system backup procedures. See - for how to relocate the - configuration files. - - - - The archive command is only invoked on completed WAL segments. Hence, - if your server generates only little WAL traffic (or has slack periods - where it does so), there could be a long delay between the completion - of a transaction and its safe recording in archive storage. To put - a limit on how old unarchived data can be, you can set - to force the server to switch - to a new WAL segment file at least that often. Note that archived - files that are archived early due to a forced switch are still the same - length as completely full files. It is therefore unwise to set a very - short archive_timeout — it will bloat your archive - storage. archive_timeout settings of a minute or so are - usually reasonable. - - - - Also, you can force a segment switch manually with - pg_switch_xlog if you want to ensure that a - just-finished transaction is archived as soon as possible. Other utility - functions related to WAL management are listed in . - - - - When wal_level is minimal some SQL commands - are optimized to avoid WAL logging, as described in . If archiving or streaming replication were - turned on during execution of one of these statements, WAL would not - contain enough information for archive recovery. (Crash recovery is - unaffected.) For this reason, wal_level can only be changed at - server start. However, archive_command can be changed with a - configuration file reload. If you wish to temporarily stop archiving, - one way to do it is to set archive_command to the empty - string (''). - This will cause WAL files to accumulate in pg_xlog/ until a - working archive_command is re-established. - - - - - Making a Base Backup - - -&xconly; - - This section describes how to make a base backup of single - Datanode or Coordinator. Please note that you should take base - backup of all the Datanodes and Coordinators. Also please note - that you don't have to take base backups at exactly the same time. - You may take base backup of each Datanode or Coordinator one after - another, or you may take some of them at the same time. You don't - have to do it at exactly the same time. - - - - - The procedure for making a base backup is relatively simple: - - - - Ensure that WAL archiving is enabled and working. - - - - - Connect to the database as a superuser and issue the command: - -SELECT pg_start_backup('label'); - - where label is any string you want to use to uniquely - identify this backup operation. (One good practice is to use the - full path where you intend to put the backup dump file.) - pg_start_backup creates a backup label file, - called backup_label, in the cluster directory with - information about your backup, including the start time and label - string. - - - - It does not matter which database within the cluster you connect to to - issue this command. You can ignore the result returned by the function; - but if it reports an error, deal with that before proceeding. - - - - By default, pg_start_backup can take a long time to finish. - This is because it performs a checkpoint, and the I/O - required for the checkpoint will be spread out over a significant - period of time, by default half your inter-checkpoint interval - (see the configuration parameter - ). This is - usually what you want, because it minimizes the impact on query - processing. If you want to start the backup as soon as - possible, use: - -SELECT pg_start_backup('label', true); - - This forces the checkpoint to be done as quickly as possible. - - - - - Perform the backup, using any convenient file-system-backup tool - such as tar or cpio (not - pg_dump or - pg_dumpall). It is neither - necessary nor desirable to stop normal operation of the database - while you do this. - - - - - Again connect to the database as a superuser, and issue the command: - -SELECT pg_stop_backup(); - - This terminates the backup mode and performs an automatic switch to - the next WAL segment. The reason for the switch is to arrange for - the last WAL segment file written during the backup interval to be - ready to archive. - - - - - Once the WAL segment files active during the backup are archived, you are - done. The file identified by pg_stop_backup's result is - the last segment that is required to form a complete set of backup files. - If archive_mode is enabled, - pg_stop_backup does not return until the last segment has - been archived. - Archiving of these files happens automatically since you have - already configured archive_command. In most cases this - happens quickly, but you are advised to monitor your archive - system to ensure there are no delays. - If the archive process has fallen behind - because of failures of the archive command, it will keep retrying - until the archive succeeds and the backup is complete. - If you wish to place a time limit on the execution of - pg_stop_backup, set an appropriate - statement_timeout value. - - - - - - - You can also use the tool to take - the backup, instead of manually copying the files. This tool will do - the equivalent of pg_start_backup(), copy and - pg_stop_backup() steps automatically, and transfers the - backup over a regular PostgreSQL connection - using the replication protocol, instead of requiring file system level - access. pg_basebackup does not interfere with file system level backups - taken using pg_start_backup()/pg_stop_backup(). - - - - Some file system backup tools emit warnings or errors - if the files they are trying to copy change while the copy proceeds. - When taking a base backup of an active database, this situation is normal - and not an error. However, you need to ensure that you can distinguish - complaints of this sort from real errors. For example, some versions - of rsync return a separate exit code for - vanished source files, and you can write a driver script to - accept this exit code as a non-error case. Also, some versions of - GNU tar return an error code indistinguishable from - a fatal error if a file was truncated while tar was - copying it. Fortunately, GNU tar versions 1.16 and - later exit with 1 if a file was changed during the backup, - and 2 for other errors. - - - - It is not necessary to be concerned about the amount of time elapsed - between pg_start_backup and the start of the actual backup, - nor between the end of the backup and pg_stop_backup; a - few minutes' delay won't hurt anything. (However, if you normally run the - server with full_page_writes disabled, you might notice a drop - in performance between pg_start_backup and - pg_stop_backup, since full_page_writes is - effectively forced on during backup mode.) You must ensure that these - steps are carried out in sequence, without any possible - overlap, or you will invalidate the backup. - - - - Be certain that your backup dump includes all of the files under - the database cluster directory (e.g., /usr/local/pgsql/data). - If you are using tablespaces that do not reside underneath this directory, - be careful to include them as well (and be sure that your backup dump - archives symbolic links as links, otherwise the restore will corrupt - your tablespaces). - - - - You can, however, omit from the backup dump the files within the - cluster's pg_xlog/ subdirectory. This - slight adjustment is worthwhile because it reduces the risk - of mistakes when restoring. This is easy to arrange if - pg_xlog/ is a symbolic link pointing to someplace outside - the cluster directory, which is a common setup anyway for performance - reasons. - - - - To make use of the backup, you will need to keep all the WAL - segment files generated during and after the file system backup. - To aid you in doing this, the pg_stop_backup function - creates a backup history file that is immediately - stored into the WAL archive area. This file is named after the first - WAL segment file that you need for the file system backup. - For example, if the starting WAL file is - 0000000100001234000055CD the backup history file will be - named something like - 0000000100001234000055CD.007C9330.backup. (The second - part of the file name stands for an exact position within the WAL - file, and can ordinarily be ignored.) Once you have safely archived - the file system backup and the WAL segment files used during the - backup (as specified in the backup history file), all archived WAL - segments with names numerically less are no longer needed to recover - the file system backup and can be deleted. However, you should - consider keeping several backup sets to be absolutely certain that - you can recover your data. - - - - The backup history file is just a small text file. It contains the - label string you gave to pg_start_backup, as well as - the starting and ending times and WAL segments of the backup. - If you used the label to identify the associated dump file, - then the archived history file is enough to tell you which dump file to - restore. - - - - Since you have to keep around all the archived WAL files back to your - last base backup, the interval between base backups should usually be - chosen based on how much storage you want to expend on archived WAL - files. You should also consider how long you are prepared to spend - recovering, if recovery should be necessary — the system will have to - replay all those WAL segments, and that could take awhile if it has - been a long time since the last base backup. - - - - It's also worth noting that the pg_start_backup function - makes a file named backup_label in the database cluster - directory, which is removed by pg_stop_backup. - This file will of course be archived as a part of your backup dump file. - The backup label file includes the label string you gave to - pg_start_backup, as well as the time at which - pg_start_backup was run, and the name of the starting WAL - file. In case of confusion it is - therefore possible to look inside a backup dump file and determine - exactly which backup session the dump file came from. - - - - It is also possible to make a backup dump while the server is - stopped. In this case, you obviously cannot use - pg_start_backup or pg_stop_backup, and - you will therefore be left to your own devices to keep track of which - backup dump is which and how far back the associated WAL files go. - It is generally better to follow the continuous archiving procedure above. - - - - - Recovering Using a Continuous Archive Backup - - -&xconly; - - This section describes recovering with continuous archive backup - for PostgreSQL. Because Coordinator and Datanode - of Postgres-XC are - essentially PostgreSQLserver, you can do - this for each Coordinator and Datanode manually. - - - - - Okay, the worst has happened and you need to recover from your backup. - Here is the procedure: - - - - Stop the server, if it's running. - - - - - If you have the space to do so, - copy the whole cluster data directory and any tablespaces to a temporary - location in case you need them later. Note that this precaution will - require that you have enough free space on your system to hold two - copies of your existing database. If you do not have enough space, - you should at least save the contents of the cluster's pg_xlog - subdirectory, as it might contain logs which - were not archived before the system went down. - - - - - Remove all existing files and subdirectories under the cluster data - directory and under the root directories of any tablespaces you are using. - - - - - Restore the database files from your file system backup. Be sure that they - are restored with the right ownership (the database system user, not - root!) and with the right permissions. If you are using - tablespaces, - you should verify that the symbolic links in pg_tblspc/ - were correctly restored. - - - - - Remove any files present in pg_xlog/; these came from the - file system backup and are therefore probably obsolete rather than current. - If you didn't archive pg_xlog/ at all, then recreate - it with proper permissions, - being careful to ensure that you re-establish it as a symbolic link - if you had it set up that way before. - - - - - If you have unarchived WAL segment files that you saved in step 2, - copy them into pg_xlog/. (It is best to copy them, - not move them, so you still have the unmodified files if a - problem occurs and you have to start over.) - - - - - Create a recovery command file recovery.conf in the cluster - data directory (see ). You might - also want to temporarily modify pg_hba.conf to prevent - ordinary users from connecting until you are sure the recovery was successful. - - - - - Start the server. The server will go into recovery mode and - proceed to read through the archived WAL files it needs. Should the - recovery be terminated because of an external error, the server can - simply be restarted and it will continue recovery. Upon completion - of the recovery process, the server will rename - recovery.conf to recovery.done (to prevent - accidentally re-entering recovery mode later) and then - commence normal database operations. - - - - - Inspect the contents of the database to ensure you have recovered to - the desired state. If not, return to step 1. If all is well, - allow your users to connect by restoring pg_hba.conf to normal. - - - - - - - The key part of all this is to set up a recovery configuration file that - describes how you want to recover and how far the recovery should - run. You can use recovery.conf.sample (normally - located in the installation's share/ directory) as a - prototype. The one thing that you absolutely must specify in - recovery.conf is the restore_command, - which tells PostgreSQL how to retrieve archived - WAL file segments. Like the archive_command, this is - a shell command string. It can contain %f, which is - replaced by the name of the desired log file, and %p, - which is replaced by the path name to copy the log file to. - (The path name is relative to the current working directory, - i.e., the cluster's data directory.) - Write %% if you need to embed an actual % - character in the command. The simplest useful command is - something like: - -restore_command = 'cp /mnt/server/archivedir/%f %p' - - which will copy previously archived WAL segments from the directory - /mnt/server/archivedir. Of course, you can use something - much more complicated, perhaps even a shell script that requests the - operator to mount an appropriate tape. - - - - It is important that the command return nonzero exit status on failure. - The command will be called requesting files that are not present - in the archive; it must return nonzero when so asked. This is not an - error condition. Not all of the requested files will be WAL segment - files; you should also expect requests for files with a suffix of - .backup or .history. Also be aware that - the base name of the %p path will be different from - %f; do not expect them to be interchangeable. - - - - WAL segments that cannot be found in the archive will be sought in - pg_xlog/; this allows use of recent un-archived segments. - However, segments that are available from the archive will be used in - preference to files in pg_xlog/. The system will not - overwrite the existing contents of pg_xlog/ when retrieving - archived files. - - - - Normally, recovery will proceed through all available WAL segments, - thereby restoring the database to the current point in time (or as - close as possible given the available WAL segments). Therefore, a normal - recovery will end with a file not found message, the exact text - of the error message depending upon your choice of - restore_command. You may also see an error message - at the start of recovery for a file named something like - 00000001.history. This is also normal and does not - indicate a problem in simple recovery situations; see - for discussion. - - - - If you want to recover to some previous point in time (say, right before - the junior DBA dropped your main transaction table), just specify the - required stopping point in recovery.conf. You can specify - the stop point, known as the recovery target, either by - date/time, named restore point or by completion of a specific transaction - ID. As of this writing only the date/time and named restore point options - are very usable, since there are no tools to help you identify with any - accuracy which transaction ID to use. - - - - - The stop point must be after the ending time of the base backup, i.e., - the end time of pg_stop_backup. You cannot use a base backup - to recover to a time when that backup was in progress. (To - recover to such a time, you must go back to your previous base backup - and roll forward from there.) - - - - - If recovery finds corrupted WAL data, recovery will - halt at that point and the server will not start. In such a case the - recovery process could be re-run from the beginning, specifying a - recovery target before the point of corruption so that recovery - can complete normally. - If recovery fails for an external reason, such as a system crash or - if the WAL archive has become inaccessible, then the recovery can simply - be restarted and it will restart almost from where it failed. - Recovery restart works much like checkpointing in normal operation: - the server periodically forces all its state to disk, and then updates - the pg_control file to indicate that the already-processed - WAL data need not be scanned again. - - - - - - Timelines - - - timelines - - - -&xconly; - - Because Coordinator and Datanode of Postgres-XC are - essentially PostgreSQLserver, you can - apply timelines for each Coordinator and Datanode manually. - - - - - The ability to restore the database to a previous point in time creates - some complexities that are akin to science-fiction stories about time - travel and parallel universes. For example, in the original history of the database, - suppose you dropped a critical table at 5:15PM on Tuesday evening, but - didn't realize your mistake until Wednesday noon. - Unfazed, you get out your backup, restore to the point-in-time 5:14PM - Tuesday evening, and are up and running. In this history of - the database universe, you never dropped the table. But suppose - you later realize this wasn't such a great idea, and would like - to return to sometime Wednesday morning in the original history. - You won't be able - to if, while your database was up-and-running, it overwrote some of the - WAL segment files that led up to the time you now wish you - could get back to. Thus, to avoid this, you need to distinguish the series of - WAL records generated after you've done a point-in-time recovery from - those that were generated in the original database history. - - - - To deal with this problem, PostgreSQL has a notion - of timelines. Whenever an archive recovery completes, - a new timeline is created to identify the series of WAL records - generated after that recovery. The timeline - ID number is part of WAL segment file names so a new timeline does - not overwrite the WAL data generated by previous timelines. It is - in fact possible to archive many different timelines. While that might - seem like a useless feature, it's often a lifesaver. Consider the - situation where you aren't quite sure what point-in-time to recover to, - and so have to do several point-in-time recoveries by trial and error - until you find the best place to branch off from the old history. Without - timelines this process would soon generate an unmanageable mess. With - timelines, you can recover to any prior state, including - states in timeline branches that you abandoned earlier. - - - - Every time a new timeline is created, PostgreSQL creates - a timeline history file that shows which timeline it branched - off from and when. These history files are necessary to allow the system - to pick the right WAL segment files when recovering from an archive that - contains multiple timelines. Therefore, they are archived into the WAL - archive area just like WAL segment files. The history files are just - small text files, so it's cheap and appropriate to keep them around - indefinitely (unlike the segment files which are large). You can, if - you like, add comments to a history file to record your own notes about - how and why this particular timeline was created. Such comments will be - especially valuable when you have a thicket of different timelines as - a result of experimentation. - - - - The default behavior of recovery is to recover along the same timeline - that was current when the base backup was taken. If you wish to recover - into some child timeline (that is, you want to return to some state that - was itself generated after a recovery attempt), you need to specify the - target timeline ID in recovery.conf. You cannot recover into - timelines that branched off earlier than the base backup. - - - - - - Tips and Examples - -&pgnotice; - - Some tips for configuring continuous archiving are given here. - - - - Standalone Hot Backups - -&pgnotice; - - It is possible to use PostgreSQL's backup facilities to - produce standalone hot backups. These are backups that cannot be used - for point-in-time recovery, yet are typically much faster to backup and - restore than pg_dump dumps. (They are also much larger - than pg_dump dumps, so in some cases the speed advantage - might be negated.) - - - - To prepare for standalone hot backups, set wal_level to - archive (or hot_standby), archive_mode to - on, and set up an archive_command that performs - archiving only when a switch file exists. For example: - -archive_command = 'test ! -f /var/lib/pgsql/backup_in_progress || cp -i %p /var/lib/pgsql/archive/%f < /dev/null' - - This command will perform archiving when - /var/lib/pgsql/backup_in_progress exists, and otherwise - silently return zero exit status (allowing PostgreSQL - to recycle the unwanted WAL file). - - - - With this preparation, a backup can be taken using a script like the - following: - -touch /var/lib/pgsql/backup_in_progress -psql -c "select pg_start_backup('hot_backup');" -tar -cf /var/lib/pgsql/backup.tar /var/lib/pgsql/data/ -psql -c "select pg_stop_backup();" -rm /var/lib/pgsql/backup_in_progress -tar -rf /var/lib/pgsql/backup.tar /var/lib/pgsql/archive/ - - The switch file /var/lib/pgsql/backup_in_progress is - created first, enabling archiving of completed WAL files to occur. - After the backup the switch file is removed. Archived WAL files are - then added to the backup so that both base backup and all required - WAL files are part of the same tar file. - Please remember to add error handling to your backup scripts. - - - - If archive storage size is a concern, use pg_compresslog, - , to - remove unnecessary and trailing - space from the WAL files. You can then use - gzip to further compress the output of - pg_compresslog: - -archive_command = 'pg_compresslog %p - | gzip > /var/lib/pgsql/archive/%f' - - You will then need to use gunzip and - pg_decompresslog during recovery: - -restore_command = 'gunzip < /mnt/server/archivedir/%f | pg_decompresslog - %p' - - - - - - <varname>archive_command</varname> Scripts - -&pgnotice; - - Many people choose to use scripts to define their - archive_command, so that their - postgresql.conf entry looks very simple: - -archive_command = 'local_backup_script.sh' - - Using a separate script file is advisable any time you want to use - more than a single command in the archiving process. - This allows all complexity to be managed within the script, which - can be written in a popular scripting language such as - bash or perl. - Any messages written to stderr from the script will appear - in the database server log, allowing complex configurations to be - diagnosed easily if they fail. - - - - Examples of requirements that might be solved within a script include: - - - - Copying data to secure off-site data storage - - - - - Batching WAL files so that they are transferred every three hours, - rather than one at a time - - - - - Interfacing with other backup and recovery software - - - - - Interfacing with monitoring software to report errors - - - - - - - - - - Caveats - - - At this writing, there are several limitations of the continuous archiving - technique. These will probably be fixed in future releases: - - - - - Operations on hash indexes are not presently WAL-logged, so - replay will not update these indexes. This will mean that any new inserts - will be ignored by the index, updated rows will apparently disappear and - deleted rows will still retain pointers. In other words, if you modify a - table with a hash index on it then you will get incorrect query results - on a standby server. When recovery completes it is recommended that you - manually - each such index after completing a recovery operation. - - - - - - If a - command is executed while a base backup is being taken, and then - the template database that the CREATE DATABASE copied - is modified while the base backup is still in progress, it is - possible that recovery will cause those modifications to be - propagated into the created database as well. This is of course - undesirable. To avoid this risk, it is best not to modify any - template databases while taking a base backup. - - - - - - - commands are WAL-logged with the literal absolute path, and will - therefore be replayed as tablespace creations with the same - absolute path. This might be undesirable if the log is being - replayed on a different machine. It can be dangerous even if the - log is being replayed on the same machine, but into a new data - directory: the replay will still overwrite the contents of the - original tablespace. To avoid potential gotchas of this sort, - the best practice is to take a new base backup after creating or - dropping tablespaces. - - - - - - - It should also be noted that the default WAL - format is fairly bulky since it includes many disk page snapshots. - These page snapshots are designed to support crash recovery, since - we might need to fix partially-written disk pages. Depending on - your system hardware and software, the risk of partial writes might - be small enough to ignore, in which case you can significantly - reduce the total volume of archived logs by turning off page - snapshots using the - parameter. (Read the notes and warnings in - before you do so.) Turning off page snapshots does not prevent - use of the logs for PITR operations. An area for future - development is to compress archived WAL data by removing - unnecessary page copies even when full_page_writes is - on. In the meantime, administrators might wish to reduce the number - of page snapshots included in WAL by increasing the checkpoint - interval parameters as much as feasible. - - - - - diff --git a/doc-xc/src/sgml/biblio.sgmlin b/doc-xc/src/sgml/biblio.sgmlin deleted file mode 100644 index 290f28c086..0000000000 --- a/doc-xc/src/sgml/biblio.sgmlin +++ /dev/null @@ -1,594 +0,0 @@ - - - - Bibliography - - - Selected references and readings for SQL - and PostgreSQL. - - - - Some white papers and technical reports from the original - POSTGRES development team - are available at the University of California, Berkeley, Computer Science - Department - web site. - - - - <acronym>SQL</acronym> Reference Books - Reference texts for SQL features. - - - The Practical <acronym>SQL</acronym> Handbook - Bowman et al, 2001 - Using SQL Variants - Fourth Edition - - - Judith - Bowman - - - Sandra - Emerson - - - Marcy - Darnovsky - - - 0-201-70309-2 - 2001 - - Addison-Wesley Professional - - - 2001 - - - - - A Guide to the <acronym>SQL</acronym> Standard - Date and Darwen, 1997 - A user's guide to the standard database language SQL - Fourth Edition - - - C. J. - Date - - - Hugh - Darwen - - - 0-201-96426-0 - 1997 - - Addison-Wesley - - - 1997 - Addison-Wesley Longman, Inc. - - - - - An Introduction to Database Systems - Date, 2004 - Eighth Edition - - - C. J. - Date - - - 0-321-19784-4 - 2003 - - Addison-Wesley - - - 2004 - Pearson Education, Inc. - - - - - Fundamentals of Database Systems - Fourth Edition - - - Ramez - Elmasri - - - Shamkant - Navathe - - - 0-321-12226-7 - 2003 - - Addison-Wesley - - - 2004 - - - - - Understanding the New <acronym>SQL</acronym> - Melton and Simon, 1993 - A complete guide - - - Jim - Melton - - - Alan R. - Simon - - - 1-55860-245-3 - 1993 - - Morgan Kaufmann - - - 1993 - Morgan Kaufmann Publishers, Inc. - - - - - Principles of Database and Knowledge - Base Systems - Ullman, 1988 - - - Jeffrey D. - Ullman - - - Volume 1 - - Computer Science Press - - 1988 - - - - - - PostgreSQL-specific Documentation - This section is for related documentation. - - - Enhancement of the ANSI SQL Implementation of PostgreSQL - Simkovics, 1998 - - - Stefan - Simkovics - - - - - - - Discusses SQL history and syntax, and describes the addition of - INTERSECT and EXCEPT constructs into - PostgreSQL. Prepared as a Master's - Thesis with the support of O. Univ. Prof. Dr. Georg Gottlob and - Univ. Ass. Mag. Katrin Seyr at Vienna University of Technology. - - - - November 29, 1998 - - Department of Information Systems, Vienna University of Technology -
Vienna, Austria
- - - - - The <productname>Postgres95</productname> User Manual - Yu and Chen, 1995 - - - A. - Yu - - - J. - Chen - - - - - The POSTGRES Group - - - - Sept. 5, 1995 - - University of California -
Berkeley, California
- - - - - - <ulink url="http://db.cs.berkeley.edu/papers/UCB-MS-zfong.pdf"> - The design and implementation of the <productname>POSTGRES</productname> query optimizer - </ulink> - - Zelaine - Fong - - - University of California, Berkeley, Computer Science Department - - - - - - - Proceedings and Articles - This section is for articles and newsletters. - - - Partial indexing in POSTGRES: research project - Olson, 1993 - - - Nels - Olson - - - 1993 - UCB Engin T7.49.1993 O676 - - University of California -
Berkeley, California
- - - - - - A Unified Framework for Version Modeling Using Production Rules in a Database System - Ong and Goh, 1990 - - - L. - Ong - - - J. - Goh - - - - - ERL Technical Memorandum M90/33 - April, 1990 - - University of California -
Berkely, California
- - - - - - - <ulink url="http://db.cs.berkeley.edu/papers/ERL-M87-13.pdf"> - The <productname>POSTGRES</productname> data model - </ulink> - Rowe and Stonebraker, 1987 - - - L. - Rowe - - - M. - Stonebraker - - - - - VLDB Conference - Sept. 1987 -
Brighton, England
- - - - - - Generalized Partial Indexes - <ulink url="http://citeseer.ist.psu.edu/seshadri95generalized.html">(cached version) -<!-- - Original URL: http://citeseer.ist.psu.edu/seshadri95generalized.html ---> - </ulink> - - Seshardri, 1995 - - - P. - Seshadri - - - A. - Swami - - - - - Eleventh International Conference on Data Engineering - 6-10 March 1995 -
Taipeh, Taiwan
- - 1995 - Cat. No.95CH35724 - - IEEE Computer Society Press -
Los Alamitos, California
- - 420-7 - - - - - <ulink url="http://db.cs.berkeley.edu/papers/ERL-M85-95.pdf"> - The design of <productname>POSTGRES</productname> - </ulink> - Stonebraker and Rowe, 1986 - - - M. - Stonebraker - - - L. - Rowe - - - - - ACM-SIGMOD Conference on Management of Data - May 1986 -
Washington, DC
- - - - - - The design of the <productname>POSTGRES</productname> rules system - Stonebraker, Hanson, Hong, 1987 - - - M. - Stonebraker - - - E. - Hanson - - - C. H. - Hong - - - - - IEEE Conference on Data Engineering - Feb. 1987 -
Los Angeles, California
- - - - - - <ulink url="http://db.cs.berkeley.edu/papers/ERL-M87-06.pdf"> - The design of the <productname>POSTGRES</productname> storage system - </ulink> - Stonebraker, 1987 - - - M. - Stonebraker - - - - - VLDB Conference - Sept. 1987 -
Brighton, England
- - - - - - <ulink url="http://db.cs.berkeley.edu/papers/ERL-M89-82.pdf"> - A commentary on the <productname>POSTGRES</productname> rules system - </ulink> - Stonebraker et al, 1989 - - - M. - Stonebraker - - - M. - Hearst - - - S. - Potamianos - - - - - SIGMOD Record 18(3) - Sept. 1989 - - - - - - <ulink url="http://db.cs.berkeley.edu/papers/ERL-M89-17.pdf"> - The case for partial indexes - </ulink> - Stonebraker, M, 1989b - - - M. - Stonebraker - - - - - SIGMOD Record 18(4) - 4-11 - Dec. 1989 - - - - - - <ulink url="http://db.cs.berkeley.edu/papers/ERL-M90-34.pdf"> - The implementation of <productname>POSTGRES</productname> - </ulink> - Stonebraker, Rowe, Hirohama, 1990 - - - M. - Stonebraker - - - L. A. - Rowe - - - M. - Hirohama - - - - - Transactions on Knowledge and Data Engineering 2(1) - - IEEE - - March 1990 - - - - - - <ulink url="http://db.cs.berkeley.edu/papers/ERL-M90-36.pdf"> - On Rules, Procedures, Caching and Views in Database Systems - </ulink> - Stonebraker et al, ACM, 1990 - - - M. - Stonebraker - - - A. - Jhingran - - - J. - Goh - - - S. - Potamianos - - - - - ACM-SIGMOD Conference on Management of Data - June 1990 - - - - - - Principles of Distributed Database Systems - Ozsu and Valduriez, 1991 - Second Edition - - - M. Tamer - Ozsu - - - Patrick - Valduriez - - - 0-13-659707-6 - 1991 - - Prentice Hall - - - 1991, 1999 - Prentice-Hall, Inc. - - - - - - Principles of Distributed Database Systems - Ozsu and Valduriez, 1991 - Second Edition - - - M. Tamer - Ozsu - - - Patrick - Valduriez - - - 0-13-659707-6 - 1991 - - Prentice Hall - - - 1991, 1999 - Prentice-Hall, Inc. - - - - - - diff --git a/doc-xc/src/sgml/bki.sgmlin b/doc-xc/src/sgml/bki.sgmlin deleted file mode 100644 index 92655d0dfb..0000000000 --- a/doc-xc/src/sgml/bki.sgmlin +++ /dev/null @@ -1,371 +0,0 @@ - - - - <acronym>BKI</acronym> Backend Interface - -&common; - - - Backend Interface (BKI) files are scripts in a - special language that is understood by the - - PostgreSQL backend when running in the - - - Postgres-XC backend when running in the - - - Postgres-XL backend when running in the - - bootstrap mode. The bootstrap mode allows system catalogs - to be created and filled from scratch, whereas ordinary SQL commands - require the catalogs to exist already. - BKI files can therefore be used to create the - database system in the first place. (And they are probably not - useful for anything else.) - - - - initdb uses a BKI file - to do part of its job when creating a new database cluster. The - input file used by initdb is created as - part of building and installing PostgreSQL - by a program named genbki.pl, which reads some - specially formatted C header files in the src/include/catalog/ - directory of the source tree. The created BKI file - is called postgres.bki and is - normally installed in the - share subdirectory of the installation tree. - - - - Related information can be found in the documentation for - initdb. - - - - <acronym>BKI</acronym> File Format - -&common; - - This section describes how the PostgreSQL - backend interprets BKI files. This description - will be easier to understand if the postgres.bki - file is at hand as an example. - - - - BKI input consists of a sequence of commands. Commands are made up - of a number of tokens, depending on the syntax of the command. - Tokens are usually separated by whitespace, but need not be if - there is no ambiguity. There is no special command separator; the - next token that syntactically cannot belong to the preceding - command starts a new one. (Usually you would put a new command on - a new line, for clarity.) Tokens can be certain key words, special - characters (parentheses, commas, etc.), numbers, or double-quoted - strings. Everything is case sensitive. - - - - Lines starting with # are ignored. - - - - - - <acronym>BKI</acronym> Commands - - - - - create - tablename - tableoid - bootstrap - shared_relation - without_oids - rowtype_oid oid - (name1 = - type1 , - name2 = type2, ...) - - - -&common; - - Create a table named tablename, and having the OID - tableoid, - with the columns given in parentheses. - - - - The following column types are supported directly by - bootstrap.c: bool, - bytea, char (1 byte), - name, int2, - int4, regproc, regclass, - regtype, text, - oid, tid, xid, - cid, int2vector, oidvector, - _int4 (array), _text (array), - _oid (array), _char (array), - _aclitem (array). Although it is possible to create - tables containing columns of other types, this cannot be done until - after pg_type has been created and filled with - appropriate entries. (That effectively means that only these - column types can be used in bootstrapped tables, but non-bootstrap - catalogs can contain any built-in type.) - - - - When bootstrap is specified, - the table will only be created on disk; nothing is entered into - pg_class, - pg_attribute, etc, for it. Thus the - table will not be accessible by ordinary SQL operations until - such entries are made the hard way (with insert - commands). This option is used for creating - pg_class etc themselves. - - - - The table is created as shared if shared_relation is - specified. - It will have OIDs unless without_oids is specified. - The table's row type OID (pg_type OID) can optionally - be specified via the rowtype_oid clause; if not specified, - an OID is automatically generated for it. (The rowtype_oid - clause is useless if bootstrap is specified, but it can be - provided anyway for documentation.) - - - - - - - open tablename - - - - - Open the table named - tablename - for insertion of data. Any currently open table is closed. - - - - - - - close tablename - - - - - Close the open table. The name of the table can be given as a - cross-check, but this is not required. - - - - - - - insert OID = oid_value ( value1 value2 ... ) - - - - - Insert a new row into the open table using value1, value2, etc., for its column - values and oid_value for its OID. If - oid_value is zero - (0) or the clause is omitted, and the table has OIDs, then the - next available OID is assigned. - - - - NULL values can be specified using the special key word - _null_. Values containing spaces must be - double quoted. - - - - - - - declare unique - index indexname - indexoid - on tablename - using amname - ( opclass1 - name1 - , ... ) - - - - - Create an index named indexname, having OID - indexoid, - on the table named - tablename, using the - amname access - method. The fields to index are called name1, name2 etc., and the operator - classes to use are opclass1, opclass2 etc., respectively. - The index file is created and appropriate catalog entries are - made for it, but the index contents are not initialized by this command. - - - - - - - declare toast - toasttableoid - toastindexoid - on tablename - - - - - Create a TOAST table for the table named - tablename. - The TOAST table is assigned OID - toasttableoid - and its index is assigned OID - toastindexoid. - As with declare index, filling of the index - is postponed. - - - - - - build indices - - - - Fill in the indices that have previously been declared. - - - - - - - - - Structure of the Bootstrap <acronym>BKI</acronym> File -&common; - - - The open command cannot be used until the tables it uses - exist and have entries for the table that is to be opened. - (These minimum tables are pg_class, - pg_attribute, pg_proc, and - pg_type.) To allow those tables themselves to be filled, - create with the bootstrap option implicitly opens - the created table for data insertion. - - - - Also, the declare index and declare toast - commands cannot be used until the system catalogs they need have been - created and filled in. - - - - Thus, the structure of the postgres.bki file has to - be: - - - - create bootstrap one of the critical tables - - - - - insert data describing at least the critical tables - - - - - close - - - - - Repeat for the other critical tables. - - - - - create (without bootstrap) a noncritical table - - - - - open - - - - - insert desired data - - - - - close - - - - - Repeat for the other noncritical tables. - - - - - Define indexes and toast tables. - - - - - build indices - - - - - - - There are doubtless other, undocumented ordering dependencies. - - - - - Example - -&common; - - The following sequence of commands will create the - table test_table with OID 420, having two columns - cola and colb of type - int4 and text, respectively, and insert - two rows into the table: - -create test_table 420 (cola = int4, colb = text) -open test_table -insert OID=421 ( 1 "value1" ) -insert OID=422 ( 2 _null_ ) -close test_table - - - - diff --git a/doc-xc/src/sgml/btree-gin.sgmlin b/doc-xc/src/sgml/btree-gin.sgmlin deleted file mode 100644 index 8e321bb891..0000000000 --- a/doc-xc/src/sgml/btree-gin.sgmlin +++ /dev/null @@ -1,59 +0,0 @@ - - - - btree_gin - - - btree_gin - - -&common; - - btree_gin provides sample GIN operator classes that - implement B-tree equivalent behavior for the data types - int2, int4, int8, float4, - float8, timestamp with time zone, - timestamp without time zone, time with time zone, - time without time zone, date, interval, - oid, money, "char", - varchar, text, bytea, bit, - varbit, macaddr, inet, and cidr. - - - - In general, these operator classes will not outperform the equivalent - standard B-tree index methods, and they lack one major feature of the - standard B-tree code: the ability to enforce uniqueness. However, - they are useful for GIN testing and as a base for developing other - GIN operator classes. Also, for queries that test both a GIN-indexable - column and a B-tree-indexable column, it might be more efficient to create - a multicolumn GIN index that uses one of these operator classes than to create - two separate indexes that would have to be combined via bitmap ANDing. - - - - Example Usage -&common; - -CREATE TABLE test (a int4); --- create index -CREATE INDEX testidx ON test USING gin (a); --- query -SELECT * FROM test WHERE a < 10; - - - - - - Authors - - - Teodor Sigaev (teodor@stack.net) and - Oleg Bartunov (oleg@sai.msu.su). See - - for additional information. - - - - - diff --git a/doc-xc/src/sgml/btree-gist.sgmlin b/doc-xc/src/sgml/btree-gist.sgmlin deleted file mode 100644 index c0348648bd..0000000000 --- a/doc-xc/src/sgml/btree-gist.sgmlin +++ /dev/null @@ -1,131 +0,0 @@ - - - - btree_gist - - - btree_gist - - -&common; - - - btree_gist provides GiST index operator classes that - implement B-tree equivalent behavior for the data types - int2, int4, int8, float4, - float8, numeric, timestamp with time zone, - timestamp without time zone, time with time zone, - time without time zone, date, interval, - oid, money, char, - varchar, text, bytea, bit, - varbit, macaddr, inet, and cidr. - - - - In general, these operator classes will not outperform the equivalent - standard B-tree index methods, and they lack one major feature of the - standard B-tree code: the ability to enforce uniqueness. However, - they provide some other features that are not available with a B-tree - index, as described below. Also, these operator classes are useful - when a multicolumn GiST index is needed, wherein some of the columns - are of data types that are only indexable with GiST but other columns - are just simple data types. Lastly, these operator classes are useful for - GiST testing and as a base for developing other GiST operator classes. - - - - - In addition to the typical B-tree search operators, btree_gist - also provides index support for <> (not - equals). This may be useful in combination with an - exclusion constraint, - as described below. - - - - In addition to the typical B-tree search operators, btree_gist - also provides index support for <> (not - equals). - - - - In addition to the typical B-tree search operators, btree_gist - also provides index support for <> (not - equals). - - - - - Also, for data types for which there is a natural distance metric, - btree_gist defines a distance operator <->, - and provides GiST index support for nearest-neighbor searches using - this operator. Distance operators are provided for - int2, int4, int8, float4, - float8, timestamp with time zone, - timestamp without time zone, - time without time zone, date, interval, - oid, and money. - - - - Example Usage - -&common; - - Simple example using btree_gist instead of btree: - - - -CREATE TABLE test (a int4); --- create index -CREATE INDEX testidx ON test USING gist (a); --- query -SELECT * FROM test WHERE a < 10; --- nearest-neighbor search: find the ten entries closest to "42" -SELECT *, a <-> 42 AS dist FROM test ORDER BY a <-> 42 LIMIT 10; - - - - - - Use an exclusion - constraint to enforce the rule that a cage at a zoo - can contain only one kind of animal: - - - -=> CREATE TABLE zoo ( - cage INTEGER, - animal TEXT, - EXCLUDE USING gist (cage WITH =, animal WITH <>) -); - -=> INSERT INTO zoo VALUES(123, 'zebra'); -INSERT 0 1 -=> INSERT INTO zoo VALUES(123, 'zebra'); -INSERT 0 1 -=> INSERT INTO zoo VALUES(123, 'lion'); -ERROR: conflicting key value violates exclusion constraint "zoo_cage_animal_excl" -DETAIL: Key (cage, animal)=(123, lion) conflicts with existing key (cage, animal)=(123, zebra). -=> INSERT INTO zoo VALUES(124, 'lion'); -INSERT 0 1 - - - - - - - - Authors - - - Teodor Sigaev (teodor@stack.net) , - Oleg Bartunov (oleg@sai.msu.su), and - Janko Richter (jankorichter@yahoo.de). See - - for additional information. - - - - - diff --git a/doc-xc/src/sgml/catalogs.sgmlin b/doc-xc/src/sgml/catalogs.sgmlin deleted file mode 100644 index bd949ddd57..0000000000 --- a/doc-xc/src/sgml/catalogs.sgmlin +++ /dev/null @@ -1,9076 +0,0 @@ - - - - - System Catalogs - -&common; - - - The system catalogs are the place where a relational database - management system stores schema metadata, such as information about - tables and columns, and internal bookkeeping information. - - PostgreSQL's system catalogs are regular - - - Postgres-XC's system catalogs are regular - - - Postgres-XL's system catalogs are regular - - tables. You can drop and recreate the tables, add columns, insert - and update values, and severely mess up your system that way. - Normally, one should not change the system catalogs by hand, there - are always SQL commands to do that. (For example, CREATE - DATABASE inserts a row into the - pg_database catalog — and actually - creates the database on disk.) There are some exceptions for - particularly esoteric operations, such as adding index access methods. - - - - Overview - -&common; - - lists the system catalogs. - More detailed documentation of each catalog follows below. - - - - Most system catalogs are copied from the template database during - database creation and are thereafter database-specific. A few - catalogs are physically shared across all databases in a cluster; - these are noted in the descriptions of the individual catalogs. - - - - System Catalogs - - - - - Catalog Name - Purpose - - - - - - pg_aggregate - aggregate functions - - - - pg_am - index access methods - - - - pg_amop - access method operators - - - - pg_amproc - access method support procedures - - - - pg_attrdef - column default values - - - - pg_attribute - table columns (attributes) - - - - pg_authid - authorization identifiers (roles) - - - - pg_auth_members - authorization identifier membership relationships - - - - pg_cast - casts (data type conversions) - - - - pg_class - tables, indexes, sequences, views (relations) - - - - pg_constraint - check constraints, unique constraints, primary key constraints, foreign key constraints - - - - pg_collation - collations (locale information) - - - - pg_conversion - encoding conversion information - - - - pg_database - databases within this database cluster - - - - pg_db_role_setting - per-role and per-database settings - - - - pg_default_acl - default privileges for object types - - - - pg_depend - dependencies between database objects - - - - pg_description - descriptions or comments on database objects - - - - pg_enum - enum label and value definitions - - - - pg_extension - installed extensions - - - - pg_foreign_data_wrapper - foreign-data wrapper definitions - - - - pg_foreign_server - foreign server definitions - - - - pg_foreign_table - additional foreign table information - - - - pg_index - additional index information - - - - pg_inherits - table inheritance hierarchy - - - - pg_language - languages for writing functions - - - - pg_largeobject - data pages for large objects - - - - pg_largeobject_metadata - metadata for large objects - - - - pg_namespace - schemas - - - - pg_opclass - access method operator classes - - - - pg_operator - operators - - - - pg_opfamily - access method operator families - - - - pg_pltemplate - template data for procedural languages - - - - pg_proc - functions and procedures - - - - pg_rewrite - query rewrite rules - - - - pg_seclabel - security labels on database objects - - - - pg_shdepend - dependencies on shared objects - - - - pg_shdescription - comments on shared objects - - - - pg_statistic - planner statistics - - - - pg_tablespace - tablespaces within this database cluster - - - - pg_trigger - triggers - - - - pg_ts_config - text search configurations - - - - pg_ts_config_map - text search configurations' token mappings - - - - pg_ts_dict - text search dictionaries - - - - pg_ts_parser - text search parsers - - - - pg_ts_template - text search templates - - - - pg_type - data types - - - - pg_user_mapping - mappings of users to foreign servers - - - - pgxc_class - replication or distribution information of tables (Postgres-XC only) - - - pgxc_node - Postgres-XC cluster nodes (Postgres-XC only) - - - pgxc_group - Postgres-XC cluster node groups (Postgres-XC only) - - - - - pgxc_class - replication or distribution information of tables (Postgres-XL only) - - - pgxc_node - Postgres-XL cluster nodes (Postgres-XC only) - - - pgxc_group - Postgres-XL cluster node groups (Postgres-XC only) - - - - -
- - - - - <structname>pg_aggregate</structname> - - - pg_aggregate - - -&common; - - The catalog pg_aggregate stores information about - aggregate functions. An aggregate function is a function that - operates on a set of values (typically one column from each row - that matches a query condition) and returns a single value computed - from all these values. Typical aggregate functions are - sum, count, and - max. Each entry in - pg_aggregate is an extension of an entry - in pg_proc. The pg_proc - entry carries the aggregate's name, input and output data types, and - other information that is similar to ordinary functions. - - - - <structname>pg_aggregate</> Columns - - - - - Name - Type - References - Description - - - - - aggfnoid - regproc - pg_proc.oid - pg_proc OID of the aggregate function - - - aggtransfn - regproc - pg_proc.oid - Transition function - - - - aggcollectfn - regproc - pg_proc.oid - Collection function (Only for Postgres-XC> - - - - - aggcollectfn - regproc - pg_proc.oid - Collection function (Only for Postgres-XL>) - - - - aggfinalfn - regproc - pg_proc.oid - Final function (zero if none) - - - aggsortop - oid - pg_operator.oid - Associated sort operator (zero if none) - - - aggtranstype - oid - pg_type.oid - - Data type of the aggregate function's internal transition (state) data - - - Data type of the aggregate function's internal transition and collection (state) data (Revised for Postgres-XC) - - - Data type of the aggregate function's internal transition and collection (state) data (Revised for Postgres-XL) - - - - agginitval - text - - - The initial value of the transition state. This is a text - field containing the initial value in its external string - representation. If this field is null, the transition state - value starts out null. - - - - - agginitcollect - text - - - The initial value of the collection state. This is a text - field containing the initial value in its external string - representation. If this field is null, the collection state - value starts out null. (Only for Postgres-XC) - - - - - - agginitcollect - text - - - The initial value of the collection state. This is a text - field containing the initial value in its external string - representation. If this field is null, the collection state - value starts out null. (Only for Postgres-XL) - - - - - -
- - - New aggregate functions are registered with the - command. See for more information about - writing aggregate functions and the meaning of the transition - functions, etc. - - - - - - - <structname>pg_am</structname> - - - pg_am - - -&common; - - The catalog pg_am stores information about index - access methods. There is one row for each index access method supported by - the system. The contents of this catalog are discussed in detail in - . - - - - <structname>pg_am</> Columns - - - - - Name - Type - References - Description - - - - - - amname - name - - Name of the access method - - - - amstrategies - int2 - - Number of operator strategies for this access method, - or zero if access method does not have a fixed set of operator - strategies - - - - amsupport - int2 - - Number of support routines for this access method - - - - amcanorder - bool - - Does the access method support ordered scans sorted by the - indexed column's value? - - - - amcanorderbyop - bool - - Does the access method support ordered scans sorted by the result - of an operator on the indexed column? - - - - amcanbackward - bool - - Does the access method support backward scanning? - - - - amcanunique - bool - - Does the access method support unique indexes? - - - - amcanmulticol - bool - - Does the access method support multicolumn indexes? - - - - amoptionalkey - bool - - Does the access method support a scan without any constraint - for the first index column? - - - - amsearchnulls - bool - - Does the access method support IS NULL/NOT NULL searches? - - - - amstorage - bool - - Can index storage data type differ from column data type? - - - - amclusterable - bool - - Can an index of this type be clustered on? - - - - ampredlocks - bool - - Does an index of this type manage fine-grained predicate locks? - - - - amkeytype - oid - pg_type.oid - Type of data stored in index, or zero if not a fixed type - - - - aminsert - regproc - pg_proc.oid - Insert this tuple function - - - - ambeginscan - regproc - pg_proc.oid - Prepare for index scan function - - - - amgettuple - regproc - pg_proc.oid - Next valid tuple function, or zero if none - - - - amgetbitmap - regproc - pg_proc.oid - Fetch all valid tuples function, or zero if none - - - - amrescan - regproc - pg_proc.oid - (Re)start index scan function - - - - amendscan - regproc - pg_proc.oid - Clean up after index scan function - - - - ammarkpos - regproc - pg_proc.oid - Mark current scan position function - - - - amrestrpos - regproc - pg_proc.oid - Restore marked scan position function - - - - ambuild - regproc - pg_proc.oid - Build new index function - - - - ambuildempty - regproc - pg_proc.oid - Build empty index function - - - - ambulkdelete - regproc - pg_proc.oid - Bulk-delete function - - - - amvacuumcleanup - regproc - pg_proc.oid - Post-VACUUM cleanup function - - - - amcostestimate - regproc - pg_proc.oid - Function to estimate cost of an index scan - - - - amoptions - regproc - pg_proc.oid - Function to parse and validate reloptions for an index - - - - -
- - - - - - <structname>pg_amop</structname> - - - pg_amop - - -&common; - - The catalog pg_amop stores information about - operators associated with access method operator families. There is one - row for each operator that is a member of an operator family. A family - member can be either a search operator or an - ordering operator. An operator - can appear in more than one family, but cannot appear in more than one - search position nor more than one ordering position within a family. - (It is allowed, though unlikely, for an operator to be used for both - search and ordering purposes.) - - - - <structname>pg_amop</> Columns - - - - - Name - Type - References - Description - - - - - - amopfamily - oid - pg_opfamily.oid - The operator family this entry is for - - - - amoplefttype - oid - pg_type.oid - Left-hand input data type of operator - - - - amoprighttype - oid - pg_type.oid - Right-hand input data type of operator - - - - amopstrategy - int2 - - Operator strategy number - - - - amoppurpose - char - - Operator purpose, either s for search or - o for ordering - - - - amopopr - oid - pg_operator.oid - OID of the operator - - - - amopmethod - oid - pg_am.oid - Index access method operator family is for - - - - amopsortfamily - oid - pg_opfamily.oid - The btree operator family this entry sorts according to, if an - ordering operator; zero if a search operator - - - - -
- - - A search operator entry indicates that an index of this operator - family can be searched to find all rows satisfying - WHERE - indexed_column - operator - constant. - Obviously, such an operator must return boolean, and its left-hand input - type must match the index's column data type. - - - - An ordering operator entry indicates that an index of this - operator family can be scanned to return rows in the order represented by - ORDER BY - indexed_column - operator - constant. - Such an operator could return any sortable data type, though again - its left-hand input type must match the index's column data type. - The exact semantics of the ORDER BY are specified by the - amopsortfamily column, which must reference - a btree operator family for the operator's result type. - - - - - At present, it's assumed that the sort order for an ordering operator - is the default for the referenced opfamily, i.e., ASC NULLS - LAST. This might someday be relaxed by adding additional columns - to specify sort options explicitly. - - - - - An entry's amopmethod must match the - opfmethod of its containing operator family (including - amopmethod here is an intentional denormalization of the - catalog structure for performance reasons). Also, - amoplefttype and amoprighttype must match - the oprleft and oprright fields of the - referenced pg_operator entry. - - - - - - - <structname>pg_amproc</structname> - - - pg_amproc - - -&common; - - The catalog pg_amproc stores information about - support procedures associated with access method operator families. There - is one row for each support procedure belonging to an operator family. - - - - <structname>pg_amproc</structname> Columns - - - - - Name - Type - References - Description - - - - - - amprocfamily - oid - pg_opfamily.oid - The operator family this entry is for - - - - amproclefttype - oid - pg_type.oid - Left-hand input data type of associated operator - - - - amprocrighttype - oid - pg_type.oid - Right-hand input data type of associated operator - - - - amprocnum - int2 - - Support procedure number - - - - amproc - regproc - pg_proc.oid - OID of the procedure - - - - -
- - - The usual interpretation of the - amproclefttype and amprocrighttype fields - is that they identify the left and right input types of the operator(s) - that a particular support procedure supports. For some access methods - these match the input data type(s) of the support procedure itself, for - others not. There is a notion of default support procedures for - an index, which are those with amproclefttype and - amprocrighttype both equal to the index opclass's - opcintype. - - - - - - - <structname>pg_attrdef</structname> - - - pg_attrdef - - -&common; - - The catalog pg_attrdef stores column default values. The main information - about columns is stored in pg_attribute - (see below). Only columns that explicitly specify a default value - (when the table is created or the column is added) will have an - entry here. - - - - <structname>pg_attrdef</> Columns - - - - - Name - Type - References - Description - - - - - - adrelid - oid - pg_class.oid - The table this column belongs to - - - - adnum - int2 - pg_attribute.attnum - The number of the column - - - - adbin - pg_node_tree - - The internal representation of the column default value - - - - adsrc - text - - A human-readable representation of the default value - - - -
- - - The adsrc field is historical, and is best - not used, because it does not track outside changes that might affect - the representation of the default value. Reverse-compiling the - adbin field (with pg_get_expr for - example) is a better way to display the default value. - - - - - - - <structname>pg_attribute</structname> - - - pg_attribute - - -&common; - - The catalog pg_attribute stores information about - table columns. There will be exactly one - pg_attribute row for every column in every - table in the database. (There will also be attribute entries for - indexes, and indeed all objects that have pg_class - entries.) - - - - The term attribute is equivalent to column and is used for - historical reasons. - - - - <structname>pg_attribute</> Columns - - - - - Name - Type - References - Description - - - - - - attrelid - oid - pg_class.oid - The table this column belongs to - - - - attname - name - - The column name - - - - atttypid - oid - pg_type.oid - The data type of this column - - - - attstattarget - int4 - - - attstattarget controls the level of detail - of statistics accumulated for this column by - . - A zero value indicates that no statistics should be collected. - A negative value says to use the system default statistics target. - The exact meaning of positive values is data type-dependent. - For scalar data types, attstattarget - is both the target number of most common values - to collect, and the target number of histogram bins to create. - - - - - attlen - int2 - - - A copy of pg_type.typlen of this column's - type - - - - - attnum - int2 - - - The number of the column. Ordinary columns are numbered from 1 - up. System columns, such as oid, - have (arbitrary) negative numbers. - - - - - attndims - int4 - - - Number of dimensions, if the column is an array type; otherwise 0. - (Presently, the number of dimensions of an array is not enforced, - so any nonzero value effectively means it's an array.) - - - - - attcacheoff - int4 - - - Always -1 in storage, but when loaded into a row descriptor - in memory this might be updated to cache the offset of the attribute - within the row - - - - - atttypmod - int4 - - - atttypmod records type-specific data - supplied at table creation time (for example, the maximum - length of a varchar column). It is passed to - type-specific input functions and length coercion functions. - The value will generally be -1 for types that do not need atttypmod. - - - - - attbyval - bool - - - A copy of pg_type.typbyval of this column's type - - - - - attstorage - char - - - Normally a copy of pg_type.typstorage of this - column's type. For TOAST-able data types, this can be altered - after column creation to control storage policy. - - - - - attalign - char - - - A copy of pg_type.typalign of this column's type - - - - - attnotnull - bool - - - This represents a not-null constraint. It is possible to - change this column to enable or disable the constraint. - - - - - atthasdef - bool - - - This column has a default value, in which case there will be a - corresponding entry in the pg_attrdef - catalog that actually defines the value. - - - - - attisdropped - bool - - - This column has been dropped and is no longer valid. A dropped - column is still physically present in the table, but is - ignored by the parser and so cannot be accessed via SQL. - - - - - attislocal - bool - - - This column is defined locally in the relation. Note that a column can - be locally defined and inherited simultaneously. - - - - - attinhcount - int4 - - - The number of direct ancestors this column has. A column with a - nonzero number of ancestors cannot be dropped nor renamed. - - - - - attcollation - oid - pg_collation.oid - - The defined collation of the column, or zero if the column is - not of a collatable data type. - - - - - attacl - aclitem[] - - - Column-level access privileges, if any have been granted specifically - on this column - - - - - attoptions - text[] - - - Attribute-level options, as keyword=value strings - - - - - -
- - - In a dropped column's pg_attribute entry, - atttypid is reset to zero, but - attlen and the other fields copied from - pg_type are still valid. This arrangement is needed - to cope with the situation where the dropped column's data type was - later dropped, and so there is no pg_type row anymore. - attlen and the other fields can be used - to interpret the contents of a row of the table. - - - - - - <structname>pg_authid</structname> - - - pg_authid - - -&common; - - The catalog pg_authid contains information about - database authorization identifiers (roles). A role subsumes the concepts - of users and groups. A user is essentially just a - role with the rolcanlogin flag set. Any role (with or - without rolcanlogin) can have other roles as members; see - pg_auth_members. - - - - Since this catalog contains passwords, it must not be publicly readable. - pg_roles - is a publicly readable view on - pg_authid that blanks out the password field. - - - - contains detailed information about user and - privilege management. - - - - Because user identities are cluster-wide, - pg_authid - is shared across all databases of a cluster: there is only one - copy of pg_authid per cluster, not - one per database. - - - - <structname>pg_authid</> Columns - - - - - Name - Type - Description - - - - - - rolname - name - Role name - - - - rolsuper - bool - Role has superuser privileges - - - - rolinherit - bool - Role automatically inherits privileges of roles it is a - member of - - - - rolcreaterole - bool - Role can create more roles - - - - rolcreatedb - bool - Role can create databases - - - - rolcatupdate - bool - - Role can update system catalogs directly. (Even a superuser cannot do - this unless this column is true) - - - - - rolcanlogin - bool - - Role can log in. That is, this role can be given as the initial - session authorization identifier. - - - - - rolreplication - bool - - Role is a replication role. That is, this role can initiate streaming - replication (see ) and set/unset - the system backup mode using pg_start_backup and - pg_stop_backup. - - - - - rolconnlimit - int4 - - For roles that can log in, this sets maximum number of concurrent - connections this role can make. -1 means no limit. - - - - - rolpassword - text - - Password (possibly encrypted); null if none. If the password - is encrypted, this column will begin with the string md5 - followed by a 32-character hexadecimal MD5 hash. The MD5 hash - will be of the user's password concatenated to their user name. - For example, if user joe has password xyzzy, - PostgreSQL will store the md5 hash of - xyzzyjoe. A password that does not follow that - format is assumed to be unencrypted. - - - - - rolvaliduntil - timestamptz - Password expiry time (only used for password authentication); - null if no expiration - - - -
- - - - - - <structname>pg_auth_members</structname> - - - pg_auth_members - - -&common; - - The catalog pg_auth_members shows the membership - relations between roles. Any non-circular set of relationships is allowed. - - - - Because user identities are cluster-wide, - pg_auth_members - is shared across all databases of a cluster: there is only one - copy of pg_auth_members per cluster, not - one per database. - - - - <structname>pg_auth_members</> Columns - - - - - Name - Type - References - Description - - - - - - roleid - oid - pg_authid.oid - ID of a role that has a member - - - - member - oid - pg_authid.oid - ID of a role that is a member of roleid - - - - grantor - oid - pg_authid.oid - ID of the role that granted this membership - - - - admin_option - bool - - True if member can grant membership in - roleid to others - - - -
- - - - - - <structname>pg_cast</structname> - - - pg_cast - - -&common; - - The catalog pg_cast stores data type conversion - paths, both built-in paths and those defined with - . - - - - It should be noted that pg_cast does not represent - every type conversion that the system knows how to perform; only those that - cannot be deduced from some generic rule. For example, casting between a - domain and its base type is not explicitly represented in - pg_cast. Another important exception is that - automatic I/O conversion casts, those performed using a data - type's own I/O functions to convert to or from text or other - string types, are not explicitly represented in - pg_cast. - - - - <structname>pg_cast</> Columns - - - - - Name - Type - References - Description - - - - - - castsource - oid - pg_type.oid - OID of the source data type - - - - casttarget - oid - pg_type.oid - OID of the target data type - - - - castfunc - oid - pg_proc.oid - - The OID of the function to use to perform this cast. Zero is - stored if the cast method doesn't require a function. - - - - - castcontext - char - - - Indicates what contexts the cast can be invoked in. - e means only as an explicit cast (using - CAST or :: syntax). - a means implicitly in assignment - to a target column, as well as explicitly. - i means implicitly in expressions, as well as the - other cases. - - - - castmethod - char - - - Indicates how the cast is performed. - f means that the function specified in the castfunc field is used. - i means that the input/output functions are used. - b means that the types are binary-coercible, thus no conversion is required. - - - - -
- - - The cast functions listed in pg_cast must - always take the cast source type as their first argument type, and - return the cast destination type as their result type. A cast - function can have up to three arguments. The second argument, - if present, must be type integer; it receives the type - modifier associated with the destination type, or -1 - if there is none. The third argument, - if present, must be type boolean; it receives true - if the cast is an explicit cast, false otherwise. - - - - It is legitimate to create a pg_cast entry - in which the source and target types are the same, if the associated - function takes more than one argument. Such entries represent - length coercion functions that coerce values of the type - to be legal for a particular type modifier value. - - - - When a pg_cast entry has different source and - target types and a function that takes more than one argument, it - represents converting from one type to another and applying a length - coercion in a single step. When no such entry is available, coercion - to a type that uses a type modifier involves two steps, one to - convert between data types and a second to apply the modifier. - - - - - <structname>pg_class</structname> - - - pg_class - - -&common; - - The catalog pg_class catalogs tables and most - everything else that has columns or is otherwise similar to a - table. This includes indexes (but see also - pg_index), sequences, views, composite types, - and TOAST tables; see relkind. - Below, when we mean all of these - kinds of objects we speak of relations. Not all - columns are meaningful for all relation types. - - - - <structname>pg_class</> Columns - - - - - Name - Type - References - Description - - - - - - relname - name - - Name of the table, index, view, etc. - - - - relnamespace - oid - pg_namespace.oid - - The OID of the namespace that contains this relation - - - - - reltype - oid - pg_type.oid - - The OID of the data type that corresponds to this table's row type, - if any (zero for indexes, which have no pg_type entry) - - - - - reloftype - oid - pg_type.oid - - For typed tables, the OID of the underlying composite type, - zero for all other relations - - - - - relowner - oid - pg_authid.oid - Owner of the relation - - - - relam - oid - pg_am.oid - If this is an index, the access method used (B-tree, hash, etc.) - - - - relfilenode - oid - - Name of the on-disk file of this relation; zero means this - is a mapped relation whose disk file name is determined - by low-level state - - - - reltablespace - oid - pg_tablespace.oid - - The tablespace in which this relation is stored. If zero, - the database's default tablespace is implied. (Not meaningful - if the relation has no on-disk file.) - - - - - relpages - int4 - - - Size of the on-disk representation of this table in pages (of size - BLCKSZ). This is only an estimate used by the - planner. It is updated by VACUUM, - ANALYZE, and a few DDL commands such as - CREATE INDEX. - - - - - reltuples - float4 - - - Number of rows in the table. This is only an estimate used by the - planner. It is updated by VACUUM, - ANALYZE, and a few DDL commands such as - CREATE INDEX. - - - - - reltoastrelid - oid - pg_class.oid - - OID of the TOAST table associated with this table, 0 if none. The - TOAST table stores large attributes out of line in a - secondary table. - - - - - reltoastidxid - oid - pg_class.oid - - For a TOAST table, the OID of its index. 0 if not a TOAST table. - - - - - relhasindex - bool - - - True if this is a table and it has (or recently had) any indexes - - - - - relisshared - bool - - - True if this table is shared across all databases in the cluster. Only - certain system catalogs (such as pg_database) - are shared. - - - - - relpersistence - char - - - p = permanent table, u = unlogged table, - t = temporary table - - - - - relkind - char - - - r = ordinary table, i = index, - S = sequence, v = view, c = - composite type, t = TOAST table, - f = foreign table - - - - - relnatts - int2 - - - Number of user columns in the relation (system columns not - counted). There must be this many corresponding entries in - pg_attribute. See also - pg_attribute.attnum. - - - - - relchecks - int2 - - - Number of CHECK constraints on the table; see - pg_constraint catalog - - - - - relhasoids - bool - - - True if we generate an OID for each row of the relation - - - - - relhaspkey - bool - - - True if the table has (or once had) a primary key - - - - - relhasrules - bool - - - True if table has (or once had) rules; see - pg_rewrite catalog - - - - - relhastriggers - bool - - - True if table has (or once had) triggers; see - pg_trigger catalog - - - - - relhassubclass - bool - - True if table has (or once had) any inheritance children - - - - relfrozenxid - xid - - - All transaction IDs before this one have been replaced with a permanent - (frozen) transaction ID in this table. This is used to track - whether the table needs to be vacuumed in order to prevent transaction - ID wraparound or to allow pg_clog to be shrunk. Zero - (InvalidTransactionId) if the relation is not a table. - - - - - relacl - aclitem[] - - - Access privileges; see - and - - for details - - - - - reloptions - text[] - - - Access-method-specific options, as keyword=value strings - - - - -
- - - Several of the Boolean flags in pg_class are maintained - lazily: they are guaranteed to be true if that's the correct state, but - may not be reset to false immediately when the condition is no longer - true. For example, relhasindex is set by - CREATE INDEX, but it is never cleared by - DROP INDEX. Instead, VACUUM clears - relhasindex if it finds the table has no indexes. This - arrangement avoids race conditions and improves concurrency. - - - - - <structname>pg_constraint</structname> - - - pg_constraint - - -&common; - - The catalog pg_constraint stores check, primary - key, unique, foreign key, and exclusion constraints on tables. - (Column constraints are not treated specially. Every column constraint is - equivalent to some table constraint.) - Not-null constraints are represented in the pg_attribute - catalog, not here. - - - - User-defined constraint triggers (created with CREATE CONSTRAINT - TRIGGER) also give rise to an entry in this table. - - - - Check constraints on domains are stored here, too. - - - - <structname>pg_constraint</> Columns - - - - - Name - Type - References - Description - - - - - - conname - name - - Constraint name (not necessarily unique!) - - - - connamespace - oid - pg_namespace.oid - - The OID of the namespace that contains this constraint - - - - - contype - char - - - c = check constraint, - f = foreign key constraint, - p = primary key constraint, - u = unique constraint, - t = constraint trigger, - x = exclusion constraint - - - - - condeferrable - bool - - Is the constraint deferrable? - - - - condeferred - bool - - Is the constraint deferred by default? - - - - convalidated - bool - - Has the constraint been validated? Can only be false for foreign keys - - - - conrelid - oid - pg_class.oid - The table this constraint is on; 0 if not a table constraint - - - - contypid - oid - pg_type.oid - The domain this constraint is on; 0 if not a domain constraint - - - - conindid - oid - pg_class.oid - The index supporting this constraint, if it's a unique, primary - key, foreign key, or exclusion constraint; else 0 - - - - confrelid - oid - pg_class.oid - If a foreign key, the referenced table; else 0 - - - - confupdtype - char - - Foreign key update action code: - a = no action, - r = restrict, - c = cascade, - n = set null, - d = set default - - - - - confdeltype - char - - Foreign key deletion action code: - a = no action, - r = restrict, - c = cascade, - n = set null, - d = set default - - - - - confmatchtype - char - - Foreign key match type: - f = full, - p = partial, - u = simple (unspecified) - - - - - conislocal - bool - - - This constraint is defined locally for the relation. Note that a - constraint can be locally defined and inherited simultaneously. - - - - - coninhcount - int4 - - - The number of direct inheritance ancestors this constraint has. - A constraint with - a nonzero number of ancestors cannot be dropped nor renamed. - - - - - conkey - int2[] - pg_attribute.attnum - If a table constraint (including foreign keys, but not constraint - triggers), list of the constrained columns - - - - confkey - int2[] - pg_attribute.attnum - If a foreign key, list of the referenced columns - - - - conpfeqop - oid[] - pg_operator.oid - If a foreign key, list of the equality operators for PK = FK comparisons - - - - conppeqop - oid[] - pg_operator.oid - If a foreign key, list of the equality operators for PK = PK comparisons - - - - conffeqop - oid[] - pg_operator.oid - If a foreign key, list of the equality operators for FK = FK comparisons - - - - conexclop - oid[] - pg_operator.oid - If an exclusion constraint, list of the per-column exclusion operators - - - - conbin - pg_node_tree - - If a check constraint, an internal representation of the expression - - - - consrc - text - - If a check constraint, a human-readable representation of the expression - - - -
- - - In the case of an exclusion constraint, conkey - is only useful for constraint elements that are simple column references. - For other cases, a zero appears in conkey - and the associated index must be consulted to discover the expression - that is constrained. (conkey thus has the - same contents as pg_index.indkey for the - index.) - - - - - consrc is not updated when referenced objects - change; for example, it won't track renaming of columns. Rather than - relying on this field, it's best to use pg_get_constraintdef() - to extract the definition of a check constraint. - - - - - - pg_class.relchecks needs to agree with the - number of check-constraint entries found in this table for each - relation. - - - - - - - <structname>pg_collation</structname> - - - pg_collation - - -&common; - - The catalog pg_collation describes the - available collations, which are essentially mappings from an SQL - name to operating system locale categories. - See for more information. - - - - <structname>pg_collation</> Columns - - - - - Name - Type - References - Description - - - - - - collname - name - - Collation name (unique per namespace and encoding) - - - - collnamespace - oid - pg_namespace.oid - - The OID of the namespace that contains this collation - - - - - collowner - oid - pg_authid.oid - Owner of the collation - - - - collencoding - int4 - - Encoding in which the collation is applicable, or -1 if it - works for any encoding - - - - collcollate - name - - LC_COLLATE for this collation object - - - - collctype - name - - LC_CTYPE for this collation object - - - -
- - - Note that the unique key on this catalog is (collname, - collencoding, collnamespace) not just - (collname, collnamespace). - PostgreSQL generally ignores all - collations that do not have collencoding equal to - either the current database's encoding or -1, and creation of new entries - with the same name as an entry with collencoding = -1 - is forbidden. Therefore it is sufficient to use a qualified SQL name - (schema.name) to identify a collation, - even though this is not unique according to the catalog definition. - The reason for defining the catalog this way is that - initdb fills it in at cluster initialization time with - entries for all locales available on the system, so it must be able to - hold entries for all encodings that might ever be used in the cluster. - - - - In the template0 database, it could be useful to create - collations whose encoding does not match the database encoding, - since they could match the encodings of databases later cloned from - template0. This would currently have to be done manually. - - - - - <structname>pg_conversion</structname> - - - pg_conversion - - - - The catalog pg_conversion describes - encoding conversion procedures. See - for more information. - - - - <structname>pg_conversion</> Columns - - - - - Name - Type - References - Description - - - - - - conname - name - - Conversion name (unique within a namespace) - - - - connamespace - oid - pg_namespace.oid - - The OID of the namespace that contains this conversion - - - - - conowner - oid - pg_authid.oid - Owner of the conversion - - - - conforencoding - int4 - - Source encoding ID - - - - contoencoding - int4 - - Destination encoding ID - - - - conproc - regproc - pg_proc.oid - Conversion procedure - - - - condefault - bool - - True if this is the default conversion - - - - -
- - - - - <structname>pg_database</structname> - - - pg_database - - -&common; - - The catalog pg_database stores information about - the available databases. Databases are created with the command. - Consult for details about the meaning - of some of the parameters. - - - - Unlike most system catalogs, pg_database - is shared across all databases of a cluster: there is only one - copy of pg_database per cluster, not - one per database. - - - - <structname>pg_database</> Columns - - - - - Name - Type - References - Description - - - - - - datname - name - - Database name - - - - datdba - oid - pg_authid.oid - Owner of the database, usually the user who created it - - - - encoding - int4 - - Character encoding for this database - (pg_encoding_to_char() can translate - this number to the encoding name) - - - - datcollate - name - - LC_COLLATE for this database - - - - datctype - name - - LC_CTYPE for this database - - - - datistemplate - bool - - - If true then this database can be used in the - TEMPLATE clause of CREATE - DATABASE to create a new database as a clone of - this one - - - - - datallowconn - bool - - - If false then no one can connect to this database. This is - used to protect the template0 database from being altered. - - - - - datconnlimit - int4 - - - Sets maximum number of concurrent connections that can be made - to this database. -1 means no limit. - - - - - datlastsysoid - oid - - - Last system OID in the database; useful - particularly to pg_dump - - - - - datfrozenxid - xid - - - All transaction IDs before this one have been replaced with a permanent - (frozen) transaction ID in this database. This is used to - track whether the database needs to be vacuumed in order to prevent - transaction ID wraparound or to allow pg_clog to be shrunk. - It is the minimum of the per-table - pg_class.relfrozenxid values. - - - - - dattablespace - oid - pg_tablespace.oid - - The default tablespace for the database. - Within this database, all tables for which - pg_class.reltablespace is zero - will be stored in this tablespace; in particular, all the non-shared - system catalogs will be there. - - - - - datacl - aclitem[] - - - Access privileges; see - and - - for details - - - - -
- - - - - <structname>pg_db_role_setting</structname> - - - pg_db_role_setting - - -&common; - - The catalog pg_db_role_setting records the default - values that have been set for run-time configuration variables, - for each role and database combination. - - - - Unlike most system catalogs, pg_db_role_setting - is shared across all databases of a cluster: there is only one - copy of pg_db_role_setting per cluster, not - one per database. - - - - <structname>pg_db_role_setting</> Columns - - - - - Name - Type - References - Description - - - - - - setdatabase - oid - pg_database.oid - The OID of the database the setting is applicable to, or zero if not database-specific - - - - setrole - oid - pg_authid.oid - The OID of the role the setting is applicable to, or zero if not role-specific - - - - setconfig - text[] - - Defaults for run-time configuration variables - - - -
- - - - - <structname>pg_default_acl</structname> - - - pg_default_acl - - -&common; - - The catalog pg_default_acl stores initial - privileges to be assigned to newly created objects. - - - - <structname>pg_default_acl</> Columns - - - - - Name - Type - References - Description - - - - - - defaclrole - oid - pg_authid.oid - The OID of the role associated with this entry - - - - defaclnamespace - oid - pg_namespace.oid - The OID of the namespace associated with this entry, - or 0 if none - - - - defaclobjtype - char - - - Type of object this entry is for: - r = relation (table, view), - S = sequence, - f = function - - - - - defaclacl - aclitem[] - - - Access privileges that this type of object should have on creation - - - - -
- - - A pg_default_acl entry shows the initial privileges to - be assigned to an object belonging to the indicated user. There are - currently two types of entry: global entries with - defaclnamespace = 0, and per-schema entries - that reference a particular schema. If a global entry is present then - it overrides the normal hard-wired default privileges - for the object type. A per-schema entry, if present, represents privileges - to be added to the global or hard-wired default privileges. - - - - Note that when an ACL entry in another catalog is null, it is taken - to represent the hard-wired default privileges for its object, - not whatever might be in pg_default_acl - at the moment. pg_default_acl is only consulted during - object creation. - - - - - - - <structname>pg_depend</structname> - - - pg_depend - - -&common; - - The catalog pg_depend records the dependency - relationships between database objects. This information allows - DROP commands to find which other objects must be dropped - by DROP CASCADE or prevent dropping in the DROP - RESTRICT case. - - - - See also pg_shdepend, - which performs a similar function for dependencies involving objects - that are shared across a database cluster. - - - - <structname>pg_depend</> Columns - - - - - Name - Type - References - Description - - - - - - classid - oid - pg_class.oid - The OID of the system catalog the dependent object is in - - - - objid - oid - any OID column - The OID of the specific dependent object - - - - objsubid - int4 - - - For a table column, this is the column number (the - objid and classid refer to the - table itself). For all other object types, this column is - zero. - - - - - refclassid - oid - pg_class.oid - The OID of the system catalog the referenced object is in - - - - refobjid - oid - any OID column - The OID of the specific referenced object - - - - refobjsubid - int4 - - - For a table column, this is the column number (the - refobjid and refclassid refer - to the table itself). For all other object types, this column - is zero. - - - - - deptype - char - - - A code defining the specific semantics of this dependency relationship; see text - - - - - -
- - - In all cases, a pg_depend entry indicates that the - referenced object cannot be dropped without also dropping the dependent - object. However, there are several subflavors identified by - deptype: - - - - DEPENDENCY_NORMAL (n) - - - A normal relationship between separately-created objects. The - dependent object can be dropped without affecting the - referenced object. The referenced object can only be dropped - by specifying CASCADE, in which case the dependent - object is dropped, too. Example: a table column has a normal - dependency on its data type. - - - - - - DEPENDENCY_AUTO (a) - - - The dependent object can be dropped separately from the - referenced object, and should be automatically dropped - (regardless of RESTRICT or CASCADE - mode) if the referenced object is dropped. Example: a named - constraint on a table is made autodependent on the table, so - that it will go away if the table is dropped. - - - - - - DEPENDENCY_INTERNAL (i) - - - The dependent object was created as part of creation of the - referenced object, and is really just a part of its internal - implementation. A DROP of the dependent object - will be disallowed outright (we'll tell the user to issue a - DROP against the referenced object, instead). A - DROP of the referenced object will be propagated - through to drop the dependent object whether - CASCADE is specified or not. Example: a trigger - that's created to enforce a foreign-key constraint is made - internally dependent on the constraint's - pg_constraint entry. - - - - - - DEPENDENCY_EXTENSION (e) - - - The dependent object is a member of the extension that is - the referenced object (see - pg_extension). - The dependent object can be dropped only via - DROP EXTENSION on the referenced object. Functionally - this dependency type acts the same as an internal dependency, but - it's kept separate for clarity and to simplify pg_dump. - - - - - - DEPENDENCY_PIN (p) - - - There is no dependent object; this type of entry is a signal - that the system itself depends on the referenced object, and so - that object must never be deleted. Entries of this type are - created only by initdb. The columns for the - dependent object contain zeroes. - - - - - - Other dependency flavors might be needed in future. - - - - - - - <structname>pg_description</structname> - - - pg_description - - -&common; - - The catalog pg_description stores optional descriptions - (comments) for each database object. Descriptions can be manipulated - with the command and viewed with - psql's \d commands. - Descriptions of many built-in system objects are provided in the initial - contents of pg_description. - - - - See also pg_shdescription, - which performs a similar function for descriptions involving objects that - are shared across a database cluster. - - - - <structname>pg_description</> Columns - - - - - Name - Type - References - Description - - - - - - objoid - oid - any OID column - The OID of the object this description pertains to - - - - classoid - oid - pg_class.oid - The OID of the system catalog this object appears in - - - - objsubid - int4 - - - For a comment on a table column, this is the column number (the - objoid and classoid refer to - the table itself). For all other object types, this column is - zero. - - - - - description - text - - Arbitrary text that serves as the description of this object - - - -
- - - - - - <structname>pg_enum</structname> - - - pg_enum - - -&common; - - The pg_enum catalog contains entries - showing the values and labels for each enum type. The - internal representation of a given enum value is actually the OID - of its associated row in pg_enum. - - - - <structname>pg_enum</> Columns - - - - - Name - Type - References - Description - - - - - - enumtypid - oid - pg_type.oid - The OID of the pg_type entry owning this enum value - - - - enumsortorder - float4 - - The sort position of this enum value within its enum type - - - - enumlabel - name - - The textual label for this enum value - - - -
- - - The OIDs for pg_enum rows follow a special - rule: even-numbered OIDs are guaranteed to be ordered in the same way - as the sort ordering of their enum type. That is, if two even OIDs - belong to the same enum type, the smaller OID must have the smaller - enumsortorder value. Odd-numbered OID values - need bear no relationship to the sort order. This rule allows the - enum comparison routines to avoid catalog lookups in many common cases. - The routines that create and alter enum types attempt to assign even - OIDs to enum values whenever possible. - - - - When an enum type is created, its members are assigned sort-order - positions 1..n. But members added later might be given - negative or fractional values of enumsortorder. - The only requirement on these values is that they be correctly - ordered and unique within each enum type. - - - - - - <structname>pg_extension</structname> - - - pg_extension - - - - The catalog pg_extension stores information - about the installed extensions. See - for details about extensions. - - - - <structname>pg_extension</> Columns - - - - - Name - Type - References - Description - - - - - - extname - name - - Name of the extension - - - - extowner - oid - pg_authid.oid - Owner of the extension - - - - extnamespace - oid - pg_namespace.oid - Schema containing the extension's exported objects - - - - extrelocatable - bool - - True if extension can be relocated to another schema - - - - extversion - text - - Version name for the extension - - - - extconfig - oid[] - pg_class.oid - Array of regclass OIDs for the extension's configuration - table(s), or NULL if none - - - - extcondition - text[] - - Array of WHERE-clause filter conditions for the - extension's configuration table(s), or NULL if none - - - - -
- - - Note that unlike most catalogs with a namespace column, - extnamespace is not meant to imply - that the extension belongs to that schema. Extension names are never - schema-qualified. Rather, extnamespace - indicates the schema that contains most or all of the extension's - objects. If extrelocatable is true, then - this schema must in fact contain all schema-qualifiable objects - belonging to the extension. - - - - - - <structname>pg_foreign_data_wrapper</structname> - - - pg_foreign_data_wrapper - - -&common; - - The catalog pg_foreign_data_wrapper stores - foreign-data wrapper definitions. A foreign-data wrapper is the - mechanism by which external data, residing on foreign servers, is - accessed. - - - - <structname>pg_foreign_data_wrapper</> Columns - - - - - Name - Type - References - Description - - - - - - fdwname - name - - Name of the foreign-data wrapper - - - - fdwowner - oid - pg_authid.oid - Owner of the foreign-data wrapper - - - - fdwhandler - oid - pg_proc.oid - - References a handler function that is responsible for - supplying execution routines for the foreign-data wrapper. - Zero if no handler is provided - - - - - fdwvalidator - oid - pg_proc.oid - - References a validator function that is responsible for - checking the validity of the options given to the - foreign-data wrapper, as well as options for foreign servers and user - mappings using the foreign-data wrapper. Zero if no validator - is provided - - - - - fdwacl - aclitem[] - - - Access privileges; see - and - - for details - - - - - fdwoptions - text[] - - - Foreign-data wrapper specific options, as keyword=value strings - - - - -
- - - - - <structname>pg_foreign_server</structname> - - - pg_foreign_server - - -&common; - - The catalog pg_foreign_server stores - foreign server definitions. A foreign server describes a source - of external data, such as a remote server. Foreign - servers are accessed via foreign-data wrappers. - - - - <structname>pg_foreign_server</> Columns - - - - - Name - Type - References - Description - - - - - - srvname - name - - Name of the foreign server - - - - srvowner - oid - pg_authid.oid - Owner of the foreign server - - - - srvfdw - oid - pg_foreign_data_wrapper.oid - OID of the foreign-data wrapper of this foreign server - - - - srvtype - text - - Type of the server (optional) - - - - srvversion - text - - Version of the server (optional) - - - - srvacl - aclitem[] - - - Access privileges; see - and - - for details - - - - - srvoptions - text[] - - - Foreign server specific options, as keyword=value strings - - - - -
- - - - - <structname>pg_foreign_table</structname> - - - pg_foreign_table - - - - The catalog pg_foreign_table contains - auxiliary information about foreign tables. A foreign table is - primarily represented by a pg_class entry, - just like a regular table. Its pg_foreign_table - entry contains the information that is pertinent only to foreign tables - and not any other kind of relation. - - - - <structname>pg_foreign_table</> Columns - - - - - Name - Type - References - Description - - - - - - ftrelid - oid - pg_class.oid - OID of the pg_class entry for this foreign table - - - - ftserver - oid - pg_foreign_server.oid - OID of the foreign server for this foreign table - - - - ftoptions - text[] - - - Foreign table options, as keyword=value strings - - - - -
- - - - - <structname>pg_index</structname> - - - pg_index - - -&common; - - The catalog pg_index contains part of the information - about indexes. The rest is mostly in - pg_class. - - - - <structname>pg_index</> Columns - - - - - Name - Type - References - Description - - - - - - indexrelid - oid - pg_class.oid - The OID of the pg_class entry for this index - - - - indrelid - oid - pg_class.oid - The OID of the pg_class entry for the table this index is for - - - - indnatts - int2 - - The number of columns in the index (duplicates - pg_class.relnatts) - - - - indisunique - bool - - If true, this is a unique index - - - - indisprimary - bool - - If true, this index represents the primary key of the table - (indisunique should always be true when this is true) - - - - indisexclusion - bool - - If true, this index supports an exclusion constraint - - - - indimmediate - bool - - If true, the uniqueness check is enforced immediately on - insertion - (irrelevant if indisunique is not true) - - - - indisclustered - bool - - If true, the table was last clustered on this index - - - - indisvalid - bool - - - If true, the index is currently valid for queries. False means the - index is possibly incomplete: it must still be modified by - INSERT/UPDATE operations, but it cannot safely - be used for queries. If it is unique, the uniqueness property is not - true either. - - - - - indcheckxmin - bool - - - If true, queries must not use the index until the xmin - of this pg_index row is below their TransactionXmin - event horizon, because the table may contain broken HOT chains with - incompatible rows that they can see - - - - - indisready - bool - - - If true, the index is currently ready for inserts. False means the - index must be ignored by INSERT/UPDATE - operations. - - - - - indkey - int2vector - pg_attribute.attnum - - This is an array of indnatts values that - indicate which table columns this index indexes. For example a value - of 1 3 would mean that the first and the third table - columns make up the index key. A zero in this array indicates that the - corresponding index attribute is an expression over the table columns, - rather than a simple column reference. - - - - - indcollation - oidvector - pg_collation.oid - - For each column in the index key, this contains the OID of the - collation to use for the index. - - - - - indclass - oidvector - pg_opclass.oid - - For each column in the index key, this contains the OID of - the operator class to use. See - pg_opclass for details. - - - - - indoption - int2vector - - - This is an array of indnatts values that - store per-column flag bits. The meaning of the bits is defined by - the index's access method. - - - - - indexprs - pg_node_tree - - - Expression trees (in nodeToString() - representation) for index attributes that are not simple column - references. This is a list with one element for each zero - entry in indkey. Null if all index attributes - are simple references. - - - - - indpred - pg_node_tree - - - Expression tree (in nodeToString() - representation) for partial index predicate. Null if not a - partial index. - - - - -
- - - - - - <structname>pg_inherits</structname> - - - pg_inherits - - -&common; - - The catalog pg_inherits records information about - table inheritance hierarchies. There is one entry for each direct - child table in the database. (Indirect inheritance can be determined - by following chains of entries.) - - - - <structname>pg_inherits</> Columns - - - - - Name - Type - References - Description - - - - - - inhrelid - oid - pg_class.oid - - The OID of the child table - - - - - inhparent - oid - pg_class.oid - - The OID of the parent table - - - - - inhseqno - int4 - - - If there is more than one direct parent for a child table (multiple - inheritance), this number tells the order in which the - inherited columns are to be arranged. The count starts at 1. - - - - -
- - - - - - <structname>pg_language</structname> - - - pg_language - - -&common; - - The catalog pg_language registers - languages in which you can write functions or stored procedures. - See - and for more information about language handlers. - - - - <structname>pg_language</> Columns - - - - - Name - Type - References - Description - - - - - - lanname - name - - Name of the language - - - - lanowner - oid - pg_authid.oid - Owner of the language - - - - lanispl - bool - - - This is false for internal languages (such as - SQL) and true for user-defined languages. - Currently, pg_dump still uses this - to determine which languages need to be dumped, but this might be - replaced by a different mechanism in the future. - - - - - lanpltrusted - bool - - - True if this is a trusted language, which means that it is believed - not to grant access to anything outside the normal SQL execution - environment. Only superusers can create functions in untrusted - languages. - - - - - lanplcallfoid - oid - pg_proc.oid - - For noninternal languages this references the language - handler, which is a special function that is responsible for - executing all functions that are written in the particular - language - - - - - laninline - oid - pg_proc.oid - - This references a function that is responsible for executing - inline anonymous code blocks - ( blocks). - Zero if inline blocks are not supported. - - - - - lanvalidator - oid - pg_proc.oid - - This references a language validator function that is responsible - for checking the syntax and validity of new functions when they - are created. Zero if no validator is provided. - - - - - lanacl - aclitem[] - - - Access privileges; see - and - - for details - - - - -
- - - - - - <structname>pg_largeobject</structname> - - - pg_largeobject - - -&common; - - The catalog pg_largeobject holds the data making up - large objects. A large object is identified by an OID - assigned when it is created. Each large object is broken into - segments or pages small enough to be conveniently stored as rows - in pg_largeobject. - The amount of data per page is defined to be LOBLKSIZE (which is currently - BLCKSZ/4, or typically 2 kB). - - - - Prior to PostgreSQL 9.0, there was no permission structure - associated with large objects. As a result, - pg_largeobject was publicly readable and could be - used to obtain the OIDs (and contents) of all large objects in the system. - This is no longer the case; use - pg_largeobject_metadata - to obtain a list of large object OIDs. - - - - <structname>pg_largeobject</> Columns - - - - - Name - Type - References - Description - - - - - - loid - oid - pg_largeobject_metadata.oid - Identifier of the large object that includes this page - - - - pageno - int4 - - Page number of this page within its large object - (counting from zero) - - - - data - bytea - - - Actual data stored in the large object. - This will never be more than LOBLKSIZE bytes and might be less. - - - - -
- - - Each row of pg_largeobject holds data - for one page of a large object, beginning at - byte offset (pageno * LOBLKSIZE) within the object. The implementation - allows sparse storage: pages might be missing, and might be shorter than - LOBLKSIZE bytes even if they are not the last page of the object. - Missing regions within a large object read as zeroes. - - - - - - <structname>pg_largeobject_metadata</structname> - - - pg_largeobject_metadata - - -&common; - - The catalog pg_largeobject_metadata - holds metadata associated with large objects. The actual large object - data is stored in - pg_largeobject. - - - - <structname>pg_largeobject_metadata</> Columns - - - - - Name - Type - References - Description - - - - - - lomowner - oid - pg_authid.oid - Owner of the large object - - - - lomacl - aclitem[] - - - Access privileges; see - and - - for details - - - - - -
- - - - <structname>pg_namespace</structname> - - - pg_namespace - - -&common; - - The catalog pg_namespace stores namespaces. - A namespace is the structure underlying SQL schemas: each namespace - can have a separate collection of relations, types, etc. without name - conflicts. - - - - <structname>pg_namespace</> Columns - - - - - Name - Type - References - Description - - - - - - nspname - name - - Name of the namespace - - - - nspowner - oid - pg_authid.oid - Owner of the namespace - - - - nspacl - aclitem[] - - - Access privileges; see - and - - for details - - - - -
- - - - - - <structname>pg_opclass</structname> - - - pg_opclass - - -&common; - - The catalog pg_opclass defines - index access method operator classes. Each operator class defines - semantics for index columns of a particular data type and a particular - index access method. An operator class essentially specifies that a - particular operator family is applicable to a particular indexable column - data type. The set of operators from the family that are actually usable - with the indexed column are whichever ones accept the column's data type - as their lefthand input. - - - - Operator classes are described at length in . - - - - <structname>pg_opclass</> Columns - - - - - Name - Type - References - Description - - - - - - opcmethod - oid - pg_am.oid - Index access method operator class is for - - - - opcname - name - - Name of this operator class - - - - opcnamespace - oid - pg_namespace.oid - Namespace of this operator class - - - - opcowner - oid - pg_authid.oid - Owner of the operator class - - - - opcfamily - oid - pg_opfamily.oid - Operator family containing the operator class - - - - opcintype - oid - pg_type.oid - Data type that the operator class indexes - - - - opcdefault - bool - - True if this operator class is the default for opcintype - - - - opckeytype - oid - pg_type.oid - Type of data stored in index, or zero if same as opcintype - - - - -
- - - An operator class's opcmethod must match the - opfmethod of its containing operator family. - Also, there must be no more than one pg_opclass - row having opcdefault true for any given combination of - opcmethod and opcintype. - - - - - - - <structname>pg_operator</structname> - - - pg_operator - - -&common; - - The catalog pg_operator stores information about operators. - See - and for more information. - - - - <structname>pg_operator</> Columns - - - - - Name - Type - References - Description - - - - - - oprname - name - - Name of the operator - - - - oprnamespace - oid - pg_namespace.oid - - The OID of the namespace that contains this operator - - - - - oprowner - oid - pg_authid.oid - Owner of the operator - - - - oprkind - char - - - b = infix (both), l = prefix - (left), r = postfix (right) - - - - - oprcanmerge - bool - - This operator supports merge joins - - - - oprcanhash - bool - - This operator supports hash joins - - - - oprleft - oid - pg_type.oid - Type of the left operand - - - - oprright - oid - pg_type.oid - Type of the right operand - - - - oprresult - oid - pg_type.oid - Type of the result - - - - oprcom - oid - pg_operator.oid - Commutator of this operator, if any - - - - oprnegate - oid - pg_operator.oid - Negator of this operator, if any - - - - oprcode - regproc - pg_proc.oid - Function that implements this operator - - - - oprrest - regproc - pg_proc.oid - Restriction selectivity estimation function for this operator - - - - oprjoin - regproc - pg_proc.oid - Join selectivity estimation function for this operator - - - -
- - - Unused column contain zeroes. For example, oprleft - is zero for a prefix operator. - - - - - - - <structname>pg_opfamily</structname> - - - pg_opfamily - - -&common; - - The catalog pg_opfamily defines operator families. - Each operator family is a collection of operators and associated - support routines that implement the semantics specified for a particular - index access method. Furthermore, the operators in a family are all - compatible, in a way that is specified by the access method. - The operator family concept allows cross-data-type operators to be used - with indexes and to be reasoned about using knowledge of access method - semantics. - - - - Operator families are described at length in . - - - - <structname>pg_opfamily</> Columns - - - - - Name - Type - References - Description - - - - - - opfmethod - oid - pg_am.oid - Index access method operator family is for - - - - opfname - name - - Name of this operator family - - - - opfnamespace - oid - pg_namespace.oid - Namespace of this operator family - - - - opfowner - oid - pg_authid.oid - Owner of the operator family - - - - -
- - - The majority of the information defining an operator family is not in its - pg_opfamily row, but in the associated rows in - pg_amop, - pg_amproc, - and - pg_opclass. - - - - - - - <structname>pg_pltemplate</structname> - - - pg_pltemplate - - -&common; - - The catalog pg_pltemplate stores - template information for procedural languages. - A template for a language allows the language to be created in a - particular database by a simple CREATE LANGUAGE command, - with no need to specify implementation details. - - - - Unlike most system catalogs, pg_pltemplate - is shared across all databases of a cluster: there is only one - copy of pg_pltemplate per cluster, not - one per database. This allows the information to be accessible in - each database as it is needed. - - - - <structname>pg_pltemplate</> Columns - - - - - Name - Type - Description - - - - - - tmplname - name - Name of the language this template is for - - - - tmpltrusted - boolean - True if language is considered trusted - - - - tmpldbacreate - boolean - True if language may be created by a database owner - - - - tmplhandler - text - Name of call handler function - - - - tmplinline - text - Name of anonymous-block handler function, or null if none - - - - tmplvalidator - text - Name of validator function, or null if none - - - - tmpllibrary - text - Path of shared library that implements language - - - - tmplacl - aclitem[] - Access privileges for template (not actually used) - - - - -
- - - There are not currently any commands that manipulate procedural language - templates; to change the built-in information, a superuser must modify - the table using ordinary INSERT, DELETE, - or UPDATE commands. - - - - - It is likely that pg_pltemplate will be removed in some - future release of PostgreSQL, in favor of - keeping this knowledge about procedural languages in their respective - extension installation scripts. - - - - - - - - <structname>pg_proc</structname> - - - pg_proc - - -&common; - - The catalog pg_proc stores information about functions (or procedures). - See - and for more information. - - - - The table contains data for aggregate functions as well as plain functions. - If proisagg is true, there should be a matching - row in pg_aggregate. - - - - <structname>pg_proc</> Columns - - - - - Name - Type - References - Description - - - - - - proname - name - - Name of the function - - - - pronamespace - oid - pg_namespace.oid - - The OID of the namespace that contains this function - - - - - proowner - oid - pg_authid.oid - Owner of the function - - - - prolang - oid - pg_language.oid - Implementation language or call interface of this function - - - - procost - float4 - - Estimated execution cost (in units of - ); if proretset, - this is cost per row returned - - - - prorows - float4 - - Estimated number of result rows (zero if not proretset) - - - - provariadic - oid - pg_type.oid - Data type of the variadic array parameter's elements, - or zero if the function does not have a variadic parameter - - - - proisagg - bool - - Function is an aggregate function - - - - proiswindow - bool - - Function is a window function - - - - prosecdef - bool - - Function is a security definer (i.e., a setuid - function) - - - - proisstrict - bool - - - Function returns null if any call argument is null. In that - case the function won't actually be called at all. Functions - that are not strict must be prepared to handle - null inputs. - - - - - proretset - bool - - Function returns a set (i.e., multiple values of the specified - data type) - - - - provolatile - char - - - provolatile tells whether the function's - result depends only on its input arguments, or is affected by outside - factors. - It is i for immutable functions, - which always deliver the same result for the same inputs. - It is s for stable functions, - whose results (for fixed inputs) do not change within a scan. - It is v for volatile functions, - whose results might change at any time. (Use v also - for functions with side-effects, so that calls to them cannot get - optimized away.) - - - - - pronargs - int2 - - Number of input arguments - - - - pronargdefaults - int2 - - Number of arguments that have defaults - - - - prorettype - oid - pg_type.oid - Data type of the return value - - - - proargtypes - oidvector - pg_type.oid - - An array with the data types of the function arguments. This includes - only input arguments (including INOUT and - VARIADIC arguments), and thus represents - the call signature of the function. - - - - - proallargtypes - oid[] - pg_type.oid - - An array with the data types of the function arguments. This includes - all arguments (including OUT and - INOUT arguments); however, if all the - arguments are IN arguments, this field will be null. - Note that subscripting is 1-based, whereas for historical reasons - proargtypes is subscripted from 0. - - - - - proargmodes - char[] - - - An array with the modes of the function arguments, encoded as - i for IN arguments, - o for OUT arguments, - b for INOUT arguments, - v for VARIADIC arguments, - t for TABLE arguments. - If all the arguments are IN arguments, - this field will be null. - Note that subscripts correspond to positions of - proallargtypes not proargtypes. - - - - - proargnames - text[] - - - An array with the names of the function arguments. - Arguments without a name are set to empty strings in the array. - If none of the arguments have a name, this field will be null. - Note that subscripts correspond to positions of - proallargtypes not proargtypes. - - - - - proargdefaults - pg_node_tree - - - Expression trees (in nodeToString() representation) - for default values. This is a list with - pronargdefaults elements, corresponding to the last - N input arguments (i.e., the last - N proargtypes positions). - If none of the arguments have defaults, this field will be null. - - - - - prosrc - text - - - This tells the function handler how to invoke the function. It - might be the actual source code of the function for interpreted - languages, a link symbol, a file name, or just about anything - else, depending on the implementation language/call convention. - - - - - probin - text - - - Additional information about how to invoke the function. - Again, the interpretation is language-specific. - - - - - proconfig - text[] - - Function's local settings for run-time configuration variables - - - - proacl - aclitem[] - - - Access privileges; see - and - - for details - - - - -
- - - For compiled functions, both built-in and dynamically loaded, - prosrc contains the function's C-language - name (link symbol). For all other currently-known language types, - prosrc contains the function's source - text. probin is unused except for - dynamically-loaded C functions, for which it gives the name of the - shared library file containing the function. - - - - - - <structname>pg_rewrite</structname> - - - pg_rewrite - - -&common; - - The catalog pg_rewrite stores rewrite rules for tables and views. - - - - <structname>pg_rewrite</> Columns - - - - - Name - Type - References - Description - - - - - - rulename - name - - Rule name - - - - ev_class - oid - pg_class.oid - The table this rule is for - - - - ev_attr - int2 - - The column this rule is for (currently, always zero to - indicate the whole table) - - - - ev_type - char - - - Event type that the rule is for: 1 = SELECT, 2 = - UPDATE, 3 = INSERT, 4 = - DELETE - - - - - ev_enabled - char - - - Controls in which modes - the rule fires. - O = rule fires in origin and local modes, - D = rule is disabled, - R = rule fires in replica mode, - A = rule fires always. - - - - - is_instead - bool - - True if the rule is an INSTEAD rule - - - - ev_qual - pg_node_tree - - - Expression tree (in the form of a - nodeToString() representation) for the - rule's qualifying condition - - - - - ev_action - pg_node_tree - - - Query tree (in the form of a - nodeToString() representation) for the - rule's action - - - - -
- - - - pg_class.relhasrules - must be true if a table has any rules in this catalog. - - - - - - - - <structname>pg_seclabel</structname> - - - pg_seclabel - - - - The catalog pg_seclabel stores security - labels on database objects. See the - statement. - - - - <structname>pg_seclabel</structname> Columns - - - - - Name - Type - References - Description - - - - - - objoid - oid - any OID column - The OID of the object this security label pertains to - - - - classoid - oid - pg_class.oid - The OID of the system catalog this object appears in - - - - objsubid - int4 - - - For a security label on a table column, this is the column number (the - objoid and classoid refer to - the table itself). For all other object types, this column is - zero. - - - - - provider - text - - The label provider associated with this label. - - - - label - text - - The security label applied to this object. - - - -
- - - - <structname>pg_shdepend</structname> - - - pg_shdepend - - -&common; - - The catalog pg_shdepend records the - dependency relationships between database objects and shared objects, - such as roles. This information allows - PostgreSQL to ensure that those objects are - unreferenced before attempting to delete them. - - - - See also pg_depend, - which performs a similar function for dependencies involving objects - within a single database. - - - - Unlike most system catalogs, pg_shdepend - is shared across all databases of a cluster: there is only one - copy of pg_shdepend per cluster, not - one per database. - - - - <structname>pg_shdepend</> Columns - - - - - Name - Type - References - Description - - - - - - dbid - oid - pg_database.oid - The OID of the database the dependent object is in, - or zero for a shared object - - - - classid - oid - pg_class.oid - The OID of the system catalog the dependent object is in - - - - objid - oid - any OID column - The OID of the specific dependent object - - - - objsubid - int4 - - - For a table column, this is the column number (the - objid and classid refer to the - table itself). For all other object types, this column is zero. - - - - - refclassid - oid - pg_class.oid - The OID of the system catalog the referenced object is in - (must be a shared catalog) - - - - refobjid - oid - any OID column - The OID of the specific referenced object - - - - deptype - char - - - A code defining the specific semantics of this dependency relationship; see text - - - - - -
- - - In all cases, a pg_shdepend entry indicates that - the referenced object cannot be dropped without also dropping the dependent - object. However, there are several subflavors identified by - deptype: - - - - SHARED_DEPENDENCY_OWNER (o) - - - The referenced object (which must be a role) is the owner of the - dependent object. - - - - - - SHARED_DEPENDENCY_ACL (a) - - - The referenced object (which must be a role) is mentioned in the - ACL (access control list, i.e., privileges list) of the - dependent object. (A SHARED_DEPENDENCY_ACL entry is - not made for the owner of the object, since the owner will have - a SHARED_DEPENDENCY_OWNER entry anyway.) - - - - - - SHARED_DEPENDENCY_PIN (p) - - - There is no dependent object; this type of entry is a signal - that the system itself depends on the referenced object, and so - that object must never be deleted. Entries of this type are - created only by initdb. The columns for the - dependent object contain zeroes. - - - - - - Other dependency flavors might be needed in future. Note in particular - that the current definition only supports roles as referenced objects. - - - - - - <structname>pg_shdescription</structname> - - - pg_shdescription - - -&common; - - The catalog pg_shdescription stores optional - descriptions (comments) for shared database objects. Descriptions can be - manipulated with the command and viewed with - psql's \d commands. - - - - See also pg_description, - which performs a similar function for descriptions involving objects - within a single database. - - - - Unlike most system catalogs, pg_shdescription - is shared across all databases of a cluster: there is only one - copy of pg_shdescription per cluster, not - one per database. - - - - <structname>pg_shdescription</> Columns - - - - - Name - Type - References - Description - - - - - - objoid - oid - any OID column - The OID of the object this description pertains to - - - - classoid - oid - pg_class.oid - The OID of the system catalog this object appears in - - - - description - text - - Arbitrary text that serves as the description of this object - - - -
- - - - - - <structname>pg_statistic</structname> - - - pg_statistic - - -&common; - - The catalog pg_statistic stores - statistical data about the contents of the database. Entries are - created by - and subsequently used by the query planner. Note that all the - statistical data is inherently approximate, even assuming that it - is up-to-date. - - - - Normally there is one entry, with stainherit = - false, for each table column that has been analyzed. - If the table has inheritance children, a second entry with - stainherit = true is also created. This row - represents the column's statistics over the inheritance tree, i.e., - statistics for the data you'd see with - SELECT column FROM table*, - whereas the stainherit = false row represents - the results of - SELECT column FROM ONLY table. - - - - pg_statistic also stores statistical data about - the values of index expressions. These are described as if they were - actual data columns; in particular, starelid - references the index. No entry is made for an ordinary non-expression - index column, however, since it would be redundant with the entry - for the underlying table column. Currently, entries for index expressions - always have stainherit = false. - - - - Since different kinds of statistics might be appropriate for different - kinds of data, pg_statistic is designed not - to assume very much about what sort of statistics it stores. Only - extremely general statistics (such as nullness) are given dedicated - columns in pg_statistic. Everything else - is stored in slots, which are groups of associated columns - whose content is identified by a code number in one of the slot's columns. - For more information see - src/include/catalog/pg_statistic.h. - - - - pg_statistic should not be readable by the - public, since even statistical information about a table's contents - might be considered sensitive. (Example: minimum and maximum values - of a salary column might be quite interesting.) - pg_stats - is a publicly readable view on - pg_statistic that only exposes information - about those tables that are readable by the current user. - - - - <structname>pg_statistic</> Columns - - - - - Name - Type - References - Description - - - - - - starelid - oid - pg_class.oid - The table or index that the described column belongs to - - - - staattnum - int2 - pg_attribute.attnum - The number of the described column - - - - stainherit - bool - - If true, the stats include inheritance child columns, not just the - values in the specified relation - - - - stanullfrac - float4 - - The fraction of the column's entries that are null - - - - stawidth - int4 - - The average stored width, in bytes, of nonnull entries - - - - stadistinct - float4 - - The number of distinct nonnull data values in the column. - A value greater than zero is the actual number of distinct values. - A value less than zero is the negative of a multiplier for the number - of rows in the table; for example, a column in which values appear about - twice on the average could be represented by - stadistinct = -0.5. - A zero value means the number of distinct values is unknown. - - - - - stakindN - int2 - - - A code number indicating the kind of statistics stored in the - Nth slot of the - pg_statistic row. - - - - - staopN - oid - pg_operator.oid - - An operator used to derive the statistics stored in the - Nth slot. For example, a - histogram slot would show the < operator - that defines the sort order of the data. - - - - - stanumbersN - float4[] - - - Numerical statistics of the appropriate kind for the - Nth slot, or null if the slot - kind does not involve numerical values - - - - - stavaluesN - anyarray - - - Column data values of the appropriate kind for the - Nth slot, or null if the slot - kind does not store any data values. Each array's element - values are actually of the specific column's data type, so there - is no way to define these columns' type more specifically than - anyarray. - - - - -
- - - - - - <structname>pg_tablespace</structname> - - - pg_tablespace - - -&common; - - The catalog pg_tablespace stores information - about the available tablespaces. Tables can be placed in particular - tablespaces to aid administration of disk layout. - - - - Unlike most system catalogs, pg_tablespace - is shared across all databases of a cluster: there is only one - copy of pg_tablespace per cluster, not - one per database. - - - - <structname>pg_tablespace</> Columns - - - - - Name - Type - References - Description - - - - - - spcname - name - - Tablespace name - - - - spcowner - oid - pg_authid.oid - Owner of the tablespace, usually the user who created it - - - - spclocation - text - - Location (directory path) of the tablespace - - - - spcacl - aclitem[] - - - Access privileges; see - and - - for details - - - - - spcoptions - text[] - - - Tablespace-level options, as keyword=value strings - - - - -
- - - - - <structname>pg_trigger</structname> - - - pg_trigger - - -&common; - - The catalog pg_trigger stores triggers on tables - and views. - See - for more information. - - - - <structname>pg_trigger</> Columns - - - - - Name - Type - References - Description - - - - - - tgrelid - oid - pg_class.oid - The table this trigger is on - - - - tgname - name - - Trigger name (must be unique among triggers of same table) - - - - tgfoid - oid - pg_proc.oid - The function to be called - - - - tgtype - int2 - - Bit mask identifying trigger firing conditions - - - - tgenabled - char - - - Controls in which modes - the trigger fires. - O = trigger fires in origin and local modes, - D = trigger is disabled, - R = trigger fires in replica mode, - A = trigger fires always. - - - - - tgisinternal - bool - - True if trigger is internally generated (usually, to enforce - the constraint identified by tgconstraint) - - - - tgconstrrelid - oid - pg_class.oid - The table referenced by a referential integrity constraint - - - - tgconstrindid - oid - pg_class.oid - The index supporting a unique, primary key, or referential integrity constraint - - - - tgconstraint - oid - pg_constraint.oid - The pg_constraint entry associated with the trigger, if any - - - - tgdeferrable - bool - - True if constraint trigger is deferrable - - - - tginitdeferred - bool - - True if constraint trigger is initially deferred - - - - tgnargs - int2 - - Number of argument strings passed to trigger function - - - - tgattr - int2vector - pg_attribute.attnum - Column numbers, if trigger is column-specific; otherwise an - empty array - - - - tgargs - bytea - - Argument strings to pass to trigger, each NULL-terminated - - - - tgqual - pg_node_tree - - Expression tree (in nodeToString() - representation) for the trigger's WHEN condition, or null - if none - - - -
- - - Currently, column-specific triggering is supported only for - UPDATE events, and so tgattr is relevant - only for that event type. tgtype might - contain bits for other event types as well, but those are presumed - to be table-wide regardless of what is in tgattr. - - - - - When tgconstraint is nonzero, - tgconstrrelid, tgconstrindid, - tgdeferrable, and tginitdeferred are - largely redundant with the referenced pg_constraint entry. - However, it is possible for a non-deferrable trigger to be associated - with a deferrable constraint: foreign key constraints can have some - deferrable and some non-deferrable triggers. - - - - - - pg_class.relhastriggers - must be true if a relation has any triggers in this catalog. - - - - - - - - <structname>pg_ts_config</structname> - - - pg_ts_config - - -&common; - - The pg_ts_config catalog contains entries - representing text search configurations. A configuration specifies - a particular text search parser and a list of dictionaries to use - for each of the parser's output token types. The parser is shown - in the pg_ts_config entry, but the - token-to-dictionary mapping is defined by subsidiary entries in pg_ts_config_map. - - - - PostgreSQL's text search features are - described at length in . - - - - <structname>pg_ts_config</> Columns - - - - - Name - Type - References - Description - - - - - - cfgname - name - - Text search configuration name - - - - cfgnamespace - oid - pg_namespace.oid - - The OID of the namespace that contains this configuration - - - - - cfgowner - oid - pg_authid.oid - Owner of the configuration - - - - cfgparser - oid - pg_ts_parser.oid - The OID of the text search parser for this configuration - - - -
- - - - - <structname>pg_ts_config_map</structname> - - - pg_ts_config_map - - -&common; - - The pg_ts_config_map catalog contains entries - showing which text search dictionaries should be consulted, and in - what order, for each output token type of each text search configuration's - parser. - - - - PostgreSQL's text search features are - described at length in . - - - - <structname>pg_ts_config_map</> Columns - - - - - Name - Type - References - Description - - - - - - mapcfg - oid - pg_ts_config.oid - The OID of the pg_ts_config entry owning this map entry - - - - maptokentype - integer - - A token type emitted by the configuration's parser - - - - mapseqno - integer - - Order in which to consult this entry (lower - mapseqnos first) - - - - mapdict - oid - pg_ts_dict.oid - The OID of the text search dictionary to consult - - - -
- - - - - <structname>pg_ts_dict</structname> - - - pg_ts_dict - - -&common; - - The pg_ts_dict catalog contains entries - defining text search dictionaries. A dictionary depends on a text - search template, which specifies all the implementation functions - needed; the dictionary itself provides values for the user-settable - parameters supported by the template. This division of labor allows - dictionaries to be created by unprivileged users. The parameters - are specified by a text string dictinitoption, - whose format and meaning vary depending on the template. - - - - PostgreSQL's text search features are - described at length in . - - - - <structname>pg_ts_dict</> Columns - - - - - Name - Type - References - Description - - - - - - dictname - name - - Text search dictionary name - - - - dictnamespace - oid - pg_namespace.oid - - The OID of the namespace that contains this dictionary - - - - - dictowner - oid - pg_authid.oid - Owner of the dictionary - - - - dicttemplate - oid - pg_ts_template.oid - The OID of the text search template for this dictionary - - - - dictinitoption - text - - Initialization option string for the template - - - -
- - - - - <structname>pg_ts_parser</structname> - - - pg_ts_parser - - -&common; - - The pg_ts_parser catalog contains entries - defining text search parsers. A parser is responsible for splitting - input text into lexemes and assigning a token type to each lexeme. - Since a parser must be implemented by C-language-level functions, - creation of new parsers is restricted to database superusers. - - - - PostgreSQL's text search features are - described at length in . - - - - <structname>pg_ts_parser</> Columns - - - - - Name - Type - References - Description - - - - - - prsname - name - - Text search parser name - - - - prsnamespace - oid - pg_namespace.oid - - The OID of the namespace that contains this parser - - - - - prsstart - regproc - pg_proc.oid - OID of the parser's startup function - - - - prstoken - regproc - pg_proc.oid - OID of the parser's next-token function - - - - prsend - regproc - pg_proc.oid - OID of the parser's shutdown function - - - - prsheadline - regproc - pg_proc.oid - OID of the parser's headline function - - - - prslextype - regproc - pg_proc.oid - OID of the parser's lextype function - - - -
- - - - - <structname>pg_ts_template</structname> - - - pg_ts_template - - -&common; - - The pg_ts_template catalog contains entries - defining text search templates. A template is the implementation - skeleton for a class of text search dictionaries. - Since a template must be implemented by C-language-level functions, - creation of new templates is restricted to database superusers. - - - - PostgreSQL's text search features are - described at length in . - - - - <structname>pg_ts_template</> Columns - - - - - Name - Type - References - Description - - - - - - tmplname - name - - Text search template name - - - - tmplnamespace - oid - pg_namespace.oid - - The OID of the namespace that contains this template - - - - - tmplinit - regproc - pg_proc.oid - OID of the template's initialization function - - - - tmpllexize - regproc - pg_proc.oid - OID of the template's lexize function - - - -
- - - - - <structname>pg_type</structname> - - - pg_type - - -&common; - - The catalog pg_type stores information about data - types. Base types and enum types (scalar types) are created with - , and - domains with - . - A composite type is automatically created for each table in the database, to - represent the row structure of the table. It is also possible to create - composite types with CREATE TYPE AS. - - - - <structname>pg_type</> Columns - - - - - Name - Type - References - Description - - - - - - typname - name - - Data type name - - - - typnamespace - oid - pg_namespace.oid - - The OID of the namespace that contains this type - - - - - typowner - oid - pg_authid.oid - Owner of the type - - - - typlen - int2 - - - For a fixed-size type, typlen is the number - of bytes in the internal representation of the type. But for a - variable-length type, typlen is negative. - -1 indicates a varlena type (one that has a length word), - -2 indicates a null-terminated C string. - - - - - typbyval - bool - - - typbyval determines whether internal - routines pass a value of this type by value or by reference. - typbyval had better be false if - typlen is not 1, 2, or 4 (or 8 on machines - where Datum is 8 bytes). - Variable-length types are always passed by reference. Note that - typbyval can be false even if the - length would allow pass-by-value. - - - - - typtype - char - - - typtype is - b for a base type, - c for a composite type (e.g., a table's row type), - d for a domain, - e for an enum type, - or p for a pseudo-type. - See also typrelid and - typbasetype. - - - - - typcategory - char - - - typcategory is an arbitrary classification - of data types that is used by the parser to determine which implicit - casts should be preferred. - See . - - - - - typispreferred - bool - - - True if the type is a preferred cast target within its - typcategory - - - - - typisdefined - bool - - - True if the type is defined, false if this is a placeholder - entry for a not-yet-defined type. When - typisdefined is false, nothing - except the type name, namespace, and OID can be relied on. - - - - - typdelim - char - - - Character that separates two values of this type when parsing - array input. Note that the delimiter is associated with the array - element data type, not the array data type. - - - - - typrelid - oid - pg_class.oid - - If this is a composite type (see - typtype), then this column points to - the pg_class entry that defines the - corresponding table. (For a free-standing composite type, the - pg_class entry doesn't really represent - a table, but it is needed anyway for the type's - pg_attribute entries to link to.) - Zero for non-composite types. - - - - - typelem - oid - pg_type.oid - - If typelem is not 0 then it - identifies another row in pg_type. - The current type can then be subscripted like an array yielding - values of type typelem. A - true array type is variable length - (typlen = -1), - but some fixed-length (typlen > 0) types - also have nonzero typelem, for example - name and point. - If a fixed-length type has a typelem then - its internal representation must be some number of values of the - typelem data type with no other data. - Variable-length array types have a header defined by the array - subroutines. - - - - - typarray - oid - pg_type.oid - - If typarray is not 0 then it - identifies another row in pg_type, which - is the true array type having this type as element - - - - - typinput - regproc - pg_proc.oid - Input conversion function (text format) - - - - typoutput - regproc - pg_proc.oid - Output conversion function (text format) - - - - typreceive - regproc - pg_proc.oid - Input conversion function (binary format), or 0 if none - - - - typsend - regproc - pg_proc.oid - Output conversion function (binary format), or 0 if none - - - - typmodin - regproc - pg_proc.oid - Type modifier input function, or 0 if type does not support modifiers - - - - typmodout - regproc - pg_proc.oid - Type modifier output function, or 0 to use the standard format - - - - typanalyze - regproc - pg_proc.oid - Custom ANALYZE function, or 0 to use the standard function - - - - typalign - char - - - - typalign is the alignment required - when storing a value of this type. It applies to storage on - disk as well as most representations of the value inside - PostgreSQL. - When multiple values are stored consecutively, such - as in the representation of a complete row on disk, padding is - inserted before a datum of this type so that it begins on the - specified boundary. The alignment reference is the beginning - of the first datum in the sequence. - - - - Possible values are: - - - c = char alignment, i.e., no alignment needed. - - - s = short alignment (2 bytes on most machines). - - - i = int alignment (4 bytes on most machines). - - - d = double alignment (8 bytes on many machines, but by no means all). - - - - - For types used in system tables, it is critical that the size - and alignment defined in pg_type - agree with the way that the compiler will lay out the column in - a structure representing a table row. - - - - - - typstorage - char - - - typstorage tells for varlena - types (those with typlen = -1) if - the type is prepared for toasting and what the default strategy - for attributes of this type should be. - Possible values are - - - p: Value must always be stored plain. - - - - e: Value can be stored in a secondary - relation (if relation has one, see - pg_class.reltoastrelid). - - - - m: Value can be stored compressed inline. - - - x: Value can be stored compressed inline or stored in secondary storage. - - - Note that m columns can also be moved out to secondary - storage, but only as a last resort (e and x columns are - moved first). - - - - - typnotnull - bool - - - typnotnull represents a not-null - constraint on a type. Used for domains only. - - - - - typbasetype - oid - pg_type.oid - - If this is a domain (see typtype), then - typbasetype identifies the type that this - one is based on. Zero if this type is not a domain. - - - - - typtypmod - int4 - - - Domains use typtypmod to record the typmod - to be applied to their base type (-1 if base type does not use a - typmod). -1 if this type is not a domain. - - - - - typndims - int4 - - - typndims is the number of array dimensions - for a domain over an array (that is, typbasetype is - an array type). - Zero for types other than domains over array types. - - - - - typcollation - oid - pg_collation.oid - - typcollation specifies the collation - of the type. If the type does not support collations, this will - be zero. A base type that supports collations will have - DEFAULT_COLLATION_OID here. A domain over a - collatable type can have some other collation OID, if one was - specified for the domain. - - - - - typdefaultbin - pg_node_tree - - - If typdefaultbin is not null, it is the - nodeToString() - representation of a default expression for the type. This is - only used for domains. - - - - - typdefault - text - - - typdefault is null if the type has no associated - default value. If typdefaultbin is not null, - typdefault must contain a human-readable version of the - default expression represented by typdefaultbin. If - typdefaultbin is null and typdefault is - not, then typdefault is the external representation of - the type's default value, which can be fed to the type's input - converter to produce a constant. - - - - -
- - - lists the system-defined values - of typcategory. Any future additions to this list will - also be upper-case ASCII letters. All other ASCII characters are reserved - for user-defined categories. - - - - <structfield>typcategory</> Codes - - - - - Code - Category - - - - - - A - Array types - - - B - Boolean types - - - C - Composite types - - - D - Date/time types - - - E - Enum types - - - G - Geometric types - - - I - Network address types - - - N - Numeric types - - - P - Pseudo-types - - - S - String types - - - T - Timespan types - - - U - User-defined types - - - V - Bit-string types - - - X - unknown type - - - -
- - - - - - <structname>pg_user_mapping</structname> - - - pg_user_mapping - - -&common; - - The catalog pg_user_mapping stores - the mappings from local user to remote. Access to this catalog is - restricted from normal users, use the view - pg_user_mappings - instead. - - - - <structname>pg_user_mapping</> Columns - - - - - Name - Type - References - Description - - - - - - umuser - oid - pg_authid.oid - OID of the local role being mapped, 0 if the user mapping is public - - - - umserver - oid - pg_foreign_server.oid - - The OID of the foreign server that contains this mapping - - - - - umoptions - text[] - - - User mapping specific options, as keyword=value strings - - - - -
- - - - - <structname>pgxc_class</structname> - - - pgxc_class - - -&xconly; - - The catalog pgxc_class stores information - whether each table is replicated or distributed, as well as - distribution method and the distribution column. - - - - <structname>pgxc_class</> Columns - - - - - Name - Type - References - Description - - - - - - pcrelid - oid - pg_class.oid - OID of the table - - - - pclocatortype - char - - - Type of locator. - - - - - pcattnum - int2 - - - Column number of used as distribution key. - - - - - pchashalgorithm - int2 - - - Indicates hashing algorithm used to distribute the tuples. - - - - - pchashbuckets - int2 - - - Indicates the number of hash buckets used to distribute duple. - - - - - nodeoids - oidvector - pgxc_node.oid - - List of node OIDs where table is located. - This list is ordered by - pgxc_node.node_name. This list is then - indexed in information in user session cache and reused as a node target list - when doing SQL operations on cluster tables. - - - - - -
- - - - <structname>pgxc_node</structname> - - - pgxc_node - - -&xconly; - - The catalog pgxc_node stores information - about cluster node information, such as connection information with - node port and host, node name, primary and preferred nodes. - - - - <structname>pgxc_node</> Columns - - - - - Name - Type - References - Description - - - - - - node_name - name - - Name of cluster node - - - - node_type - char - - Type of cluster node. - It is C for a Coordinator. - It is D for a Datanode. - - - - - node_port - int4 - - Port number of cluster node - - - - node_host - name - - Host name or IP number of cluster node - - - - nodeis_primary - bool - - Defines if node is a primary node. - Only Datanode can be a primary node. - - - - - nodeis_preferred - bool - - Defines if node is a preferred node. - Only a Datanode can be a preferred node. - - - - - node_id - int4 - - Integer node identifier of node. - It is generated when node is created. - - - - -
- - - - <structname>pgxc_group</structname> - - - pgxc_group - - -&xconly; - - The catalog pgxc_group stores information - about cluster node group information, which is a list of cluster node - OIDs. Groups can be used as aliases. - - - - <structname>pgxc_group</> Columns - - - - - Name - Type - References - Description - - - - - - group_name - name - - Name of cluster node group - - - - group_members - oidvector - pgxc_node.oid - List of node OIDs of the node group - - - - -
- - - - - <structname>pgxc_class</structname> - - - pgxc_class - - -&xlonly; - - The catalog pgxc_class stores information - whether each table is replicated or distributed, as well as - distribution method and the distribution column. - - - - <structname>pgxc_class</> Columns - - - - - Name - Type - References - Description - - - - - - pcrelid - oid - pg_class.oid - OID of the table - - - - pclocatortype - char - - - Type of locator. - - - - - pcattnum - int2 - - - Column number of used as distribution key. - - - - - pchashalgorithm - int2 - - - Indicates hashing algorithm used to distribute the tuples. - - - - - pchashbuckets - int2 - - - Indicates the number of hash buckets used to distribute duple. - - - - - nodeoids - oidvector - pgxc_node.oid - - List of node OIDs where table is located. - This list is ordered by - pgxc_node.node_name. This list is then - indexed in information in user session cache and reused as a node target list - when doing SQL operations on cluster tables. - - - - - -
- - - - <structname>pgxc_node</structname> - - - pgxc_node - - -&xlonly; - - The catalog pgxc_node stores information - about cluster node information, such as connection information with - node port and host, node name, primary and preferred nodes. - - - - <structname>pgxc_node</> Columns - - - - - Name - Type - References - Description - - - - - - node_name - name - - Name of cluster node - - - - node_type - char - - Type of cluster node. - It is C for a Coordinator. - It is D for a Datanode. - - - - - node_port - int4 - - Port number of cluster node - - - - node_host - name - - Host name or IP number of cluster node - - - - nodeis_primary - bool - - Defines if node is a primary node. - Only Datanode can be a primary node. - - - - - nodeis_preferred - bool - - Defines if node is a preferred node. - Only a Datanode can be a preferred node. - - - - - node_id - int4 - - Integer node identifier of node. - It is generated when node is created. - - - - -
- - - - <structname>pgxc_group</structname> - - - pgxc_group - - -&xlonly; - - The catalog pgxc_group stores information - about cluster node group information, which is a list of cluster node - OIDs. Groups can be used as aliases. - - - - <structname>pgxc_group</> Columns - - - - - Name - Type - References - Description - - - - - - group_name - name - - Name of cluster node group - - - - group_members - oidvector - pgxc_node.oid - List of node OIDs of the node group - - - - -
- - - - - System Views - -&common; - - In addition to the system catalogs, PostgreSQL - provides a number of built-in views. Some system views provide convenient - access to some commonly used queries on the system catalogs. Other views - provide access to internal server state. - - - - The information schema () provides - an alternative set of views which overlap the functionality of the system - views. Since the information schema is SQL-standard whereas the views - described here are PostgreSQL-specific, - it's usually better to use the information schema if it provides all - the information you need. - - - - lists the system views described here. - More detailed documentation of each view follows below. - There are some additional views that provide access to the results of - the statistics collector; they are described in . - - - - Except where noted, all the views described here are read-only. - - - - System Views - - - - - View Name - Purpose - - - - - - pg_available_extensions - available extensions - - - - pg_available_extension_versions - available versions of extensions - - - - pg_cursors - open cursors - - - - pg_group - groups of database users - - - - pg_indexes - indexes - - - - pg_locks - currently held locks - - - - pg_prepared_statements - prepared statements - - - - pg_prepared_xacts - prepared transactions - - - - pg_roles - database roles - - - - pg_rules - rules - - - - pg_seclabels - security labels - - - - pg_settings - parameter settings - - - - pg_shadow - database users - - - - pg_stats - planner statistics - - - - pg_tables - tables - - - - pg_timezone_abbrevs - time zone abbreviations - - - - pg_timezone_names - time zone names - - - - pg_user - database users - - - - pg_user_mappings - user mappings - - - - pg_views - views - - - - -
- - - - <structname>pg_available_extensions</structname> - - - pg_available_extensions - - - - The pg_available_extensions view lists the - extensions that are available for installation. - See also the - pg_extension - catalog, which shows the extensions currently installed. - - - - <structname>pg_available_extensions</> Columns - - - - - Name - Type - Description - - - - - - name - name - Extension name - - - - default_version - text - Name of default version, or NULL if none is - specified - - - - installed_version - text - Currently installed version of the extension, - or NULL if not installed - - - - comment - text - Comment string from the extension's control file - - - -
- - - The pg_available_extensions view is read only. - - - - - <structname>pg_available_extension_versions</structname> - - - pg_available_extension_versions - - - - The pg_available_extension_versions view lists the - specific extension versions that are available for installation. - See also the pg_extension - catalog, which shows the extensions currently installed. - - - - <structname>pg_available_extension_versions</> Columns - - - - - Name - Type - Description - - - - - - name - name - Extension name - - - - version - text - Version name - - - - installed - bool - True if this version of this extension is currently - installed - - - - superuser - bool - True if only superusers are allowed to install this extension - - - - relocatable - bool - True if extension can be relocated to another schema - - - - schema - name - Name of the schema that the extension must be installed into, - or NULL if partially or fully relocatable - - - - requires - name[] - Names of prerequisite extensions, - or NULL if none - - - - comment - text - Comment string from the extension's control file - - - -
- - - The pg_available_extension_versions view is read - only. - - - - - <structname>pg_cursors</structname> - - - pg_cursors - - -&common; - - The pg_cursors view lists the cursors that - are currently available. Cursors can be defined in several ways: - - - - via the - statement in SQL - - - - - - via the Bind message in the frontend/backend protocol, as - described in - - - - - - via the Server Programming Interface (SPI), as described in - - - - - - The pg_cursors view displays cursors - created by any of these means. Cursors only exist for the duration - of the transaction that defines them, unless they have been - declared WITH HOLD. Therefore non-holdable - cursors are only present in the view until the end of their - creating transaction. - - - - Cursors are used internally to implement some of the components - of PostgreSQL, such as procedural languages. - Therefore, the pg_cursors view might include cursors - that have not been explicitly created by the user. - - - - - - <structname>pg_cursors</> Columns - - - - - Name - Type - Description - - - - - - name - text - The name of the cursor - - - - statement - text - The verbatim query string submitted to declare this cursor - - - - is_holdable - boolean - - true if the cursor is holdable (that is, it - can be accessed after the transaction that declared the cursor - has committed); false otherwise - - - - - is_binary - boolean - - true if the cursor was declared - BINARY; false - otherwise - - - - - is_scrollable - boolean - - true if the cursor is scrollable (that is, it - allows rows to be retrieved in a nonsequential manner); - false otherwise - - - - - creation_time - timestamptz - The time at which the cursor was declared - - - -
- - - The pg_cursors view is read only. - - - - - - <structname>pg_group</structname> - - - pg_group - - -&common; - - The view pg_group exists for backwards - compatibility: it emulates a catalog that existed in - PostgreSQL before version 8.1. - It shows the names and members of all roles that are marked as not - rolcanlogin, which is an approximation to the set - of roles that are being used as groups. - - - - <structname>pg_group</> Columns - - - - - Name - Type - References - Description - - - - - - groname - name - pg_authid.rolname - Name of the group - - - - grosysid - oid - pg_authid.oid - ID of this group - - - - grolist - oid[] - pg_authid.oid - An array containing the IDs of the roles in this group - - - -
- - - - - <structname>pg_indexes</structname> - - - pg_indexes - - -&common; - - The view pg_indexes provides access to - useful information about each index in the database. - - - - <structname>pg_indexes</> Columns - - - - - Name - Type - References - Description - - - - - schemaname - name - pg_namespace.nspname - Name of schema containing table and index - - - tablename - name - pg_class.relname - Name of table the index is for - - - indexname - name - pg_class.relname - Name of index - - - tablespace - name - pg_tablespace.spcname - Name of tablespace containing index (null if default for database) - - - indexdef - text - - Index definition (a reconstructed CREATE INDEX - command) - - - -
- - - - - <structname>pg_locks</structname> - - - pg_locks - - -&common; - - The view pg_locks provides access to - information about the locks held by open transactions within the - database server. See for more discussion - of locking. - - - - pg_locks contains one row per active lockable - object, requested lock mode, and relevant transaction. Thus, the same - lockable object might - appear many times, if multiple transactions are holding or waiting - for locks on it. However, an object that currently has no locks on it - will not appear at all. - - - - There are several distinct types of lockable objects: - whole relations (e.g., tables), individual pages of relations, - individual tuples of relations, - transaction IDs (both virtual and permanent IDs), - and general database objects (identified by class OID and object OID, - in the same way as in pg_description or - pg_depend). Also, the right to extend a - relation is represented as a separate lockable object. - - - - <structname>pg_locks</> Columns - - - - - Name - Type - References - Description - - - - - locktype - text - - - Type of the lockable object: - relation, - extend, - page, - tuple, - transactionid, - virtualxid, - object, - userlock, or - advisory - - - - database - oid - pg_database.oid - - OID of the database in which the object exists, or - zero if the object is a shared object, or - null if the object is a transaction ID - - - - relation - oid - pg_class.oid - - OID of the relation, or null if the object is not - a relation or part of a relation - - - - page - integer - - - Page number within the relation, or null if the object - is not a tuple or relation page - - - - tuple - smallint - - - Tuple number within the page, or null if the object is not a tuple - - - - virtualxid - text - - - Virtual ID of a transaction, or null if the object is not a - virtual transaction ID - - - - transactionid - xid - - - ID of a transaction, or null if the object is not a transaction ID - - - - classid - oid - pg_class.oid - - OID of the system catalog containing the object, or null if the - object is not a general database object - - - - objid - oid - any OID column - - OID of the object within its system catalog, or null if the - object is not a general database object. - For advisory locks it is used to distinguish the two key - spaces (1 for an int8 key, 2 for two int4 keys). - - - - objsubid - smallint - - - For a table column, this is the column number (the - classid and objid refer to the - table itself). For all other object types, this column is - zero. Null if the object is not a general database object - - - - virtualtransaction - text - - - Virtual ID of the transaction that is holding or awaiting this lock - - - - pid - integer - - - Process ID of the server process holding or awaiting this - lock. Null if the lock is held by a prepared transaction. - - - - mode - text - - Name of the lock mode held or desired by this process (see and ) - - - granted - boolean - - True if lock is held, false if lock is awaited - - - -
- - - granted is true in a row representing a lock - held by the indicated transaction. False indicates that this transaction is - currently waiting to acquire this lock, which implies that some other - transaction is holding a conflicting lock mode on the same lockable object. - The waiting transaction will sleep until the other lock is released (or a - deadlock situation is detected). A single transaction can be waiting to - acquire at most one lock at a time. - - - - Every transaction holds an exclusive lock on its virtual transaction ID for - its entire duration. If a permanent ID is assigned to the transaction - (which normally happens only if the transaction changes the state of the - database), it also holds an exclusive lock on its permanent transaction ID - until it ends. When one transaction finds it necessary to wait specifically - for another transaction, it does so by attempting to acquire share lock on - the other transaction ID (either virtual or permanent ID depending on the - situation). That will succeed only when the other transaction - terminates and releases its locks. - - - - Although tuples are a lockable type of object, - information about row-level locks is stored on disk, not in memory, - and therefore row-level locks normally do not appear in this view. - If a transaction is waiting for a - row-level lock, it will usually appear in the view as waiting for the - permanent transaction ID of the current holder of that row lock. - - - - Advisory locks can be acquired on keys consisting of either a single - bigint value or two integer values. A bigint key is displayed with its - high-order half in the classid column, its low-order half - in the objid column, and objsubid equal - to 1. Integer keys are displayed with the first key in the - classid column, the second key in the objid - column, and objsubid equal to 2. The actual meaning of - the keys is up to the user. Advisory locks are local to each database, - so the database column is meaningful for an advisory lock. - - - - When the pg_locks view is accessed, the - internal lock manager data structures are momentarily locked, and - a copy is made for the view to display. This ensures that the - view produces a consistent set of results, while not blocking - normal lock manager operations longer than necessary. Nonetheless - there could be some impact on database performance if this view is - frequently accessed. - - - - pg_locks provides a global view of all locks - in the database cluster, not only those relevant to the current database. - Although its relation column can be joined - against pg_class.oid to identify locked - relations, this will only work correctly for relations in the current - database (those for which the database column - is either the current database's OID or zero). - - - - The pid column can be joined to the - procpid column of the - pg_stat_activity view to get more - information on the session holding or waiting to hold each lock. - Also, if you are using prepared transactions, the - transaction column can be joined to the - transaction column of the - pg_prepared_xacts view to get more - information on prepared transactions that hold locks. - (A prepared transaction can never be waiting for a lock, - but it continues to hold the locks it acquired while running.) - - - - - - <structname>pg_prepared_statements</structname> - - - pg_prepared_statements - - -&common; - - The pg_prepared_statements view displays - all the prepared statements that are available in the current - session. See for more information about prepared - statements. - - - - pg_prepared_statements contains one row - for each prepared statement. Rows are added to the view when a new - prepared statement is created and removed when a prepared statement - is released (for example, via the command). - - - - <structname>pg_prepared_statements</> Columns - - - - - Name - Type - Description - - - - - name - text - - The identifier of the prepared statement - - - - statement - text - - The query string submitted by the client to create this - prepared statement. For prepared statements created via SQL, - this is the PREPARE statement submitted by - the client. For prepared statements created via the - frontend/backend protocol, this is the text of the prepared - statement itself. - - - - prepare_time - timestamptz - - The time at which the prepared statement was created - - - - parameter_types - regtype[] - - The expected parameter types for the prepared statement in the - form of an array of regtype. The OID corresponding - to an element of this array can be obtained by casting the - regtype value to oid. - - - - from_sql - boolean - - true if the prepared statement was created - via the PREPARE SQL statement; - false if the statement was prepared via the - frontend/backend protocol - - - - -
- - - The pg_prepared_statements view is read only. - - - - - <structname>pg_prepared_xacts</structname> - - - pg_prepared_xacts - - -&common; - - The view pg_prepared_xacts displays - information about transactions that are currently prepared for two-phase - commit (see for details). - - - - pg_prepared_xacts contains one row per prepared - transaction. An entry is removed when the transaction is committed or - rolled back. - - - - <structname>pg_prepared_xacts</> Columns - - - - - Name - Type - References - Description - - - - - transaction - xid - - - Numeric transaction identifier of the prepared transaction - - - - gid - text - - - Global transaction identifier that was assigned to the transaction - - - - prepared - timestamp with time zone - - - Time at which the transaction was prepared for commit - - - - owner - name - pg_authid.rolname - - Name of the user that executed the transaction - - - - database - name - pg_database.datname - - Name of the database in which the transaction was executed - - - - -
- - - When the pg_prepared_xacts view is accessed, the - internal transaction manager data structures are momentarily locked, and - a copy is made for the view to display. This ensures that the - view produces a consistent set of results, while not blocking - normal operations longer than necessary. Nonetheless - there could be some impact on database performance if this view is - frequently accessed. - - - - - - <structname>pg_roles</structname> - - - pg_roles - - -&common; - - The view pg_roles provides access to - information about database roles. This is simply a publicly - readable view of - pg_authid - that blanks out the password field. - - - - This view explicitly exposes the OID column of the underlying table, - since that is needed to do joins to other catalogs. - - - - <structname>pg_roles</> Columns - - - - - Name - Type - References - Description - - - - - - rolname - name - - Role name - - - - rolsuper - bool - - Role has superuser privileges - - - - rolinherit - bool - - Role automatically inherits privileges of roles it is a - member of - - - - rolcreaterole - bool - - Role can create more roles - - - - rolcreatedb - bool - - Role can create databases - - - - rolcatupdate - bool - - - Role can update system catalogs directly. (Even a superuser cannot do - this unless this column is true.) - - - - - rolcanlogin - bool - - - Role can log in. That is, this role can be given as the initial - session authorization identifier - - - - - rolconnlimit - int4 - - - For roles that can log in, this sets maximum number of concurrent - connections this role can make. -1 means no limit. - - - - - rolpassword - text - - Not the password (always reads as ********) - - - - rolvaliduntil - timestamptz - - Password expiry time (only used for password authentication); - null if no expiration - - - - oid - oid - pg_authid.oid - ID of role - - - -
- - - - - <structname>pg_rules</structname> - - - pg_rules - - -&common; - - The view pg_rules provides access to - useful information about query rewrite rules. - - - - <structname>pg_rules</> Columns - - - - - Name - Type - References - Description - - - - - schemaname - name - pg_namespace.nspname - Name of schema containing table - - - tablename - name - pg_class.relname - Name of table the rule is for - - - rulename - name - pg_rewrite.rulename - Name of rule - - - definition - text - - Rule definition (a reconstructed creation command) - - - -
- - - The pg_rules view excludes the ON SELECT rules - of views; those can be seen in pg_views. - - - - - - <structname>pg_seclabels</structname> - - - pg_seclabels - - - - The view pg_seclabels provides information about - security labels. It as an easier-to-query version of the - pg_seclabel catalog. - - - - <structname>pg_seclabels</> Columns - - - - - Name - Type - References - Description - - - - - objoid - oid - any OID column - The OID of the object this security label pertains to - - - classoid - oid - pg_class.oid - The OID of the system catalog this object appears in - - - objsubid - int4 - - - For a security label on a table column, this is the column number (the - objoid and classoid refer to - the table itself). For all other object types, this column is - zero. - - - - objtype - text - - - The type of object to which this label applies, as text. - - - - objnamespace - oid - pg_namespace.oid - - The OID of the namespace for this object, if applicable; - otherwise NULL. - - - - objname - text - - - The name of the object to which this label applies, as text. - - - - provider - text - pg_seclabel.provider - The label provider associated with this label. - - - label - text - pg_seclabel.label - The security label applied to this object. - - - -
- - - - <structname>pg_settings</structname> - - - pg_settings - - -&common; - - The view pg_settings provides access to - run-time parameters of the server. It is essentially an alternative - interface to the - and commands. - It also provides access to some facts about each parameter that are - not directly available from SHOW, such as minimum and - maximum values. - - - - <structname>pg_settings</> Columns - - - - - Name - Type - Description - - - - - name - text - Run-time configuration parameter name - - - setting - text - Current value of the parameter - - - unit - text - Implicit unit of the parameter - - - category - text - Logical group of the parameter - - - short_desc - text - A brief description of the parameter - - - extra_desc - text - Additional, more detailed, description of the parameter - - - context - text - Context required to set the parameter's value (see below) - - - vartype - text - Parameter type (bool, enum, - integer, real, or string) - - - - source - text - Source of the current parameter value - - - min_val - text - Minimum allowed value of the parameter (null for non-numeric - values) - - - max_val - text - Maximum allowed value of the parameter (null for non-numeric - values) - - - enumvals - text[] - Allowed values of an enum parameter (null for non-enum - values) - - - boot_val - text - Parameter value assumed at server startup if the parameter is - not otherwise set - - - reset_val - text - Value that RESET would reset the parameter to - in the current session - - - sourcefile - text - Configuration file the current value was set in (null for - values set from sources other than configuration files, or when - examined by a non-superuser); - helpful when using include directives in configuration files - - - sourceline - integer - Line number within the configuration file the current value was - set at (null for values set from sources other than configuration files, - or when examined by a non-superuser) - - - - -
- - - There are several possible values of context. - In order of decreasing difficulty of changing the setting, they are: - - - - - internal - - - These settings cannot be changed directly; they reflect internally - determined values. Some of them may be adjustable by rebuilding the - server with different configuration options, or by changing options - supplied to initdb. - - - - - postmaster - - - These settings can only be applied when the server starts, so any change - requires restarting the server. Values for these settings are typically - stored in the postgresql.conf file, or passed on - the command line when starting the server. Of course, settings with any - of the lower context types can also be - set at server start time. - - - - - sighup - - - Changes to these settings can be made in - postgresql.conf without restarting the server. - Send a SIGHUP signal to the postmaster to - cause it to re-read postgresql.conf and apply - the changes. The postmaster will also forward the - SIGHUP signal to its child processes so that - they all pick up the new value. - - - - - backend - - - Changes to these settings can be made in - postgresql.conf without restarting the server; - they can also be set for a particular session in the connection request - packet (for example, via libpq's PGOPTIONS - environment variable). However, these settings never change in a - session after it is started. If you change them in - postgresql.conf, send a - SIGHUP signal to the postmaster to cause it to - re-read postgresql.conf. The new values will only - affect subsequently-launched sessions. - - - - - superuser - - - These settings can be set from postgresql.conf, - or within a session via the SET command; but only superusers - can change them via SET. Changes in - postgresql.conf will affect existing sessions - only if no session-local value has been established with SET. - - - - - user - - - These settings can be set from postgresql.conf, - or within a session via the SET command. Any user is - allowed to change his session-local value. Changes in - postgresql.conf will affect existing sessions - only if no session-local value has been established with SET. - - - - - - - See for more information about the various - ways to change these parameters. - - - - The pg_settings view cannot be inserted into or - deleted from, but it can be updated. An UPDATE applied - to a row of pg_settings is equivalent to executing - the command on that named - parameter. The change only affects the value used by the current - session. If an UPDATE is issued within a transaction - that is later aborted, the effects of the UPDATE command - disappear when the transaction is rolled back. Once the surrounding - transaction is committed, the effects will persist until the end of the - session, unless overridden by another UPDATE or - SET. - - - - - - <structname>pg_shadow</structname> - - - pg_shadow - - -&common; - - The view pg_shadow exists for backwards - compatibility: it emulates a catalog that existed in - PostgreSQL before version 8.1. - It shows properties of all roles that are marked as - rolcanlogin in - pg_authid. - - - - The name stems from the fact that this table - should not be readable by the public since it contains passwords. - pg_user - is a publicly readable view on - pg_shadow that blanks out the password field. - - - - <structname>pg_shadow</> Columns - - - - - Name - Type - References - Description - - - - - - usename - name - pg_authid.rolname - User name - - - - usesysid - oid - pg_authid.oid - ID of this user - - - - usecreatedb - bool - - User can create databases - - - - usesuper - bool - - User is a superuser - - - - usecatupd - bool - - - User can update system catalogs. (Even a superuser cannot do - this unless this column is true.) - - - - - passwd - text - - Password (possibly encrypted); null if none. See - pg_authid - for details of how encrypted passwords are stored. - - - - valuntil - abstime - - Password expiry time (only used for password authentication) - - - - useconfig - text[] - - Session defaults for run-time configuration variables - - - -
- - - - - <structname>pg_stats</structname> - - - pg_stats - - -&common; - - The view pg_stats provides access to - the information stored in the pg_statistic - catalog. This view allows access only to rows of - pg_statistic that correspond to tables the - user has permission to read, and therefore it is safe to allow public - read access to this view. - - - - pg_stats is also designed to present the - information in a more readable format than the underlying catalog - — at the cost that its schema must be extended whenever new slot types - are defined for pg_statistic. - - - - <structname>pg_stats</> Columns - - - - - Name - Type - References - Description - - - - - schemaname - name - pg_namespace.nspname - Name of schema containing table - - - - tablename - name - pg_class.relname - Name of table - - - - attname - name - pg_attribute.attname - Name of the column described by this row - - - - inherited - bool - - If true, this row includes inheritance child columns, not just the - values in the specified table - - - - null_frac - real - - Fraction of column entries that are null - - - - avg_width - integer - - Average width in bytes of column's entries - - - - n_distinct - real - - - If greater than zero, the estimated number of distinct values in the - column. If less than zero, the negative of the number of distinct - values divided by the number of rows. (The negated form is used when - ANALYZE believes that the number of distinct values is - likely to increase as the table grows; the positive form is used when - the column seems to have a fixed number of possible values.) For - example, -1 indicates a unique column in which the number of distinct - values is the same as the number of rows. - - - - - most_common_vals - anyarray - - - A list of the most common values in the column. (Null if - no values seem to be more common than any others.) - For some data types such as tsvector, this is a list of - the most common element values rather than values of the type itself. - - - - - most_common_freqs - real[] - - - A list of the frequencies of the most common values or elements, - i.e., number of occurrences of each divided by total number of rows. - (Null when most_common_vals is.) - For some data types such as tsvector, it can also store some - additional information, making it longer than the - most_common_vals array. - - - - - histogram_bounds - anyarray - - - A list of values that divide the column's values into groups of - approximately equal population. The values in - most_common_vals, if present, are omitted from this - histogram calculation. (This column is null if the column data type - does not have a < operator or if the - most_common_vals list accounts for the entire - population.) - - - - - correlation - real - - - Statistical correlation between physical row ordering and - logical ordering of the column values. This ranges from -1 to +1. - When the value is near -1 or +1, an index scan on the column will - be estimated to be cheaper than when it is near zero, due to reduction - of random access to the disk. (This column is null if the column data - type does not have a < operator.) - - - - -
- - - The maximum number of entries in the most_common_vals - and histogram_bounds arrays can be set on a - column-by-column basis using the ALTER TABLE SET STATISTICS - command, or globally by setting the - run-time parameter. - - - - - - <structname>pg_tables</structname> - - - pg_tables - - -&common; - - The view pg_tables provides access to - useful information about each table in the database. - - - - <structname>pg_tables</> Columns - - - - - Name - Type - References - Description - - - - - schemaname - name - pg_namespace.nspname - Name of schema containing table - - - tablename - name - pg_class.relname - Name of table - - - tableowner - name - pg_authid.rolname - Name of table's owner - - - tablespace - name - pg_tablespace.spcname - Name of tablespace containing table (null if default for database) - - - hasindexes - boolean - pg_class.relhasindex - True if table has (or recently had) any indexes - - - hasrules - boolean - pg_class.relhasrules - True if table has (or once had) rules - - - hastriggers - boolean - pg_class.relhastriggers - True if table has (or once had) triggers - - - -
- - - - - <structname>pg_timezone_abbrevs</structname> - - - pg_timezone_abbrevs - - -&common; - - The view pg_timezone_abbrevs provides a list - of time zone abbreviations that are currently recognized by the datetime - input routines. The contents of this view change when the - run-time parameter is modified. - - - - <structname>pg_timezone_abbrevs</> Columns - - - - - Name - Type - Description - - - - - abbrev - text - Time zone abbreviation - - - utc_offset - interval - Offset from UTC (positive means east of Greenwich) - - - is_dst - boolean - True if this is a daylight-savings abbreviation - - - -
- - - - - <structname>pg_timezone_names</structname> - - - pg_timezone_names - - -&common; - - The view pg_timezone_names provides a list - of time zone names that are recognized by SET TIMEZONE, - along with their associated abbreviations, UTC offsets, - and daylight-savings status. - Unlike the abbreviations shown in pg_timezone_abbrevs, many of these names imply a set of daylight-savings transition - date rules. Therefore, the associated information changes across local DST - boundaries. The displayed information is computed based on the current - value of CURRENT_TIMESTAMP. - - - - <structname>pg_timezone_names</> Columns - - - - - Name - Type - Description - - - - - name - text - Time zone name - - - abbrev - text - Time zone abbreviation - - - utc_offset - interval - Offset from UTC (positive means east of Greenwich) - - - is_dst - boolean - True if currently observing daylight savings - - - -
- - - - - <structname>pg_user</structname> - - - pg_user - - -&common; - - The view pg_user provides access to - information about database users. This is simply a publicly - readable view of - pg_shadow - that blanks out the password field. - - - - <structname>pg_user</> Columns - - - - - Name - Type - Description - - - - - usename - name - User name - - - - usesysid - int4 - User ID (arbitrary number used to reference this user) - - - - usecreatedb - bool - User can create databases - - - - usesuper - bool - User is a superuser - - - - usecatupd - bool - - User can update system catalogs. (Even a superuser cannot do - this unless this column is true.) - - - - - passwd - text - Not the password (always reads as ********) - - - - valuntil - abstime - Password expiry time (only used for password authentication) - - - - useconfig - text[] - Session defaults for run-time configuration variables - - - -
- - - - - <structname>pg_user_mappings</structname> - - - pg_user_mappings - - -&common; - - The view pg_user_mappings provides access - to information about user mappings. This is essentially a publicly - readable view of - pg_user_mapping - that leaves out the options field if the user has no rights to use - it. - - - - <structname>pg_user_mappings</> Columns - - - - - Name - Type - References - Description - - - - - - umid - oid - pg_user_mapping.oid - OID of the user mapping - - - - srvid - oid - pg_foreign_server.oid - - The OID of the foreign server that contains this mapping - - - - - srvname - text - - - Name of the foreign server - - - - - umuser - oid - pg_authid.oid - OID of the local role being mapped, 0 if the user mapping is public - - - - usename - name - - Name of the local user to be mapped - - - - umoptions - text[] - - - User mapping specific options, as keyword=value - strings, if the current user is the owner of the foreign - server, else null - - - - -
- - - - - <structname>pg_views</structname> - - - pg_views - - -&common; - - The view pg_views provides access to - useful information about each view in the database. - - - - <structname>pg_views</> Columns - - - - - Name - Type - References - Description - - - - - schemaname - name - pg_namespace.nspname - Name of schema containing view - - - viewname - name - pg_class.relname - Name of view - - - viewowner - name - pg_authid.rolname - Name of view's owner - - - definition - text - - View definition (a reconstructed SELECT query) - - - -
- - - - diff --git a/doc-xc/src/sgml/charset.sgmlin b/doc-xc/src/sgml/charset.sgmlin deleted file mode 100644 index 64ef6e8692..0000000000 --- a/doc-xc/src/sgml/charset.sgmlin +++ /dev/null @@ -1,1716 +0,0 @@ - - - - Localization - - -&common; - - This chapter describes the available localization features from the - point of view of the administrator. - - PostgreSQL supports two localization - facilities: - - - Postgres-XC inherits supports of two localization - facilities from PostgreSQL: - - - Postgres-XL inherits supports of two localization - facilities from PostgreSQL: - - - - - - Using the locale features of the operating system to provide - locale-specific collation order, number formatting, translated - messages, and other aspects. - This is covered in and - . - - - - - - Providing a number of different character sets to support storing text - in all kinds of languages, and providing character set translation - between client and server. - This is covered in . - - - - - - - - Locale Support - - locale -&common; - - - Locale support refers to an application respecting - cultural preferences regarding alphabets, sorting, number - - formatting, etc. PostgreSQL uses the standard ISO - - - formatting, etc. Postgres-XC uses the standard ISO - - - formatting, etc. Postgres-XL uses the standard ISO - - C and POSIX locale facilities provided by the server operating - system. For additional information refer to the documentation of your - system. - - - - Overview - -&common; - - Locale support is automatically initialized when a database - cluster is created using initdb. - initdb will initialize the database cluster - with the locale setting of its execution environment by default, - so if your system is already set to use the locale that you want - in your database cluster then there is nothing else you need to - do. If you want to use a different locale (or you are not sure - which locale your system is set to), you can instruct - initdb exactly which locale to use by - specifying the option. For example: - -initdb --locale=sv_SE - - - - - This example for Unix systems sets the locale to Swedish - (sv) as spoken - in Sweden (SE). Other possibilities might include - en_US (U.S. English) and fr_CA (French - Canadian). If more than one character set can be used for a - locale then the specifications can take the form - language_territory.codeset. For example, - fr_BE.UTF-8 represents the French language (fr) as - spoken in Belgium (BE), with a UTF-8 character set - encoding. - - - - What locales are available on your - system under what names depends on what was provided by the operating - system vendor and what was installed. On most Unix systems, the command - locale -a will provide a list of available locales. - Windows uses more verbose locale names, such as German_Germany - or Swedish_Sweden.1252, but the principles are the same. - - - - Occasionally it is useful to mix rules from several locales, e.g., - use English collation rules but Spanish messages. To support that, a - set of locale subcategories exist that control only certain - aspects of the localization rules: - - - - - - LC_COLLATE - String sort order - - - LC_CTYPE - Character classification (What is a letter? Its upper-case equivalent?) - - - LC_MESSAGES - Language of messages - - - LC_MONETARY - Formatting of currency amounts - - - LC_NUMERIC - Formatting of numbers - - - LC_TIME - Formatting of dates and times - - - - - - The category names translate into names of - initdb options to override the locale choice - for a specific category. For instance, to set the locale to - French Canadian, but use U.S. rules for formatting currency, use - initdb --locale=fr_CA --lc-monetary=en_US. - - - - If you want the system to behave as if it had no locale support, - use the special locale name C, or equivalently - POSIX. - - - - Some locale categories must have their values - fixed when the database is created. You can use different settings - for different databases, but once a database is created, you cannot - change them for that database anymore. LC_COLLATE - and LC_CTYPE are these categories. They affect - the sort order of indexes, so they must be kept fixed, or indexes on - text columns would become corrupt. - (But you can alleviate this restriction using collations, as discussed - in .) - The default values for these - categories are determined when initdb is run, and - those values are used when new databases are created, unless - specified otherwise in the CREATE DATABASE command. - - - - The other locale categories can be changed whenever desired - by setting the server configuration parameters - that have the same name as the locale categories (see for details). The values - that are chosen by initdb are actually only written - into the configuration file postgresql.conf to - serve as defaults when the server is started. If you remove these - assignments from postgresql.conf then the - server will inherit the settings from its execution environment. - - - - Note that the locale behavior of the server is determined by the - environment variables seen by the server, not by the environment - of any client. Therefore, be careful to configure the correct locale settings - before starting the server. A consequence of this is that if - client and server are set up in different locales, messages might - appear in different languages depending on where they originated. - - - - - When we speak of inheriting the locale from the execution - environment, this means the following on most operating systems: - For a given locale category, say the collation, the following - environment variables are consulted in this order until one is - found to be set: LC_ALL, LC_COLLATE - (or the variable corresponding to the respective category), - LANG. If none of these environment variables are - set then the locale defaults to C. - - - - Some message localization libraries also look at the environment - variable LANGUAGE which overrides all other locale - settings for the purpose of setting the language of messages. If - in doubt, please refer to the documentation of your operating - system, in particular the documentation about - gettext. - - - - - To enable messages to be translated to the user's preferred language, - NLS must have been selected at build time - (configure --enable-nls). All other locale support is - built in automatically. - - - - - Behavior - -&common; - - The locale settings influence the following SQL features: - - - - - Sort order in queries using ORDER BY or the standard - comparison operators on textual data - ORDER BYand locales - - - - - - The upper, lower, and initcap - functions - upperand locales - lowerand locales - - - - - - Pattern matching operators (LIKE, SIMILAR TO, - and POSIX-style regular expressions); locales affect both case - insensitive matching and the classification of characters by - character-class regular expressions - LIKEand locales - regular expressionsand locales - - - - - - The to_char family of functions - to_charand locales - - - - - - The ability to use indexes with LIKE clauses - - - - - - - The drawback of using locales other than C or - - POSIX in PostgreSQL is its performance - - - POSIX in Postgres-XC is its performance - - - POSIX in Postgres-XL is its performance - - impact. It slows character handling and prevents ordinary indexes - from being used by LIKE. For this reason use locales - only if you actually need them. - - - - - As a workaround to allow PostgreSQL to use indexes - - - As a workaround to allow Postgres-XC to use indexes - - - As a workaround to allow Postgres-XL to use indexes - - with LIKE clauses under a non-C locale, several custom - operator classes exist. These allow the creation of an index that - performs a strict character-by-character comparison, ignoring - locale comparison rules. Refer to - for more information. Another approach is to create indexes using - the C collation, as discussed in - . - - - - - Problems - -&common; - - If locale support doesn't work according to the explanation above, - check that the locale support in your operating system is - correctly configured. To check what locales are installed on your - system, you can use the command locale -a if - your operating system provides it. - - - - - Check that PostgreSQL is actually using the locale - - - Check that Postgres-XC is actually using the locale - - - Check that Postgres-XL is actually using the locale - - that you think it is. The LC_COLLATE and LC_CTYPE - settings are determined when a database is created, and cannot be - changed except by creating a new database. Other locale - settings including LC_MESSAGES and LC_MONETARY - are initially determined by the environment the server is started - in, but can be changed on-the-fly. You can check the active locale - settings using the SHOW command. - - - - The directory src/test/locale in the source - distribution contains a test suite for - - PostgreSQL's locale support. - - - Postgres-XC's locale support. - - - Postgres-XL's locale support. - - - - - Client applications that handle server-side errors by parsing the - text of the error message will obviously have problems when the - server's messages are in a different language. Authors of such - applications are advised to make use of the error code scheme - instead. - - - - Maintaining catalogs of message translations requires the on-going - efforts of many volunteers that want to see - - PostgreSQL speak their preferred language well. - - - Postgres-XC speak their preferred language well. - - - Postgres-XL speak their preferred language well. - - If messages in your language are currently not available or not fully - translated, your assistance would be appreciated. If you want to - help, refer to or write to the developers' - mailing list. - - - - - - - Collation Support - - collation - - - The collation feature allows specifying the sort order and character - classification behavior of data per-column, or even per-operation. - This alleviates the restriction that the - LC_COLLATE and LC_CTYPE settings - of a database cannot be changed after its creation. - - - - Concepts - - - Conceptually, every expression of a collatable data type has a - collation. (The built-in collatable data types are - text, varchar, and char. - User-defined base types can also be marked collatable, and of course - a domain over a collatable data type is collatable.) If the - expression is a column reference, the collation of the expression is the - defined collation of the column. If the expression is a constant, the - collation is the default collation of the data type of the - constant. The collation of a more complex expression is derived - from the collations of its inputs, as described below. - - - - The collation of an expression can be the default - collation, which means the locale settings defined for the - database. It is also possible for an expression's collation to be - indeterminate. In such cases, ordering operations and other - operations that need to know the collation will fail. - - - - When the database system has to perform an ordering or a character - classification, it uses the collation of the input expression. This - happens, for example, with ORDER BY clauses - and function or operator calls such as <. - The collation to apply for an ORDER BY clause - is simply the collation of the sort key. The collation to apply for a - function or operator call is derived from the arguments, as described - below. In addition to comparison operators, collations are taken into - account by functions that convert between lower and upper case - letters, such as lower, upper, and - initcap; by pattern matching operators; and by - to_char and related functions. - - - - For a function or operator call, the collation that is derived by - examining the argument collations is used at run time for performing - the specified operation. If the result of the function or operator - call is of a collatable data type, the collation is also used at parse - time as the defined collation of the function or operator expression, - in case there is a surrounding expression that requires knowledge of - its collation. - - - - The collation derivation of an expression can be - implicit or explicit. This distinction affects how collations are - combined when multiple different collations appear in an - expression. An explicit collation derivation occurs when a - COLLATE clause is used; all other collation - derivations are implicit. When multiple collations need to be - combined, for example in a function call, the following rules are - used: - - - - - If any input expression has an explicit collation derivation, then - all explicitly derived collations among the input expressions must be - the same, otherwise an error is raised. If any explicitly - derived collation is present, that is the result of the - collation combination. - - - - - - Otherwise, all input expressions must have the same implicit - collation derivation or the default collation. If any non-default - collation is present, that is the result of the collation combination. - Otherwise, the result is the default collation. - - - - - - If there are conflicting non-default implicit collations among the - input expressions, then the combination is deemed to have indeterminate - collation. This is not an error condition unless the particular - function being invoked requires knowledge of the collation it should - apply. If it does, an error will be raised at run-time. - - - - - For example, consider this table definition: - -CREATE TABLE test1 ( - a text COLLATE "de_DE", - b text COLLATE "es_ES", - ... -); - - - Then in - -SELECT a < 'foo' FROM test1; - - the < comparison is performed according to - de_DE rules, because the expression combines an - implicitly derived collation with the default collation. But in - -SELECT a < ('foo' COLLATE "fr_FR") FROM test1; - - the comparison is performed using fr_FR rules, - because the explicit collation derivation overrides the implicit one. - Furthermore, given - -SELECT a < b FROM test1; - - the parser cannot determine which collation to apply, since the - a and b columns have conflicting - implicit collations. Since the < operator - does need to know which collation to use, this will result in an - error. The error can be resolved by attaching an explicit collation - specifier to either input expression, thus: - -SELECT a < b COLLATE "de_DE" FROM test1; - - or equivalently - -SELECT a COLLATE "de_DE" < b FROM test1; - - On the other hand, the structurally similar case - -SELECT a || b FROM test1; - - does not result in an error, because the || operator - does not care about collations: its result is the same regardless - of the collation. - - - - The collation assigned to a function or operator's combined input - expressions is also considered to apply to the function or operator's - result, if the function or operator delivers a result of a collatable - data type. So, in - -SELECT * FROM test1 ORDER BY a || 'foo'; - - the ordering will be done according to de_DE rules. - But this query: - -SELECT * FROM test1 ORDER BY a || b; - - results in an error, because even though the || operator - doesn't need to know a collation, the ORDER BY clause does. - As before, the conflict can be resolved with an explicit collation - specifier: - -SELECT * FROM test1 ORDER BY a || b COLLATE "fr_FR"; - - - - - - Managing Collations - - - A collation is an SQL schema object that maps an SQL name to - operating system locales. In particular, it maps to a combination - of LC_COLLATE and LC_CTYPE. (As - the name would suggest, the main purpose of a collation is to set - LC_COLLATE, which controls the sort order. But - it is rarely necessary in practice to have an - LC_CTYPE setting that is different from - LC_COLLATE, so it is more convenient to collect - these under one concept than to create another infrastructure for - setting LC_CTYPE per expression.) Also, a collation - is tied to a character set encoding (see ). - The same collation name may exist for different encodings. - - - - On all platforms, the collations named default, - C, and POSIX are available. Additional - collations may be available depending on operating system support. - The default collation selects the LC_COLLATE - and LC_CTYPE values specified at database creation time. - The C and POSIX collations both specify - traditional C behavior, in which only the ASCII letters - A through Z - are treated as letters, and sorting is done strictly by character - code byte values. - - - - If the operating system provides support for using multiple locales - within a single program (newlocale and related functions), - then when a database cluster is initialized, initdb - populates the system catalog pg_collation with - collations based on all the locales it finds on the operating - system at the time. For example, the operating system might - provide a locale named de_DE.utf8. - initdb would then create a collation named - de_DE.utf8 for encoding UTF8 - that has both LC_COLLATE and - LC_CTYPE set to de_DE.utf8. - It will also create a collation with the .utf8 - tag stripped off the name. So you could also use the collation - under the name de_DE, which is less cumbersome - to write and makes the name less encoding-dependent. Note that, - nevertheless, the initial set of collation names is - platform-dependent. - - - - In case a collation is needed that has different values for - LC_COLLATE and LC_CTYPE, a new - collation may be created using - the command. That command - can also be used to create a new collation from an existing - collation, which can be useful to be able to use - operating-system-independent collation names in applications. - - - - Within any particular database, only collations that use that - database's encoding are of interest. Other entries in - pg_collation are ignored. Thus, a stripped collation - name such as de_DE can be considered unique - within a given database even though it would not be unique globally. - Use of the stripped collation names is recommendable, since it will - make one less thing you need to change if you decide to change to - another database encoding. Note however that the default, - C, and POSIX collations can be used - regardless of the database encoding. - - - - PostgreSQL considers distinct collation - objects to be incompatible even when they have identical properties. - Thus for example, - -SELECT a COLLATE "C" < b COLLATE "POSIX" FROM test1; - - will draw an error even though the C and POSIX - collations have identical behaviors. Mixing stripped and non-stripped - collation names is therefore not recommended. - - - - - - Character Set Support - - character set -&common; - - - - The character set support in PostgreSQL - - - The character set support in Postgres-XC - - - The character set support in Postgres-XL - - allows you to store text in a variety of character sets (also called - encodings), including - single-byte character sets such as the ISO 8859 series and - multiple-byte character sets such as EUC (Extended Unix - Code), UTF-8, and Mule internal code. All supported character sets - can be used transparently by clients, but a few are not supported - for use within the server (that is, as a server-side encoding). - The default character set is selected while - - initializing your PostgreSQL database - - - initializing your Postgres-XC database - - - initializing your Postgres-XL database - - cluster using initdb. It can be overridden when you - create a database, so you can have multiple - databases each with a different character set. - - - - An important restriction, however, is that each database's character set - must be compatible with the database's LC_CTYPE (character - classification) and LC_COLLATE (string sort order) locale - settings. For C or - POSIX locale, any character set is allowed, but for other - locales there is only one character set that will work correctly. - (On Windows, however, UTF-8 encoding can be used with any locale.) - - - - Supported Character Sets -&common; - - - shows the character sets available - - for use in PostgreSQL. - - - for use in Postgres-XC. - - - for use in Postgres-XL. - - - - - - <productname>PostgreSQL</productname> Character Sets - - - <productname>Postgres-XC</productname> Character Sets - - - <productname>Postgres-XL</productname> Character Sets - - - - - Name - Description - Language - Server? - - Bytes/Char - Aliases - - - - - BIG5 - Big Five - Traditional Chinese - No - 1-2 - WIN950, Windows950 - - - EUC_CN - Extended UNIX Code-CN - Simplified Chinese - Yes - 1-3 - - - - EUC_JP - Extended UNIX Code-JP - Japanese - Yes - 1-3 - - - - EUC_JIS_2004 - Extended UNIX Code-JP, JIS X 0213 - Japanese - Yes - 1-3 - - - - EUC_KR - Extended UNIX Code-KR - Korean - Yes - 1-3 - - - - EUC_TW - Extended UNIX Code-TW - Traditional Chinese, Taiwanese - Yes - 1-3 - - - - GB18030 - National Standard - Chinese - No - 1-2 - - - - GBK - Extended National Standard - Simplified Chinese - No - 1-2 - WIN936, Windows936 - - - ISO_8859_5 - ISO 8859-5, ECMA 113 - Latin/Cyrillic - Yes - 1 - - - - ISO_8859_6 - ISO 8859-6, ECMA 114 - Latin/Arabic - Yes - 1 - - - - ISO_8859_7 - ISO 8859-7, ECMA 118 - Latin/Greek - Yes - 1 - - - - ISO_8859_8 - ISO 8859-8, ECMA 121 - Latin/Hebrew - Yes - 1 - - - - JOHAB - JOHAB - Korean (Hangul) - No - 1-3 - - - - KOI8R - KOI8-R - Cyrillic (Russian) - Yes - 1 - KOI8 - - - KOI8U - KOI8-U - Cyrillic (Ukrainian) - Yes - 1 - - - - LATIN1 - ISO 8859-1, ECMA 94 - Western European - Yes - 1 - ISO88591 - - - LATIN2 - ISO 8859-2, ECMA 94 - Central European - Yes - 1 - ISO88592 - - - LATIN3 - ISO 8859-3, ECMA 94 - South European - Yes - 1 - ISO88593 - - - LATIN4 - ISO 8859-4, ECMA 94 - North European - Yes - 1 - ISO88594 - - - LATIN5 - ISO 8859-9, ECMA 128 - Turkish - Yes - 1 - ISO88599 - - - LATIN6 - ISO 8859-10, ECMA 144 - Nordic - Yes - 1 - ISO885910 - - - LATIN7 - ISO 8859-13 - Baltic - Yes - 1 - ISO885913 - - - LATIN8 - ISO 8859-14 - Celtic - Yes - 1 - ISO885914 - - - LATIN9 - ISO 8859-15 - LATIN1 with Euro and accents - Yes - 1 - ISO885915 - - - LATIN10 - ISO 8859-16, ASRO SR 14111 - Romanian - Yes - 1 - ISO885916 - - - MULE_INTERNAL - Mule internal code - Multilingual Emacs - Yes - 1-4 - - - - SJIS - Shift JIS - Japanese - No - 1-2 - Mskanji, ShiftJIS, WIN932, Windows932 - - - SHIFT_JIS_2004 - Shift JIS, JIS X 0213 - Japanese - No - 1-2 - - - - SQL_ASCII - unspecified (see text) - any - Yes - 1 - - - - UHC - Unified Hangul Code - Korean - No - 1-2 - WIN949, Windows949 - - - UTF8 - Unicode, 8-bit - all - Yes - 1-4 - Unicode - - - WIN866 - Windows CP866 - Cyrillic - Yes - 1 - ALT - - - WIN874 - Windows CP874 - Thai - Yes - 1 - - - - WIN1250 - Windows CP1250 - Central European - Yes - 1 - - - - WIN1251 - Windows CP1251 - Cyrillic - Yes - 1 - WIN - - - WIN1252 - Windows CP1252 - Western European - Yes - 1 - - - - WIN1253 - Windows CP1253 - Greek - Yes - 1 - - - - WIN1254 - Windows CP1254 - Turkish - Yes - 1 - - - - WIN1255 - Windows CP1255 - Hebrew - Yes - 1 - - - - WIN1256 - Windows CP1256 - Arabic - Yes - 1 - - - - WIN1257 - Windows CP1257 - Baltic - Yes - 1 - - - - WIN1258 - Windows CP1258 - Vietnamese - Yes - 1 - ABC, TCVN, TCVN5712, VSCII - - - -
- - - Not all client APIs support all the listed character sets. For example, the - - PostgreSQL - - - Postgres-XC - - - Postgres-XL - - JDBC driver does not support MULE_INTERNAL, LATIN6, - LATIN8, and LATIN10. - - - - The SQL_ASCII setting behaves considerably differently - from the other settings. When the server character set is - SQL_ASCII, the server interprets byte values 0-127 - according to the ASCII standard, while byte values 128-255 are taken - as uninterpreted characters. No encoding conversion will be done when - the setting is SQL_ASCII. Thus, this setting is not so - much a declaration that a specific encoding is in use, as a declaration - of ignorance about the encoding. In most cases, if you are - working with any non-ASCII data, it is unwise to use the - SQL_ASCII setting because - - PostgreSQL will be unable to help you by - - - Postgres-XC will be unable to help you by - - - Postgres-XL will be unable to help you by - - converting or validating non-ASCII characters. - - - - - Setting the Character Set -&common; - - - initdb defines the default character set (encoding) - - for a PostgreSQL cluster. For example, - - - for a Postgres-XC cluster. For example, - - - for a Postgres-XL cluster. For example, - - - -initdb -E EUC_JP - - - sets the default character set to - EUC_JP (Extended Unix Code for Japanese). You - can use instead of - if you prefer longer option strings. - If no option is - given, initdb attempts to determine the appropriate - encoding to use based on the specified or default locale. - - - - You can specify a non-default encoding at database creation time, - provided that the encoding is compatible with the selected locale: - - -createdb -E EUC_KR -T template0 --lc-collate=ko_KR.euckr --lc-ctype=ko_KR.euckr korean - - - This will create a database named korean that - uses the character set EUC_KR, and locale ko_KR. - Another way to accomplish this is to use this SQL command: - - -CREATE DATABASE korean WITH ENCODING 'EUC_KR' LC_COLLATE='ko_KR.euckr' LC_CTYPE='ko_KR.euckr' TEMPLATE=template0; - - - Notice that the above commands specify copying the template0 - database. When copying any other database, the encoding and locale - settings cannot be changed from those of the source database, because - that might result in corrupt data. For more information see - . - - - - The encoding for a database is stored in the system catalog - pg_database. You can see it by using the - psql option or the - \l command. - - -$ psql -l - List of databases - Name | Owner | Encoding | Collation | Ctype | Access Privileges ------------+----------+-----------+-------------+-------------+------------------------------------- - clocaledb | hlinnaka | SQL_ASCII | C | C | - englishdb | hlinnaka | UTF8 | en_GB.UTF8 | en_GB.UTF8 | - japanese | hlinnaka | UTF8 | ja_JP.UTF8 | ja_JP.UTF8 | - korean | hlinnaka | EUC_KR | ko_KR.euckr | ko_KR.euckr | - postgres | hlinnaka | UTF8 | fi_FI.UTF8 | fi_FI.UTF8 | - template0 | hlinnaka | UTF8 | fi_FI.UTF8 | fi_FI.UTF8 | {=c/hlinnaka,hlinnaka=CTc/hlinnaka} - template1 | hlinnaka | UTF8 | fi_FI.UTF8 | fi_FI.UTF8 | {=c/hlinnaka,hlinnaka=CTc/hlinnaka} -(7 rows) - - - - - - - On most modern operating systems, PostgreSQL - - - On most modern operating systems, Postgres-XC - - - On most modern operating systems, Postgres-XL - - can determine which character set is implied by the LC_CTYPE - setting, and it will enforce that only the matching database encoding is - used. On older systems it is your responsibility to ensure that you use - the encoding expected by the locale you have selected. A mistake in - this area is likely to lead to strange behavior of locale-dependent - operations such as sorting. - - - - - PostgreSQL will allow superusers to create - - - Postgres-XC will allow superusers to create - - - Postgres-XL will allow superusers to create - - databases with SQL_ASCII encoding even when - LC_CTYPE is not C or POSIX. As noted - above, SQL_ASCII does not enforce that the data stored in - the database has any particular encoding, and so this choice poses risks - of locale-dependent misbehavior. Using this combination of settings is - deprecated and may someday be forbidden altogether. - - - - - - Automatic Character Set Conversion Between Server and Client -&common; - - - - PostgreSQL supports automatic - - - Postgres-XC supports automatic - - - Postgres-XL supports automatic - - character set conversion between server and client for certain - character set combinations. The conversion information is stored in the - - pg_conversion system catalog. PostgreSQL - - - pg_conversion system catalog. Postgres-XC - - - pg_conversion system catalog. Postgres-XL - - comes with some predefined conversions, as shown in . You can create a new - conversion using the SQL command CREATE CONVERSION. - - - - Client/Server Character Set Conversions - - - - Server Character Set - Available Client Character Sets - - - - - BIG5 - not supported as a server encoding - - - - EUC_CN - EUC_CN, - MULE_INTERNAL, - UTF8 - - - - EUC_JP - EUC_JP, - MULE_INTERNAL, - SJIS, - UTF8 - - - - EUC_KR - EUC_KR, - MULE_INTERNAL, - UTF8 - - - - EUC_TW - EUC_TW, - BIG5, - MULE_INTERNAL, - UTF8 - - - - GB18030 - not supported as a server encoding - - - - GBK - not supported as a server encoding - - - - ISO_8859_5 - ISO_8859_5, - KOI8R, - MULE_INTERNAL, - UTF8, - WIN866, - WIN1251 - - - - ISO_8859_6 - ISO_8859_6, - UTF8 - - - - ISO_8859_7 - ISO_8859_7, - UTF8 - - - - ISO_8859_8 - ISO_8859_8, - UTF8 - - - - JOHAB - JOHAB, - UTF8 - - - - KOI8R - KOI8R, - ISO_8859_5, - MULE_INTERNAL, - UTF8, - WIN866, - WIN1251 - - - - KOI8U - KOI8U, - UTF8 - - - - LATIN1 - LATIN1, - MULE_INTERNAL, - UTF8 - - - - LATIN2 - LATIN2, - MULE_INTERNAL, - UTF8, - WIN1250 - - - - LATIN3 - LATIN3, - MULE_INTERNAL, - UTF8 - - - - LATIN4 - LATIN4, - MULE_INTERNAL, - UTF8 - - - - LATIN5 - LATIN5, - UTF8 - - - - LATIN6 - LATIN6, - UTF8 - - - - LATIN7 - LATIN7, - UTF8 - - - - LATIN8 - LATIN8, - UTF8 - - - - LATIN9 - LATIN9, - UTF8 - - - - LATIN10 - LATIN10, - UTF8 - - - - MULE_INTERNAL - MULE_INTERNAL, - BIG5, - EUC_CN, - EUC_JP, - EUC_KR, - EUC_TW, - ISO_8859_5, - KOI8R, - LATIN1 to LATIN4, - SJIS, - WIN866, - WIN1250, - WIN1251 - - - - SJIS - not supported as a server encoding - - - - SQL_ASCII - any (no conversion will be performed) - - - - UHC - not supported as a server encoding - - - - UTF8 - all supported encodings - - - - WIN866 - WIN866, - ISO_8859_5, - KOI8R, - MULE_INTERNAL, - UTF8, - WIN1251 - - - - WIN874 - WIN874, - UTF8 - - - - WIN1250 - WIN1250, - LATIN2, - MULE_INTERNAL, - UTF8 - - - - WIN1251 - WIN1251, - ISO_8859_5, - KOI8R, - MULE_INTERNAL, - UTF8, - WIN866 - - - - WIN1252 - WIN1252, - UTF8 - - - - WIN1253 - WIN1253, - UTF8 - - - - WIN1254 - WIN1254, - UTF8 - - - - WIN1255 - WIN1255, - UTF8 - - - - WIN1256 - WIN1256, - UTF8 - - - - WIN1257 - WIN1257, - UTF8 - - - - WIN1258 - WIN1258, - UTF8 - - - - -
- - - To enable automatic character set conversion, you have to - - tell PostgreSQL the character set - - - tell Postgres-XC the character set - - - tell Postgres-XL the character set - - (encoding) you would like to use in the client. There are several - ways to accomplish this: - - - - - Using the \encoding command in - psql. - \encoding allows you to change client - encoding on the fly. For - example, to change the encoding to SJIS, type: - - -\encoding SJIS - - - - - - - libpq () has functions to control the client encoding. - - - - - - Using SET client_encoding TO. - - Setting the client encoding can be done with this SQL command: - - -SET CLIENT_ENCODING TO 'value'; - - - Also you can use the standard SQL syntax SET NAMES - for this purpose: - - -SET NAMES 'value'; - - - To query the current client encoding: - - -SHOW client_encoding; - - - To return to the default encoding: - - -RESET client_encoding; - - - - - - - Using PGCLIENTENCODING. If the environment variable - PGCLIENTENCODING is defined in the client's - environment, that client encoding is automatically selected - when a connection to the server is made. (This can - subsequently be overridden using any of the other methods - mentioned above.) - - - - - - Using the configuration variable . If the - client_encoding variable is set, that client - encoding is automatically selected when a connection to the - server is made. (This can subsequently be overridden using any - of the other methods mentioned above.) - - - - - - - - If the conversion of a particular character is not possible - — suppose you chose EUC_JP for the - server and LATIN1 for the client, and some - Japanese characters are returned that do not have a representation in - LATIN1 — an error is reported. - - - - If the client character set is defined as SQL_ASCII, - encoding conversion is disabled, regardless of the server's character - set. Just as for the server, use of SQL_ASCII is unwise - unless you are working with all-ASCII data. - - - - - Further Reading -&common; - - - These are good sources to start learning about various kinds of encoding - systems. - - - - - - - - An extensive collection of documents about character sets, encodings, - and code pages. - - - - - - CJKV Information Processing: Chinese, Japanese, Korean & Vietnamese Computing - - - - Contains detailed explanations of EUC_JP, - EUC_CN, EUC_KR, - EUC_TW. - - - - - - - - - - The web site of the Unicode Consortium. - - - - - - RFC 3629 - - - - UTF-8 (8-bit UCS/Unicode Transformation - Format) is defined here. - - - - - - - - - - diff --git a/doc-xc/src/sgml/chkpass.sgmlin b/doc-xc/src/sgml/chkpass.sgmlin deleted file mode 100644 index fdbe0feacc..0000000000 --- a/doc-xc/src/sgml/chkpass.sgmlin +++ /dev/null @@ -1,97 +0,0 @@ - - - - chkpass - - - chkpass - - -&common; - - - This module implements a data type chkpass that is - designed for storing encrypted passwords. - Each password is automatically converted to encrypted form upon entry, - and is always stored encrypted. To compare, simply compare against a clear - text password and the comparison function will encrypt it before comparing. - - - - There are provisions in the code to report an error if the password is - determined to be easily crackable. However, this is currently just - a stub that does nothing. - - - - If you precede an input string with a colon, it is assumed to be an - already-encrypted password, and is stored without further encryption. - This allows entry of previously-encrypted passwords. - - - - On output, a colon is prepended. This makes it possible to dump and reload - passwords without re-encrypting them. If you want the encrypted password - without the colon then use the raw() function. - This allows you to use the - type with things like Apache's Auth_PostgreSQL module. - - - - The encryption uses the standard Unix function crypt(), - and so it suffers - from all the usual limitations of that function; notably that only the - first eight characters of a password are considered. - - - - Note that the chkpass data type is not indexable. - - - - - Sample usage: - - - -test=# create table test (p chkpass); -CREATE TABLE -test=# insert into test values ('hello'); -INSERT 0 1 -test=# select * from test; - p ----------------- - :dVGkpXdOrE3ko -(1 row) - -test=# select raw(p) from test; - raw ---------------- - dVGkpXdOrE3ko -(1 row) - -test=# select p = 'hello' from test; - ?column? ----------- - t -(1 row) - -test=# select p = 'goodbye' from test; - ?column? ----------- - f -(1 row) - - - - Author - - - D'Arcy J.M. Cain (darcy@druid.net) - - - - diff --git a/doc-xc/src/sgml/citext.sgmlin b/doc-xc/src/sgml/citext.sgmlin deleted file mode 100644 index 26e2fab679..0000000000 --- a/doc-xc/src/sgml/citext.sgmlin +++ /dev/null @@ -1,313 +0,0 @@ - - - - citext - - - citext - - -&common; - - - The citext module provides a case-insensitive - character string type, citext. Essentially, it internally calls - lower when comparing values. Otherwise, it behaves almost - exactly like text. - - - - Rationale - -&common; - - - The standard approach to doing case-insensitive matches - in PostgreSQL has been to use the lower - function when comparing values, for example - - -SELECT * FROM tab WHERE lower(col) = LOWER(?); - - - - - This works reasonably well, but has a number of drawbacks: - - - - - - It makes your SQL statements verbose, and you always have to remember to - use lower on both the column and the query value. - - - - - It won't use an index, unless you create a functional index using - lower. - - - - - If you declare a column as UNIQUE or PRIMARY - KEY, the implicitly generated index is case-sensitive. So it's - useless for case-insensitive searches, and it won't enforce - uniqueness case-insensitively. - - - - - - The citext data type allows you to eliminate calls - to lower in SQL queries, and allows a primary key to - be case-insensitive. citext is locale-aware, just - like text, which means that the matching of upper case and - lower case characters is dependent on the rules of - the database's LC_CTYPE setting. Again, this behavior is - identical to the use of lower in queries. But because it's - done transparently by the data type, you don't have to remember to do - anything special in your queries. - - - - - - How to Use It - - - Here's a simple example of usage: - - - -CREATE TABLE users ( - nick CITEXT PRIMARY KEY, - pass TEXT NOT NULL -); - -INSERT INTO users VALUES ( 'larry', md5(random()::text) ); -INSERT INTO users VALUES ( 'Tom', md5(random()::text) ); -INSERT INTO users VALUES ( 'Damian', md5(random()::text) ); -INSERT INTO users VALUES ( 'NEAL', md5(random()::text) ); -INSERT INTO users VALUES ( 'Bjørn', md5(random()::text) ); - -SELECT * FROM users WHERE nick = 'Larry'; - - - - -CREATE TABLE users ( - id int PRIMARY KEY, - nick CITEXT, - pass TEXT NOT NULL -); - -INSERT INTO users VALUES (1, 'larry', md5(random()::text) ); -INSERT INTO users VALUES (2, 'Tom', md5(random()::text) ); -INSERT INTO users VALUES (3, 'Damian', md5(random()::text) ); -INSERT INTO users VALUES (4, 'NEAL', md5(random()::text) ); -INSERT INTO users VALUES (5, 'Bjørn', md5(random()::text) ); - -SELECT * FROM users WHERE nick = 'Larry'; - - - - -CREATE TABLE users ( - id int PRIMARY KEY, - nick CITEXT, - pass TEXT NOT NULL -); - -INSERT INTO users VALUES (1, 'larry', md5(random()::text) ); -INSERT INTO users VALUES (2, 'Tom', md5(random()::text) ); -INSERT INTO users VALUES (3, 'Damian', md5(random()::text) ); -INSERT INTO users VALUES (4, 'NEAL', md5(random()::text) ); -INSERT INTO users VALUES (5, 'Bjørn', md5(random()::text) ); - -SELECT * FROM users WHERE nick = 'Larry'; - - - - The SELECT statement will return one tuple, even though - the nick column was set to larry and the query - was for Larry. - - - -&xconly; - - Please note that the column of the type CITEXT - cannot be the distribution column; - - - - - Please note that the column of the type CITEXT - cannot be the distribution column; - - - - - - - String Comparison Behavior - -&common; - - citext performs comparisons by converting each string to lower - case (as though lower were called) and then comparing the - results normally. Thus, for example, two strings are considered equal - if lower would produce identical results for them. - - - - In order to emulate a case-insensitive collation as closely as possible, - there are citext-specific versions of a number of string-processing - operators and functions. So, for example, the regular expression - operators ~ and ~* exhibit the same behavior when - applied to citext: they both match case-insensitively. - The same is true - for !~ and !~*, as well as for the - LIKE operators ~~ and ~~*, and - !~~ and !~~*. If you'd like to match - case-sensitively, you can cast the operator's arguments to text. - - - - Similarly, all of the following functions perform matching - case-insensitively if their arguments are citext: - - - - - - regexp_replace() - - - - - regexp_split_to_array() - - - - - regexp_split_to_table() - - - - - replace() - - - - - split_part() - - - - - strpos() - - - - - translate() - - - - - - For the regexp functions, if you want to match case-sensitively, you can - specify the c flag to force a case-sensitive match. Otherwise, - you must cast to text before using one of these functions if - you want case-sensitive behavior. - - - - - - Limitations - - - -&common; - - - citext's case-folding behavior depends on - the LC_CTYPE setting of your database. How it compares - values is therefore determined when the database is created. - It is not truly - case-insensitive in the terms defined by the Unicode standard. - Effectively, what this means is that, as long as you're happy with your - collation, you should be happy with citext's comparisons. But - if you have data in different languages stored in your database, users - of one language may find their query results are not as expected if the - collation is for another language. - - - - - - As of PostgreSQL 9.1, you can attach a - COLLATE specification to citext columns or data - values. Currently, citext operators will honor a non-default - COLLATE specification while comparing case-folded strings, - but the initial folding to lower case is always done according to the - database's LC_CTYPE setting (that is, as though - COLLATE "default" were given). This may be changed in a - future release so that both steps follow the input COLLATE - specification. - - - - - - citext is not as efficient as text because the - operator functions and the B-tree comparison functions must make copies - of the data and convert it to lower case for comparisons. It is, - however, slightly more efficient than using lower to get - case-insensitive matching. - - - - - - citext doesn't help much if you need data to compare - case-sensitively in some contexts and case-insensitively in other - contexts. The standard answer is to use the text type and - manually use the lower function when you need to compare - case-insensitively; this works all right if case-insensitive comparison - is needed only infrequently. If you need case-insensitive behavior most - of the time and case-sensitive infrequently, consider storing the data - as citext and explicitly casting the column to text - when you want case-sensitive comparison. In either situation, you will - need two indexes if you want both types of searches to be fast. - - - - - - The schema containing the citext operators must be - in the current search_path (typically public); - if it is not, the normal case-sensitive text operators - will be invoked instead. - - - - - - - Author - - - David E. Wheeler david@kineticode.com - - - - Inspired by the original citext module by Donald Fraser. - - - - - diff --git a/doc-xc/src/sgml/client-auth.sgmlin b/doc-xc/src/sgml/client-auth.sgmlin deleted file mode 100644 index d43d626be3..0000000000 --- a/doc-xc/src/sgml/client-auth.sgmlin +++ /dev/null @@ -1,1938 +0,0 @@ - - - - Client Authentication - - - client authentication - - -&common; - - When a client application connects to the database server, it - - specifies which PostgreSQL database user name it - - - specifies which Postgres-XC database user name it - - - specifies which Postgres-XL database user name it - - wants to connect as, much the same way one logs into a Unix computer - as a particular user. Within the SQL environment the active database - user name determines access privileges to database objects — see - for more information. Therefore, it is - essential to restrict which database users can connect. - - - - - As explained in , - - PostgreSQL actually does privilege - - - Postgres-XC actually does privilege - - - Postgres-XL actually does privilege - - management in terms of roles. In this chapter, we - consistently use database user to mean role with the - LOGIN privilege. - - - - - Authentication is the process by which the - database server establishes the identity of the client, and by - extension determines whether the client application (or the user - who runs the client application) is permitted to connect with the - database user name that was requested. - - - - - PostgreSQL offers a number of different - - - Postgres-XC offers a number of different - - - Postgres-XL offers a number of different - - client authentication methods. The method used to authenticate a - particular client connection can be selected on the basis of - (client) host address, database, and user. - - - - - PostgreSQL database user names are logically - - - Postgres-XC database user names are logically - - - Postgres-XL database user names are logically - - separate from user names of the operating system in which the server - runs. If all the users of a particular server also have accounts on - the server's machine, it makes sense to assign database user names - that match their operating system user names. However, a server that - accepts remote connections might have many database users who have no local - operating system - account, and in such cases there need be no connection between - database user names and OS user names. - - - - The <filename>pg_hba.conf</filename> File - - - pg_hba.conf - -&common; - - - Client authentication is controlled by a configuration file, - which traditionally is named - pg_hba.conf and is stored in the database - cluster's data directory. - (HBA stands for host-based authentication.) A default - pg_hba.conf file is installed when the data - directory is initialized by initdb. It is - possible to place the authentication configuration file elsewhere, - however; see the configuration parameter. - - - - The general format of the pg_hba.conf file is - a set of records, one per line. Blank lines are ignored, as is any - text after the # comment character. - Records cannot be continued across lines. - A record is made - up of a number of fields which are separated by spaces and/or tabs. - Fields can contain white space if the field value is quoted. - Quoting one of the keywords in a database, user, or address field (e.g., - all or replication) makes the word lose its special - character, and just match a database, user, or host with that name. - - - - Each record specifies a connection type, a client IP address range - (if relevant for the connection type), a database name, a user name, - and the authentication method to be used for connections matching - these parameters. The first record with a matching connection type, - client address, requested database, and user name is used to perform - authentication. There is no fall-through or - backup: if one record is chosen and the authentication - fails, subsequent records are not considered. If no record matches, - access is denied. - - - - A record can have one of the seven formats - -local database user auth-method auth-options -host database user address auth-method auth-options -hostssl database user address auth-method auth-options -hostnossl database user address auth-method auth-options -host database user IP-address IP-mask auth-method auth-options -hostssl database user IP-address IP-mask auth-method auth-options -hostnossl database user IP-address IP-mask auth-method auth-options - - The meaning of the fields is as follows: - - - - local - - - This record matches connection attempts using Unix-domain - sockets. Without a record of this type, Unix-domain socket - connections are disallowed. - - - - - - host - - - This record matches connection attempts made using TCP/IP. - host records match either - SSL or non-SSL connection - attempts. - - - - Remote TCP/IP connections will not be possible unless - the server is started with an appropriate value for the - configuration parameter, - since the default behavior is to listen for TCP/IP connections - only on the local loopback address localhost. - - - - - - - hostssl - - - This record matches connection attempts made using TCP/IP, - but only when the connection is made with SSL - encryption. - - - - To make use of this option the server must be built with - SSL support. Furthermore, - SSL must be enabled at server start time - by setting the configuration parameter (see - for more information). - - - - - - hostnossl - - - This record type has the opposite behavior of hostssl; - it only matches connection attempts made over - TCP/IP that do not use SSL. - - - - - - database - - - Specifies which database name(s) this record matches. The value - all specifies that it matches all databases. - The value sameuser specifies that the record - matches if the requested database has the same name as the - requested user. The value samerole specifies that - the requested user must be a member of the role with the same - name as the requested database. (samegroup is an - obsolete but still accepted spelling of samerole.) - The value replication specifies that the record - matches if a replication connection is requested (note that - replication connections do not specify any particular database). - Otherwise, this is the name of - - a specific PostgreSQL database. - - - a specific Postgres-XC database. - - - a specific Postgres-XL database. - - Multiple database names can be supplied by separating them with - commas. A separate file containing database names can be specified by - preceding the file name with @. - - - - - - user - - - Specifies which database user name(s) this record - matches. The value all specifies that it - matches all users. Otherwise, this is either the name of a specific - database user, or a group name preceded by +. - (Recall that there is no real distinction between users and groups - - in PostgreSQL; a + mark really means - - - in Postgres-XC; a + mark really means - - - in Postgres-XL; a + mark really means - - match any of the roles that are directly or indirectly members - of this role, while a name without a + mark matches - only that specific role.) - Multiple user names can be supplied by separating them with commas. - A separate file containing user names can be specified by preceding the - file name with @. - - - - - - address - - - Specifies the client machine addresses that this record - matches. This field can contain either a host name, an IP - address range, or one of the special key words mentioned below. - - - - An IP address is specified in standard dotted decimal - notation with a CIDR mask length. The mask - length indicates the number of high-order bits of the client - IP address that must match. Bits to the right of this must - be zero in the given IP address. - There must not be any white space between the IP address, the - /, and the CIDR mask length. - - - - Typical examples of an IP address range specified this way are - 172.20.143.89/32 for a single host, or - 172.20.143.0/24 for a small network, or - 10.6.0.0/16 for a larger one. - 0.0.0.0/0 represents all - IPv4 addresses, and ::/0 represents - all IPv6 addresses. - To specify a single host, use a CIDR mask of 32 for IPv4 or - 128 for IPv6. In a network address, do not omit trailing zeroes. - - - - An IP address given in IPv4 format will match IPv6 connections that - have the corresponding address, for example 127.0.0.1 - will match the IPv6 address ::ffff:127.0.0.1. An entry - given in IPv6 format will match only IPv6 connections, even if the - represented address is in the IPv4-in-IPv6 range. Note that entries - in IPv6 format will be rejected if the system's C library does not have - support for IPv6 addresses. - - - - You can also write all to match any IP address, - samehost to match any of the server's own IP - addresses, or samenet to match any address in any - subnet that the server is directly connected to. - - - - If a host name is specified (anything that is not an IP address - or a special key word is processed as a potential host name), - that name is compared with the result of a reverse name - resolution of the client's IP address (e.g., reverse DNS - lookup, if DNS is used). Host name comparisons are case - insensitive. If there is a match, then a forward name - resolution (e.g., forward DNS lookup) is performed on the host - name to check whether any of the addresses it resolves to are - equal to the client's IP address. If both directions match, - then the entry is considered to match. (The host name that is - used in pg_hba.conf should be the one that - address-to-name resolution of the client's IP address returns, - otherwise the line won't be matched. Some host name databases - allow associating an IP address with multiple host names, but - the operating system will only return one host name when asked - to resolve an IP address.) - - - - A host name specification that starts with a dot - (.) matches a suffix of the actual host - name. So .example.com would match - foo.example.com (but not just - example.com). - - - - When host names are specified - in pg_hba.conf, you should make sure that - name resolution is reasonably fast. It can be of advantage to - set up a local name resolution cache such - as nscd. Also, you may wish to enable the - configuration parameter log_hostname to see - the client's host name instead of the IP address in the log. - - - - - Occasionally, users have wondered why host names are handled - in this seemingly complicated way with two name resolutions - and requiring reverse lookup of IP addresses, which is - sometimes not set up or points to some undesirable host name. - It is primarily for efficiency: A connection attempt requires - two resolver lookups of the current client's address. If - there is resolver problem with that address, it becomes only - that client's problem. A hypothetical alternative - implementation which only does forward lookups would have to - resolve every host name mentioned in - pg_hba.conf at every connection attempt. - That would already be slow by itself. And if there is a - resolver problem with one of the host names, it becomes - everyone's problem. - - - - Also, a reverse lookup is necessary to implement the suffix - matching feature, because the actual client host name needs to - be known in order to match it against the pattern. - - - - Note that this behavior is consistent with other popular - implementations of host name-based access control, such as the - Apache HTTP Server and TCP Wrappers. - - - - - This field only applies to host, - hostssl, and hostnossl records. - - - - - - IP-address - IP-mask - - - These fields can be used as an alternative to the - CIDR-address notation. Instead of - specifying the mask length, the actual mask is specified in a - separate column. For example, 255.0.0.0 represents an IPv4 - CIDR mask length of 8, and 255.255.255.255 represents a - CIDR mask length of 32. - - - - These fields only apply to host, - hostssl, and hostnossl records. - - - - - - auth-method - - - Specifies the authentication method to use when a connection matches - this record. The possible choices are summarized here; details - are in . - - - - trust - - - Allow the connection unconditionally. This method - allows anyone that can connect to the - - PostgreSQL database server to login as - any PostgreSQL user they wish, - - - Postgres-XC database server to login as - any Postgres-XC user they wish, - - - Postgres-XL database server to login as - any Postgres-XL user they wish, - - without the need for a password or any other authentication. See for details. - - - - - - reject - - - Reject the connection unconditionally. This is useful for - filtering out certain hosts from a group, for example a - reject line could block a specific host from connecting, - while a later line allows the remaining hosts in a specific - network to connect. - - - - - - md5 - - - Require the client to supply an MD5-encrypted password for - authentication. - See for details. - - - - - - password - - - Require the client to supply an unencrypted password for - authentication. - Since the password is sent in clear text over the - network, this should not be used on untrusted networks. - See for details. - - - - - - gss - - - Use GSSAPI to authenticate the user. This is only - available for TCP/IP connections. See for details. - - - - - - sspi - - - Use SSPI to authenticate the user. This is only - available on Windows. See for details. - - - - - - krb5 - - - Use Kerberos V5 to authenticate the user. This is only - available for TCP/IP connections. See for details. - - - - - - ident - - - Obtain the operating system user name of the client - by contacting the ident server on the client - and check if it matches the requested database user name. - Ident authentication can only be used on TCP/IP - connections. When specified for local connections, peer - authentication will be used instead. - See for details. - - - - - - peer - - - Obtain the client's operating system user name from the operating - system and check if it matches the requested database user name. - This is only available for local connections. - See for details. - - - - - - ldap - - - Authenticate using an LDAP server. See for details. - - - - - - radius - - - Authenticate using a RADIUS server. See for details. - - - - - - cert - - - Authenticate using SSL client certificates. See - for details. - - - - - - pam - - - Authenticate using the Pluggable Authentication Modules - (PAM) service provided by the operating system. See for details. - - - - - - - - - - - auth-options - - - After the auth-method field, there can be field(s) of - the form name=value that - specify options for the authentication method. Details about which - options are available for which authentication methods appear below. - - - - - - - - Files included by @ constructs are read as lists of names, - which can be separated by either whitespace or commas. Comments are - introduced by #, just as in - pg_hba.conf, and nested @ constructs are - allowed. Unless the file name following @ is an absolute - path, it is taken to be relative to the directory containing the - referencing file. - - - - Since the pg_hba.conf records are examined - sequentially for each connection attempt, the order of the records is - significant. Typically, earlier records will have tight connection - match parameters and weaker authentication methods, while later - records will have looser match parameters and stronger authentication - methods. For example, one might wish to use trust - authentication for local TCP/IP connections but require a password for - remote TCP/IP connections. In this case a record specifying - trust authentication for connections from 127.0.0.1 would - appear before a record specifying password authentication for a wider - range of allowed client IP addresses. - - - - The pg_hba.conf file is read on start-up and when - the main server process receives a - SIGHUPSIGHUP - signal. If you edit the file on an - active system, you will need to signal the postmaster - (using pg_ctl reload or kill -HUP) to make it - re-read the file. - - - - - To connect to a particular database, a user must not only pass the - pg_hba.conf checks, but must have the - CONNECT privilege for the database. If you wish to - restrict which users can connect to which databases, it's usually - easier to control this by granting/revoking CONNECT privilege - than to put the rules in pg_hba.conf entries. - - - - - Some examples of pg_hba.conf entries are shown in - . See the next section for details on the - different authentication methods. - - - - Example <filename>pg_hba.conf</filename> Entries - -# Allow any user on the local system to connect to any database with -# any database user name using Unix-domain sockets (the default for local -# connections). -# -# TYPE DATABASE USER ADDRESS METHOD -local all all trust - -# The same using local loopback TCP/IP connections. -# -# TYPE DATABASE USER ADDRESS METHOD -host all all 127.0.0.1/32 trust - -# The same as the previous line, but using a separate netmask column -# -# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD -host all all 127.0.0.1 255.255.255.255 trust - -# The same over IPv6. -# -# TYPE DATABASE USER ADDRESS METHOD -host all all ::1/128 trust - -# The same using a host name (would typically cover both IPv4 and IPv6). -# -# TYPE DATABASE USER ADDRESS METHOD -host all all localhost trust - -# Allow any user from any host with IP address 192.168.93.x to connect -# to database "postgres" as the same user name that ident reports for -# the connection (typically the operating system user name). -# -# TYPE DATABASE USER ADDRESS METHOD -host postgres all 192.168.93.0/24 ident - -# Allow any user from host 192.168.12.10 to connect to database -# "postgres" if the user's password is correctly supplied. -# -# TYPE DATABASE USER ADDRESS METHOD -host postgres all 192.168.12.10/32 md5 - -# Allow any user from hosts in the example.com domain to connect to -# any database if the user's password is correctly supplied. -# -# TYPE DATABASE USER ADDRESS METHOD -host all all .example.com md5 - -# In the absence of preceding "host" lines, these two lines will -# reject all connections from 192.168.54.1 (since that entry will be -# matched first), but allow Kerberos 5 connections from anywhere else -# on the Internet. The zero mask causes no bits of the host IP -# address to be considered, so it matches any host. -# -# TYPE DATABASE USER ADDRESS METHOD -host all all 192.168.54.1/32 reject -host all all 0.0.0.0/0 krb5 - -# Allow users from 192.168.x.x hosts to connect to any database, if -# they pass the ident check. If, for example, ident says the user is -# "bryanh" and he requests to connect as PostgreSQL user "guest1", the -# connection is allowed if there is an entry in pg_ident.conf for map -# "omicron" that says "bryanh" is allowed to connect as "guest1". -# -# TYPE DATABASE USER ADDRESS METHOD -host all all 192.168.0.0/16 ident map=omicron - -# If these are the only three lines for local connections, they will -# allow local users to connect only to their own databases (databases -# with the same name as their database user name) except for administrators -# and members of role "support", who can connect to all databases. The file -# $PGDATA/admins contains a list of names of administrators. Passwords -# are required in all cases. -# -# TYPE DATABASE USER ADDRESS METHOD -local sameuser all md5 -local all @admins md5 -local all +support md5 - -# The last two lines above can be combined into a single line: -local all @admins,+support md5 - -# The database column can also use lists and file names: -local db1,db2,@demodbs all md5 - - - - - - User Name Maps - - - User name maps - -&common; - - - When using an external authentication system like Ident or GSSAPI, - the name of the operating system user that initiated the connection - might not be the same as the database user he needs to connect as. - In this case, a user name map can be applied to map the operating system - user name to a database user. To use user name mapping, specify - map=map-name - in the options field in pg_hba.conf. This option is - supported for all authentication methods that receive external user names. - Since different mappings might be needed for different connections, - the name of the map to be used is specified in the - map-name parameter in pg_hba.conf - to indicate which map to use for each individual connection. - - - - User name maps are defined in the ident map file, which by default is named - pg_ident.confpg_ident.conf - and is stored in the - cluster's data directory. (It is possible to place the map file - elsewhere, however; see the - configuration parameter.) - The ident map file contains lines of the general form: - -map-name system-username database-username - - Comments and whitespace are handled in the same way as in - pg_hba.conf. The - map-name is an arbitrary name that will be used to - refer to this mapping in pg_hba.conf. The other - two fields specify an operating system user name and a matching - database user name. The same map-name can be - used repeatedly to specify multiple user-mappings within a single map. - - - There is no restriction regarding how many database users a given - operating system user can correspond to, nor vice versa. Thus, entries - in a map should be thought of as meaning this operating system - user is allowed to connect as this database user, rather than - implying that they are equivalent. The connection will be allowed if - there is any map entry that pairs the user name obtained from the - external authentication system with the database user name that the - user has requested to connect as. - - - If the system-username field starts with a slash (/), - the remainder of the field is treated as a regular expression. - (See for details of - - PostgreSQL's regular expression syntax.) The regular - - - Postgres-XC's regular expression syntax.) The regular - - - Postgres-XL's regular expression syntax.) The regular - - expression can include a single capture, or parenthesized subexpression, - which can then be referenced in the database-username - field as \1 (backslash-one). This allows the mapping of - multiple user names in a single line, which is particularly useful for - simple syntax substitutions. For example, these entries - -mymap /^(.*)@mydomain\.com$ \1 -mymap /^(.*)@otherdomain\.com$ guest - - will remove the domain part for users with system user names that end with - @mydomain.com, and allow any user whose system name ends with - @otherdomain.com to log in as guest. - - - - - Keep in mind that by default, a regular expression can match just part of - a string. It's usually wise to use ^ and $, as - shown in the above example, to force the match to be to the entire - system user name. - - - - - The pg_ident.conf file is read on start-up and - when the main server process receives a - SIGHUPSIGHUP - signal. If you edit the file on an - active system, you will need to signal the postmaster - (using pg_ctl reload or kill -HUP) to make it - re-read the file. - - - - A pg_ident.conf file that could be used in - conjunction with the pg_hba.conf file in is shown in . In this example, anyone - logged in to a machine on the 192.168 network that does not have the - operating system user name bryanh, ann, or - robert would not be granted access. Unix user - robert would only be allowed access when he tries to - - connect as PostgreSQL user bob, not - - - connect as Postgres-XC user bob, not - - - connect as Postgres-XL user bob, not - - as robert or anyone else. ann would - only be allowed to connect as ann. User - bryanh would be allowed to connect as either - bryanh or as guest1. - - - - An Example <filename>pg_ident.conf</> File - -# MAPNAME SYSTEM-USERNAME PG-USERNAME - -omicron bryanh bryanh -omicron ann ann -# bob has user name robert on these machines -omicron robert bob -# bryanh can also connect as guest1 -omicron bryanh guest1 - - - - - - Authentication Methods - - The following subsections describe the authentication methods in more detail. - - - - Trust Authentication - -&common; - - When trust authentication is specified, - - PostgreSQL assumes that anyone who can - - - Postgres-XC assumes that anyone who can - - - Postgres-XL assumes that anyone who can - - connect to the server is authorized to access the database with - whatever database user name they specify (even superuser names). - Of course, restrictions made in the database and - user columns still apply. - This method should only be used when there is adequate - operating-system-level protection on connections to the server. - - - - trust authentication is appropriate and very - convenient for local connections on a single-user workstation. It - is usually not appropriate by itself on a multiuser - machine. However, you might be able to use trust even - on a multiuser machine, if you restrict access to the server's - Unix-domain socket file using file-system permissions. To do this, set the - unix_socket_permissions (and possibly - unix_socket_group) configuration parameters as - described in . Or you - could set the unix_socket_directory - configuration parameter to place the socket file in a suitably - restricted directory. - - - - Setting file-system permissions only helps for Unix-socket connections. - Local TCP/IP connections are not restricted by file-system permissions. - Therefore, if you want to use file-system permissions for local security, - remove the host ... 127.0.0.1 ... line from - pg_hba.conf, or change it to a - non-trust authentication method. - - - - trust authentication is only suitable for TCP/IP connections - if you trust every user on every machine that is allowed to connect - to the server by the pg_hba.conf lines that specify - trust. It is seldom reasonable to use trust - for any TCP/IP connections other than those from localhost (127.0.0.1). - - - - - - Password Authentication - - - MD5 - - - password - authentication - -&common; - - - The password-based authentication methods are md5 - and password. These methods operate - similarly except for the way that the password is sent across the - connection, namely MD5-hashed and clear-text respectively. - - - - If you are at all concerned about password - sniffing attacks then md5 is preferred. - Plain password should always be avoided if possible. - However, md5 cannot be used with the feature. If the connection is - protected by SSL encryption then password can be used - safely (though SSL certificate authentication might be a better - choice if one is depending on using SSL). - - - - - PostgreSQL database passwords are - - - Postgres-XC database passwords are - - - Postgres-XL database passwords are - - separate from operating system user passwords. The password for - each database user is stored in the pg_authid system - catalog. Passwords can be managed with the SQL commands - and - , - e.g., CREATE USER foo WITH PASSWORD 'secret'. - If no password has been set up for a user, the stored password - is null and password authentication will always fail for that user. - - - - - - GSSAPI Authentication - - - GSSAPI - -&common; - - - GSSAPI is an industry-standard protocol - for secure authentication defined in RFC 2743. - - PostgreSQL supports - - - Postgres-XC supports - - - Postgres-XL supports - - GSSAPI with Kerberos - authentication according to RFC 1964. GSSAPI - provides automatic authentication (single sign-on) for systems - that support it. The authentication itself is secure, but the - data sent over the database connection will be sent unencrypted unless - SSL is used. - - - - When GSSAPI uses - Kerberos, it uses a standard principal - in the format - servicename/hostname@realm. For information about the parts of the principal, and - how to set up the required keys, see . - - - - - GSSAPI support has to be enabled when PostgreSQL is built; - - - GSSAPI support has to be enabled when Postgres-XC is built; - - - GSSAPI support has to be enabled when Postgres-XL is built; - - see for more information. - - - - The following configuration options are supported for GSSAPI: - - - include_realm - - - If set to 1, the realm name from the authenticated user - principal is included in the system user name that's passed through - user name mapping (). This is - useful for handling users from multiple realms. - - - - - - map - - - Allows for mapping between system and database user names. See - for details. For a Kerberos - principal username/hostbased@EXAMPLE.COM, the - user name used for mapping is username/hostbased - if include_realm is disabled, and - username/hostbased@EXAMPLE.COM if - include_realm is enabled. - - - - - - krb_realm - - - Sets the realm to match user principal names against. If this parameter - is set, only users of that realm will be accepted. If it is not set, - users of any realm can connect, subject to whatever user name mapping - is done. - - - - - - - - - SSPI Authentication - - - SSPI - -&common; - - - SSPI is a Windows - technology for secure authentication with single sign-on. - - PostgreSQL will use SSPI in - - - Postgres-XC will use SSPI in - - - Postgres-XL will use SSPI in - - negotiate mode, which will use - Kerberos when possible and automatically - fall back to NTLM in other cases. - SSPI authentication only works when both - server and client are running Windows. - - - - When using Kerberos authentication, - SSPI works the same way - GSSAPI does; see - for details. - - - - The following configuration options are supported for SSPI: - - - - include_realm - - - If set to 1, the realm name from the authenticated user - principal is included in the system user name that's passed through - user name mapping (). This is - useful for handling users from multiple realms. - - - - - - map - - - Allows for mapping between system and database user names. See - for details. - - - - - - krb_realm - - - Sets the realm to match user principal names against. If this parameter - is set, only users of that realm will be accepted. If it is not set, - users of any realm can connect, subject to whatever user name mapping - is done. - - - - - - - - - Kerberos Authentication - - - Kerberos - -&common; - - - - Native Kerberos authentication has been deprecated and should be used - only for backward compatibility. New and upgraded installations are - encouraged to use the industry-standard GSSAPI - authentication method (see ) instead. - - - - - Kerberos is an industry-standard secure - authentication system suitable for distributed computing over a public - network. A description of the Kerberos system - is beyond the scope of this document; in full generality it can be - quite complex (yet powerful). The - - Kerberos FAQ or - MIT Kerberos page - can be good starting points for exploration. - Several sources for Kerberos distributions exist. - Kerberos provides secure authentication but - does not encrypt queries or data passed over the network; for that - use SSL. - - - - - PostgreSQL supports Kerberos version 5. Kerberos - support has to be enabled when PostgreSQL is built; - - - Postgres-XC supports Kerberos version 5. Kerberos - support has to be enabled when Postgres-XC is built; - - - Postgres-XL supports Kerberos version 5. Kerberos - support has to be enabled when Postgres-XL is built; - - see for more information. - - - - - PostgreSQL operates like a normal Kerberos service. - - - Postgres-XC operates like a normal Kerberos service. - - - Postgres-XL operates like a normal Kerberos service. - - The name of the service principal is - servicename/hostname@realm. - - - - servicename can be set on the server side using the - configuration parameter, and on the - client side using the krbsrvname connection parameter. (See - also .) The installation default can be - changed from the default postgres at build time using - ./configure --with-krb-srvnam=whatever. - In most environments, - this parameter never needs to be changed. However, it is necessary - - when supporting multiple PostgreSQL installations - - - when supporting multiple Postgres-XC installations - - - when supporting multiple Postgres-XL installations - - on the same host. - Some Kerberos implementations might also require a different service name, - such as Microsoft Active Directory which requires the service name - to be in upper case (POSTGRES). - - - - hostname is the fully qualified host name of the - server machine. The service principal's realm is the preferred realm - of the server machine. - - - - - Client principals must have their PostgreSQL database user - - - Client principals must have their Postgres-XC database user - - - Client principals must have their Postgres-XL database user - - name as their first component, for example - pgusername@realm. Alternatively, you can use a user name - mapping to map from the first component of the principal name to the - database user name. By default, the realm of the client is - - not checked by PostgreSQL. If you have cross-realm - - - not checked by Postgres-XC. If you have cross-realm - - - not checked by Postgres-XL. If you have cross-realm - - authentication enabled and need to verify the realm, use the - krb_realm parameter, or enable include_realm - and use user name mapping to check the realm. - - - - Make sure that your server keytab file is readable (and preferably - - only readable) by the PostgreSQL server - - - only readable) by the Postgres-XC server - - - only readable) by the Postgres-XL server - - account. (See also .) The location - of the key file is specified by the configuration - parameter. The default is - /usr/local/pgsql/etc/krb5.keytab (or whatever - directory was specified as sysconfdir at build time). - - - - The keytab file is generated by the Kerberos software; see the - Kerberos documentation for details. The following example is - for MIT-compatible Kerberos 5 implementations: - -kadmin% ank -randkey postgres/server.my.domain.org -kadmin% ktadd -k krb5.keytab postgres/server.my.domain.org - - - - - When connecting to the database make sure you have a ticket for a - principal matching the requested database user name. For example, for - database user name fred, principal - fred@EXAMPLE.COM would be able to connect. To also allow - principal fred/users.example.com@EXAMPLE.COM, use a user name - map, as described in . - - - - If you use - mod_auth_kerb - and mod_perl on your - Apache web server, you can use - AuthType KerberosV5SaveCredentials with a - mod_perl script. This gives secure - database access over the web, with no additional passwords required. - - - - The following configuration options are supported for - Kerberos: - - - map - - - Allows for mapping between system and database user names. See - for details. - - - - - - include_realm - - - If set to 1, the realm name from the authenticated user - principal is included in the system user name that's passed through - user name mapping (). This is - useful for handling users from multiple realms. - - - - - - krb_realm - - - Sets the realm to match user principal names against. If this parameter - is set, only users of that realm will be accepted. If it is not set, - users of any realm can connect, subject to whatever user name mapping - is done. - - - - - - krb_server_hostname - - - Sets the host name part of the service principal. - This, combined with krb_srvname, is used to generate - the complete service principal, that is - krb_srvname/krb_server_hostname@REALM. - If not set, the default is the server host name. - - - - - - - - - Ident Authentication - - - ident - -&common; - - - The ident authentication method works by obtaining the client's - operating system user name from an ident server and using it as - the allowed database user name (with an optional user name mapping). - This is only supported on TCP/IP connections. - - - - - When ident is specified for a local (non-TCP/IP) connection, - peer authentication (see ) will be - used instead. - - - - - The following configuration options are supported for ident: - - - map - - - Allows for mapping between system and database user names. See - for details. - - - - - - - - The Identification Protocol is described in - RFC 1413. Virtually every Unix-like - operating system ships with an ident server that listens on TCP - port 113 by default. The basic functionality of an ident server - is to answer questions like What user initiated the - connection that goes out of your port X - and connects to my port Y?. - - Since PostgreSQL knows both X and - - - Since Postgres-XC knows both X and - - - Since Postgres-XL knows both X and - - Y when a physical connection is established, it - can interrogate the ident server on the host of the connecting - client and can theoretically determine the operating system user - for any given connection. - - - - The drawback of this procedure is that it depends on the integrity - of the client: if the client machine is untrusted or compromised, - an attacker could run just about any program on port 113 and - return any user name he chooses. This authentication method is - therefore only appropriate for closed networks where each client - machine is under tight control and where the database and system - administrators operate in close contact. In other words, you must - trust the machine running the ident server. - Heed the warning: -
- RFC 1413 - - The Identification Protocol is not intended as an authorization - or access control protocol. - -
- - - - Some ident servers have a nonstandard option that causes the returned - user name to be encrypted, using a key that only the originating - machine's administrator knows. This option must not be - - used when using the ident server with PostgreSQL, - since PostgreSQL does not have any way to decrypt the - - - used when using the ident server with Postgres-XC, - since Postgres-XC does not have any way to decrypt the - - - used when using the ident server with Postgres-XL, - since Postgres-XL does not have any way to decrypt the - - returned string to determine the actual user name. - - - - - Peer Authentication - - - peer - - -&common; - - The peer authentication method works by obtaining the client's - operating system user name from the kernel and using it as the - allowed database user name (with optional user name mapping). This - method is only supported on local connections. - - - - The following configuration options are supported for peer: - - - map - - - Allows for mapping between system and database user names. See - for details. - - - - - - - - Peer authentication is only available on operating systems providing - the getpeereid() function, the SO_PEERCRED - socket parameter, or similar mechanisms. Currently that includes - Linux, - most flavors of BSD including - Mac OS X, - and Solaris. - - - - - - LDAP Authentication - - - LDAP - -&common; - - - This authentication method operates similarly to - password except that it uses LDAP - as the password verification method. LDAP is used only to validate - the user name/password pairs. Therefore the user must already - exist in the database before LDAP can be used for - authentication. - - - - LDAP authentication can operate in two modes. In the first mode, - the server will bind to the distinguished name constructed as - prefix username suffix. - Typically, the prefix parameter is used to specify - cn=, or DOMAIN\ in an Active - Directory environment. suffix is used to specify the - remaining part of the DN in a non-Active Directory environment. - - - - In the second mode, the server first binds to the LDAP directory with - a fixed user name and password, specified with ldapbinduser - and ldapbinddn, and performs a search for the user trying - to log in to the database. If no user and password is configured, an - anonymous bind will be attempted to the directory. The search will be - performed over the subtree at ldapbasedn, and will try to - do an exact match of the attribute specified in - ldapsearchattribute. If no attribute is specified, the - uid attribute will be used. Once the user has been found in - this search, the server disconnects and re-binds to the directory as - this user, using the password specified by the client, to verify that the - login is correct. This method allows for significantly more flexibility - in where the user objects are located in the directory, but will cause - two separate connections to the LDAP server to be made. - - - - The following configuration options are supported for LDAP: - - - ldapserver - - - Name or IP of LDAP server to connect to. - - - - - ldapport - - - Port number on LDAP server to connect to. If no port is specified, - the LDAP library's default port setting will be used. - - - - - ldaptls - - - - Set to 1 to make the connection between PostgreSQL and the - - - Set to 1 to make the connection between Postgres-XC and the - - - Set to 1 to make the connection between Postgres-XL and the - - LDAP server use TLS encryption. Note that this only encrypts - the traffic to the LDAP server — the connection to the client - will still be unencrypted unless SSL is used. - - - - - ldapprefix - - - String to prepend to the user name when forming the DN to bind as, - when doing simple bind authentication. - - - - - ldapsuffix - - - String to append to the user name when forming the DN to bind as, - when doing simple bind authentication. - - - - - ldapbasedn - - - Root DN to begin the search for the user in, when doing search+bind - authentication. - - - - - ldapbinddn - - - DN of user to bind to the directory with to perform the search when - doing search+bind authentication. - - - - - ldapbindpasswd - - - Password for user to bind to the directory with to perform the search - when doing search+bind authentication. - - - - - ldapsearchattribute - - - Attribute to match against the user name in the search when doing - search+bind authentication. - - - - - - - - - Since LDAP often uses commas and spaces to separate the different - parts of a DN, it is often necessary to use double-quoted parameter - values when configuring LDAP options, for example: - -ldapserver=ldap.example.net ldapprefix="cn=" ldapsuffix=", dc=example, dc=net" - - - - - - - - RADIUS Authentication - - - RADIUS - -&common; - - - This authentication method operates similarly to - password except that it uses RADIUS - as the password verification method. RADIUS is used only to validate - the user name/password pairs. Therefore the user must already - exist in the database before RADIUS can be used for - authentication. - - - - When using RADIUS authentication, an Access Request message will be sent - to the configured RADIUS server. This request will be of type - Authenticate Only, and include parameters for - user name, password (encrypted) and - NAS Identifier. The request will be encrypted using - a secret shared with the server. The RADIUS server will respond to - this server with either Access Accept or - Access Reject. There is no support for RADIUS accounting. - - - - The following configuration options are supported for RADIUS: - - - radiusserver - - - The name or IP address of the RADIUS server to connect to. - This parameter is required. - - - - - - radiussecret - - - The shared secret used when talking securely to the RADIUS - - server. This must have exactly the same value on the PostgreSQL - - - server. This must have exactly the same value on the Postgres-XC - - - server. This must have exactly the same value on the Postgres-XL - - and RADIUS servers. It is recommended that this be a string of - at least 16 characters. This parameter is required. - - - The encryption vector used will only be cryptographically - - strong if PostgreSQL is built with support for - - - strong if Postgres-XC is built with support for - - - strong if Postgres-XL is built with support for - - OpenSSL. In other cases, the transmission to the - RADIUS server should only be considered obfuscated, not secured, and - external security measures should be applied if necessary. - - - - - - - - radiusport - - - The port number on the RADIUS server to connect to. If no port - is specified, the default port 1812 will be used. - - - - - - radiusidentifier - - - The string used as NAS Identifier in the RADIUS - requests. This parameter can be used as a second parameter - identifying for example which database user the user is attempting - to authenticate as, which can be used for policy matching on - the RADIUS server. If no identifier is specified, the default - postgresql will be used. - - - - - - - - - - Certificate Authentication - - - Certificate - -&common; - - - This authentication method uses SSL client certificates to perform - authentication. It is therefore only available for SSL connections. - When using this authentication method, the server will require that - the client provide a valid certificate. No password prompt will be sent - to the client. The cn (Common Name) attribute of the - certificate - will be compared to the requested database user name, and if they match - the login will be allowed. User name mapping can be used to allow - cn to be different from the database user name. - - - - The following configuration options are supported for SSL certificate - authentication: - - - map - - - Allows for mapping between system and database user names. See - for details. - - - - - - - - - PAM Authentication - - - PAM - -&common; - - - This authentication method operates similarly to - password except that it uses PAM (Pluggable - Authentication Modules) as the authentication mechanism. The - default PAM service name is postgresql. - PAM is used only to validate user name/password pairs. - Therefore the user must already exist in the database before PAM - can be used for authentication. For more information about - PAM, please read the - Linux-PAM Page - and the - Solaris PAM Page. - - - - The following configuration options are supported for PAM: - - - pamservice - - - PAM service name. - - - - - - - - - If PAM is set up to read /etc/shadow, authentication - - will fail because the PostgreSQL server is started by a non-root - - - will fail because the Postgres-XC server is started by a non-root - - - will fail because the Postgres-XL server is started by a non-root - - user. However, this is not an issue when PAM is configured to use - LDAP or other authentication methods. - - - - - - - Authentication Problems - -&common; - - Authentication failures and related problems generally - manifest themselves through error messages like the following: - - - - -FATAL: no pg_hba.conf entry for host "123.123.123.123", user "andym", database "testdb" - - This is what you are most likely to get if you succeed in contacting - the server, but it does not want to talk to you. As the message - suggests, the server refused the connection request because it found - no matching entry in its pg_hba.conf - configuration file. - - - - -FATAL: password authentication failed for user "andym" - - Messages like this indicate that you contacted the server, and it is - willing to talk to you, but not until you pass the authorization - method specified in the pg_hba.conf file. Check - the password you are providing, or check your Kerberos or ident - software if the complaint mentions one of those authentication - types. - - - - -FATAL: user "andym" does not exist - - The indicated database user name was not found. - - - - -FATAL: database "testdb" does not exist - - The database you are trying to connect to does not exist. Note that - if you do not specify a database name, it defaults to the database - user name, which might or might not be the right thing. - - - - - The server log might contain more information about an - authentication failure than is reported to the client. If you are - confused about the reason for a failure, check the server log. - - - - - diff --git a/doc-xc/src/sgml/common.sgmlin b/doc-xc/src/sgml/common.sgmlin deleted file mode 100644 index 5f18dcc5b4..0000000000 --- a/doc-xc/src/sgml/common.sgmlin +++ /dev/null @@ -1,14 +0,0 @@ - - - -The following description applies both to Postgres-XC and PostgreSQL if not described explicitly. - - - - - - -The following description applies both to Postgres-XL and PostgreSQL if not described explicitly. - - - diff --git a/doc-xc/src/sgml/config.sgmlin b/doc-xc/src/sgml/config.sgmlin deleted file mode 100644 index 9ed17fd759..0000000000 --- a/doc-xc/src/sgml/config.sgmlin +++ /dev/null @@ -1,7544 +0,0 @@ - - - - - Server Configuration - - - Coordinator and Datanode Configuration - - - Coordinator and Datanode Configuration - - - - configuration - of the server - - -&common; - - - There are many configuration parameters that affect the behavior of - the database system. In the first section of this chapter, we - describe how to set configuration parameters. The subsequent sections - discuss each parameter in detail. - - - - - There are many configuration parameters that affect the behavior of - the database system. In the first section of this chapter, we - describe how to set configuration parameters for Coordinator and - Datanodes. The subsequent sections discuss each parameter in - detail. - - - - - There are many configuration parameters that affect the behavior of - the database system. In the first section of this chapter, we - describe how to set configuration parameters for Coordinator and - Datanodes. The subsequent sections discuss each parameter in - detail. - - - - - Setting Parameters - -&common; - - All parameter names are case-insensitive. Every parameter takes a - value of one of five types: Boolean, integer, floating point, - string or enum. Boolean values can be written as on, - off, true, - false, yes, - no, 1, 0 - (all case-insensitive) or any unambiguous prefix of these. - - - - Some settings specify a memory or time value. Each of these has an - implicit unit, which is either kilobytes, blocks (typically eight - kilobytes), milliseconds, seconds, or minutes. Default units can be - found by referencing pg_settings.unit. - For convenience, - a different unit can also be specified explicitly. Valid memory units - are kB (kilobytes), MB - (megabytes), and GB (gigabytes); valid time units - are ms (milliseconds), s - (seconds), min (minutes), h - (hours), and d (days). Note that the multiplier - for memory units is 1024, not 1000. - - - - Parameters of type enum are specified in the same way as string - parameters, but are restricted to a limited set of values. The allowed - values can be found - from pg_settings.enumvals. - Enum parameter values are case-insensitive. - - - - One way to set these parameters is to edit the file - postgresql.confpostgresql.conf, - which is normally kept in the data directory. (A default copy is - installed there when the database cluster directory is - initialized.) An example of what this file might look like is: - -# This is a comment -log_connections = yes -log_destination = 'syslog' -search_path = '"$user", public' -shared_buffers = 128MB - - One parameter is specified per line. The equal sign between name and - value is optional. Whitespace is insignificant and blank lines are - ignored. Hash marks (#) designate the rest of the - line as a comment. Parameter values that are not simple identifiers or - numbers must be single-quoted. To embed a single quote in a parameter - value, write either two quotes (preferred) or backslash-quote. - - - - - include - in configuration file - - In addition to parameter settings, the postgresql.conf - file can contain include directives, which specify - another file to read and process as if it were inserted into the - configuration file at this point. Include directives simply look like: - -include 'filename' - - If the file name is not an absolute path, it is taken as relative to - the directory containing the referencing configuration file. - Inclusions can be nested. - - - - - SIGHUP - - - The configuration file is reread whenever the main server process receives a - SIGHUP signal (which is most easily sent by means - of pg_ctl reload). The main server process - also propagates this signal to all currently running server - processes so that existing sessions also get the new - value. Alternatively, you can send the signal to a single server - process directly. Some parameters can only be set at server start; - any changes to their entries in the configuration file will be ignored - until the server is restarted. - - - The configuration file is reread whenever the main Coordinator/Datanode process receives a - SIGHUP signal (which is most easily sent by means - of pg_ctl reload). The main Coordinator/Datanode process - also propagates this signal to all currently running server - processes so that existing sessions also get the new - value. Alternatively, you can send the signal to a single server - process directly. Some parameters can only be set at server start; - any changes to their entries in the configuration file will be ignored - until the server is restarted. - - - The configuration file is reread whenever the main Coordinator/Datanode process receives a - SIGHUP signal (which is most easily sent by means - of pg_ctl reload). The main Coordinator/Datanode process - also propagates this signal to all currently running server - processes so that existing sessions also get the new - value. Alternatively, you can send the signal to a single server - process directly. Some parameters can only be set at server start; - any changes to their entries in the configuration file will be ignored - until the server is restarted. - - - - - A second way to set these configuration parameters is to give them - as a command-line option to the postgres command, such as: - - -postgres -c log_connections=yes -c log_destination='syslog' - - - - -postgres --coordinator -c log_connections=yes -c log_destination='syslog' - - - - -postgres --coordinator -c log_connections=yes -c log_destination='syslog' - - - Command-line options override any conflicting settings in - postgresql.conf. Note that this means you won't - be able to change the value on-the-fly by editing - postgresql.conf, so while the command-line - method might be convenient, it can cost you flexibility later. - - - - Occasionally it is useful to give a command line option to - one particular session only. The environment variable - PGOPTIONS can be used for this purpose on the - client side: - -env PGOPTIONS='-c geqo=off' psql - - (This works for any libpq-based client application, not - just psql.) Note that this won't work for - parameters that are fixed when the server is started or that must be - specified in postgresql.conf. - - - - Furthermore, it is possible to assign a set of parameter settings to - a user or a database. Whenever a session is started, the default - settings for the user and database involved are loaded. The - commands - and , - respectively, are used to configure these settings. Per-database - settings override anything received from the - postgres command-line or the configuration - file, and in turn are overridden by per-user settings; both are - overridden by per-session settings. - - - - Some parameters can be changed in individual SQL - sessions with the - command, for example: - -SET ENABLE_SEQSCAN TO OFF; - - If SET is allowed, it overrides all other sources of - values for the parameter. Some parameters cannot be changed via - SET: for example, if they control behavior that - cannot be changed without restarting the entire - - PostgreSQL server. Also, - - - Postgres-XC server. Also, - - - Postgres-XL server. Also, - - some SET or ALTER parameter modifications - require superuser permission. - - - - The - command allows inspection of the current values of all parameters. - - - - The virtual table pg_settings also allows - displaying and updating session run-time parameters; see for details and a description of the - different variable types and when they can be changed. - pg_settings is equivalent to SHOW - and SET, but can be more convenient - to use because it can be joined with other tables, or selected from using - any desired selection condition. It also contains more information about - what values are allowed for the parameters. - - - - - File Locations -&common; - - In addition to the postgresql.conf file - - already mentioned, PostgreSQL uses - - - already mentioned, Postgres-XC uses - - - already mentioned, Postgres-XL uses - - two other manually-edited configuration files, which control - client authentication (their use is discussed in ). By default, all three - configuration files are stored in the database cluster's data - directory. The parameters described in this section allow the - configuration files to be placed elsewhere. (Doing so can ease - administration. In particular it is often easier to ensure that - the configuration files are properly backed-up when they are - kept separate.) - - - - - data_directory (string) - - data_directory configuration parameter - - - - Specifies the directory to use for data storage. - This parameter can only be set at server start. - - - - - - config_file (string) - - config_file configuration parameter - - - - Specifies the main server configuration file - (customarily called postgresql.conf). - This parameter can only be set on the postgres command line. - - - - - - hba_file (string) - - hba_file configuration parameter - - - - Specifies the configuration file for host-based authentication - (customarily called pg_hba.conf). - This parameter can only be set at server start. - - - - - - ident_file (string) - - ident_file configuration parameter - - - - Specifies the configuration file for - user name mapping - (customarily called pg_ident.conf). - This parameter can only be set at server start. - - - - - - external_pid_file (string) - - external_pid_file configuration parameter - - - - Specifies the name of an additional process-id (PID) file that the - server should create for use by server administration programs. - This parameter can only be set at server start. - - - - - - - In a default installation, none of the above parameters are set - explicitly. Instead, the - data directory is specified by the command-line - option or the PGDATA environment variable, and the - configuration files are all found within the data directory. - - - - If you wish to keep the configuration files elsewhere than the - data directory, the postgres - command-line option or PGDATA environment variable - must point to the directory containing the configuration files, - and the data_directory parameter must be set in - postgresql.conf (or on the command line) to show - where the data directory is actually located. Notice that - data_directory overrides and - PGDATA for the location - of the data directory, but not for the location of the configuration - files. - - - - If you wish, you can specify the configuration file names and locations - individually using the parameters config_file, - hba_file and/or ident_file. - config_file can only be specified on the - postgres command line, but the others can be - set within the main configuration file. If all three parameters plus - data_directory are explicitly set, then it is not necessary - to specify or PGDATA. - - - - When setting any of these parameters, a relative path will be interpreted - with respect to the directory in which postgres - is started. - - - - - Connections and Authentication - - - Connection Settings -&common; - - - - listen_addresses (string) - - listen_addresses configuration parameter - - - - Specifies the TCP/IP address(es) on which the server is - to listen for connections from client applications. - The value takes the form of a comma-separated list of host names - and/or numeric IP addresses. The special entry * - corresponds to all available IP interfaces. The entry - 0.0.0.0 allows listening for all IPv4 addresses and - :: allows listening for all IPv6 addresses. - If the list is empty, the server does not listen on any IP interface - at all, in which case only Unix-domain sockets can be used to connect - to it. - The default value is localhost, - which allows only local TCP/IP loopback connections to be - made. While client authentication () allows fine-grained control - over who can access the server, listen_addresses - controls which interfaces accept connection attempts, which - can help prevent repeated malicious connection requests on - insecure network interfaces. This parameter can only be set - at server start. - - - - - - port (integer) - - port configuration parameter - - - - The TCP port the server listens on; 5432 by default. Note that the - same port number is used for all IP addresses the server listens on. - This parameter can only be set at server start. - - - - - - max_connections (integer) - - max_connections configuration parameter - - - - Determines the maximum number of concurrent connections to the - database server. The default is typically 100 connections, but - might be less if your kernel settings will not support it (as - determined during initdb). This parameter can - only be set at server start. - - - - - In the case of the Coordinator, this parameter determines how many - connections can each Coordinator accept. - - - In the case of the Datanode, number of connection to each - Datanode may become as large as max_connections - multiplied by the number of Coordinators. - - - - - In the case of the Coordinator, this parameter determines how many - connections can each Coordinator accept. - - - In the case of the Datanode, number of connection to each - Datanode may become as large as max_connections - multiplied by the number of Coordinators. - - - - - - Increasing this parameter might cause PostgreSQL - to request more System V shared - memory or semaphores than your operating system's default configuration - allows. See for information on how to - adjust those parameters, if necessary. - - - Increasing this parameter might cause Coordinator or Datanode - to request more System V shared - memory or semaphores than your operating system's default configuration - allows. See for information on how to - adjust those parameters, if necessary. - - - Increasing this parameter might cause Coordinator or Datanode - to request more System V shared - memory or semaphores than your operating system's default configuration - allows. See for information on how to - adjust those parameters, if necessary. - - - - - When running a standby server, you must set this parameter to the - same or higher value than on the master server. Otherwise, queries - will not be allowed in the standby server. - - - - - - superuser_reserved_connections - (integer) - - superuser_reserved_connections configuration parameter - - - - - Determines the number of connection slots that - are reserved for connections by PostgreSQL - superusers. At most - connections can ever be active simultaneously. Whenever the - number of active concurrent connections is at least - max_connections minus - superuser_reserved_connections, new - connections will be accepted only for superusers, and no - new replication connections will be accepted. - - - Determines the number of connection slots that - are reserved for connections by Coordinator or Datanode - superusers. At most - connections can ever be active simultaneously. Whenever the - number of active concurrent connections is at least - max_connections minus - superuser_reserved_connections, new - connections will be accepted only for superusers, and no - new replication connections will be accepted. - - - Determines the number of connection slots that - are reserved for connections by Coordinator or Datanode - superusers. At most - connections can ever be active simultaneously. Whenever the - number of active concurrent connections is at least - max_connections minus - superuser_reserved_connections, new - connections will be accepted only for superusers, and no - new replication connections will be accepted. - - - - - The default value is three connections. The value must be less - than the value of max_connections. This - parameter can only be set at server start. - - - - - - unix_socket_directory (string) - - unix_socket_directory configuration parameter - - - - Specifies the directory of the Unix-domain socket on which the - server is to listen for - connections from client applications. The default is normally - /tmp, but can be changed at build time. - This parameter can only be set at server start. - - - - In addition to the socket file itself, which is named - .s.PGSQL.nnnn where - nnnn is the server's port number, an ordinary file - named .s.PGSQL.nnnn.lock will be - created in the unix_socket_directory directory. Neither - file should ever be removed manually. - - - - This parameter is irrelevant on Windows, which does not have - Unix-domain sockets. - - - - - - unix_socket_group (string) - - unix_socket_group configuration parameter - - - - Sets the owning group of the Unix-domain socket. (The owning - user of the socket is always the user that starts the - server.) In combination with the parameter - unix_socket_permissions this can be used as - an additional access control mechanism for Unix-domain connections. - By default this is the empty string, which uses the default - group of the server user. This parameter can only be set at - server start. - - - - This parameter is irrelevant on Windows, which does not have - Unix-domain sockets. - - - - - - unix_socket_permissions (integer) - - unix_socket_permissions configuration parameter - - - - Sets the access permissions of the Unix-domain socket. Unix-domain - sockets use the usual Unix file system permission set. - The parameter value is expected to be a numeric mode - specified in the format accepted by the - chmod and umask - system calls. (To use the customary octal format the number - must start with a 0 (zero).) - - - - The default permissions are 0777, meaning - anyone can connect. Reasonable alternatives are - 0770 (only user and group, see also - unix_socket_group) and 0700 - (only user). (Note that for a Unix-domain socket, only write - permission matters, so there is no point in setting or revoking - read or execute permissions.) - - - - This access control mechanism is independent of the one - described in . - - - - This parameter can only be set at server start. - - - - This parameter is irrelevant on Windows, which does not have - Unix-domain sockets. - - - - - - bonjour (boolean) - - bonjour configuration parameter - - - - Enables advertising the server's existence via - Bonjour. The default is off. - This parameter can only be set at server start. - - - - - - bonjour_name (string) - - bonjour_name configuration parameter - - - - Specifies the Bonjour service - name. The computer name is used if this parameter is set to the - empty string '' (which is the default). This parameter is - ignored if the server was not compiled with - Bonjour support. - This parameter can only be set at server start. - - - - - - tcp_keepalives_idle (integer) - - tcp_keepalives_idle configuration parameter - - - - Specifies the number of seconds before sending a keepalive packet on - an otherwise idle connection. A value of 0 uses the system default. - This parameter is supported only on systems that support the - TCP_KEEPIDLE or TCP_KEEPALIVE symbols, and on - Windows; on other systems, it must be zero. This parameter is ignored - for connections made via a Unix-domain socket. - - - - On Windows, a value of 0 will set this parameter to 2 hours, - since Windows does not provide a way to read the system default value. - - - - - - - tcp_keepalives_interval (integer) - - tcp_keepalives_interval configuration parameter - - - - Specifies the number of seconds between sending keepalives on an - otherwise idle connection. A value of 0 uses the system default. - This parameter is supported only on systems that support the - TCP_KEEPINTVL symbol, and on Windows; on other systems, it - must be zero. This parameter is ignored for connections made via a - Unix-domain socket. - - - - On Windows, a value of 0 will set this parameter to 1 second, - since Windows does not provide a way to read the system default value. - - - - - - - tcp_keepalives_count (integer) - - tcp_keepalives_count configuration parameter - - - - Specifies the number of keepalive packets to send on an otherwise idle - connection. A value of 0 uses the system default. This parameter is - supported only on systems that support the TCP_KEEPCNT - symbol; on other systems, it must be zero. This parameter is ignored - for connections made via a Unix-domain socket. - - - - This parameter is not supported on Windows, and must be zero. - - - - - - - - - Security and Authentication -&common; - - - authentication_timeout (integer) - timeoutclient authentication - client authenticationtimeout during - - authentication_timeout configuration parameter - - - - - Maximum time to complete client authentication, in seconds. If a - would-be client has not completed the authentication protocol in - this much time, the server closes the connection. This prevents - hung clients from occupying a connection indefinitely. - The default is one minute (1m). - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - - - - ssl (boolean) - - ssl configuration parameter - - - - Enables SSL connections. Please read - before using this. The default - is off. This parameter can only be set at server - start. SSL communication is only possible with - TCP/IP connections. - - - - - - ssl_renegotiation_limit (integer) - - ssl_renegotiation_limit configuration parameter - - - - Specifies how much data can flow over an SSL-encrypted - connection before renegotiation of the session keys will take - place. Renegotiation decreases an attacker's chances of doing - cryptanalysis when large amounts of traffic can be examined, but it - also carries a large performance penalty. The sum of sent and received - traffic is used to check the limit. If this parameter is set to 0, - renegotiation is disabled. The default is 512MB. - - - - SSL libraries from before November 2009 are insecure when using SSL - renegotiation, due to a vulnerability in the SSL protocol. As a - stop-gap fix for this vulnerability, some vendors shipped SSL - libraries incapable of doing renegotiation. If any such libraries - are in use on the client or server, SSL renegotiation should be - disabled. - - - - - - - ssl_ciphers (string) - - ssl_ciphers configuration parameter - - - - Specifies a list of SSL ciphers that are allowed to be - used on secure connections. See the openssl - manual page for a list of supported ciphers. - - - - - - password_encryption (boolean) - - password_encryption configuration parameter - - - - When a password is specified in or - - without writing either ENCRYPTED or - UNENCRYPTED, this parameter determines whether the - password is to be encrypted. The default is on - (encrypt the password). - - - - - - krb_server_keyfile (string) - - krb_server_keyfile configuration parameter - - - - Sets the location of the Kerberos server key file. See - or - for details. This parameter can only be set in the - postgresql.conf file or on the server command line. - - - - - - krb_srvname (string) - - krb_srvname configuration parameter - - - - Sets the Kerberos service name. See - for details. This parameter can only be set in the - postgresql.conf file or on the server command line. - - - - - - krb_caseins_users (boolean) - - krb_caseins_users configuration parameter - - - - Sets whether Kerberos and GSSAPI user names should be treated - case-insensitively. - The default is off (case sensitive). This parameter can only be - set in the postgresql.conf file or on the server command line. - - - - - - db_user_namespace (boolean) - - db_user_namespace configuration parameter - - - - This parameter enables per-database user names. It is off by default. - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - - If this is on, you should create users as username@dbname. - When username is passed by a connecting client, - @ and the database name are appended to the user - name and that database-specific user name is looked up by the - server. Note that when you create users with names containing - @ within the SQL environment, you will need to - quote the user name. - - - - With this parameter enabled, you can still create ordinary global - users. Simply append @ when specifying the user - name in the client, e.g. joe@. The @ - will be stripped off before the user name is looked up by the - server. - - - - db_user_namespace causes the client's and - server's user name representation to differ. - Authentication checks are always done with the server's user name - so authentication methods must be configured for the - server's user name, not the client's. Because - md5 uses the user name as salt on both the - client and server, md5 cannot be used with - db_user_namespace. - - - - - This feature is intended as a temporary measure until a - complete solution is found. At that time, this option will - be removed. - - - - - - - - - - - Resource Consumption - - - Memory -&common; - - - shared_buffers (integer) - - shared_buffers configuration parameter - - - - Sets the amount of memory the database server uses for shared - memory buffers. The default is typically 32 megabytes - (32MB), but might be less if your kernel settings will - not support it (as determined during initdb). - This setting must be at least 128 kilobytes. (Non-default - values of BLCKSZ change the minimum.) However, - settings significantly higher than the minimum are usually needed - for good performance. This parameter can only be set at server start. - - - - If you have a dedicated database server with 1GB or more of RAM, a - reasonable starting value for shared_buffers is 25% - of the memory in your system. There are some workloads where even - large settings for shared_buffers are effective, but - - because PostgreSQL also relies on the - - - because Postgres-XC also relies on the - - - because Postgres-XL also relies on the - - operating system cache, it is unlikely that an allocation of more than - 40% of RAM to shared_buffers will work better than a - smaller amount. Larger settings for shared_buffers - usually require a corresponding increase in - checkpoint_segments, in order to spread out the - process of writing large quantities of new or changed data over a - longer period of time. - - - - On systems with less than 1GB of RAM, a smaller percentage of RAM is - appropriate, so as to leave adequate space for the operating system. - Also, on Windows, large values for shared_buffers - aren't as effective. You may find better results keeping the setting - relatively low and using the operating system cache more instead. The - useful range for shared_buffers on Windows systems - is generally from 64MB to 512MB. - - - - - Increasing this parameter might cause PostgreSQL - - - Increasing this parameter might cause Postgres-XC - - - Increasing this parameter might cause Postgres-XL - - to request more System V shared - memory than your operating system's default configuration - allows. See for information on how to - adjust those parameters, if necessary. - - - - - - temp_buffers (integer) - - temp_buffers configuration parameter - - - - Sets the maximum number of temporary buffers used by each database - session. These are session-local buffers used only for access to - temporary tables. The default is eight megabytes - (8MB). The setting can be changed within individual - sessions, but only before the first use of temporary tables - within the session; subsequent attempts to change the value will - have no effect on that session. - - - - A session will allocate temporary buffers as needed up to the limit - given by temp_buffers. The cost of setting a large - value in sessions that do not actually need many temporary - buffers is only a buffer descriptor, or about 64 bytes, per - increment in temp_buffers. However if a buffer is - actually used an additional 8192 bytes will be consumed for it - (or in general, BLCKSZ bytes). - - - - - - max_prepared_transactions (integer) - - max_prepared_transactions configuration parameter - - - - Sets the maximum number of transactions that can be in the - prepared state simultaneously (see ). - Setting this parameter to zero (which is the default) - disables the prepared-transaction feature. - This parameter can only be set at server start. - - - - If you are not planning to use prepared transactions, this parameter - should be set to zero to prevent accidental creation of prepared - transactions. If you are using prepared transactions, you will - probably want max_prepared_transactions to be at - least as large as , so that every - session can have a prepared transaction pending. - - - - - Increasing this parameter might cause PostgreSQL - - - Increasing this parameter might cause Postgres-XC - - - Increasing this parameter might cause Postgres-XL - - to request more System V shared - memory than your operating system's default configuration - allows. See for information on how to - adjust those parameters, if necessary. - - - - When running a standby server, you must set this parameter to the - same or higher value than on the master server. Otherwise, queries - will not be allowed in the standby server. - - - - - Even though your application does not issue PREPARE - TRANSACTION explicitly, Coordinator may generate this - command when an updating transaction involves more than one - Coordinators and Datanodes. For Datanodes, you should specify - this value as the same value as max_connections. - - - - - Even though your application does not issue PREPARE - TRANSACTION explicitly, Coordinator may generate this - command when an updating transaction involves more than one - Coordinators and Datanodes. For Datanodes, you should specify - this value as the same value as max_connections. - - - - - - - - work_mem (integer) - - work_mem configuration parameter - - - - Specifies the amount of memory to be used by internal sort operations - and hash tables before writing to temporary disk files. The value - defaults to one megabyte (1MB). - Note that for a complex query, several sort or hash operations might be - running in parallel; each operation will be allowed to use as much memory - as this value specifies before it starts to write data into temporary - files. Also, several running sessions could be doing such operations - concurrently. Therefore, the total memory used could be many - times the value of work_mem; it is necessary to - keep this fact in mind when choosing the value. Sort operations are - used for ORDER BY, DISTINCT, and - merge joins. - Hash tables are used in hash joins, hash-based aggregation, and - hash-based processing of IN subqueries. - - - - - - maintenance_work_mem (integer) - - maintenance_work_mem configuration parameter - - - - Specifies the maximum amount of memory to be used by maintenance - operations, such as VACUUM, CREATE - INDEX, and ALTER TABLE ADD FOREIGN KEY. It defaults - to 16 megabytes (16MB). Since only one of these - operations can be executed at a time by a database session, and - an installation normally doesn't have many of them running - concurrently, it's safe to set this value significantly larger - than work_mem. Larger settings might improve - performance for vacuuming and for restoring database dumps. - - - Note that when autovacuum runs, up to - times this memory may be - allocated, so be careful not to set the default value too high. - - - - - - max_stack_depth (integer) - - max_stack_depth configuration parameter - - - - Specifies the maximum safe depth of the server's execution stack. - The ideal setting for this parameter is the actual stack size limit - enforced by the kernel (as set by ulimit -s or local - equivalent), less a safety margin of a megabyte or so. The safety - margin is needed because the stack depth is not checked in every - routine in the server, but only in key potentially-recursive routines - such as expression evaluation. The default setting is two - megabytes (2MB), which is conservatively small and - unlikely to risk crashes. However, it might be too small to allow - execution of complex functions. Only superusers can change this - setting. - - - - Setting max_stack_depth higher than - the actual kernel limit will mean that a runaway recursive function - can crash an individual backend process. On platforms where - - PostgreSQL can determine the kernel limit, - - - Postgres-XC can determine the kernel limit, - - - Postgres-XL can determine the kernel limit, - - the server will not allow this variable to be set to an unsafe - value. However, not all platforms provide the information, - so caution is recommended in selecting a value. - - - - - - - - - Kernel Resource Usage - -&common; - - max_files_per_process (integer) - - max_files_per_process configuration parameter - - - - Sets the maximum number of simultaneously open files allowed to each - server subprocess. The default is one thousand files. If the kernel is enforcing - a safe per-process limit, you don't need to worry about this setting. - But on some platforms (notably, most BSD systems), the kernel will - allow individual processes to open many more files than the system - can actually support if many processes all try to open - that many files. If you find yourself seeing Too many open - files failures, try reducing this setting. - This parameter can only be set at server start. - - - - - - shared_preload_libraries (string) - - shared_preload_libraries configuration parameter - - - - This variable specifies one or more shared libraries - to be preloaded at server start. For example, - '$libdir/mylib' would cause - mylib.so (or on some platforms, - mylib.sl) to be preloaded from the installation's - standard library directory. - All library names are converted to lower case unless double-quoted. - If more than one library is to be loaded, separate their names - with commas. This parameter can only be set at server start. - - - - - PostgreSQL procedural language - libraries can be preloaded in this way, typically by using the - syntax '$libdir/plXXX' where - XXX is pgsql, perl, - tcl, or python. - - - Postgres-XC procedural language - libraries can be preloaded in this way, typically by using the - syntax '$libdir/plXXX' where - XXX is pgsql, perl, - tcl, or python. - - - Postgres-XL procedural language - libraries can be preloaded in this way, typically by using the - syntax '$libdir/plXXX' where - XXX is pgsql, perl, - tcl, or python. - - - - - By preloading a shared library, the library startup time is avoided - when the library is first used. However, the time to start each new - server process might increase slightly, even if that process never - uses the library. So this parameter is recommended only for - libraries that will be used in most sessions. - - - - - - - On Windows hosts, preloading a library at server start will not reduce - the time required to start each new server process; each server process - will re-load all preload libraries. However, shared_preload_libraries - is still useful on Windows hosts because some shared libraries may - need to perform certain operations that only take place at postmaster start - (for example, a shared library may need to reserve lightweight locks - or shared memory and you can't do that after the postmaster has started). - - - - - If a specified library is not found, - the server will fail to start. - - - - - Every PostgreSQL-supported library has a magic - block that is checked to guarantee compatibility. - For this reason, non-PostgreSQL libraries cannot be - loaded in this way. - - - Every Postgres-XC-supported library has a magic - block that is checked to guarantee compatibility. - For this reason, non-Postgres-XC libraries cannot be - loaded in this way. - - - Every Postgres-XL-supported library has a magic - block that is checked to guarantee compatibility. - For this reason, non-Postgres-XL libraries cannot be - loaded in this way. - - - - - - - - - - Cost-based Vacuum Delay - -&common; - - During the execution of - and - commands, the system maintains an - internal counter that keeps track of the estimated cost of the - various I/O operations that are performed. When the accumulated - cost reaches a limit (specified by - vacuum_cost_limit), the process performing - the operation will sleep for a short period of time, as specified by - vacuum_cost_delay. Then it will reset the - counter and continue execution. - - - - The intent of this feature is to allow administrators to reduce - the I/O impact of these commands on concurrent database - activity. There are many situations where it is not - important that maintenance commands like - VACUUM and ANALYZE finish - quickly; however, it is usually very important that these - commands do not significantly interfere with the ability of the - system to perform other database operations. Cost-based vacuum - delay provides a way for administrators to achieve this. - - - - This feature is disabled by default for manually issued - VACUUM commands. To enable it, set the - vacuum_cost_delay variable to a nonzero - value. - - - - - vacuum_cost_delay (integer) - - vacuum_cost_delay configuration parameter - - - - The length of time, in milliseconds, that the process will sleep - when the cost limit has been exceeded. - The default value is zero, which disables the cost-based vacuum - delay feature. Positive values enable cost-based vacuuming. - Note that on many systems, the effective resolution - of sleep delays is 10 milliseconds; setting - vacuum_cost_delay to a value that is - not a multiple of 10 might have the same results as setting it - to the next higher multiple of 10. - - - - When using cost-based vacuuming, appropriate values for - vacuum_cost_delay are usually quite small, perhaps - 10 or 20 milliseconds. Adjusting vacuum's resource consumption - is best done by changing the other vacuum cost parameters. - - - - - - vacuum_cost_page_hit (integer) - - vacuum_cost_page_hit configuration parameter - - - - The estimated cost for vacuuming a buffer found in the shared buffer - cache. It represents the cost to lock the buffer pool, lookup - the shared hash table and scan the content of the page. The - default value is one. - - - - - - vacuum_cost_page_miss (integer) - - vacuum_cost_page_miss configuration parameter - - - - The estimated cost for vacuuming a buffer that has to be read from - disk. This represents the effort to lock the buffer pool, - lookup the shared hash table, read the desired block in from - the disk and scan its content. The default value is 10. - - - - - - vacuum_cost_page_dirty (integer) - - vacuum_cost_page_dirty configuration parameter - - - - The estimated cost charged when vacuum modifies a block that was - previously clean. It represents the extra I/O required to - flush the dirty block out to disk again. The default value is - 20. - - - - - - vacuum_cost_limit (integer) - - vacuum_cost_limit configuration parameter - - - - The accumulated cost that will cause the vacuuming process to sleep. - The default value is 200. - - - - - - - - There are certain operations that hold critical locks and should - therefore complete as quickly as possible. Cost-based vacuum - delays do not occur during such operations. Therefore it is - possible that the cost accumulates far higher than the specified - limit. To avoid uselessly long delays in such cases, the actual - delay is calculated as vacuum_cost_delay * - accumulated_balance / - vacuum_cost_limit with a maximum of - vacuum_cost_delay * 4. - - - - - - Background Writer -&common; - - There is a separate server - process called the background writer, whose function - is to issue writes of dirty (new or modified) shared - buffers. It writes shared buffers so server processes handling - user queries seldom or never need to wait for a write to occur. - However, the background writer does cause a net overall - increase in I/O load, because while a repeatedly-dirtied page might - otherwise be written only once per checkpoint interval, the - background writer might write it several times as it is dirtied - in the same interval. The parameters discussed in this subsection - can be used to tune the behavior for local needs. - - - - - bgwriter_delay (integer) - - bgwriter_delay configuration parameter - - - - Specifies the delay between activity rounds for the - background writer. In each round the writer issues writes - for some number of dirty buffers (controllable by the - following parameters). It then sleeps for bgwriter_delay - milliseconds, and repeats. The default value is 200 milliseconds - (200ms). Note that on many systems, the effective - resolution of sleep delays is 10 milliseconds; setting - bgwriter_delay to a value that is not a multiple of - 10 might have the same results as setting it to the next higher - multiple of 10. This parameter can only be set in the - postgresql.conf file or on the server command line. - - - - - - bgwriter_lru_maxpages (integer) - - bgwriter_lru_maxpages configuration parameter - - - - In each round, no more than this many buffers will be written - by the background writer. Setting this to zero disables - background writing (except for checkpoint activity). - The default value is 100 buffers. - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - - - - bgwriter_lru_multiplier (floating point) - - bgwriter_lru_multiplier configuration parameter - - - - The number of dirty buffers written in each round is based on the - number of new buffers that have been needed by server processes - during recent rounds. The average recent need is multiplied by - bgwriter_lru_multiplier to arrive at an estimate of the - number of buffers that will be needed during the next round. Dirty - buffers are written until there are that many clean, reusable buffers - available. (However, no more than bgwriter_lru_maxpages - buffers will be written per round.) - Thus, a setting of 1.0 represents a just in time policy - of writing exactly the number of buffers predicted to be needed. - Larger values provide some cushion against spikes in demand, - while smaller values intentionally leave writes to be done by - server processes. - The default is 2.0. - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - - - - - Smaller values of bgwriter_lru_maxpages and - bgwriter_lru_multiplier reduce the extra I/O load - caused by the background writer, but make it more likely that server - processes will have to issue writes for themselves, delaying interactive - queries. - - - - - Asynchronous Behavior -&common; - - - effective_io_concurrency (integer) - - effective_io_concurrency configuration parameter - - - - Sets the number of concurrent disk I/O operations that - PostgreSQL expects can be executed - simultaneously. Raising this value will increase the number of I/O - operations that any individual PostgreSQL session - attempts to initiate in parallel. The allowed range is 1 to 1000, - or zero to disable issuance of asynchronous I/O requests. Currently, - this setting only affects bitmap heap scans. - - - - A good starting point for this setting is the number of separate - drives comprising a RAID 0 stripe or RAID 1 mirror being used for the - database. (For RAID 5 the parity drive should not be counted.) - However, if the database is often busy with multiple queries issued in - concurrent sessions, lower values may be sufficient to keep the disk - array busy. A value higher than needed to keep the disks busy will - only result in extra CPU overhead. - - - - For more exotic systems, such as memory-based storage or a RAID array - that is limited by bus bandwidth, the correct value might be the - number of I/O paths available. Some experimentation may be needed - to find the best value. - - - - Asynchronous I/O depends on an effective posix_fadvise - function, which some operating systems lack. If the function is not - present then setting this parameter to anything but zero will result - in an error. On some operating systems (e.g., Solaris), the function - is present but does not actually do anything. - - - - - - - - - Write Ahead Log -&common; - - See also for details on WAL - and checkpoint tuning. - - - - Settings - -&common; - - wal_level (enum) - - wal_level configuration parameter - - - - wal_level determines how much information is written - to the WAL. The default value is minimal, which writes - only the information needed to recover from a crash or immediate - shutdown. archive adds logging required for WAL archiving, - and hot_standby further adds information required to run - read-only queries on a standby server. - This parameter can only be set at server start. - - - In minimal level, WAL-logging of some bulk operations, like - CREATE INDEX, CLUSTER and COPY on - a table that was created or truncated in the same transaction can be - safely skipped, which can make those operations much faster (see - ). But minimal WAL does not contain - enough information to reconstruct the data from a base backup and the - WAL logs, so either archive or hot_standby - level must be used to enable - WAL archiving () and streaming - replication. - - - - In hot_standby level, the same information is logged as - with archive, plus information needed to reconstruct - the status of running transactions from the WAL. To enable read-only - queries on a standby server, wal_level must be set to - hot_standby on the primary, and - must be enabled in the standby. It is - thought that there is - little measurable difference in performance between using - hot_standby and archive levels, so feedback - is welcome if any production impacts are noticeable. - - - - - - - - fsync configuration parameter - - fsync (boolean) - - - - If this parameter is on, the PostgreSQL server - - - If this parameter is on, the Postgres-XC server - - - If this parameter is on, the Postgres-XL server - - will try to make sure that updates are physically written to - disk, by issuing fsync() system calls or various - equivalent methods (see ). - This ensures that the database cluster can recover to a - consistent state after an operating system or hardware crash. - - - - While turning off fsync is often a performance - benefit, this can result in unrecoverable data corruption in - the event of a power failure or system crash. Thus it - is only advisable to turn off fsync if - you can easily recreate your entire database from external - data. - - - - Examples of safe circumstances for turning off - fsync include the initial loading of a new - database cluster from a backup file, using a database cluster - for processing a batch of data after which the database - will be thrown away and recreated, - or for a read-only database clone which - gets recreated frequently and is not used for failover. High - quality hardware alone is not a sufficient justification for - turning off fsync. - - - - In many situations, turning off - for noncritical transactions can provide much of the potential - performance benefit of turning off fsync, without - the attendant risks of data corruption. - - - - fsync can only be set in the postgresql.conf - file or on the server command line. - If you turn this parameter off, also consider turning off - . - - - - - - synchronous_commit (boolean) - - synchronous_commit configuration parameter - - - - Specifies whether transaction commit will wait for WAL records - to be written to disk before the command returns a success - indication to the client. Valid values are on, - local, and off. The default, and safe, value - is on. When off, there can be a delay between - when success is reported to the client and when the transaction is - really guaranteed to be safe against a server crash. (The maximum - delay is three times .) Unlike - , setting this parameter to off - does not create any risk of database inconsistency: an operating - system or database crash might - result in some recent allegedly-committed transactions being lost, but - the database state will be just the same as if those transactions had - been aborted cleanly. So, turning synchronous_commit off - can be a useful alternative when performance is more important than - exact certainty about the durability of a transaction. For more - discussion see . - - - If is set, this - parameter also controls whether or not transaction commit will wait - for the transaction's WAL records to be flushed to disk and replicated - to the standby server. The commit wait will last until a reply from - the current synchronous standby indicates it has written the commit - record of the transaction to durable storage. If synchronous - replication is in use, it will normally be sensible either to wait - both for WAL records to reach both the local and remote disks, or - to allow the transaction to commit asynchronously. However, the - special value local is available for transactions that - wish to wait for local flush to disk, but not synchronous replication. - - - This parameter can be changed at any time; the behavior for any - one transaction is determined by the setting in effect when it - commits. It is therefore possible, and useful, to have some - transactions commit synchronously and others asynchronously. - For example, to make a single multistatement transaction commit - asynchronously when the default is the opposite, issue SET - LOCAL synchronous_commit TO OFF within the transaction. - - - - - - wal_sync_method (enum) - - wal_sync_method configuration parameter - - - - Method used for forcing WAL updates out to disk. - If fsync is off then this setting is irrelevant, - since WAL file updates will not be forced out at all. - Possible values are: - - - - - open_datasync (write WAL files with open() option O_DSYNC) - - - - - fdatasync (call fdatasync() at each commit) - - - - - fsync (call fsync() at each commit) - - - - - fsync_writethrough (call fsync() at each commit, forcing write-through of any disk write cache) - - - - - open_sync (write WAL files with open() option O_SYNC) - - - - - The open_* options also use O_DIRECT if available. - Not all of these choices are available on all platforms. - The default is the first method in the above list that is supported - by the platform, except that fdatasync is the default on - Linux. The default is not necessarily ideal; it might be - necessary to change this setting or other aspects of your system - configuration in order to create a crash-safe configuration or - achieve optimal performance. - These aspects are discussed in . - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - - - - - full_page_writes configuration parameter - - full_page_writes (boolean) - - - - When this parameter is on, the PostgreSQL server - - - When this parameter is on, the Postgres-XC server - - - When this parameter is on, the Postgres-XL server - - writes the entire content of each disk page to WAL during the - first modification of that page after a checkpoint. - This is needed because - a page write that is in process during an operating system crash might - be only partially completed, leading to an on-disk page - that contains a mix of old and new data. The row-level change data - normally stored in WAL will not be enough to completely restore - such a page during post-crash recovery. Storing the full page image - guarantees that the page can be correctly restored, but at the price - of increasing the amount of data that must be written to WAL. - (Because WAL replay always starts from a checkpoint, it is sufficient - to do this during the first change of each page after a checkpoint. - Therefore, one way to reduce the cost of full-page writes is to - increase the checkpoint interval parameters.) - - - - Turning this parameter off speeds normal operation, but - might lead to either unrecoverable data corruption, or silent - data corruption, after a system failure. The risks are similar to turning off - fsync, though smaller, and it should be turned off - only based on the same circumstances recommended for that parameter. - - - - Turning off this parameter does not affect use of - WAL archiving for point-in-time recovery (PITR) - (see ). - - - - This parameter can only be set in the postgresql.conf - file or on the server command line. - The default is on. - - - - - - wal_buffers (integer) - - wal_buffers configuration parameter - - - - The amount of shared memory used for WAL data that has not yet been - written to disk. The default setting of -1 selects a size equal to - 1/32nd (about 3%) of , but not less - than 64kB nor more than the size of one WAL - segment, typically 16MB. This value can be set - manually if the automatic choice is too large or too small, - but any positive value less than 32kB will be - treated as 32kB. - This parameter can only be set at server start. - - - - The contents of the WAL buffers are written out to disk at every - transaction commit, so extremely large values are unlikely to - provide a significant benefit. However, setting this value to at - least a few megabytes can improve write performance on a busy - server where many clients are committing at once. The auto-tuning - selected by the default setting of -1 should give reasonable - results in most cases. - - - - - Increasing this parameter might cause PostgreSQL - - - Increasing this parameter might cause Postgres-XC - - - Increasing this parameter might cause Postgres-XL - - to request more System V shared - memory than your operating system's default configuration - allows. See for information on how to - adjust those parameters, if necessary. - - - - - - wal_writer_delay (integer) - - wal_writer_delay configuration parameter - - - - Specifies the delay between activity rounds for the WAL writer. - In each round the writer will flush WAL to disk. It then sleeps for - wal_writer_delay milliseconds, and repeats. The default - value is 200 milliseconds (200ms). Note that on many - systems, the effective resolution of sleep delays is 10 milliseconds; - setting wal_writer_delay to a value that is not a multiple - of 10 might have the same results as setting it to the next higher - multiple of 10. This parameter can only be set in the - postgresql.conf file or on the server command line. - - - - - - commit_delay (integer) - - commit_delay configuration parameter - - - - When the commit data for a transaction is flushed to disk, any - additional commits ready at that time are also flushed out. - commit_delay adds a time delay, set in - microseconds, before a transaction attempts to - flush the WAL buffer out to disk. A nonzero delay can allow more - transactions to be committed with only one flush operation, if - system load is high enough that additional transactions become - ready to commit within the given interval. But the delay is - just wasted if no other transactions become ready to - commit. Therefore, the delay is only performed if at least - commit_siblings other transactions are - active at the instant that a server process has written its - commit record. - The default commit_delay is zero (no delay). - Since all pending commit data will be written at every flush - regardless of this setting, it is rare that adding delay - by increasing this parameter will actually improve performance. - - - - - - commit_siblings (integer) - - commit_siblings configuration parameter - - - - Minimum number of concurrent open transactions to require - before performing the commit_delay delay. A larger - value makes it more probable that at least one other - transaction will become ready to commit during the delay - interval. The default is five transactions. - - - - - - - - Checkpoints -&common; - - - checkpoint_segments (integer) - - checkpoint_segments configuration parameter - - - - Maximum number of log file segments between automatic WAL - checkpoints (each segment is normally 16 megabytes). The default - is three segments. Increasing this parameter can increase the - amount of time needed for crash recovery. - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - - - - checkpoint_timeout (integer) - - checkpoint_timeout configuration parameter - - - - Maximum time between automatic WAL checkpoints, in - seconds. The default is five minutes (5min). - Increasing this parameter can increase the amount of time needed - for crash recovery. - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - - - - checkpoint_completion_target (floating point) - - checkpoint_completion_target configuration parameter - - - - Specifies the target of checkpoint completion, as a fraction of - total time between checkpoints. The default is 0.5. - - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - - - - checkpoint_warning (integer) - - checkpoint_warning configuration parameter - - - - Write a message to the server log if checkpoints caused by - the filling of checkpoint segment files happen closer together - than this many seconds (which suggests that - checkpoint_segments ought to be raised). The default is - 30 seconds (30s). Zero disables the warning. - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - - - - - - Archiving -&common; - - - archive_mode (boolean) - - archive_mode configuration parameter - - - - When archive_mode is enabled, completed WAL segments - are sent to archive storage by setting - . - archive_mode and archive_command are - separate variables so that archive_command can be - changed without leaving archiving mode. - This parameter can only be set at server start. wal_level - must be set to archive or hot_standby to - enable archive_mode. - - - - - - archive_command (string) - - archive_command configuration parameter - - - - The shell command to execute to archive a completed WAL file - segment. Any %p in the string is - replaced by the path name of the file to archive, and any - %f is replaced by only the file name. - (The path name is relative to the working directory of the server, - i.e., the cluster's data directory.) - Use %% to embed an actual % character in the - command. It is important for the command to return a zero - exit status only if it succeeds. For more information see - . - - - This parameter can only be set in the postgresql.conf - file or on the server command line. It is ignored unless - archive_mode was enabled at server start. - If archive_command is an empty string (the default) while - archive_mode is enabled, WAL archiving is temporarily - disabled, but the server continues to accumulate WAL segment files in - the expectation that a command will soon be provided. Setting - archive_command to a command that does nothing but - return true, e.g. /bin/true (REM on - Windows), effectively disables - archiving, but also breaks the chain of WAL files needed for - archive recovery, so it should only be used in unusual circumstances. - - - - - - archive_timeout (integer) - - archive_timeout configuration parameter - - - - The is only invoked for - completed WAL segments. Hence, if your server generates little WAL - traffic (or has slack periods where it does so), there could be a - long delay between the completion of a transaction and its safe - recording in archive storage. To limit how old unarchived - data can be, you can set archive_timeout to force the - server to switch to a new WAL segment file periodically. When this - parameter is greater than zero, the server will switch to a new - segment file whenever this many seconds have elapsed since the last - segment file switch, and there has been any database activity, - including a single checkpoint. (Increasing - checkpoint_timeout will reduce unnecessary - checkpoints on an idle system.) - Note that archived files that are closed early - due to a forced switch are still the same length as completely full - files. Therefore, it is unwise to use a very short - archive_timeout — it will bloat your archive - storage. archive_timeout settings of a minute or so are - usually reasonable. This parameter can only be set in the - postgresql.conf file or on the server command line. - - - - - - - - - - Streaming Replication - -&pgonly; - - Streaming replication has not been tested - with Postgres-XC yet. Because this - version of streaming replication is based upon asynchronous log shipping, - there could be a risk to have the status of Coordinators and - Datanodes inconsistent. The development team leaves the test - and the use of this entirely to users. - - - -&pgonly; - - Streaming replication only been thoroughly tested in asynchronous mode - with Postgres-XL. - - - - - These settings control the behavior of the built-in - streaming replication feature. - These parameters would be set on the primary server that is - to send replication data to one or more standby servers. - - - - - max_wal_senders (integer) - - max_wal_senders configuration parameter - - - - Specifies the maximum number of concurrent connections from standby - servers or streaming base backup clients (i.e., the maximum number of - simultaneously running WAL sender - processes). The default is zero. This parameter can only be set at - server start. wal_level must be set to archive - or hot_standby to allow connections from standby servers. - - - - - wal_sender_delay (integer) - - wal_sender_delay configuration parameter - - - - Specifies the delay between activity rounds for WAL sender processes. - In each round the WAL sender sends any WAL accumulated since the last - round to the standby server. It then sleeps for - wal_sender_delay milliseconds, and repeats. The sleep - is interrupted by transaction commit, so the effects of a committed - transaction are sent to standby servers as soon as the commit - happens, regardless of this setting. The default value is one second - (1s). - Note that on many systems, the effective resolution of sleep delays is - 10 milliseconds; setting wal_sender_delay to a value that - is not a multiple of 10 might have the same results as setting it to - the next higher multiple of 10. This parameter can only be set in the - postgresql.conf file or on the server command line. - - - - - - wal_keep_segments (integer) - - wal_keep_segments configuration parameter - - - - Specifies the minimum number of past log file segments kept in the - pg_xlog - directory, in case a standby server needs to fetch them for streaming - replication. Each segment is normally 16 megabytes. If a standby - server connected to the primary falls behind by more than - wal_keep_segments segments, the primary might remove - a WAL segment still needed by the standby, in which case the - replication connection will be terminated. (However, the standby - server can recover by fetching the segment from archive, if WAL - archiving is in use.) - - - - This sets only the minimum number of segments retained in - pg_xlog; the system might need to retain more segments - for WAL archival or to recover from a checkpoint. If - wal_keep_segments is zero (the default), the system - doesn't keep any extra segments for standby purposes, and the number - of old WAL segments available to standby servers is a function of - the location of the previous checkpoint and status of WAL - archiving. This parameter has no effect on restartpoints. - This parameter can only be set in the - postgresql.conf file or on the server command line. - - - - - - vacuum_defer_cleanup_age (integer) - - vacuum_defer_cleanup_age configuration parameter - - - - Specifies the number of transactions by which VACUUM and - HOT updates will defer cleanup of dead row versions. The - default is zero transactions, meaning that dead row versions can be - removed as soon as possible, that is, as soon as they are no longer - visible to any open transaction. You may wish to set this to a - non-zero value on a primary server that is supporting hot standby - servers, as described in . This allows - more time for queries on the standby to complete without incurring - conflicts due to early cleanup of rows. However, since the value - is measured in terms of number of write transactions occurring on the - primary server, it is difficult to predict just how much additional - grace time will be made available to standby queries. - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - You should also consider setting hot_standby_feedback - as an alternative to using this parameter. - - - - - - replication_timeout (integer) - - replication_timeout configuration parameter - - - - Terminate replication connections that are inactive longer - than the specified number of milliseconds. This is useful for - the primary server to detect a standby crash or network outage. - A value of zero disables the timeout mechanism. This parameter - can only be set in - the postgresql.conf file or on the server command line. - The default value is 60 seconds. - - - To prevent connections from being terminated prematurely, - - must be enabled on the standby, and its value must be less than the - value of replication_timeout. - - - - - - - - Synchronous Replication - - - These settings control the behavior of the built-in - synchronous replication feature. - These parameters would be set on the primary server that is - to send replication data to one or more standby servers. - - - - - synchronous_standby_names (string) - - synchronous_standby_names configuration parameter - - - - Specifies a priority ordered list of standby names that can offer - synchronous replication. At any one time there will be at most one - synchronous standby that will wake sleeping users following commit. - The synchronous standby will be the first named standby that is - both currently connected and streaming in real-time to the standby - (as shown by a state of "STREAMING"). Other standby servers - with listed later will become potential synchronous standbys. - If the current synchronous standby disconnects for whatever reason - it will be replaced immediately with the next highest priority standby. - Specifying more than one standby name can allow very high availability. - - - The standby name is currently taken as the application_name of the - standby, as set in the primary_conninfo on the standby. Names are - not enforced for uniqueness. In case of duplicates one of the standbys - will be chosen to be the synchronous standby, though exactly which - one is indeterminate. - The special entry * matches any application_name, including - the default application name of walreceiver. - - - If no synchronous standby names are specified, then synchronous - replication is not enabled and transaction commit will never wait for - replication. This is the default configuration. Even when - synchronous replication is enabled, individual transactions can be - configured not to wait for replication by setting the - parameter to - local or off. - - - - - - - - - - Standby Servers - - These settings control the behavior of a standby server that is - to receive replication data. - - - - - - - - hot_standby (boolean) - - hot_standby configuration parameter - - - - Specifies whether or not you can connect and run queries during - recovery, as described in . - The default value is off. - This parameter can only be set at server start. It only has effect - during archive recovery or in standby mode. - - - - - - - max_standby_archive_delay (integer) - - max_standby_archive_delay configuration parameter - - - - - - When Hot Standby is active, this parameter determines how long the - standby server should wait before canceling standby queries that - conflict with about-to-be-applied WAL entries, as described in - . - - max_standby_archive_delay applies when WAL data is - being read from WAL archive (and is therefore not current). - The default is 30 seconds. Units are milliseconds if not specified. - A value of -1 allows the standby to wait forever for conflicting - queries to complete. - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - Note that max_standby_archive_delay is not the same as the - maximum length of time a query can run before cancellation; rather it - is the maximum total time allowed to apply any one WAL segment's data. - Thus, if one query has resulted in significant delay earlier in the - WAL segment, subsequent conflicting queries will have much less grace - time. - - - - - - max_standby_streaming_delay (integer) - - max_standby_streaming_delay configuration parameter - - - - - - When Hot Standby is active, this parameter determines how long the - standby server should wait before canceling standby queries that - conflict with about-to-be-applied WAL entries, as described in - . - - max_standby_streaming_delay applies when WAL data is - being received via streaming replication. - The default is 30 seconds. Units are milliseconds if not specified. - A value of -1 allows the standby to wait forever for conflicting - queries to complete. - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - Note that max_standby_streaming_delay is not the same as - the maximum length of time a query can run before cancellation; rather - it is the maximum total time allowed to apply WAL data once it has - been received from the primary server. Thus, if one query has - resulted in significant delay, subsequent conflicting queries will - have much less grace time until the standby server has caught up - again. - - - - - - wal_receiver_status_interval (integer) - - wal_receiver_status_interval configuration parameter - - - - Specifies the minimum frequency, in seconds, for the WAL receiver - process on the standby to send information about replication progress - to the primary, where they can be seen using the - pg_stat_replication view. The standby will report - the last transaction log position it has written, the last position it - has flushed to disk, and the last position it has applied. Updates are - sent each time the write or flush positions changed, or at least as - often as specified by this parameter. Thus, the apply position may - lag slightly behind the true position. Setting this parameter to zero - disables status updates completely. This parameter can only be set in - the postgresql.conf file or on the server command line. - The default value is 10 seconds. - - - When is enabled on the primary, - wal_receiver_status_interval must be enabled, and its value - must be less than the value of replication_timeout. - - - - - - - - hot_standby_feedback (boolean) - - hot_standby_feedback configuration parameter - - - - Specifies whether or not a hot standby will send feedback to the primary - about queries currently executing on the standby. This parameter can - be used to eliminate query cancels caused by cleanup records, but - can cause database bloat on the primary for some workloads. - The default value is off. Feedback messages will not - be sent more frequently than once per wal_receiver_status_interval. - - - - - - - - - - - Query Planning - - - Planner Method Configuration - - - These configuration parameters provide a crude method of - influencing the query plans chosen by the query optimizer. If - the default plan chosen by the optimizer for a particular query - is not optimal, a temporary solution is to use one - of these configuration parameters to force the optimizer to - choose a different plan. - Better ways to improve the quality of the - plans chosen by the optimizer include adjusting the planer cost - constants (see ), - running manually, increasing - the value of the configuration parameter, - and increasing the amount of statistics collected for - specific columns using ALTER TABLE SET - STATISTICS. - - - - - enable_bitmapscan (boolean) - - bitmap scan - - - enable_bitmapscan configuration parameter - - - - Enables or disables the query planner's use of bitmap-scan plan - types. The default is on. - - - - - - enable_hashagg (boolean) - - enable_hashagg configuration parameter - - - - Enables or disables the query planner's use of hashed - aggregation plan types. The default is on. - - - - - - enable_hashjoin (boolean) - - enable_hashjoin configuration parameter - - - - Enables or disables the query planner's use of hash-join plan - types. The default is on. - - - - - - enable_indexscan (boolean) - - index scan - - - enable_indexscan configuration parameter - - - - Enables or disables the query planner's use of index-scan plan - types. The default is on. - - - - - - enable_material (boolean) - - enable_material configuration parameter - - - - Enables or disables the query planner's use of materialization. - It is impossible to suppress materialization entirely, - but turning this variable off prevents the planner from inserting - materialize nodes except in cases where it is required for correctness. - The default is on. - - - - - - enable_mergejoin (boolean) - - enable_mergejoin configuration parameter - - - - Enables or disables the query planner's use of merge-join plan - types. The default is on. - - - - - - enable_nestloop (boolean) - - enable_nestloop configuration parameter - - - - Enables or disables the query planner's use of nested-loop join - plans. It is impossible to suppress nested-loop joins entirely, - but turning this variable off discourages the planner from using - one if there are other methods available. The default is - on. - - - - - - enable_seqscan (boolean) - - sequential scan - - - enable_seqscan configuration parameter - - - - Enables or disables the query planner's use of sequential scan - plan types. It is impossible to suppress sequential scans - entirely, but turning this variable off discourages the planner - from using one if there are other methods available. The - default is on. - - - - - - enable_sort (boolean) - - enable_sort configuration parameter - - - - Enables or disables the query planner's use of explicit sort - steps. It is impossible to suppress explicit sorts entirely, - but turning this variable off discourages the planner from - using one if there are other methods available. The default - is on. - - - - - - enable_tidscan (boolean) - - enable_tidscan configuration parameter - - - - Enables or disables the query planner's use of TID - scan plan types. The default is on. - - - - - - - - Planner Cost Constants - - - The cost variables described in this section are measured - on an arbitrary scale. Only their relative values matter, hence - scaling them all up or down by the same factor will result in no change - in the planner's choices. By default, these cost variables are based on - the cost of sequential page fetches; that is, - seq_page_cost is conventionally set to 1.0 - and the other cost variables are set with reference to that. But - you can use a different scale if you prefer, such as actual execution - times in milliseconds on a particular machine. - - - - - Unfortunately, there is no well-defined method for determining ideal - values for the cost variables. They are best treated as averages over - the entire mix of queries that a particular installation will receive. This - means that changing them on the basis of just a few experiments is very - risky. - - - - - - - seq_page_cost (floating point) - - seq_page_cost configuration parameter - - - - Sets the planner's estimate of the cost of a disk page fetch - that is part of a series of sequential fetches. The default is 1.0. - This value can be overridden for a particular tablespace by setting - the tablespace parameter of the same name - (see ). - - - - - - random_page_cost (floating point) - - random_page_cost configuration parameter - - - - Sets the planner's estimate of the cost of a - non-sequentially-fetched disk page. The default is 4.0. - This value can be overridden for a particular tablespace by setting - the tablespace parameter of the same name - (see ). - - - - Reducing this value relative to seq_page_cost - will cause the system to prefer index scans; raising it will - make index scans look relatively more expensive. You can raise - or lower both values together to change the importance of disk I/O - costs relative to CPU costs, which are described by the following - parameters. - - - - - Although the system will let you set random_page_cost to - less than seq_page_cost, it is not physically sensible - to do so. However, setting them equal makes sense if the database - is entirely cached in RAM, since in that case there is no penalty - for touching pages out of sequence. Also, in a heavily-cached - database you should lower both values relative to the CPU parameters, - since the cost of fetching a page already in RAM is much smaller - than it would normally be. - - - - - - - cpu_tuple_cost (floating point) - - cpu_tuple_cost configuration parameter - - - - Sets the planner's estimate of the cost of processing - each row during a query. - The default is 0.01. - - - - - - cpu_index_tuple_cost (floating point) - - cpu_index_tuple_cost configuration parameter - - - - Sets the planner's estimate of the cost of processing - each index entry during an index scan. - The default is 0.005. - - - - - - cpu_operator_cost (floating point) - - cpu_operator_cost configuration parameter - - - - Sets the planner's estimate of the cost of processing each - operator or function executed during a query. - The default is 0.0025. - - - - - - effective_cache_size (integer) - - effective_cache_size configuration parameter - - - - Sets the planner's assumption about the effective size of the - disk cache that is available to a single query. This is - factored into estimates of the cost of using an index; a - higher value makes it more likely index scans will be used, a - lower value makes it more likely sequential scans will be - used. When setting this parameter you should consider both - - PostgreSQL's shared buffers and the - portion of the kernel's disk cache that will be used for - PostgreSQL data files. Also, take - - - Postgres-XC's shared buffers and the - portion of the kernel's disk cache that will be used for - Postgres-XC data files. Also, take - - - Postgres-XL's shared buffers and the - portion of the kernel's disk cache that will be used for - Postgres-XL data files. Also, take - - into account the expected number of concurrent queries on different - tables, since they will have to share the available - space. This parameter has no effect on the size of shared - - memory allocated by PostgreSQL, nor - - - memory allocated by Postgres-XC, nor - - - memory allocated by Postgres-XL, nor - - does it reserve kernel disk cache; it is used only for estimation - purposes. The system also does not assume data remains in - the disk cache between queries. The default is 128 megabytes - (128MB). - - - - - - - - - Genetic Query Optimizer - - - The genetic query optimizer (GEQO) is an algorithm that does query - planning using heuristic searching. This reduces planning time for - complex queries (those joining many relations), at the cost of producing - plans that are sometimes inferior to those found by the normal - exhaustive-search algorithm. Also, GEQO's searching is randomized and - therefore its plans may vary nondeterministically. - For more information see . - - - - - - - genetic query optimization - - - GEQO - genetic query optimization - - - geqo configuration parameter - - geqo (boolean) - - - Enables or disables genetic query optimization. - This is on by default. It is usually best not to turn it off in - production; the geqo_threshold variable provides - more granular control of GEQO. - - - - - - geqo_threshold (integer) - - geqo_threshold configuration parameter - - - - Use genetic query optimization to plan queries with at least - this many FROM items involved. (Note that a - FULL OUTER JOIN construct counts as only one FROM - item.) The default is 12. For simpler queries it is usually best - to use the deterministic, exhaustive planner, but for queries with - many tables the deterministic planner takes too long, often - longer than the penalty of executing a suboptimal plan. - - - - - - geqo_effort - (integer) - - geqo_effort configuration parameter - - - - Controls the trade-off between planning time and query plan - quality in GEQO. This variable must be an integer in the - range from 1 to 10. The default value is five. Larger values - increase the time spent doing query planning, but also - increase the likelihood that an efficient query plan will be - chosen. - - - - geqo_effort doesn't actually do anything - directly; it is only used to compute the default values for - the other variables that influence GEQO behavior (described - below). If you prefer, you can set the other parameters by - hand instead. - - - - - - geqo_pool_size (integer) - - geqo_pool_size configuration parameter - - - - Controls the pool size used by GEQO, that is the - number of individuals in the genetic population. It must be - at least two, and useful values are typically 100 to 1000. If - it is set to zero (the default setting) then a suitable - value is chosen based on geqo_effort and - the number of tables in the query. - - - - - - geqo_generations (integer) - - geqo_generations configuration parameter - - - - Controls the number of generations used by GEQO, that is - the number of iterations of the algorithm. It must - be at least one, and useful values are in the same range as - the pool size. If it is set to zero (the default setting) - then a suitable value is chosen based on - geqo_pool_size. - - - - - - geqo_selection_bias (floating point) - - geqo_selection_bias configuration parameter - - - - Controls the selection bias used by GEQO. The selection bias - is the selective pressure within the population. Values can be - from 1.50 to 2.00; the latter is the default. - - - - - - geqo_seed (floating point) - - geqo_seed configuration parameter - - - - Controls the initial value of the random number generator used - by GEQO to select random paths through the join order search space. - The value can range from zero (the default) to one. Varying the - value changes the set of join paths explored, and may result in a - better or worse best path being found. - - - - - - - - Other Planner Options - - - - - default_statistics_target (integer) - - default_statistics_target configuration parameter - - - - Sets the default statistics target for table columns without - a column-specific target set via ALTER TABLE - SET STATISTICS. Larger values increase the time needed to - do ANALYZE, but might improve the quality of the - planner's estimates. The default is 100. For more information - - on the use of statistics by the PostgreSQL - - - on the use of statistics by the Postgres-XC - - - on the use of statistics by the Postgres-XL - - query planner, refer to . - - - - - - constraint_exclusion (enum) - - constraint exclusion - - - constraint_exclusion configuration parameter - - - - Controls the query planner's use of table constraints to - optimize queries. - The allowed values of constraint_exclusion are - on (examine constraints for all tables), - off (never examine constraints), and - partition (examine constraints only for inheritance child - tables and UNION ALL subqueries). - partition is the default setting. - It is often used with inheritance and partitioned tables to - improve performance. - - - - When this parameter allows it for a particular table, the planner - compares query conditions with the table's CHECK - constraints, and omits scanning tables for which the conditions - contradict the constraints. For example: - - -CREATE TABLE parent(key integer, ...); -CREATE TABLE child1000(check (key between 1000 and 1999)) INHERITS(parent); -CREATE TABLE child2000(check (key between 2000 and 2999)) INHERITS(parent); -... -SELECT * FROM parent WHERE key = 2400; - - - With constraint exclusion enabled, this SELECT - will not scan child1000 at all, improving performance. - - - - Currently, constraint exclusion is enabled by default - only for cases that are often used to implement table partitioning. - Turning it on for all tables imposes extra planning overhead that is - quite noticeable on simple queries, and most often will yield no - benefit for simple queries. If you have no partitioned tables - you might prefer to turn it off entirely. - - - - - - Refer to for - more information on using constraint exclusion and partitioning. - - - - - - - cursor_tuple_fraction (floating point) - - cursor_tuple_fraction configuration parameter - - - - Sets the planner's estimate of the fraction of a cursor's rows that - will be retrieved. The default is 0.1. Smaller values of this - setting bias the planner towards using fast start plans - for cursors, which will retrieve the first few rows quickly while - perhaps taking a long time to fetch all rows. Larger values - put more emphasis on the total estimated time. At the maximum - setting of 1.0, cursors are planned exactly like regular queries, - considering only the total estimated time and not how soon the - first rows might be delivered. - - - - - - from_collapse_limit (integer) - - from_collapse_limit configuration parameter - - - - The planner will merge sub-queries into upper queries if the - resulting FROM list would have no more than - this many items. Smaller values reduce planning time but might - yield inferior query plans. The default is eight. - For more information see . - - - - Setting this value to or more - may trigger use of the GEQO planner, resulting in nondeterministic - plans. See . - - - - - - join_collapse_limit (integer) - - join_collapse_limit configuration parameter - - - - The planner will rewrite explicit JOIN - constructs (except FULL JOINs) into lists of - FROM items whenever a list of no more than this many items - would result. Smaller values reduce planning time but might - yield inferior query plans. - - - - By default, this variable is set the same as - from_collapse_limit, which is appropriate - for most uses. Setting it to 1 prevents any reordering of - explicit JOINs. Thus, the explicit join order - specified in the query will be the actual order in which the - relations are joined. Because the query planner does not always choose - the optimal join order, advanced users can elect to - temporarily set this variable to 1, and then specify the join - order they desire explicitly. - For more information see . - - - - Setting this value to or more - may trigger use of the GEQO planner, resulting in nondeterministic - plans. See . - - - - - - - - - - Error Reporting and Logging - - - server log - - - - Where To Log - - - where to log - -&common; - - - - log_destination (string) - - log_destination configuration parameter - - - - - PostgreSQL supports several methods - - - Postgres-XC supports several methods - - - Postgres-XL supports several methods - - for logging server messages, including - stderr, csvlog and - syslog. On Windows, - eventlog is also supported. Set this - parameter to a list of desired log destinations separated by - commas. The default is to log to stderr - only. - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - If csvlog is included in log_destination, - log entries are output in comma separated - value (CSV) format, which is convenient for - loading logs into programs. - See for details. - logging_collector must be enabled to generate - CSV-format log output. - - - - - On most Unix systems, you will need to alter the configuration of - your system's syslog daemon in order - to make use of the syslog option for - - log_destination. PostgreSQL - - - log_destination. Postgres-XC - - - log_destination. Postgres-XL - - can log to syslog facilities - LOCAL0 through LOCAL7 (see ), but the default - syslog configuration on most platforms - will discard all such messages. You will need to add something like: - -local0.* /var/log/postgresql - - to the syslog daemon's configuration file - to make it work. - - - - - - - logging_collector (boolean) - - logging_collector configuration parameter - - - - This parameter captures plain and CSV-format log messages - sent to stderr and redirects them into log files. - This approach is often more useful than - logging to syslog, since some types of messages - might not appear in syslog output (a common example - is dynamic-linker failure messages). - This parameter can only be set at server start. - - - - - The logging collector is designed to never lose messages. This means - that in case of extremely high load, server processes could be - blocked due to trying to send additional log messages when the - collector has fallen behind. In contrast, syslog - prefers to drop messages if it cannot write them, which means it's - less reliable in those cases but it will not block the rest of the - system. - - - - - - - - log_directory (string) - - log_directory configuration parameter - - - - When logging_collector is enabled, - this parameter determines the directory in which log files will be created. - It can be specified as an absolute path, or relative to the - cluster data directory. - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - - - - log_filename (string) - - log_filename configuration parameter - - - - When logging_collector is enabled, - this parameter sets the file names of the created log files. The value - is treated as a strftime pattern, - so %-escapes can be used to specify time-varying - file names. (Note that if there are - any time-zone-dependent %-escapes, the computation - is done in the zone specified - by .) - Note that the system's strftime is not used - directly, so platform-specific (nonstandard) extensions do not work. - - - If you specify a file name without escapes, you should plan to - use a log rotation utility to avoid eventually filling the - entire disk. In releases prior to 8.4, if - no % escapes were - - present, PostgreSQL would append - - - present, Postgres-XC would append - - - present, Postgres-XL would append - - the epoch of the new log file's creation time, but this is no - longer the case. - - - If CSV-format output is enabled in log_destination, - .csv will be appended to the timestamped - log file name to create the file name for CSV-format output. - (If log_filename ends in .log, the suffix is - replaced instead.) - In the case of the example above, the CSV - file name will be server_log.1093827753.csv. - - - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - - - - log_file_mode (integer) - - log_file_mode configuration parameter - - - - On Unix systems this parameter sets the permissions for log files - when logging_collector is enabled. (On Microsoft - Windows this parameter is ignored.) - The parameter value is expected to be a numeric mode - specified in the format accepted by the - chmod and umask - system calls. (To use the customary octal format the number - must start with a 0 (zero).) - - - The default permissions are 0600, meaning only the - server owner can read or write the log files. The other commonly - useful setting is 0640, allowing members of the owner's - group to read the files. Note however that to make use of such a - setting, you'll need to alter to - store the files somewhere outside the cluster data directory. In - any case, it's unwise to make the log files world-readable, since - they might contain sensitive data. - - - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - - - - log_rotation_age (integer) - - log_rotation_age configuration parameter - - - - When logging_collector is enabled, - this parameter determines the maximum lifetime of an individual log file. - After this many minutes have elapsed, a new log file will - be created. Set to zero to disable time-based creation of - new log files. - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - - - - log_rotation_size (integer) - - log_rotation_size configuration parameter - - - - When logging_collector is enabled, - this parameter determines the maximum size of an individual log file. - After this many kilobytes have been emitted into a log file, - a new log file will be created. Set to zero to disable size-based - creation of new log files. - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - - - - log_truncate_on_rotation (boolean) - - log_truncate_on_rotation configuration parameter - - - - When logging_collector is enabled, - - this parameter will cause PostgreSQL to truncate (overwrite), - - - this parameter will cause Postgres-XC to truncate (overwrite), - - - this parameter will cause Postgres-XL to truncate (overwrite), - - rather than append to, any existing log file of the same name. - However, truncation will occur only when a new file is being opened - due to time-based rotation, not during server startup or size-based - rotation. When off, pre-existing files will be appended to in - all cases. For example, using this setting in combination with - a log_filename like postgresql-%H.log - would result in generating twenty-four hourly log files and then - cyclically overwriting them. - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - Example: To keep 7 days of logs, one log file per day named - server_log.Mon, server_log.Tue, - etc, and automatically overwrite last week's log with this week's log, - set log_filename to server_log.%a, - log_truncate_on_rotation to on, and - log_rotation_age to 1440. - - - Example: To keep 24 hours of logs, one log file per hour, but - also rotate sooner if the log file size exceeds 1GB, set - log_filename to server_log.%H%M, - log_truncate_on_rotation to on, - log_rotation_age to 60, and - log_rotation_size to 1000000. - Including %M in log_filename allows - any size-driven rotations that might occur to select a file name - different from the hour's initial file name. - - - - - - syslog_facility (enum) - - syslog_facility configuration parameter - - - - When logging to syslog is enabled, this parameter - determines the syslog - facility to be used. You can choose - from LOCAL0, LOCAL1, - LOCAL2, LOCAL3, LOCAL4, - LOCAL5, LOCAL6, LOCAL7; - the default is LOCAL0. See also the - documentation of your system's - syslog daemon. - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - - - - syslog_ident (string) - - syslog_identity configuration parameter - - - - When logging to syslog is enabled, this parameter - determines the program name used to identify - - PostgreSQL messages in - - - Postgres-XC messages in - - - Postgres-XL messages in - - syslog logs. The default is - postgres. - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - - - - silent_mode (boolean) - - silent_mode configuration parameter - - - - Runs the server silently. If this parameter is set, the server - will automatically run in background and disassociate from the - controlling terminal. - This parameter can only be set at server start. - - - - - When this parameter is set, - the server's standard output and standard error are redirected - to the file postmaster.log within the data directory. - There is no provision for rotating this file, so it will grow - indefinitely unless server log output is redirected elsewhere - by other settings. It is recommended that log_destination - be set to syslog or that logging_collector be - enabled when using this option. Even with those measures, errors - reported early during startup may appear in - postmaster.log rather than the normal log destination. - - - - - - - - - When To Log - - - - - client_min_messages (enum) - - client_min_messages configuration parameter - - -&common; - - Controls which message levels are sent to the client. - Valid values are DEBUG5, - DEBUG4, DEBUG3, DEBUG2, - DEBUG1, LOG, NOTICE, - WARNING, ERROR, FATAL, - and PANIC. Each level - includes all the levels that follow it. The later the level, - the fewer messages are sent. The default is - NOTICE. Note that LOG has a different - rank here than in log_min_messages. - - - - - - log_min_messages (enum) - - log_min_messages configuration parameter - - - - Controls which message levels are written to the server log. - Valid values are DEBUG5, DEBUG4, - DEBUG3, DEBUG2, DEBUG1, - INFO, NOTICE, WARNING, - ERROR, LOG, FATAL, and - PANIC. Each level includes all the levels that - follow it. The later the level, the fewer messages are sent - to the log. The default is WARNING. Note that - LOG has a different rank here than in - client_min_messages. - Only superusers can change this setting. - - - - - - log_min_error_statement (enum) - - log_min_error_statement configuration parameter - - - - Controls which SQL statements that cause an error - condition are recorded in the server log. The current - SQL statement is included in the log entry for any message of - the specified severity or higher. - Valid values are DEBUG5, - DEBUG4, DEBUG3, - DEBUG2, DEBUG1, - INFO, NOTICE, - WARNING, ERROR, - LOG, - FATAL, and PANIC. - The default is ERROR, which means statements - causing errors, log messages, fatal errors, or panics will be logged. - To effectively turn off logging of failing statements, - set this parameter to PANIC. - Only superusers can change this setting. - - - - - - log_min_duration_statement (integer) - - log_min_duration_statement configuration parameter - - - - Causes the duration of each completed statement to be logged - if the statement ran for at least the specified number of - milliseconds. Setting this to zero prints all statement durations. - Minus-one (the default) disables logging statement durations. - For example, if you set it to 250ms - then all SQL statements that run 250ms or longer will be - logged. Enabling this parameter can be helpful in tracking down - unoptimized queries in your applications. - Only superusers can change this setting. - - - - For clients using extended query protocol, durations of the Parse, - Bind, and Execute steps are logged independently. - - - - - When using this option together with - , - the text of statements that are logged because of - log_statement will not be repeated in the - duration log message. - If you are not using syslog, it is recommended - that you log the PID or session ID using - - so that you can link the statement message to the later - duration message using the process ID or session ID. - - - - - - - - - explains the message - - severity levels used by PostgreSQL. If logging output - - - severity levels used by Postgres-XC. If logging output - - - severity levels used by Postgres-XL. If logging output - - is sent to syslog or Windows' - eventlog, the severity levels are translated - as shown in the table. - - - - Message Severity Levels - - - - Severity - Usage - syslog - eventlog - - - - - - DEBUG1..DEBUG5 - Provides successively-more-detailed information for use by - developers. - DEBUG - INFORMATION - - - - INFO - Provides information implicitly requested by the user, - e.g., output from VACUUM VERBOSE. - INFO - INFORMATION - - - - NOTICE - Provides information that might be helpful to users, e.g., - notice of truncation of long identifiers. - NOTICE - INFORMATION - - - - WARNING - Provides warnings of likely problems, e.g., COMMIT - outside a transaction block. - NOTICE - WARNING - - - - ERROR - Reports an error that caused the current command to - abort. - WARNING - ERROR - - - - LOG - Reports information of interest to administrators, e.g., - checkpoint activity. - INFO - INFORMATION - - - - FATAL - Reports an error that caused the current session to - abort. - ERR - ERROR - - - - PANIC - Reports an error that caused all database sessions to abort. - CRIT - ERROR - - - -
- - - - What To Log - - - - - application_name (string) - - application_name configuration parameter - - -&common; - - The application_name can be any string of less than - NAMEDATALEN characters (64 characters in a standard build). - It is typically set by an application upon connection to the server. - The name will be displayed in the pg_stat_activity view - and included in CSV log entries. It can also be included in regular - log entries via the parameter. - Only printable ASCII characters may be used in the - application_name value. Other characters will be - replaced with question marks (?). - - - - - - debug_print_parse (boolean) - debug_print_rewritten (boolean) - debug_print_plan (boolean) - - debug_print_parse configuration parameter - - - debug_print_rewritten configuration parameter - - - debug_print_plan configuration parameter - - - - These parameters enable various debugging output to be emitted. - When set, they print the resulting parse tree, the query rewriter - output, or the execution plan for each executed query. - These messages are emitted at LOG message level, so by - default they will appear in the server log but will not be sent to the - client. You can change that by adjusting - and/or - . - These parameters are off by default. - - - - - - debug_pretty_print (boolean) - - debug_pretty_print configuration parameter - - - - When set, debug_pretty_print indents the messages - produced by debug_print_parse, - debug_print_rewritten, or - debug_print_plan. This results in more readable - but much longer output than the compact format used when - it is off. It is on by default. - - - - - - log_checkpoints (boolean) - - log_checkpoints configuration parameter - - - - Causes checkpoints and restartpoints to be logged in the server log. - Some statistics are included in the log messages, including the number - of buffers written and the time spent writing them. - This parameter can only be set in the postgresql.conf - file or on the server command line. The default is off. - - - - - - log_connections (boolean) - - log_connections configuration parameter - - - - Causes each attempted connection to the server to be logged, - as well as successful completion of client authentication. - This parameter cannot be changed after session start. - The default is off. - - - - - Some client programs, like psql, attempt - to connect twice while determining if a password is required, so - duplicate connection received messages do not - necessarily indicate a problem. - - - - - - - log_disconnections (boolean) - - log_disconnections configuration parameter - - - - This outputs a line in the server log similar to - log_connections but at session termination, - and includes the duration of the session. This is off by - default. - This parameter cannot be changed after session start. - - - - - - - log_duration (boolean) - - log_duration configuration parameter - - - - Causes the duration of every completed statement to be logged. - The default is off. - Only superusers can change this setting. - - - - For clients using extended query protocol, durations of the Parse, - Bind, and Execute steps are logged independently. - - - - - The difference between setting this option and setting - to zero is that - exceeding log_min_duration_statement forces the text of - the query to be logged, but this option doesn't. Thus, if - log_duration is on and - log_min_duration_statement has a positive value, all - durations are logged but the query text is included only for - statements exceeding the threshold. This behavior can be useful for - gathering statistics in high-load installations. - - - - - - - log_error_verbosity (enum) - - log_error_verbosity configuration parameter - - - - Controls the amount of detail written in the server log for each - message that is logged. Valid values are TERSE, - DEFAULT, and VERBOSE, each adding more - fields to displayed messages. TERSE excludes - the logging of DETAIL, HINT, - QUERY, and CONTEXT error information. - VERBOSE output includes the SQLSTATE error - code (see also ) and the source code file name, function name, - and line number that generated the error. - Only superusers can change this setting. - - - - - - log_hostname (boolean) - - log_hostname configuration parameter - - - - By default, connection log messages only show the IP address of the - connecting host. Turning this parameter on causes logging of the - host name as well. Note that depending on your host name resolution - setup this might impose a non-negligible performance penalty. - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - - - - log_line_prefix (string) - - log_line_prefix configuration parameter - - - - This is a printf-style string that is output at the - beginning of each log line. - % characters begin escape sequences - that are replaced with status information as outlined below. - Unrecognized escapes are ignored. Other - characters are copied straight to the log line. Some escapes are - only recognized by session processes, and are ignored by - background processes such as the main server process. - This parameter can only be set in the postgresql.conf - file or on the server command line. The default is an empty string. - - - - - - Escape - Effect - Session only - - - - - %a - Application name - yes - - - %u - User name - yes - - - %d - Database name - yes - - - %r - Remote host name or IP address, and remote port - yes - - - %h - Remote host name or IP address - yes - - - %p - Process ID - no - - - %t - Time stamp without milliseconds - no - - - %m - Time stamp with milliseconds - no - - - %i - Command tag: type of session's current command - yes - - - %e - SQLSTATE error code - no - - - %c - Session ID: see below - no - - - %l - Number of the log line for each session or process, starting at 1 - no - - - %s - Process start time stamp - no - - - %v - Virtual transaction ID (backendID/localXID) - no - - - %x - Transaction ID (0 if none is assigned) - no - - - %q - Produces no output, but tells non-session - processes to stop at this point in the string; ignored by - session processes - no - - - %% - Literal % - no - - - - - - The %c escape prints a quasi-unique session identifier, - consisting of two 4-byte hexadecimal numbers (without leading zeros) - separated by a dot. The numbers are the process start time and the - process ID, so %c can also be used as a space saving way - of printing those items. For example, to generate the session - identifier from pg_stat_activity, use this query: - -SELECT to_hex(EXTRACT(EPOCH FROM backend_start)::integer) || '.' || - to_hex(procpid) -FROM pg_stat_activity; - - - - - - - If you set a nonempty value for log_line_prefix, - you should usually make its last character be a space, to provide - visual separation from the rest of the log line. A punctuation - character can be used too. - - - - - - Syslog produces its own - time stamp and process ID information, so you probably do not want to - include those escapes if you are logging to syslog. - - - - - - - log_lock_waits (boolean) - - log_lock_waits configuration parameter - - - - Controls whether a log message is produced when a session waits - longer than to acquire a - lock. This is useful in determining if lock waits are causing - poor performance. The default is off. - - - - - - log_statement (enum) - - log_statement configuration parameter - - - - Controls which SQL statements are logged. Valid values are - none (off), ddl, mod, and - all (all statements). ddl logs all data definition - statements, such as CREATE, ALTER, and - DROP statements. mod logs all - ddl statements, plus data-modifying statements - such as INSERT, - UPDATE, DELETE, TRUNCATE, - and COPY FROM. - PREPARE, EXECUTE, and - EXPLAIN ANALYZE statements are also logged if their - contained command is of an appropriate type. For clients using - extended query protocol, logging occurs when an Execute message - is received, and values of the Bind parameters are included - (with any embedded single-quote marks doubled). - - - - The default is none. Only superusers can change this - setting. - - - - - Statements that contain simple syntax errors are not logged - even by the log_statement = all setting, - because the log message is emitted only after basic parsing has - been done to determine the statement type. In the case of extended - query protocol, this setting likewise does not log statements that - fail before the Execute phase (i.e., during parse analysis or - planning). Set log_min_error_statement to - ERROR (or lower) to log such statements. - - - - - - - log_temp_files (integer) - - log_temp_files configuration parameter - - - - Controls logging of temporary file names and sizes. - Temporary files can be - created for sorts, hashes, and temporary query results. - A log entry is made for each temporary file when it is deleted. - A value of zero logs all temporary file information, while positive - values log only files whose size is greater than or equal to - the specified number of kilobytes. The - default setting is -1, which disables such logging. - Only superusers can change this setting. - - - - - - log_timezone (string) - - log_timezone configuration parameter - - - - Sets the time zone used for timestamps written in the server log. - Unlike , this value is cluster-wide, - so that all sessions will report timestamps consistently. - If not explicitly set, the server initializes this variable to the - time zone specified by its system environment. See for more information. - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - - - - - - Using CSV-Format Log Output -&common; - - Including csvlog in the log_destination list - provides a convenient way to import log files into a database table. - This option emits log lines in comma-separated-values - (CSV) format, - with these columns: - time stamp with milliseconds, - user name, - database name, - process ID, - client host:port number, - session ID, - per-session line number, - command tag, - session start time, - virtual transaction ID, - regular transaction ID, - error severity, - SQLSTATE code, - error message, - error message detail, - hint, - internal query that led to the error (if any), - character count of the error position therein, - error context, - user query that led to the error (if any and enabled by - log_min_error_statement), - character count of the error position therein, - - location of the error in the PostgreSQL source code - - - location of the error in the Postgres-XC source code - - - location of the error in the Postgres-XL source code - - (if log_error_verbosity is set to verbose), - and application name. - Here is a sample table definition for storing CSV-format log output: - - -CREATE TABLE postgres_log -( - log_time timestamp(3) with time zone, - user_name text, - database_name text, - process_id integer, - connection_from text, - session_id text, - session_line_num bigint, - command_tag text, - session_start_time timestamp with time zone, - virtual_transaction_id text, - transaction_id bigint, - error_severity text, - sql_state_code text, - message text, - detail text, - hint text, - internal_query text, - internal_query_pos integer, - context text, - query text, - query_pos integer, - location text, - application_name text, - PRIMARY KEY (session_id, session_line_num) -); - - - - - To import a log file into this table, use the COPY FROM - command: - - -COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; - - - - - There are a few things you need to do to simplify importing CSV log - files: - - - - - Set log_filename and - log_rotation_age to provide a consistent, - predictable naming scheme for your log files. This lets you - predict what the file name will be and know when an individual log - file is complete and therefore ready to be imported. - - - - - - Set log_rotation_size to 0 to disable - size-based log rotation, as it makes the log file name difficult - to predict. - - - - - - Set log_truncate_on_rotation to on so - that old log data isn't mixed with the new in the same file. - - - - - - The table definition above includes a primary key specification. - This is useful to protect against accidentally importing the same - information twice. The COPY command commits all of the - data it imports at one time, so any error will cause the entire - import to fail. If you import a partial log file and later import - the file again when it is complete, the primary key violation will - cause the import to fail. Wait until the log is complete and - closed before importing. This procedure will also protect against - accidentally importing a partial line that hasn't been completely - written, which would also cause COPY to fail. - - - - - - - - - - Run-time Statistics - - - Query and Index Statistics Collector -&common; - - These parameters control server-wide statistics collection features. - When statistics collection is enabled, the data that is produced can be - accessed via the pg_stat and - pg_statio family of system views. - Refer to for more information. - - - - - - track_activities (boolean) - - track_activities configuration parameter - - - - Enables the collection of information on the currently - executing command of each session, along with the time when - that command began execution. This parameter is on by - default. Note that even when enabled, this information is not - visible to all users, only to superusers and the user owning - the session being reported on, so it should not represent a - security risk. - Only superusers can change this setting. - - - - - - track_activity_query_size (integer) - - track_activity_query_size configuration parameter - - - - Specifies the number of bytes reserved to track the currently - executing command for each active session, for the - pg_stat_activity.current_query field. - The default value is 1024. This parameter can only be set at server - start. - - - - - - track_counts (boolean) - - track_counts configuration parameter - - - - Enables collection of statistics on database activity. - This parameter is on by default, because the autovacuum - daemon needs the collected information. - Only superusers can change this setting. - - - - - - track_functions (enum) - - track_functions configuration parameter - - - - Enables tracking of function call counts and time used. Specify - pl to track only procedural-language functions, - all to also track SQL and C language functions. - The default is none, which disables function - statistics tracking. Only superusers can change this setting. - - - - - SQL-language functions that are simple enough to be inlined - into the calling query will not be tracked, regardless of this - setting. - - - - - - - update_process_title (boolean) - - update_process_title configuration parameter - - - - Enables updating of the process title every time a new SQL command - is received by the server. The process title is typically viewed - by the ps command, - or in Windows by using the Process Explorer. - Only superusers can change this setting. - - - - - - stats_temp_directory (string) - - stats_temp_directory configuration parameter - - - - Sets the directory to store temporary statistics data in. This can be - a path relative to the data directory or an absolute path. The default - is pg_stat_tmp. Pointing this at a RAM-based - file system will decrease physical I/O requirements and can lead to - improved performance. - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - - - - - - - Statistics Monitoring -&common; - - - - - log_statement_stats (boolean) - log_parser_stats (boolean) - log_planner_stats (boolean) - log_executor_stats (boolean) - - log_statement_stats configuration parameter - - - log_parser_stats configuration parameter - - - log_planner_stats configuration parameter - - - log_executor_stats configuration parameter - - - - - For each query, output performance statistics of the respective - module to the server log. This is a crude profiling - instrument, similar to the Unix getrusage() operating - system facility. log_statement_stats reports total - statement statistics, while the others report per-module statistics. - log_statement_stats cannot be enabled together with - any of the per-module options. All of these options are disabled by - default. Only superusers can change these settings. - - - - - - - - - - - Automatic Vacuuming - - - autovacuum - configuration parameters - -&common; - - These settings control the behavior of the autovacuum - feature. Refer to for - more information. - - - - - - autovacuum (boolean) - - autovacuum configuration parameter - - - - Controls whether the server should run the - autovacuum launcher daemon. This is on by default; however, - must also be enabled for - autovacuum to work. - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - Note that even when this parameter is disabled, the system - will launch autovacuum processes if necessary to - prevent transaction ID wraparound. See for more information. - - - - - - log_autovacuum_min_duration (integer) - - log_autovacuum_min_duration configuration parameter - - - - Causes each action executed by autovacuum to be logged if it ran for at - least the specified number of milliseconds. Setting this to zero logs - all autovacuum actions. Minus-one (the default) disables logging - autovacuum actions. For example, if you set this to - 250ms then all automatic vacuums and analyzes that run - 250ms or longer will be logged. In addition, when this parameter is - set to any value other than -1, a message will be - logged if an autovacuum action is skipped due to the existence of a - conflicting lock. Enabling this parameter can be helpful - in tracking autovacuum activity. This setting can only be set in - the postgresql.conf file or on the server command line. - - - - - - autovacuum_max_workers (integer) - - autovacuum_max_workers configuration parameter - - - - Specifies the maximum number of autovacuum processes (other than the - autovacuum launcher) which may be running at any one time. The default - is three. This parameter can only be set at server start. - - - - - - autovacuum_naptime (integer) - - autovacuum_naptime configuration parameter - - - - Specifies the minimum delay between autovacuum runs on any given - database. In each round the daemon examines the - database and issues VACUUM and ANALYZE commands - as needed for tables in that database. The delay is measured - in seconds, and the default is one minute (1min). - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - - - - autovacuum_vacuum_threshold (integer) - - autovacuum_vacuum_threshold configuration parameter - - - - Specifies the minimum number of updated or deleted tuples needed - to trigger a VACUUM in any one table. - The default is 50 tuples. - This parameter can only be set in the postgresql.conf - file or on the server command line. - This setting can be overridden for individual tables by - changing storage parameters. - - - - - - autovacuum_analyze_threshold (integer) - - autovacuum_analyze_threshold configuration parameter - - - - Specifies the minimum number of inserted, updated or deleted tuples - needed to trigger an ANALYZE in any one table. - The default is 50 tuples. - This parameter can only be set in the postgresql.conf - file or on the server command line. - This setting can be overridden for individual tables by - changing storage parameters. - - - - - - autovacuum_vacuum_scale_factor (floating point) - - autovacuum_vacuum_scale_factor configuration parameter - - - - Specifies a fraction of the table size to add to - autovacuum_vacuum_threshold - when deciding whether to trigger a VACUUM. - The default is 0.2 (20% of table size). - This parameter can only be set in the postgresql.conf - file or on the server command line. - This setting can be overridden for individual tables by - changing storage parameters. - - - - - - autovacuum_analyze_scale_factor (floating point) - - autovacuum_analyze_scale_factor configuration parameter - - - - Specifies a fraction of the table size to add to - autovacuum_analyze_threshold - when deciding whether to trigger an ANALYZE. - The default is 0.1 (10% of table size). - This parameter can only be set in the postgresql.conf - file or on the server command line. - This setting can be overridden for individual tables by - changing storage parameters. - - - - - - autovacuum_freeze_max_age (integer) - - autovacuum_freeze_max_age configuration parameter - - - - Specifies the maximum age (in transactions) that a table's - pg_class.relfrozenxid field can - attain before a VACUUM operation is forced - to prevent transaction ID wraparound within the table. - Note that the system will launch autovacuum processes to - prevent wraparound even when autovacuum is otherwise disabled. - - - - Vacuum also allows removal of old files from the - pg_clog subdirectory, which is why the default - is a relatively low 200 million transactions. - This parameter can only be set at server start, but the setting - can be reduced for individual tables by - changing storage parameters. - For more information see . - - - - - - autovacuum_vacuum_cost_delay (integer) - - autovacuum_vacuum_cost_delay configuration parameter - - - - Specifies the cost delay value that will be used in automatic - VACUUM operations. If -1 is specified, the regular - value will be used. - The default value is 20 milliseconds. - This parameter can only be set in the postgresql.conf - file or on the server command line. - This setting can be overridden for individual tables by - changing storage parameters. - - - - - - autovacuum_vacuum_cost_limit (integer) - - autovacuum_vacuum_cost_limit configuration parameter - - - - Specifies the cost limit value that will be used in automatic - VACUUM operations. If -1 is specified (which is the - default), the regular - value will be used. Note that - the value is distributed proportionally among the running autovacuum - workers, if there is more than one, so that the sum of the limits of - each worker never exceeds the limit on this variable. - This parameter can only be set in the postgresql.conf - file or on the server command line. - This setting can be overridden for individual tables by - changing storage parameters. - - - - - - - - - Client Connection Defaults - - - Statement Behavior - -&common; - - - search_path (string) - - search_path configuration parameter - - pathfor schemas - - - This variable specifies the order in which schemas are searched - when an object (table, data type, function, etc.) is referenced by a - simple name with no schema specified. When there are objects of - identical names in different schemas, the one found first - in the search path is used. An object that is not in any of the - schemas in the search path can only be referenced by specifying - its containing schema with a qualified (dotted) name. - - - - The value for search_path must be a comma-separated - list of schema names. If one of the list items is - the special value $user, then the schema - having the name returned by SESSION_USER is substituted, if there - is such a schema. (If not, $user is ignored.) - - - - The system catalog schema, pg_catalog, is always - searched, whether it is mentioned in the path or not. If it is - mentioned in the path then it will be searched in the specified - order. If pg_catalog is not in the path then it will - be searched before searching any of the path items. - - - - Likewise, the current session's temporary-table schema, - pg_temp_nnn, is always searched if it - exists. It can be explicitly listed in the path by using the - alias pg_temp. If it is not listed in the path then - it is searched first (even before pg_catalog). However, - the temporary schema is only searched for relation (table, view, - sequence, etc) and data type names. It is never searched for - function or operator names. - - - - When objects are created without specifying a particular target - schema, they will be placed in the first schema listed - in the search path. An error is reported if the search path is - empty. - - - - The default value for this parameter is - '"$user", public' (where the second part will be - ignored if there is no schema named public). - This supports shared use of a database (where no users - have private schemas, and all share use of public), - private per-user schemas, and combinations of these. Other - effects can be obtained by altering the default search path - setting, either globally or per-user. - - - - The current effective value of the search path can be examined - via the SQL function - current_schemas(). This is not quite the same as - examining the value of search_path, since - current_schemas() shows how the items - appearing in search_path were resolved. - - - - For more information on schema handling, see . - - - - - - default_tablespace (string) - - default_tablespace configuration parameter - - tablespacedefault - - - This variable specifies the default tablespace in which to create - objects (tables and indexes) when a CREATE command does - not explicitly specify a tablespace. - - - - The value is either the name of a tablespace, or an empty string - to specify using the default tablespace of the current database. - If the value does not match the name of any existing tablespace, - - PostgreSQL will automatically use the default - - - Postgres-XC will automatically use the default - - - Postgres-XL will automatically use the default - - tablespace of the current database. If a nondefault tablespace - is specified, the user must have CREATE privilege - for it, or creation attempts will fail. - - - - This variable is not used for temporary tables; for them, - is consulted instead. - - - - This variable is also not used when creating databases. - By default, a new database inherits its tablespace setting from - the template database it is copied from. - - - - For more information on tablespaces, - see . - - - - - - temp_tablespaces (string) - - temp_tablespaces configuration parameter - - tablespacetemporary - - - This variable specifies tablespaces in which to create temporary - objects (temp tables and indexes on temp tables) when a - CREATE command does not explicitly specify a tablespace. - Temporary files for purposes such as sorting large data sets - are also created in these tablespaces. - - - - The value is a list of names of tablespaces. When there is more than - - one name in the list, PostgreSQL chooses a random - - - one name in the list, Postgres-XC chooses a random - - - one name in the list, Postgres-XL chooses a random - - member of the list each time a temporary object is to be created; - except that within a transaction, successively created temporary - objects are placed in successive tablespaces from the list. - If the selected element of the list is an empty string, - - PostgreSQL will automatically use the default - - - Postgres-XC will automatically use the default - - - Postgres-XL will automatically use the default - - tablespace of the current database instead. - - - - When temp_tablespaces is set interactively, specifying a - nonexistent tablespace is an error, as is specifying a tablespace for - which the user does not have CREATE privilege. However, - when using a previously set value, nonexistent tablespaces are - ignored, as are tablespaces for which the user lacks - CREATE privilege. In particular, this rule applies when - using a value set in postgresql.conf. - - - - The default value is an empty string, which results in all temporary - objects being created in the default tablespace of the current - database. - - - - See also . - - - - - - check_function_bodies (boolean) - - check_function_bodies configuration parameter - - - - This parameter is normally on. When set to off, it - disables validation of the function body string during . Disabling validation is - occasionally useful to avoid problems such as forward references - when restoring function definitions from a dump. - - - - In Postgres-XC setting check_function_bodies - to off is not recommended. If SQL functions are created after setting - check_function_bodies to off, the behaviour of the - function when executed is un-defined. - - - - - - - In Postgres-XL setting check_function_bodies - to off is not recommended. If SQL functions are created after setting - check_function_bodies to off, the behaviour of the - function when executed is un-defined. - - - - - - - - - - - transaction isolation level - setting default - - - default_transaction_isolation configuration parameter - - default_transaction_isolation (enum) - - - Each SQL transaction has an isolation level, which can be - either read uncommitted, read - committed, repeatable read, or - serializable. This parameter controls the - default isolation level of each new transaction. The default - is read committed. - - - - Consult and for more information. - - - - - - - read-only transaction - setting default - - - default_transaction_read_only configuration parameter - - - default_transaction_read_only (boolean) - - - A read-only SQL transaction cannot alter non-temporary tables. - This parameter controls the default read-only status of each new - transaction. The default is off (read/write). - - - - Consult for more information. - - - - - - - deferrable transaction - setting default - - - default_transaction_deferrable configuration parameter - - - default_transaction_deferrable (boolean) - - - When running at the serializable isolation level, - a deferrable read-only SQL transaction may be delayed before - it is allowed to proceed. However, once it begins executing - it does not incur any of the overhead required to ensure - serializability; so serialization code will have no reason to - force it to abort because of concurrent updates, making this - option suitable for long-running read-only transactions. - - - - This parameter controls the default deferrable status of each - new transaction. It currently has no effect on read-write - transactions or those operating at isolation levels lower - than serializable. The default is off. - - - - Consult for more information. - - - - - - - session_replication_role (enum) - - session_replication_role configuration parameter - - - - Controls firing of replication-related triggers and rules for the - current session. Setting this variable requires - superuser privilege and results in discarding any previously cached - query plans. Possible values are origin (the default), - replica and local. - See for - more information. - - - - - - statement_timeout (integer) - - statement_timeout configuration parameter - - - - Abort any statement that takes over the specified number of - milliseconds, starting from the time the command arrives at the server - from the client. If log_min_error_statement is set to - ERROR or lower, the statement that timed out will also be - logged. A value of zero (the default) turns this off. - - - - Setting statement_timeout in - postgresql.conf is not recommended because it - affects all sessions. - - - - - - vacuum_freeze_table_age (integer) - - vacuum_freeze_table_age configuration parameter - - - - VACUUM performs a whole-table scan if the table's - pg_class.relfrozenxid field has reached - the age specified by this setting. The default is 150 million - transactions. Although users can set this value anywhere from zero to - one billion, VACUUM will silently limit the effective value - to 95% of , so that a - periodical manual VACUUM has a chance to run before an - anti-wraparound autovacuum is launched for the table. For more - information see - . - - - - - - vacuum_freeze_min_age (integer) - - vacuum_freeze_min_age configuration parameter - - - - Specifies the cutoff age (in transactions) that VACUUM - should use to decide whether to replace transaction IDs with - FrozenXID while scanning a table. - The default is 50 million transactions. Although - users can set this value anywhere from zero to one billion, - VACUUM will silently limit the effective value to half - the value of , so - that there is not an unreasonably short time between forced - autovacuums. For more information see . - - - - - - bytea_output (enum) - - bytea_output configuration parameter - - - - Sets the output format for values of type bytea. - Valid values are hex (the default) - - and escape (the traditional PostgreSQL - - - and escape (the traditional Postgres-XC - - - and escape (the traditional Postgres-XL - - format). See for more - information. The bytea type always - accepts both formats on input, regardless of this setting. - - - - - - xmlbinary (enum) - - xmlbinary configuration parameter - - - - Sets how binary values are to be encoded in XML. This applies - for example when bytea values are converted to - XML by the functions xmlelement or - xmlforest. Possible values are - base64 and hex, which - are both defined in the XML Schema standard. The default is - base64. For further information about - XML-related functions, see . - - - - The actual choice here is mostly a matter of taste, - constrained only by possible restrictions in client - applications. Both methods support all possible values, - although the hex encoding will be somewhat larger than the - base64 encoding. - - - - - - xmloption (enum) - - xmloption configuration parameter - - - SET XML OPTION - - - XML option - - - - Sets whether DOCUMENT or - CONTENT is implicit when converting between - XML and character string values. See for a description of this. Valid - values are DOCUMENT and - CONTENT. The default is - CONTENT. - - - - According to the SQL standard, the command to set this option is - -SET XML OPTION { DOCUMENT | CONTENT }; - - - This syntax is also available in PostgreSQL. - - - This syntax is also available in Postgres-XC. - - - This syntax is also available in Postgres-XL. - - - - - - - - - Locale and Formatting -&common; - - - - - DateStyle (string) - - DateStyle configuration parameter - - - - Sets the display format for date and time values, as well as the - rules for interpreting ambiguous date input values. For - historical reasons, this variable contains two independent - components: the output format specification (ISO, - Postgres, SQL, or German) - and the input/output specification for year/month/day ordering - (DMY, MDY, or YMD). These - can be set separately or together. The keywords Euro - and European are synonyms for DMY; the - keywords US, NonEuro, and - NonEuropean are synonyms for MDY. See - for more information. The - built-in default is ISO, MDY, but - initdb will initialize the - configuration file with a setting that corresponds to the - behavior of the chosen lc_time locale. - - - - - - IntervalStyle (enum) - - IntervalStyle configuration parameter - - - - Sets the display format for interval values. - The value sql_standard will produce - output matching SQL standard interval literals. - The value postgres (which is the default) will produce - output matching PostgreSQL releases prior to 8.4 - when the - parameter was set to ISO. - The value postgres_verbose will produce output - matching PostgreSQL releases prior to 8.4 - when the DateStyle - parameter was set to non-ISO output. - The value iso_8601 will produce output matching the time - interval format with designators defined in section - 4.4.3.2 of ISO 8601. - - - The IntervalStyle parameter also affects the - interpretation of ambiguous interval input. See - for more information. - - - - - - timezone (string) - - timezone configuration parameter - - time zone - - - Sets the time zone for displaying and interpreting time stamps. - If not explicitly set, the server initializes this variable to the - time zone specified by its system environment. See for more information. - - - - - - timezone_abbreviations (string) - - timezone_abbreviations configuration parameter - - time zone names - - - Sets the collection of time zone abbreviations that will be accepted - by the server for datetime input. The default is 'Default', - which is a collection that works in most of the world; there are - also 'Australia' and 'India', and other collections can be defined - for a particular installation. See for more information. - - - - - - - significant digits - - - floating-point - display - - - extra_float_digits configuration parameter - - - extra_float_digits (integer) - - - This parameter adjusts the number of digits displayed for - floating-point values, including float4, float8, - and geometric data types. The parameter value is added to the - standard number of digits (FLT_DIG or DBL_DIG - as appropriate). The value can be set as high as 3, to include - partially-significant digits; this is especially useful for dumping - float data that needs to be restored exactly. Or it can be set - negative to suppress unwanted digits. - - - - - - client_encoding (string) - - client_encoding configuration parameter - - character set - - - Sets the client-side encoding (character set). - The default is to use the database encoding. - The character sets supported by the PostgreSQL - server are described in . - - - - - - lc_messages (string) - - lc_messages configuration parameter - - - - Sets the language in which messages are displayed. Acceptable - values are system-dependent; see for - more information. If this variable is set to the empty string - (which is the default) then the value is inherited from the - execution environment of the server in a system-dependent way. - - - - On some systems, this locale category does not exist. Setting - this variable will still work, but there will be no effect. - Also, there is a chance that no translated messages for the - desired language exist. In that case you will continue to see - the English messages. - - - - Only superusers can change this setting, because it affects the - messages sent to the server log as well as to the client, and - an improper value might obscure the readability of the server - logs. - - - - - - lc_monetary (string) - - lc_monetary configuration parameter - - - - Sets the locale to use for formatting monetary amounts, for - example with the to_char family of - functions. Acceptable values are system-dependent; see for more information. If this variable is - set to the empty string (which is the default) then the value - is inherited from the execution environment of the server in a - system-dependent way. - - - - - - lc_numeric (string) - - lc_numeric configuration parameter - - - - Sets the locale to use for formatting numbers, for example - with the to_char family of - functions. Acceptable values are system-dependent; see for more information. If this variable is - set to the empty string (which is the default) then the value - is inherited from the execution environment of the server in a - system-dependent way. - - - - - - lc_time (string) - - lc_time configuration parameter - - - - Sets the locale to use for formatting dates and times, for example - with the to_char family of - functions. Acceptable values are system-dependent; see for more information. If this variable is - set to the empty string (which is the default) then the value - is inherited from the execution environment of the server in a - system-dependent way. - - - - - - default_text_search_config (string) - - default_text_search_config configuration parameter - - - - Selects the text search configuration that is used by those variants - of the text search functions that do not have an explicit argument - specifying the configuration. - See for further information. - The built-in default is pg_catalog.simple, but - initdb will initialize the - configuration file with a setting that corresponds to the - chosen lc_ctype locale, if a configuration - matching that locale can be identified. - - - - - - - - - Other Defaults -&common; - - - - - dynamic_library_path (string) - - dynamic_library_path configuration parameter - - dynamic loading - - - If a dynamically loadable module needs to be opened and the - file name specified in the CREATE FUNCTION or - LOAD command - does not have a directory component (i.e., the - name does not contain a slash), the system will search this - path for the required file. - - - - The value for dynamic_library_path must be a - list of absolute directory paths separated by colons (or semi-colons - on Windows). If a list element starts - with the special string $libdir, the - - compiled-in PostgreSQL package - - - compiled-in Postgres-XC package - - - compiled-in Postgres-XL package - - library directory is substituted for $libdir; this - is where the modules provided by the standard - - PostgreSQL distribution are installed. - - - Postgres-XC distribution are installed. - - - Postgres-XL distribution are installed. - - (Use pg_config --pkglibdir to find out the name of - this directory.) For example: - -dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir' - - or, in a Windows environment: - -dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - - - - - The default value for this parameter is - '$libdir'. If the value is set to an empty - string, the automatic path search is turned off. - - - - This parameter can be changed at run time by superusers, but a - setting done that way will only persist until the end of the - client connection, so this method should be reserved for - development purposes. The recommended way to set this parameter - is in the postgresql.conf configuration - file. - - - - - - gin_fuzzy_search_limit (integer) - - gin_fuzzy_search_limit configuration parameter - - - - Soft upper limit of the size of the set returned by GIN index scans. For more - information see . - - - - - - local_preload_libraries (string) - - local_preload_libraries configuration parameter - - - $libdir/plugins - - - - This variable specifies one or more shared libraries that are - to be preloaded at connection start. If more than one library - is to be loaded, separate their names with commas. All library - names are converted to lower case unless double-quoted. - This parameter cannot be changed after the start of a particular - session. - - - - Because this is not a superuser-only option, the libraries - that can be loaded are restricted to those appearing in the - plugins subdirectory of the installation's - standard library directory. (It is the database administrator's - responsibility to ensure that only safe libraries - are installed there.) Entries in local_preload_libraries - can specify this directory explicitly, for example - $libdir/plugins/mylib, or just specify - the library name — mylib would have - the same effect as $libdir/plugins/mylib. - - - - Unlike local_preload_libraries, there is no - performance advantage to loading a library at session - start rather than when it is first used. Rather, the intent of - this feature is to allow debugging or performance-measurement - libraries to be loaded into specific sessions without an explicit - LOAD command being given. For example, debugging could - be enabled for all sessions under a given user name by setting - this parameter with ALTER ROLE SET. - - - - If a specified library is not found, - the connection attempt will fail. - - - - Every PostgreSQL-supported library has a magic - block that is checked to guarantee compatibility. - For this reason, non-PostgreSQL libraries cannot be - loaded in this way. - - - - - - - - - - Lock Management -&common; - - - - - - deadlock - timeout during - - - timeout - deadlock - - - deadlock_timeout configuration parameter - - - deadlock_timeout (integer) - - - This is the amount of time, in milliseconds, to wait on a lock - before checking to see if there is a deadlock condition. The - check for deadlock is relatively expensive, so the server doesn't run - it every time it waits for a lock. We optimistically assume - that deadlocks are not common in production applications and - just wait on the lock for a while before checking for a - deadlock. Increasing this value reduces the amount of time - wasted in needless deadlock checks, but slows down reporting of - real deadlock errors. The default is one second (1s), - which is probably about the smallest value you would want in - practice. On a heavily loaded server you might want to raise it. - Ideally the setting should exceed your typical transaction time, - so as to improve the odds that a lock will be released before - the waiter decides to check for deadlock. - - - - When is set, - this parameter also determines the length of time to wait before - a log message is issued about the lock wait. If you are trying - to investigate locking delays you might want to set a shorter than - normal deadlock_timeout. - - -&xconly; - - Postgres-XC does not detect global deadlocks - where multiple node (Coordinators and/or Datanodes) are - involved. - - - -&xlonly; - - Postgres-XL does not detect global deadlocks - where multiple node (Coordinators and/or Datanodes) are - involved. To get around this it is recommended to set - statement_timeout to cause those statements to - fail in a normal processing environment. If however, it is a reporting - environment, you may want to set this higher globally, or just for - the session temporarily. - - - - - - - max_locks_per_transaction (integer) - - max_locks_per_transaction configuration parameter - - - - The shared lock table tracks locks on - max_locks_per_transaction * ( + ) objects (e.g., tables); - hence, no more than this many distinct objects can be locked at - any one time. This parameter controls the average number of object - locks allocated for each transaction; individual transactions - can lock more objects as long as the locks of all transactions - fit in the lock table. This is not the number of - rows that can be locked; that value is unlimited. The default, - 64, has historically proven sufficient, but you might need to - raise this value if you have clients that touch many different - tables in a single transaction. This parameter can only be set at - server start. - - - - - Increasing this parameter might cause PostgreSQL - - - Increasing this parameter might cause Postgres-XC - - - Increasing this parameter might cause Postgres-XL - - to request more System V shared - memory than your operating system's default configuration - allows. See for information on how to - adjust those parameters, if necessary. - - - - When running a standby server, you must set this parameter to the - same or higher value than on the master server. Otherwise, queries - will not be allowed in the standby server. - - - - - - max_pred_locks_per_transaction (integer) - - max_pred_locks_per_transaction configuration parameter - - - - The shared predicate lock table tracks locks on - max_pred_locks_per_transaction * ( + ) objects (e.g., tables); - hence, no more than this many distinct objects can be locked at - any one time. This parameter controls the average number of object - locks allocated for each transaction; individual transactions - can lock more objects as long as the locks of all transactions - fit in the lock table. This is not the number of - rows that can be locked; that value is unlimited. The default, - 64, has generally been sufficient in testing, but you might need to - raise this value if you have clients that touch many different - tables in a single serializable transaction. This parameter can - only be set at server start. - - - - Increasing this parameter might cause PostgreSQL - to request more System V shared - memory than your operating system's default configuration - allows. See for information on how to - adjust those parameters, if necessary. - - - - - - - - - Version and Platform Compatibility - - - Previous PostgreSQL Versions -&common; - - - - array_nulls (boolean) - - array_nulls configuration parameter - - - - This controls whether the array input parser recognizes - unquoted NULL as specifying a null array element. - By default, this is on, allowing array values containing - null values to be entered. However, PostgreSQL versions - before 8.2 did not support null values in arrays, and therefore would - treat NULL as specifying a normal array element with - the string value NULL. For backward compatibility with - applications that require the old behavior, this variable can be - turned off. - - - - Note that it is possible to create array values containing null values - even when this variable is off. - - - - - - backslash_quote (enum) - stringsbackslash quotes - - backslash_quote configuration parameter - - - - This controls whether a quote mark can be represented by - \' in a string literal. The preferred, SQL-standard way - to represent a quote mark is by doubling it ('') but - - PostgreSQL has historically also accepted - - - Postgres-XC has historically also accepted - - - Postgres-XL has historically also accepted - - \'. However, use of \' creates security risks - because in some client character set encodings, there are multibyte - characters in which the last byte is numerically equivalent to ASCII - \. If client-side code does escaping incorrectly then a - SQL-injection attack is possible. This risk can be prevented by - making the server reject queries in which a quote mark appears to be - escaped by a backslash. - The allowed values of backslash_quote are - on (allow \' always), - off (reject always), and - safe_encoding (allow only if client encoding does not - allow ASCII \ within a multibyte character). - safe_encoding is the default setting. - - - - Note that in a standard-conforming string literal, \ just - means \ anyway. This parameter only affects the handling of - non-standard-conforming literals, including - escape string syntax (E'...'). - - - - - - default_with_oids (boolean) - - default_with_oids configuration parameter - - - - This controls whether CREATE TABLE and - CREATE TABLE AS include an OID column in - newly-created tables, if neither WITH OIDS - nor WITHOUT OIDS is specified. It also - determines whether OIDs will be included in tables created by - SELECT INTO. The parameter is off - by default; in PostgreSQL 8.0 and earlier, it - was on by default. - - - - The use of OIDs in user tables is considered deprecated, so - most installations should leave this variable disabled. - Applications that require OIDs for a particular table should - specify WITH OIDS when creating the - table. This variable can be enabled for compatibility with old - applications that do not follow this behavior. - - - - - - escape_string_warning (boolean) - stringsescape warning - - escape_string_warning configuration parameter - - - - When on, a warning is issued if a backslash (\) - appears in an ordinary string literal ('...' - syntax) and standard_conforming_strings is off. - The default is on. - - - Applications that wish to use backslash as escape should be - modified to use escape string syntax (E'...'), - because the default behavior of ordinary strings is now to treat - backslash as an ordinary character, per SQL standard. This variable - can be enabled to help locate code that needs to be changed. - - - - - - lo_compat_privileges (boolean) - - lo_compat_privileges configuration parameter - - - - In PostgreSQL releases prior to 9.0, large objects - did not have access privileges and were, in effect, readable and - writable by all users. Setting this variable to on - disables the new privilege checks, for compatibility with prior - releases. The default is off. - - - Setting this variable does not disable all security checks related to - large objects — only those for which the default behavior has - changed in PostgreSQL 9.0. - For example, lo_import() and - lo_export() need superuser privileges independent - of this setting. - - - - - - quote_all_identifiers (boolean) - - quote_all_identifiers configuration parameter - - - - When the database generates SQL, force all identifiers to be quoted, - even if they are not (currently) keywords. This will affect the - output of EXPLAIN as well as the results of functions - like pg_get_viewdef. See also the - option of - and . - - - - - - sql_inheritance (boolean) - - sql_inheritance configuration parameter - - inheritance - - - This controls the inheritance semantics. If turned off, - subtables are not accessed by various commands by default; basically - an implied ONLY key word. This was added for - compatibility with releases prior to 7.1. See - for more information. - - - - - - standard_conforming_strings (boolean) - stringsstandard conforming - - standard_conforming_strings configuration parameter - - - - This controls whether ordinary string literals - ('...') treat backslashes literally, as specified in - the SQL standard. - Beginning in PostgreSQL 9.1, the default is - on (prior releases defaulted to off). - Applications can check this - parameter to determine how string literals will be processed. - The presence of this parameter can also be taken as an indication - that the escape string syntax (E'...') is supported. - Escape string syntax () - should be used if an application desires - backslashes to be treated as escape characters. - - - - - - synchronize_seqscans (boolean) - - synchronize_seqscans configuration parameter - - - - This allows sequential scans of large tables to synchronize with each - other, so that concurrent scans read the same block at about the - same time and hence share the I/O workload. When this is enabled, - a scan might start in the middle of the table and then wrap - around the end to cover all rows, so as to synchronize with the - activity of scans already in progress. This can result in - unpredictable changes in the row ordering returned by queries that - have no ORDER BY clause. Setting this parameter to - off ensures the pre-8.3 behavior in which a sequential - scan always starts from the beginning of the table. The default - is on. - - - - - - - - - Platform and Client Compatibility -&common; - - - - transform_null_equals (boolean) - IS NULL - - transform_null_equals configuration parameter - - - - When on, expressions of the form expr = - NULL (or NULL = - expr) are treated as - expr IS NULL, that is, they - return true if expr evaluates to the null value, - and false otherwise. The correct SQL-spec-compliant behavior of - expr = NULL is to always - return null (unknown). Therefore this parameter defaults to - off. - - - - However, filtered forms in Microsoft - Access generate queries that appear to use - expr = NULL to test for - null values, so if you use that interface to access the database you - might want to turn this option on. Since expressions of the - form expr = NULL always - return the null value (using the SQL standard interpretation), they are not - very useful and do not appear often in normal applications so - this option does little harm in practice. But new users are - frequently confused about the semantics of expressions - involving null values, so this option is off by default. - - - - Note that this option only affects the exact form = NULL, - not other comparison operators or other expressions - that are computationally equivalent to some expression - involving the equals operator (such as IN). - Thus, this option is not a general fix for bad programming. - - - - Refer to for related information. - - - - - - - - - - Error Handling - - - - - exit_on_error (boolean) - - exit_on_error configuration parameter - - - - If true, any error will terminate the current session. By default, - this is set to false, so that only FATAL errors will terminate the - session. - - - - - - restart_after_crash (boolean) - - restart_after_crash configuration parameter - - - - When set to true, which is the default, PostgreSQL - will automatically reinitialize after a backend crash. Leaving this - value set to true is normally the best way to maximize the availability - of the database. However, in some circumstances, such as when - PostgreSQL is being invoked by clusterware, it may be - useful to disable the restart so that the clusterware can gain - control and take any actions it deems appropriate. - - - - - - - - - - Preset Options -&common; - - - The following parameters are read-only, and are determined - - when PostgreSQL is compiled or when it is - - - when Postgres-XC is compiled or when it is - - - when Postgres-XL is compiled or when it is - - installed. As such, they have been excluded from the sample - postgresql.conf file. These options report - - various aspects of PostgreSQL behavior - - - various aspects of Postgres-XC behavior - - - various aspects of Postgres-XL behavior - - that might be of interest to certain applications, particularly - administrative front-ends. - - - - - - block_size (integer) - - block_size configuration parameter - - - - Reports the size of a disk block. It is determined by the value - of BLCKSZ when building the server. The default - value is 8192 bytes. The meaning of some configuration - variables (such as ) is - influenced by block_size. See for information. - - - - - - integer_datetimes (boolean) - - integer_datetimes configuration parameter - - - - - Reports whether PostgreSQL was built with - support for 64-bit-integer dates and times. This can be - disabled by configuring with --disable-integer-datetimes - when building PostgreSQL. The default value is - on. - - - Reports whether Postgres-XC was built with - support for 64-bit-integer dates and times. This can be - disabled by configuring with --disable-integer-datetimes - when building Postgres-XC. The default value is - on. - - - Reports whether Postgres-XL was built with - support for 64-bit-integer dates and times. This can be - disabled by configuring with --disable-integer-datetimes - when building Postgres-XL. The default value is - on. - - - - - - - lc_collate (string) - - lc_collate configuration parameter - - - - Reports the locale in which sorting of textual data is done. - See for more information. - This value is determined when a database is created. - - - - - - lc_ctype (string) - - lc_ctype configuration parameter - - - - Reports the locale that determines character classifications. - See for more information. - This value is determined when a database is created. - Ordinarily this will be the same as lc_collate, - but for special applications it might be set differently. - - - - - - max_function_args (integer) - - max_function_args configuration parameter - - - - Reports the maximum number of function arguments. It is determined by - the value of FUNC_MAX_ARGS when building the server. The - default value is 100 arguments. - - - - - - max_identifier_length (integer) - - max_identifier_length configuration parameter - - - - Reports the maximum identifier length. It is determined as one - less than the value of NAMEDATALEN when building - the server. The default value of NAMEDATALEN is - 64; therefore the default - max_identifier_length is 63 bytes, which - can be less than 63 characters when using multibyte encodings. - - - - - - max_index_keys (integer) - - max_index_keys configuration parameter - - - - Reports the maximum number of index keys. It is determined by - the value of INDEX_MAX_KEYS when building the server. The - default value is 32 keys. - - - - - - segment_size (integer) - - segment_size configuration parameter - - - - Reports the number of blocks (pages) that can be stored within a file - segment. It is determined by the value of RELSEG_SIZE - when building the server. The maximum size of a segment file in bytes - is equal to segment_size multiplied by - block_size; by default this is 1GB. - - - - - - server_encoding (string) - - server_encoding configuration parameter - - character set - - - Reports the database encoding (character set). - It is determined when the database is created. Ordinarily, - clients need only be concerned with the value of . - - - - - - server_version (string) - - server_version configuration parameter - - - - Reports the version number of the server. It is determined by the - value of PG_VERSION when building the server. - - - - - - server_version_num (integer) - - server_version_num configuration parameter - - - - Reports the version number of the server as an integer. It is determined - by the value of PG_VERSION_NUM when building the server. - - - - - - wal_block_size (integer) - - wal_block_size configuration parameter - - - - Reports the size of a WAL disk block. It is determined by the value - of XLOG_BLCKSZ when building the server. The default value - is 8192 bytes. - - - - - - wal_segment_size (integer) - - wal_segment_size configuration parameter - - - - Reports the number of blocks (pages) in a WAL segment file. - The total size of a WAL segment file in bytes is equal to - wal_segment_size multiplied by wal_block_size; - by default this is 16MB. See for - more information. - - - - - - - - - Customized Options -&common; - - - This feature was designed to allow parameters not normally known to - - PostgreSQL to be added by add-on modules - - - Postgres-XC to be added by add-on modules - - - Postgres-XL to be added by add-on modules - - (such as procedural languages). This allows add-on modules to be - configured in the standard ways. - - - - - - custom_variable_classes (string) - - custom_variable_classes configuration parameter - - - - This variable specifies one or several class names to be used for - custom variables, in the form of a comma-separated list. A custom - variable is a variable not normally known - - to PostgreSQL proper but used by some - - - to Postgres-XC proper but used by some - - - to Postgres-XL proper but used by some - - add-on module. Such variables must have names consisting of a class - name, a dot, and a variable name. custom_variable_classes - specifies all the class names in use in a particular installation. - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - - - - - - The difficulty with setting custom variables in - postgresql.conf is that the file must be read before add-on - modules have been loaded, and so custom variables would ordinarily be - rejected as unknown. When custom_variable_classes is set, - the server will accept definitions of arbitrary variables within each - specified class. These variables will be treated as placeholders and - will have no function until the module that defines them is loaded. When a - module for a specific class is loaded, it will add the proper variable - definitions for its class name, convert any placeholder - values according to those definitions, and issue warnings for any - unrecognized placeholders of its class that remain. - - - - Here is an example of what postgresql.conf might contain - when using custom variables: - - -custom_variable_classes = 'plpgsql,plperl' -plpgsql.variable_conflict = use_variable -plperl.use_strict = true -plruby.use_strict = true # generates error: unknown class name - - - - - - Developer Options -&common; - - - The following parameters are intended for work on the - - PostgreSQL source code, and in some cases - - - Postgres-XC source code, and in some cases - - - Postgres-XL source code, and in some cases - - to assist with recovery of severely damaged databases. There - should be no reason to use them on a production database. - As such, they have been excluded from the sample - postgresql.conf file. Note that many of these - parameters require special source compilation flags to work at all. - - - - - allow_system_table_mods (boolean) - - allow_system_table_mods configuration parameter - - - - Allows modification of the structure of system tables. - This is used by initdb. - This parameter can only be set at server start. - - - - - - debug_assertions (boolean) - - debug_assertions configuration parameter - - - - Turns on various assertion checks. This is a debugging aid. If - you are experiencing strange problems or crashes you might want - to turn this on, as it might expose programming mistakes. To use - this parameter, the macro USE_ASSERT_CHECKING - - must be defined when PostgreSQL is - - - must be defined when Postgres-XC is - - - must be defined when Postgres-XL is - - built (accomplished by the configure option - ). Note that - debug_assertions defaults to on - - if PostgreSQL has been built with - - - if Postgres-XC has been built with - - - if Postgres-XL has been built with - - assertions enabled. - - - - - - ignore_system_indexes (boolean) - - ignore_system_indexes configuration parameter - - - - Ignore system indexes when reading system tables (but still - update the indexes when modifying the tables). This is useful - when recovering from damaged system indexes. - This parameter cannot be changed after session start. - - - - - - post_auth_delay (integer) - - post_auth_delay configuration parameter - - - - If nonzero, a delay of this many seconds occurs when a new - server process is started, after it conducts the - authentication procedure. This is intended to give developers an - opportunity to attach to the server process with a debugger. - This parameter cannot be changed after session start. - - - - - - pre_auth_delay (integer) - - pre_auth_delay configuration parameter - - - - If nonzero, a delay of this many seconds occurs just after a - new server process is forked, before it conducts the - authentication procedure. This is intended to give developers an - opportunity to attach to the server process with a debugger to - trace down misbehavior in authentication. - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - - - - trace_notify (boolean) - - trace_notify configuration parameter - - - - Generates a great amount of debugging output for the - LISTEN and NOTIFY - commands. or - must be - DEBUG1 or lower to send this output to the - client or server logs, respectively. - - - - - - trace_recovery_messages (enum) - - trace_recovery_messages configuration parameter - - - - Enables logging of recovery-related debugging output that otherwise - would not be logged. This parameter allows the user to override the - normal setting of , but only for - specific messages. This is intended for use in debugging Hot Standby. - Valid values are DEBUG5, DEBUG4, - DEBUG3, DEBUG2, DEBUG1, and - LOG. The default, LOG, does not affect - logging decisions at all. The other values cause recovery-related - debug messages of that priority or higher to be logged as though they - had LOG priority; for common settings of - log_min_messages this results in unconditionally sending - them to the server log. - This parameter can only be set in the postgresql.conf - file or on the server command line. - - - - - - trace_sort (boolean) - - trace_sort configuration parameter - - - - If on, emit information about resource usage during sort operations. - This parameter is only available if the TRACE_SORT macro - - was defined when PostgreSQL was compiled. - - - was defined when Postgres-XC was compiled. - - - was defined when Postgres-XL was compiled. - - (However, TRACE_SORT is currently defined by default.) - - - - - - trace_locks (boolean) - - trace_locks configuration parameter - - - - If on, emit information about lock usage. Information dumped - includes the type of lock operation, the type of lock and the unique - identifier of the object being locked or unlocked. Also included - are bit masks for the lock types already granted on this object as - well as for the lock types awaited on this object. For each lock - type a count of the number of granted locks and waiting locks is - also dumped as well as the totals. An example of the log file output - is shown here: - -LOG: LockAcquire: new: lock(0xb7acd844) id(24688,24696,0,0,0,1) - grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0 - wait(0) type(AccessShareLock) -LOG: GrantLock: lock(0xb7acd844) id(24688,24696,0,0,0,1) - grantMask(2) req(1,0,0,0,0,0,0)=1 grant(1,0,0,0,0,0,0)=1 - wait(0) type(AccessShareLock) -LOG: UnGrantLock: updated: lock(0xb7acd844) id(24688,24696,0,0,0,1) - grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0 - wait(0) type(AccessShareLock) -LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - grantMask(0) req(0,0,0,0,0,0,0)=0 grant(0,0,0,0,0,0,0)=0 - wait(0) type(INVALID) - - Details of the structure being dumped may be found in - src/include/storage/lock.h. - - - This parameter is only available if the LOCK_DEBUG - - macro was defined when PostgreSQL was - - - macro was defined when Postgres-XC was - - - macro was defined when Postgres-XL was - - compiled. - - - - - - trace_lwlocks (boolean) - - trace_lwlocks configuration parameter - - - - If on, emit information about lightweight lock usage. Lightweight - locks are intended primarily to provide mutual exclusion of access - to shared-memory data structures. - - - This parameter is only available if the LOCK_DEBUG - - macro was defined when PostgreSQL was - - - macro was defined when Postgres-XC was - - - macro was defined when Postgres-XL was - - compiled. - - - - - - trace_userlocks (boolean) - - trace_userlocks configuration parameter - - - - If on, emit information about user lock usage. Output is the same - as for trace_locks, only for user locks. - - - User locks were removed as of PostgreSQL version 8.2. This option - currently has no effect. - - - This parameter is only available if the LOCK_DEBUG - - macro was defined when PostgreSQL was - - - macro was defined when Postgres-XC was - - - macro was defined when Postgres-XL was - - compiled. - - - - - - trace_lock_oidmin (integer) - - trace_lock_oidmin configuration parameter - - - - If set, do not trace locks for tables below this OID. (use to avoid - output on system tables) - - - This parameter is only available if the LOCK_DEBUG - - macro was defined when PostgreSQL was - - - macro was defined when Postgres-XC was - - - macro was defined when Postgres-XL was - - compiled. - - - - - - trace_lock_table (integer) - - trace_lock_table configuration parameter - - - - Unconditionally trace locks on this table (OID). - - - This parameter is only available if the LOCK_DEBUG - - macro was defined when PostgreSQL was - - - macro was defined when Postgres-XC was - - - macro was defined when Postgres-XL was - - compiled. - - - - - - debug_deadlocks (boolean) - - debug_deadlocks configuration parameter - - - - If set, dumps information about all current locks when a - deadlock timeout occurs. - - - This parameter is only available if the LOCK_DEBUG - - macro was defined when PostgreSQL was - - - macro was defined when Postgres-XC was - - - macro was defined when Postgres-XL was - - compiled. - - -&xconly; - - Postgres-XC does not detect global deadlocks - where multiple node (Coordinators and/or Datanodes) are - involved. - - - -&xlonly; - - Postgres-XL does not detect global deadlocks - where multiple node (Coordinators and/or Datanodes) are - involved. - - - - - - - log_btree_build_stats (boolean) - - log_btree_build_stats configuration parameter - - - - If set, logs system resource usage statistics (memory and CPU) on - various B-tree operations. - - - This parameter is only available if the BTREE_BUILD_STATS - - macro was defined when PostgreSQL was - - - macro was defined when Postgres-XC was - - - macro was defined when Postgres-XL was - - compiled. - - - - - - wal_debug (boolean) - - wal_debug configuration parameter - - - - If on, emit WAL-related debugging output. This parameter is - only available if the WAL_DEBUG macro was - - defined when PostgreSQL was - - - defined when Postgres-XC was - - - defined when Postgres-XL was - - compiled. - - - - - - zero_damaged_pages (boolean) - - zero_damaged_pages configuration parameter - - - - Detection of a damaged page header normally causes - - PostgreSQL to report an error, aborting the current - - - Postgres-XC to report an error, aborting the current - - - Postgres-XL to report an error, aborting the current - - transaction. Setting zero_damaged_pages to on causes - the system to instead report a warning, zero out the damaged - page in memory, and continue processing. This behavior will destroy data, - namely all the rows on the damaged page. However, it does allow you to get - past the error and retrieve rows from any undamaged pages that might - be present in the table. It is useful for recovering data if - corruption has occurred due to a hardware or software error. You should - generally not set this on until you have given up hope of recovering - data from the damaged pages of a table. Zeroed-out pages are not - forced to disk so it is recommended to recreate the table or - the index before turning this parameter off again. The - default setting is off, and it can only be changed - by a superuser. - - - - - - - Short Options -&common; - - - For convenience there are also single letter command-line option - switches available for some parameters. They are described in - . Some of these - options exist for historical reasons, and their presence as a - single-letter option does not necessarily indicate an endorsement - to use the option heavily. - - - - Short Option Key - - - - Short Option - Equivalent - - - - - - - debug_assertions = x - - - - shared_buffers = x - - - - log_min_messages = DEBUGx - - - - datestyle = euro - - - - , , , - , , - , - - - enable_bitmapscan = off, - enable_hashjoin = off, - enable_indexscan = off, - enable_mergejoin = off, - enable_nestloop = off, - enable_seqscan = off, - enable_tidscan = off - - - - - fsync = off - - - - listen_addresses = x - - - - listen_addresses = '*' - - - - unix_socket_directory = x - - - - ssl = on - - - - max_connections = x - - - - allow_system_table_mods = on - - - - port = x - - - - ignore_system_indexes = on - - - - log_statement_stats = on - - - - work_mem = x - - - , , - log_parser_stats = on, - log_planner_stats = on, - log_executor_stats = on - - - - post_auth_delay = x - - - -
- - - - - - - Postgres-XC Specific Parameters -&xconly; - - Because Postgres-XC distribute data into multiple - Datanodes and multiple Coordinators can accept transactions in - parallel, specific Coordinator must know what Coordinators and - Datanodes to connect. Coordinator and Datanode also must know - where they can request transaction information. The following - describes these additional GUC parameters. - - - - - - max_pool_size (integer) - - max_pool_size configuration parameter - - - - Specify the maximum connection pool of the Coordinator to Datanodes. - Because each transaction can be involved by all the Datanodes, - this parameter should at least be max_connections - multiplied by number of Datanodes. - - - - - - min_pool_size (integer) - - min_pool_size configuration parameter - - - - Minumum number of the connection from the Coordinator to Datanodes. - - - - - - max_coordinators (integer) - - max_coordinators configuration parameter - - - - Maximum number of Coordinators that can be configured in the cluster. - - - - - - max_datanodes (integer) - - max_datanodes configuration parameter - - - - Maximum number of Datanodes that can be configured in the cluster. - - - - - - pgxc_node_name (integer) - - pgxc_node_name configuration parameter - - - - Specifies the node name. A node uses this parameter to identify itself - with pgxc_node - .nodename - - - - - - pooler_port (integer) - - pooler_port configuration parameter - - - - Reports the port number assigned to the connection pooler. - - - - - - gtm_host (string) - - gtm_host configuration parameter - - - - Reports the name or IP address of the GTM. If you use GTM-Proxy, specify the GTM-Proxy's one. - - - - - - gtm_port (integer) - - gtm_port configuration parameter - - - - Reports the port number of GTM. - - - - - - gtm_backup_barrier (string) - - gtm_backup_barrier configuration parameter - - - - Specify if GTM backs up the restart point for each barrier. - Default value is "OFF". - Superuser may set this variable by SET command, or this can be set in the file - postgresql.conf file. - - - - - - - enforce_two_phase_commit (boolean) - - enforce_two_phase_commit configuration parameter - - - - Enforce the usage of two-phase commit instead for transactions involving temporary - objects or ON COMMIT actions. - - - - - - xc_maintenance_mode (bool) - - xc_maintenance_mode configuration parameter - - - - Specify to enter into maintenance mode. Turning this parameter to on will - change behavior of several statements. Each statement - behavior may not be compatible in future releases, so users - must be extremely careful when they attempt to set this - value to on. - - - Behavior of and - statements are affected by - this parameter. - - - If this is set to ON, you can do many other maintenance work to update - Datanode locally through EXECUTE DIRECT or connecting - directly to Datanodes. As a DBA, you are totally responsible to any side - effects. You must be extremely careful not to bring in any inconsistencies - to Postgres-XC database cluster. - - - This parameter can only be set by superuser - with SET command. Otherwise, the setting - will be ignored. - - - As a session parameter, this parameter is shared among all - the connections of the session. It affects originating Coordinator as - well as remote nodes involved in session. - - - - - - - - - - - - Postgres-XL Specific Parameters -&xlonly; - - Because Postgres-XL distributes data into multiple - Datanodes and multiple Coordinators can accept transactions in - parallel, the Coordinators must know what Coordinators and - Datanodes to connect to. The Coordinators and Datanodes also must know - where they can request transaction information. The following - describes these additional GUC parameters. - - - - - - max_pool_size (integer) - - max_pool_size configuration parameter - - - - Specify the maximum connection pool of the Coordinator to Datanodes. - Because each transaction can be involved by all the Datanodes, - this parameter should at least be max_connections - multiplied by number of Datanodes. - - - - - - min_pool_size (integer) - - min_pool_size configuration parameter - - - - Minumum number of the connection from the Coordinator to Datanodes. - - - - - - pool_maintenance_timeout (integer) - - pool_maintenance_timeout configuration parameter - - - - This parameter specifies how long to wait until pooler - maintenance is performed. During such maintenance, - old idle connections are discarded. - This parameter is useful in multi-tenant environments where - many connections to many different databases may be used, - so that idle connections may cleaned up. - - - - - - remote_query_cost (integer) - - remote_query_cost configuration parameter - - - - This parameter specifies the cost overhead of setting up - a remote query to obtain remote data. It is used by - the planner in costing queries. - - - - - - network_byte_cost (integer) - - network_byte_cost configuration parameter - - - - This parameter is used in query cost planning to - estimate the cost involved in row shipping and obtaining - remote data based on the expected data size. - Row shipping is expensive and adds latency, so this - setting helps to favor plans that minimizes row shipping. - - - - - - sequence_range (integer) - - sequence_range configuration parameter - - - - This parameter is used to get several sequence values - at once from GTM. This greatly speeds up COPY and INSERT SELECT - operations where the target table uses sequences. - Postgres-XL will not use this entire - amount at once, but will increase the request size over - time if many requests are done in a short time frame in - the same session. - After a short time without any sequence requests, decreases back down to 1. - Note that any settings here are overriden if the CACHE clause was - used in or . - - - - - - max_coordinators (integer) - - max_coordinators configuration parameter - - - - Maximum number of Coordinators that can be configured in the cluster. - - - - - - max_datanodes (integer) - - max_datanodes configuration parameter - - - - Maximum number of Datanodes that can be configured in the cluster. - - - - - - pgxc_node_name (integer) - - pgxc_node_name configuration parameter - - - - Specifies the node name. A node uses this parameter to identify itself - with pgxc_node - .nodename - - - - - - pooler_port (integer) - - pooler_port configuration parameter - - - - Specifies the port number assigned to the connection pooler process. - This is used in both the Coordinator and Datanode processes to - connect to other nodes. - - - - - - gtm_host (string) - - gtm_host configuration parameter - - - - Specifies the host name or IP address of the GTM. If you use GTM-Proxy, specify the GTM-Proxy's one. - - - - - - gtm_port (integer) - - gtm_port configuration parameter - - - - Specifieis the port number of GTM. - - - - - - xc_maintenance_mode (bool) - - xc_maintenance_mode configuration parameter - - - - Specify to enter into maintenance mode. Turning this parameter to on will - change behavior of several statements. Each statement - behavior may not be compatible in future releases, so users - must be extremely careful when they attempt to set this - value to on. - - - Behavior of and - statements are affected by - this parameter. - - - If this is set to ON, you can do maintenance work to update - Datanode locally through EXECUTE DIRECT or connecting - directly to Datanodes. As a DBA, you are totally responsible to any side - effects. You must be extremely careful not to bring in any inconsistencies - to Postgres-XL database cluster. - - - This parameter can only be set by superuser - with SET command. Otherwise, the setting - will be ignored. - - - As a session parameter, this parameter is shared among all - the connections of the session. It affects originating Coordinator as - well as remote nodes involved in session. - - - - - - shared_queues (integer) - - shared_queues configuration parameter - - - - Datanode Only - - - For some joins that occur in queries, data from one Datanode may - need to be joined with data from another Datanode. - Postgres-XL uses shared queues for this purpose. - During execution each Datanode knows if it needs to produce or consume - tuples, or both. - - - Note that there may be mulitple shared_queues used even for a single - query. So a value should be set taking into account the number of - connections it can accept and expected number of such joins occurring - simultaneously. - - - - - - shared_queue_size (integer) - - shared_queue_size configuration parameter - - - - Datanode Only - - - This parameter sets the size of each each shared queue allocated. - - - - - - - - - diff --git a/doc-xc/src/sgml/contacts.sgmlin b/doc-xc/src/sgml/contacts.sgmlin deleted file mode 100644 index a981625027..0000000000 --- a/doc-xc/src/sgml/contacts.sgmlin +++ /dev/null @@ -1,26 +0,0 @@ - - - -Contacts - - - diff --git a/doc-xc/src/sgml/contrib-spi.sgmlin b/doc-xc/src/sgml/contrib-spi.sgmlin deleted file mode 100644 index 5ef2da84c8..0000000000 --- a/doc-xc/src/sgml/contrib-spi.sgmlin +++ /dev/null @@ -1,237 +0,0 @@ - - - - spi - - - SPI - examples - - -&pgnotice; - - - The spi module provides several workable examples - of using SPI and triggers. While these functions are of some value in - their own right, they are even more useful as examples to modify for - your own purposes. The functions are general enough to be used - with any table, but you have to specify table and field names (as described - below) while creating a trigger. - - - - Each of the groups of functions described below is provided as a - separately-installable extension. - - - - refint — Functions for Implementing Referential Integrity - -&pgnotice; - - check_primary_key() and - check_foreign_key() are used to check foreign key constraints. - (This functionality is long since superseded by the built-in foreign - key mechanism, of course, but the module is still useful as an example.) - - - - check_primary_key() checks the referencing table. - To use, create a BEFORE INSERT OR UPDATE trigger using this - function on a table referencing another table. Specify as the trigger - arguments: the referencing table's column name(s) which form the foreign - key, the referenced table name, and the column names in the referenced table - which form the primary/unique key. To handle multiple foreign - keys, create a trigger for each reference. - - - - check_foreign_key() checks the referenced table. - To use, create a BEFORE DELETE OR UPDATE trigger using this - function on a table referenced by other table(s). Specify as the trigger - arguments: the number of referencing tables for which the function has to - perform checking, the action if a referencing key is found - (cascade — to delete the referencing row, - restrict — to abort transaction if referencing keys - exist, setnull — to set referencing key fields to null), - the triggered table's column names which form the primary/unique key, then - the referencing table name and column names (repeated for as many - referencing tables as were specified by first argument). Note that the - primary/unique key columns should be marked NOT NULL and should have a - unique index. - - - - There are examples in refint.example. - - - - - timetravel — Functions for Implementing Time Travel - -&pgnotice; - - Long ago, PostgreSQL had a built-in time travel feature - that kept the insert and delete times for each tuple. This can be - emulated using these functions. To use these functions, - you must add to a table two columns of abstime type to store - the date when a tuple was inserted (start_date) and changed/deleted - (stop_date): - - -CREATE TABLE mytab ( - ... ... - start_date abstime, - stop_date abstime - ... ... -); - - - The columns can be named whatever you like, but in this discussion - we'll call them start_date and stop_date. - - - - When a new row is inserted, start_date should normally be set to - current time, and stop_date to infinity. The trigger - will automatically substitute these values if the inserted data - contains nulls in these columns. Generally, inserting explicit - non-null data in these columns should only be done when re-loading - dumped data. - - - - Tuples with stop_date equal to infinity are valid - now, and can be modified. Tuples with a finite stop_date cannot - be modified anymore — the trigger will prevent it. (If you need - to do that, you can turn off time travel as shown below.) - - - - For a modifiable row, on update only the stop_date in the tuple being - updated will be changed (to current time) and a new tuple with the modified - data will be inserted. Start_date in this new tuple will be set to current - time and stop_date to infinity. - - - - A delete does not actually remove the tuple but only sets its stop_date - to current time. - - - - To query for tuples valid now, include - stop_date = 'infinity' in the query's WHERE condition. - (You might wish to incorporate that in a view.) Similarly, you can - query for tuples valid at any past time with suitable conditions on - start_date and stop_date. - - - - timetravel() is the general trigger function that supports - this behavior. Create a BEFORE INSERT OR UPDATE OR DELETE - trigger using this function on each time-traveled table. Specify two - trigger arguments: the actual - names of the start_date and stop_date columns. - Optionally, you can specify one to three more arguments, which must refer - to columns of type text. The trigger will store the name of - the current user into the first of these columns during INSERT, the - second column during UPDATE, and the third during DELETE. - - - - set_timetravel() allows you to turn time-travel on or off for - a table. - set_timetravel('mytab', 1) will turn TT ON for table mytab. - set_timetravel('mytab', 0) will turn TT OFF for table mytab. - In both cases the old status is reported. While TT is off, you can modify - the start_date and stop_date columns freely. Note that the on/off status - is local to the current database session — fresh sessions will - always start out with TT ON for all tables. - - - - get_timetravel() returns the TT state for a table without - changing it. - - - - There is an example in timetravel.example. - - - - - autoinc — Functions for Autoincrementing Fields - -&pgnotice; - - autoinc() is a trigger that stores the next value of - a sequence into an integer field. This has some overlap with the - built-in serial column feature, but it is not the same: - autoinc() will override attempts to substitute a - different field value during inserts, and optionally it can be - used to increment the field during updates, too. - - - - To use, create a BEFORE INSERT (or optionally BEFORE - INSERT OR UPDATE) trigger using this function. Specify two - trigger arguments: the name of the integer column to be modified, - and the name of the sequence object that will supply values. - (Actually, you can specify any number of pairs of such names, if - you'd like to update more than one autoincrementing column.) - - - - There is an example in autoinc.example. - - - - - - insert_username — Functions for Tracking Who Changed a Table - -&pgnotice; - - insert_username() is a trigger that stores the current - user's name into a text field. This can be useful for tracking - who last modified a particular row within a table. - - - - To use, create a BEFORE INSERT and/or UPDATE - trigger using this function. Specify a single trigger - argument: the name of the text column to be modified. - - - - There is an example in insert_username.example. - - - - - - moddatetime — Functions for Tracking Last Modification Time - -&pgnotice; - - moddatetime() is a trigger that stores the current - time into a timestamp field. This can be useful for tracking - the last modification time of a particular row within a table. - - - - To use, create a BEFORE UPDATE - trigger using this function. Specify a single trigger - argument: the name of the column to be modified. - The column must be of type timestamp or timestamp with - time zone. - - - - There is an example in moddatetime.example. - - - - - diff --git a/doc-xc/src/sgml/contrib.sgmlin b/doc-xc/src/sgml/contrib.sgmlin deleted file mode 100644 index d53edfeb4d..0000000000 --- a/doc-xc/src/sgml/contrib.sgmlin +++ /dev/null @@ -1,152 +0,0 @@ - - - - Additional Supplied Modules - -&pgnotice; - - - This appendix contains information regarding the modules that - can be found in the contrib directory of the - PostgreSQL distribution. - These include porting tools, analysis utilities, - and plug-in features that are not part of the core PostgreSQL system, - mainly because they address a limited audience or are too experimental - to be part of the main source tree. This does not preclude their - usefulness. - - - - When building from the source distribution, these modules are not built - automatically, unless you build the "world" target - (see ). - You can build and install all of them by running: - -gmake -gmake install - - in the contrib directory of a configured source tree; - or to build and install - just one selected module, do the same in that module's subdirectory. - Many of the modules have regression tests, which can be executed by - running: - -gmake installcheck - - once you have a PostgreSQL server running. (Note that - gmake check is not supported; you must have an operational - database server to perform these tests, and you must have built and - installed the module(s) to be tested.) - - - - If you are using a pre-packaged version of PostgreSQL, - these modules are typically made available as a separate subpackage, - such as postgresql-contrib. - - - - Many modules supply new user-defined functions, operators, or types. - To make use of one of these modules, after you have installed the code - you need to register the new SQL objects in the database system. - In PostgreSQL 9.1 and later, this is done by executing - a command. In a fresh database, - you can simply do - - -CREATE EXTENSION module_name; - - - This command must be run by a database superuser. This registers the - new SQL objects in the current database only, so you need to run this - command in each database that you want - the module's facilities to be available in. Alternatively, run it in - database template1 so that the extension will be copied into - subsequently-created databases by default. - - - - Many modules allow you to install their objects in a schema of your - choice. To do that, add SCHEMA - schema_name to the CREATE EXTENSION - command. By default, the objects will be placed in your current creation - target schema, typically public. - - - - If your database was brought forward by dump and reload from a pre-9.1 - version of PostgreSQL, and you had been using the pre-9.1 - version of the module in it, you should instead do - - -CREATE EXTENSION module_name FROM unpackaged; - - - This will update the pre-9.1 objects of the module into a proper - extension object. Future updates to the module will be - managed by . - For more information about extension updates, see - . - - - &adminpack; - &auth-delay; - &auto-explain; - &btree-gin; - &btree-gist; - &chkpass; - &citext; - &cube; - &dblink; - &dict-int; - &dict-xsyn; - &dummy-seclabel; - &earthdistance; - &file-fdw; - &fuzzystrmatch; - &hstore; - &intagg; - &intarray; - &isn; - &lo; - <ree; - &oid2name; - &pageinspect; - &passwordcheck; - &pgarchivecleanup; - &pgbench; - &pgbuffercache; - &pgcrypto; - &pgfreespacemap; - &pgrowlocks; - &pgstandby; - &pgstatstatements; - &pgstattuple; - &pgtestfsync; - &pgtrgm; - &pgupgrade; - - &pgxcclean; - &pgxcctl; - &pgxcddl; - &pgxcmonitor; - - - &pgxcclean; - &pgxcctl; - &pgxcddl; - &pgxcmonitor; - - &seg; - &sepgsql; - &contrib-spi; - &sslinfo; - &tablefunc; - &test-parser; - &tsearch2; - &unaccent; - &uuid-ossp; - &vacuumlo; - &xml2; - - diff --git a/doc-xc/src/sgml/cube.sgmlin b/doc-xc/src/sgml/cube.sgmlin deleted file mode 100644 index 1508c6da1f..0000000000 --- a/doc-xc/src/sgml/cube.sgmlin +++ /dev/null @@ -1,432 +0,0 @@ - - - - cube - - - cube - - -&common; - - - This module implements a data type cube for - representing multidimensional cubes. - - - - Syntax - -&common; - - - shows the valid external - representations for the cube - type. x, y, etc. denote - floating-point numbers. - - - - Cube External Representations - - - - x - A one-dimensional point - (or, zero-length one-dimensional interval) - - - - (x) - Same as above - - - x1,x2,...,xn - A point in n-dimensional space, represented internally as a - zero-volume cube - - - - (x1,x2,...,xn) - Same as above - - - (x),(y) - A one-dimensional interval starting at x and ending at y or vice versa; the - order does not matter - - - - [(x),(y)] - Same as above - - - (x1,...,xn),(y1,...,yn) - An n-dimensional cube represented by a pair of its diagonally - opposite corners - - - - [(x1,...,xn),(y1,...,yn)] - Same as above - - - -
- - - It does not matter which order the opposite corners of a cube are - entered in. The cube functions - automatically swap values if needed to create a uniform - lower left — upper right internal representation. - - - - White space is ignored, so [(x),(y)] is the same as - [ ( x ), ( y ) ]. - - - - - Precision - -&common; - - - Values are stored internally as 64-bit floating point numbers. This means - that numbers with more than about 16 significant digits will be truncated. - - - - - Usage - -&common; - - - The cube module includes a GiST index operator class for - cube values. - The operators supported by the GiST operator class are shown in . - - - - Cube GiST Operators - - - - Operator - Description - - - - - - a = b - The cubes a and b are identical. - - - - a && b - The cubes a and b overlap. - - - - a @> b - The cube a contains the cube b. - - - - a <@ b - The cube a is contained in the cube b. - - - -
- - - (Before PostgreSQL 8.2, the containment operators @> and <@ were - respectively called @ and ~. These names are still available, but are - deprecated and will eventually be retired. Notice that the old names - are reversed from the convention formerly followed by the core geometric - data types!) - - - - The standard B-tree operators are also provided, for example - - - - - - Operator - Description - - - - - - [a, b] < [c, d] - Less than - - - - [a, b] > [c, d] - Greater than - - - - - - These operators do not make a lot of sense for any practical - purpose but sorting. These operators first compare (a) to (c), - and if these are equal, compare (b) to (d). That results in - reasonably good sorting in most cases, which is useful if - you want to use ORDER BY with this type. - - - - shows the available functions. - - - - Cube Functions - - - - cube(float8) returns cube - Makes a one dimensional cube with both coordinates the same. - cube(1) == '(1)' - - - - - cube(float8, float8) returns cube - Makes a one dimensional cube. - cube(1,2) == '(1),(2)' - - - - - cube(float8[]) returns cube - Makes a zero-volume cube using the coordinates - defined by the array. - cube(ARRAY[1,2]) == '(1,2)' - - - - - cube(float8[], float8[]) returns cube - Makes a cube with upper right and lower left - coordinates as defined by the two arrays, which must be of the - same length. - cube('{1,2}'::float[], '{3,4}'::float[]) == '(1,2),(3,4)' - - - - - - cube(cube, float8) returns cube - Makes a new cube by adding a dimension on to an - existing cube with the same values for both parts of the new coordinate. - This is useful for building cubes piece by piece from calculated values. - cube('(1)',2) == '(1,2),(1,2)' - - - - - cube(cube, float8, float8) returns cube - Makes a new cube by adding a dimension on to an - existing cube. This is useful for building cubes piece by piece from - calculated values. cube('(1,2)',3,4) == '(1,3),(2,4)' - - - - - cube_dim(cube) returns int - Returns the number of dimensions of the cube - - - - - cube_ll_coord(cube, int) returns double - Returns the n'th coordinate value for the lower left - corner of a cube - - - - - cube_ur_coord(cube, int) returns double - - Returns the n'th coordinate value for the - upper right corner of a cube - - - - - cube_is_point(cube) returns bool - Returns true if a cube is a point, that is, - the two defining corners are the same. - - - - cube_distance(cube, cube) returns double - Returns the distance between two cubes. If both - cubes are points, this is the normal distance function. - - - - - cube_subset(cube, int[]) returns cube - - Makes a new cube from an existing cube, using a list of - dimension indexes from an array. Can be used to find both the LL and UR - coordinates of a single dimension, e.g. - cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[2]) = '(3),(7)'. - Or can be used to drop dimensions, or reorder them as desired, e.g. - cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[3,2,1,1]) = '(5, 3, - 1, 1),(8, 7, 6, 6)'. - - - - - cube_union(cube, cube) returns cube - Produces the union of two cubes - - - - - cube_inter(cube, cube) returns cube - Produces the intersection of two cubes - - - - - cube_enlarge(cube c, double r, int n) returns cube - Increases the size of a cube by a specified radius in at least - n dimensions. If the radius is negative the cube is shrunk instead. This - is useful for creating bounding boxes around a point for searching for - nearby points. All defined dimensions are changed by the radius r. - LL coordinates are decreased by r and UR coordinates are increased by r. - If a LL coordinate is increased to larger than the corresponding UR - coordinate (this can only happen when r < 0) than both coordinates - are set to their average. If n is greater than the number of defined - dimensions and the cube is being increased (r >= 0) then 0 is used - as the base for the extra coordinates. - - - - -
- - - - Defaults - -&common; - - - I believe this union: - - -select cube_union('(0,5,2),(2,3,1)', '0'); -cube_union -------------------- -(0, 0, 0),(2, 5, 2) -(1 row) - - - - does not contradict common sense, neither does the intersection - - - -select cube_inter('(0,-1),(1,1)', '(-2),(2)'); -cube_inter -------------- -(0, 0),(1, 0) -(1 row) - - - - In all binary operations on differently-dimensioned cubes, I assume the - lower-dimensional one to be a Cartesian projection, i. e., having zeroes - in place of coordinates omitted in the string representation. The above - examples are equivalent to: - - - -cube_union('(0,5,2),(2,3,1)','(0,0,0),(0,0,0)'); -cube_inter('(0,-1),(1,1)','(-2,0),(2,0)'); - - - - The following containment predicate uses the point syntax, - while in fact the second argument is internally represented by a box. - This syntax makes it unnecessary to define a separate point type - and functions for (box,point) predicates. - - - -select cube_contains('(0,0),(1,1)', '0.5,0.5'); -cube_contains --------------- -t -(1 row) - - - - - Notes - -&common; - - - For examples of usage, see the regression test sql/cube.sql. - - - - To make it harder for people to break things, there - is a limit of 100 on the number of dimensions of cubes. This is set - in cubedata.h if you need something bigger. - - - - - Credits - - - Original author: Gene Selkov, Jr. selkovjr@mcs.anl.gov, - Mathematics and Computer Science Division, Argonne National Laboratory. - - - - My thanks are primarily to Prof. Joe Hellerstein - () for elucidating the - gist of the GiST (), and - to his former student, Andy Dong (), for his example - written for Illustra, - . - I am also grateful to all Postgres developers, present and past, for - enabling myself to create my own world and live undisturbed in it. And I - would like to acknowledge my gratitude to Argonne Lab and to the - U.S. Department of Energy for the years of faithful support of my database - research. - - - - Minor updates to this package were made by Bruno Wolff III - bruno@wolff.to in August/September of 2002. These include - changing the precision from single precision to double precision and adding - some new functions. - - - - Additional updates were made by Joshua Reich josh@root.net in - July 2006. These include cube(float8[], float8[]) and - cleaning up the code to use the V1 call protocol instead of the deprecated - V0 protocol. - - - - diff --git a/doc-xc/src/sgml/datatype.sgmlin b/doc-xc/src/sgml/datatype.sgmlin deleted file mode 100644 index 0e7ad9606e..0000000000 --- a/doc-xc/src/sgml/datatype.sgmlin +++ /dev/null @@ -1,5067 +0,0 @@ - - - - Data Types - - - data type - - - - type - data type - - -&common; - - - PostgreSQL has a rich set of native data - types available to users. Users can add new types to - PostgreSQL using the command. - - - Postgres-XC has inherits from PostgreSQL a rich set of native data - types available to users. Users can add new types to - Postgres-XC using the command. - - - Postgres-XL inherits from a rich set of native data - types available to users. Users can add new types to - Postgres-XL using the command. - - - - - shows all the built-in general-purpose data - types. Most of the alternative names listed in the - Aliases column are the names used internally by - - PostgreSQL for historical reasons. In - - - Postgres-XC for historical reasons. In - - - Postgres-XL for historical reasons. In - - addition, some internally used or deprecated types are available, - but are not listed here. - - - - Data Types - - - - Name - Aliases - Description - - - - - - bigint - int8 - signed eight-byte integer - - - - bigserial - serial8 - autoincrementing eight-byte integer - - - - bit [ (n) ] - - fixed-length bit string - - - - bit varying [ (n) ] - varbit - variable-length bit string - - - - boolean - bool - logical Boolean (true/false) - - - - box - - rectangular box on a plane - - - - bytea - - binary data (byte array) - - - - character varying [ (n) ] - varchar [ (n) ] - variable-length character string - - - - character [ (n) ] - char [ (n) ] - fixed-length character string - - - - cidr - - IPv4 or IPv6 network address - - - - circle - - circle on a plane - - - - date - - calendar date (year, month, day) - - - - double precision - float8 - double precision floating-point number (8 bytes) - - - - inet - - IPv4 or IPv6 host address - - - - integer - int, int4 - signed four-byte integer - - - - interval [ fields ] [ (p) ] - - time span - - - - line - - infinite line on a plane - - - - lseg - - line segment on a plane - - - - macaddr - - MAC (Media Access Control) address - - - - money - - currency amount - - - - numeric [ (p, - s) ] - decimal [ (p, - s) ] - exact numeric of selectable precision - - - - path - - geometric path on a plane - - - - point - - geometric point on a plane - - - - polygon - - closed geometric path on a plane - - - - real - float4 - single precision floating-point number (4 bytes) - - - - smallint - int2 - signed two-byte integer - - - - serial - serial4 - autoincrementing four-byte integer - - - - text - - variable-length character string - - - - time [ (p) ] [ without time zone ] - - time of day (no time zone) - - - - time [ (p) ] with time zone - timetz - time of day, including time zone - - - - timestamp [ (p) ] [ without time zone ] - - date and time (no time zone) - - - - timestamp [ (p) ] with time zone - timestamptz - date and time, including time zone - - - - tsquery - - text search query - - - - tsvector - - text search document - - - - txid_snapshot - - user-level transaction ID snapshot - - - - uuid - - universally unique identifier - - - - xml - - XML data - - - -
- - - Compatibility - - The following types (or spellings thereof) are specified by - SQL: bigint, bit, bit - varying, boolean, char, - character varying, character, - varchar, date, double - precision, integer, interval, - numeric, decimal, real, - smallint, time (with or without time zone), - timestamp (with or without time zone), - xml. - - - - - Each data type has an external representation determined by its input - and output functions. Many of the built-in types have - obvious external formats. However, several types are either unique - - to PostgreSQL, such as geometric - - - to Postgres-XC, such as geometric - - - to Postgres-XL, such as geometric - - paths, or have several possible formats, such as the date - and time types. - Some of the input and output functions are not invertible, i.e., - the result of an output function might lose accuracy when compared to - the original input. - - - - Numeric Types - - - data type - numeric - -&common; - - Numeric types consist of two-, four-, and eight-byte integers, - four- and eight-byte floating-point numbers, and selectable-precision - decimals. lists the - available types. - - - - Numeric Types - - - - Name - Storage Size - Description - Range - - - - - - smallint - 2 bytes - small-range integer - -32768 to +32767 - - - integer - 4 bytes - typical choice for integer - -2147483648 to +2147483647 - - - bigint - 8 bytes - large-range integer - -9223372036854775808 to 9223372036854775807 - - - - decimal - variable - user-specified precision, exact - up to 131072 digits before the decimal point; up to 16383 digits after the decimal point - - - numeric - variable - user-specified precision, exact - up to 131072 digits before the decimal point; up to 16383 digits after the decimal point - - - - real - 4 bytes - variable-precision, inexact - 6 decimal digits precision - - - double precision - 8 bytes - variable-precision, inexact - 15 decimal digits precision - - - - serial - 4 bytes - autoincrementing integer - 1 to 2147483647 - - - - bigserial - 8 bytes - large autoincrementing integer - 1 to 9223372036854775807 - - - -
- - - The syntax of constants for the numeric types is described in - . The numeric types have a - full set of corresponding arithmetic operators and - functions. Refer to for more - information. The following sections describe the types in detail. - - - - Integer Types - - - integer - - - - smallint - - - - bigint - - - - int4 - integer - - - - int2 - smallint - - - - int8 - bigint - -&common; - - The types smallint, integer, and - bigint store whole numbers, that is, numbers without - fractional components, of various ranges. Attempts to store - values outside of the allowed range will result in an error. - - - - The type integer is the common choice, as it offers - the best balance between range, storage size, and performance. - The smallint type is generally only used if disk - space is at a premium. The bigint type should only - be used if the range of the integer type is insufficient, - because the latter is definitely faster. - - - - On very minimal operating systems the bigint type - might not function correctly, because it relies on compiler support - for eight-byte integers. On such machines, bigint - acts the same as integer, but still takes up eight - bytes of storage. (We are not aware of any modern - platform where this is the case.) - - - - SQL only specifies the integer types - integer (or int), - smallint, and bigint. The - type names int2, int4, and - int8 are extensions, which are also used by some - other SQL database systems. - - - - - - Arbitrary Precision Numbers - - - numeric (data type) - - - - arbitrary precision numbers - - - - decimal - numeric - -&common; - - The type numeric can store numbers with a - very large number of digits and perform calculations exactly. It is - especially recommended for storing monetary amounts and other - quantities where exactness is required. However, arithmetic on - numeric values is very slow compared to the integer - types, or to the floating-point types described in the next section. - - - - We use the following terms below: The - scale of a numeric is the - count of decimal digits in the fractional part, to the right of - the decimal point. The precision of a - numeric is the total count of significant digits in - the whole number, that is, the number of digits to both sides of - the decimal point. So the number 23.5141 has a precision of 6 - and a scale of 4. Integers can be considered to have a scale of - zero. - - - - Both the maximum precision and the maximum scale of a - numeric column can be - configured. To declare a column of type numeric use - the syntax: - -NUMERIC(precision, scale) - - The precision must be positive, the scale zero or positive. - Alternatively: - -NUMERIC(precision) - - selects a scale of 0. Specifying: - -NUMERIC - - without any precision or scale creates a column in which numeric - values of any precision and scale can be stored, up to the - implementation limit on precision. A column of this kind will - not coerce input values to any particular scale, whereas - numeric columns with a declared scale will coerce - input values to that scale. (The SQL standard - requires a default scale of 0, i.e., coercion to integer - precision. We find this a bit useless. If you're concerned - about portability, always specify the precision and scale - explicitly.) - - - - - The maximum allowed precision when explicitly specified in the - type declaration is 1000; NUMERIC without a specified - precision is subject to the limits described in . - - - - - If the scale of a value to be stored is greater than the declared - scale of the column, the system will round the value to the specified - number of fractional digits. Then, if the number of digits to the - left of the decimal point exceeds the declared precision minus the - declared scale, an error is raised. - - - - Numeric values are physically stored without any extra leading or - trailing zeroes. Thus, the declared precision and scale of a column - are maximums, not fixed allocations. (In this sense the numeric - type is more akin to varchar(n) - than to char(n).) The actual storage - requirement is two bytes for each group of four decimal digits, - plus five to eight bytes overhead. - - - - NaN - not a number - - - - not a number - numeric (data type) - - - - In addition to ordinary numeric values, the numeric - type allows the special value NaN, meaning - not-a-number. Any operation on NaN - yields another NaN. When writing this value - as a constant in an SQL command, you must put quotes around it, - for example UPDATE table SET x = 'NaN'. On input, - the string NaN is recognized in a case-insensitive manner. - - - - - In most implementations of the not-a-number concept, - NaN is not considered equal to any other numeric - value (including NaN). In order to allow - numeric values to be sorted and used in tree-based - - indexes, PostgreSQL treats NaN - - - indexes, Postgres-XC treats NaN - - - indexes, Postgres-XL treats NaN - - values as equal, and greater than all non-NaN - values. - - - - - The types decimal and numeric are - equivalent. Both types are part of the SQL - standard. - - - - - - Floating-Point Types - - - real - - - - double precision - - - - float4 - real - - - - float8 - double precision - - - - floating point - -&common; - - The data types real and double - precision are inexact, variable-precision numeric types. - In practice, these types are usually implementations of - IEEE Standard 754 for Binary Floating-Point - Arithmetic (single and double precision, respectively), to the - extent that the underlying processor, operating system, and - compiler support it. - - - - Inexact means that some values cannot be converted exactly to the - internal format and are stored as approximations, so that storing - and retrieving a value might show slight discrepancies. - Managing these errors and how they propagate through calculations - is the subject of an entire branch of mathematics and computer - science and will not be discussed here, except for the - following points: - - - - If you require exact storage and calculations (such as for - monetary amounts), use the numeric type instead. - - - - - - If you want to do complicated calculations with these types - for anything important, especially if you rely on certain - behavior in boundary cases (infinity, underflow), you should - evaluate the implementation carefully. - - - - - - Comparing two floating-point values for equality might not - always work as expected. - - - - - - - On most platforms, the real type has a range of at least - 1E-37 to 1E+37 with a precision of at least 6 decimal digits. The - double precision type typically has a range of around - 1E-307 to 1E+308 with a precision of at least 15 digits. Values that - are too large or too small will cause an error. Rounding might - take place if the precision of an input number is too high. - Numbers too close to zero that are not representable as distinct - from zero will cause an underflow error. - - - - not a number - double precision - - - - In addition to ordinary numeric values, the floating-point types - have several special values: - -Infinity --Infinity -NaN - - These represent the IEEE 754 special values - infinity, negative infinity, and - not-a-number, respectively. (On a machine whose - floating-point arithmetic does not follow IEEE 754, these values - will probably not work as expected.) When writing these values - as constants in an SQL command, you must put quotes around them, - for example UPDATE table SET x = 'Infinity'. On input, - these strings are recognized in a case-insensitive manner. - - - - - IEEE754 specifies that NaN should not compare equal - to any other floating-point value (including NaN). - In order to allow floating-point values to be sorted and used - - in tree-based indexes, PostgreSQL treats - - - in tree-based indexes, Postgres-XC treats - - - in tree-based indexes, Postgres-XL treats - - NaN values as equal, and greater than all - non-NaN values. - - - - - - PostgreSQL also supports the SQL-standard - - - Postgres-XC also supports the SQL-standard - - - Postgres-XL also supports the SQL-standard - - notations float and - float(p) for specifying - inexact numeric types. Here, p specifies - the minimum acceptable precision in binary digits. - - PostgreSQL accepts - - - Postgres-XC accepts - - - Postgres-XL accepts - - float(1) to float(24) as selecting the - real type, while - float(25) to float(53) select - double precision. Values of p - outside the allowed range draw an error. - float with no precision specified is taken to mean - double precision. - - - - - Prior to PostgreSQL 7.4, the precision in - float(p) was taken to mean - so many decimal digits. This has been corrected to match the SQL - standard, which specifies that the precision is measured in binary - digits. The assumption that real and - double precision have exactly 24 and 53 bits in the - mantissa respectively is correct for IEEE-standard floating point - implementations. On non-IEEE platforms it might be off a little, but - for simplicity the same ranges of p are used - on all platforms. - - - - - - - Serial Types - - - serial - - - - bigserial - - - - serial4 - - - - serial8 - - - - auto-increment - serial - - - - sequence - and serial type - -&common; - - The data types serial and bigserial - are not true types, but merely - a notational convenience for creating unique identifier columns - (similar to the AUTO_INCREMENT property - supported by some other databases). In the current - implementation, specifying: - - -CREATE TABLE tablename ( - colname SERIAL -); - - - is equivalent to specifying: - - -CREATE SEQUENCE tablename_colname_seq; -CREATE TABLE tablename ( - colname integer NOT NULL DEFAULT nextval('tablename_colname_seq') -); -ALTER SEQUENCE tablename_colname_seq OWNED BY tablename.colname; - - - Thus, we have created an integer column and arranged for its default - values to be assigned from a sequence generator. A NOT NULL - constraint is applied to ensure that a null value cannot be - inserted. (In most cases you would also want to attach a - UNIQUE or PRIMARY KEY constraint to prevent - duplicate values from being inserted by accident, but this is - not automatic.) Lastly, the sequence is marked as owned by - the column, so that it will be dropped if the column or table is dropped. - - - - - Prior to PostgreSQL 7.3, serial - implied UNIQUE. This is no longer automatic. If - you wish a serial column to have a unique constraint or be a - primary key, it must now be specified, just like - any other data type. - - - - - To insert the next value of the sequence into the serial - column, specify that the serial - column should be assigned its default value. This can be done - either by excluding the column from the list of columns in - the INSERT statement, or through the use of - the DEFAULT key word. - - - - The type names serial and serial4 are - equivalent: both create integer columns. The type - names bigserial and serial8 work - the same way, except that they create a bigint - column. bigserial should be used if you anticipate - the use of more than 231 identifiers over the - lifetime of the table. - - - - The sequence created for a serial column is - automatically dropped when the owning column is dropped. - You can drop the sequence without dropping the column, but this - will force removal of the column default expression. - - - - - - Monetary Types - -&common; - - The money type stores a currency amount with a fixed - fractional precision; see . The fractional precision is - determined by the database's setting. - The range shown in the table assumes there are two fractional digits. - Input is accepted in a variety of formats, including integer and - floating-point literals, as well as typical - currency formatting, such as '$1,000.00'. - Output is generally in the latter form but depends on the locale. - - - - Monetary Types - - - - Name - Storage Size - Description - Range - - - - - money - 8 bytes - currency amount - -92233720368547758.08 to +92233720368547758.07 - - - -
- - - Since the output of this data type is locale-sensitive, it might not - work to load money data into a database that has a different - setting of lc_monetary. To avoid problems, before - restoring a dump into a new database make sure lc_monetary has - the same or equivalent value as in the database that was dumped. - - - - Values of the numeric, int, and - bigint data types can be cast to money. - Conversion from the real and double precision - data types can be done by casting to numeric first, for - example: - -SELECT '12.34'::float8::numeric::money; - - However, this is not recommended. Floating point numbers should not be - used to handle money due to the potential for rounding errors. - - - - A money value can be cast to numeric without - loss of precision. Conversion to other types could potentially lose - precision, and must also be done in two stages: - -SELECT '52093.89'::money::numeric::float8; - - - - - When a money value is divided by another money - value, the result is double precision (i.e., a pure number, - not money); the currency units cancel each other out in the division. - - - - - - Character Types - - - character string - data types - - - - string - character string - - - - character - - - - character varying - - - - text - - - - char - - - - varchar - - -&common; - - Character Types - - - - Name - Description - - - - - character varying(n), varchar(n) - variable-length with limit - - - character(n), char(n) - fixed-length, blank padded - - - text - variable unlimited length - - - -
- - - shows the - general-purpose character types available in - - PostgreSQL. - - - Postgres-XC. - - - Postgres-XL. - - - - - SQL defines two primary character types: - character varying(n) and - character(n), where n - is a positive integer. Both of these types can store strings up to - n characters (not bytes) in length. An attempt to store a - longer string into a column of these types will result in an - error, unless the excess characters are all spaces, in which case - the string will be truncated to the maximum length. (This somewhat - bizarre exception is required by the SQL - standard.) If the string to be stored is shorter than the declared - length, values of type character will be space-padded; - values of type character varying will simply store the - shorter - string. - - - - If one explicitly casts a value to character - varying(n) or - character(n), then an over-length - value will be truncated to n characters without - raising an error. (This too is required by the - SQL standard.) - - - - The notations varchar(n) and - char(n) are aliases for character - varying(n) and - character(n), respectively. - character without length specifier is equivalent to - character(1). If character varying is used - without length specifier, the type accepts strings of any size. The - - latter is a PostgreSQL extension. - - - latter is a Postgres-XC, as well as PostgreSQL extension. - - - latter is a Postgres-XL, as well as PostgreSQL extension. - - - - - - In addition, PostgreSQL provides the - - - In addition, Postgres-XC provides the - - - In addition, Postgres-XL provides the - - text type, which stores strings of any length. - Although the type text is not in the - SQL standard, several other SQL database - management systems have it as well. - - - - Values of type character are physically padded - with spaces to the specified width n, and are - stored and displayed that way. However, the padding spaces are - treated as semantically insignificant. Trailing spaces are - disregarded when comparing two values of type character, - and they will be removed when converting a character value - to one of the other string types. Note that trailing spaces - are semantically significant in - character varying and text values, and - when using pattern matching, e.g. LIKE, - regular expressions. - - - - The storage requirement for a short string (up to 126 bytes) is 1 byte - plus the actual string, which includes the space padding in the case of - character. Longer strings have 4 bytes of overhead instead - of 1. Long strings are compressed by the system automatically, so - the physical requirement on disk might be less. Very long values are also - stored in background tables so that they do not interfere with rapid - access to shorter column values. In any case, the longest - possible character string that can be stored is about 1 GB. (The - maximum value that will be allowed for n in the data - type declaration is less than that. It wouldn't be useful to - change this because with multibyte character encodings the number of - characters and bytes can be quite different. If you desire to - store long strings with no specific upper limit, use - text or character varying without a length - specifier, rather than making up an arbitrary length limit.) - - - - - There is no performance difference among these three types, - apart from increased storage space when using the blank-padded - type, and a few extra CPU cycles to check the length when storing into - a length-constrained column. While - character(n) has performance - advantages in some other database systems, there is no such advantage in - - PostgreSQL; in fact - - - Postgres-XC; in fact - - - Postgres-XL; in fact - - character(n) is usually the slowest of - the three because of its additional storage costs. In most situations - text or character varying should be used - instead. - - - - - Refer to for information about - the syntax of string literals, and to - for information about available operators and functions. The - database character set determines the character set used to store - textual values; for more information on character set support, - refer to . - - - - Using the Character Types - - -CREATE TABLE test1 (a character(4)); -INSERT INTO test1 VALUES ('ok'); -SELECT a, char_length(a) FROM test1; -- - - a | char_length -------+------------- - ok | 2 - - -CREATE TABLE test2 (b varchar(5)); -INSERT INTO test2 VALUES ('ok'); -INSERT INTO test2 VALUES ('good '); -INSERT INTO test2 VALUES ('too long'); -ERROR: value too long for type character varying(5) -INSERT INTO test2 VALUES ('too long'::varchar(5)); -- explicit truncation -SELECT b, char_length(b) FROM test2; - - b | char_length --------+------------- - ok | 2 - good | 5 - too l | 5 - - - - - - The char_length function is discussed in - . - - - - - - - There are two other fixed-length character types in - - PostgreSQL, shown in - - Postgres-XC, shown in - - Postgres-XL, shown in - linkend="datatype-character-special-table">. The name - type exists only for the storage of identifiers - in the internal system catalogs and is not intended for use by the general user. Its - length is currently defined as 64 bytes (63 usable characters plus - terminator) but should be referenced using the constant - NAMEDATALEN in C source code. - The length is set at compile time (and - is therefore adjustable for special uses); the default maximum - length might change in a future release. The type "char" - (note the quotes) is different from char(1) in that it - only uses one byte of storage. It is internally used in the system - catalogs as a simplistic enumeration type. - - - - Special Character Types - - - - Name - Storage Size - Description - - - - - "char" - 1 byte - single-byte internal type - - - name - 64 bytes - internal type for object names - - - -
- - - - - Binary Data Types - - - binary data - - - - bytea - -&common; - - The bytea data type allows storage of binary strings; - see . - - - - Binary Data Types - - - - Name - Storage Size - Description - - - - - bytea - 1 or 4 bytes plus the actual binary string - variable-length binary string - - - -
- - - A binary string is a sequence of octets (or bytes). Binary - strings are distinguished from character strings in two - ways. First, binary strings specifically allow storing - octets of value zero and other non-printable - octets (usually, octets outside the range 32 to 126). - Character strings disallow zero octets, and also disallow any - other octet values and sequences of octet values that are invalid - according to the database's selected character set encoding. - Second, operations on binary strings process the actual bytes, - whereas the processing of character strings depends on locale settings. - In short, binary strings are appropriate for storing data that the - programmer thinks of as raw bytes, whereas character - strings are appropriate for storing text. - - - - The bytea type supports two external formats for - - input and output: PostgreSQL's historical - - - input and output: Postgres-XC's historical - - - input and output: Postgres-XL's historical - - escape format, and hex format. Both - of these are always accepted on input. The output format depends - on the configuration parameter ; - the default is hex. (Note that the hex format was introduced in - PostgreSQL 9.0; earlier versions and some - tools don't understand it.) - - - - The SQL standard defines a different binary - string type, called BLOB or BINARY LARGE - OBJECT. The input format is different from - bytea, but the provided functions and operators are - mostly the same. - - - - <type>bytea</> Hex Format - -&common; - - The hex format encodes binary data as 2 hexadecimal digits - per byte, most significant nibble first. The entire string is - preceded by the sequence \x (to distinguish it - from the escape format). In some contexts, the initial backslash may - need to be escaped by doubling it, in the same cases in which backslashes - have to be doubled in escape format; details appear below. - The hexadecimal digits can - be either upper or lower case, and whitespace is permitted between - digit pairs (but not within a digit pair nor in the starting - \x sequence). - The hex format is compatible with a wide - range of external applications and protocols, and it tends to be - faster to convert than the escape format, so its use is preferred. - - - - Example: - -SELECT E'\\xDEADBEEF'; - - - - - - <type>bytea</> Escape Format - -&common; - - The escape format is the traditional - - PostgreSQL format for the bytea - - - Postgres-XC format for the bytea - - - Postgres-XL format for the bytea - - type. It - takes the approach of representing a binary string as a sequence - of ASCII characters, while converting those bytes that cannot be - represented as an ASCII character into special escape sequences. - If, from the point of view of the application, representing bytes - as characters makes sense, then this representation can be - convenient. But in practice it is usually confusing because it - fuzzes up the distinction between binary strings and character - strings, and also the particular escape mechanism that was chosen is - somewhat unwieldy. So this format should probably be avoided - for most new applications. - - - - When entering bytea values in escape format, - octets of certain - values must be escaped, while all octet - values can be escaped. In - general, to escape an octet, convert it into its three-digit - octal value and precede it - by a backslash (or two backslashes, if writing the value as a - literal using escape string syntax). - Backslash itself (octet value 92) can alternatively be represented by - double backslashes. - - shows the characters that must be escaped, and gives the alternative - escape sequences where applicable. - - - - <type>bytea</> Literal Escaped Octets - - - - Decimal Octet Value - Description - Escaped Input Representation - Example - Output Representation - - - - - - 0 - zero octet - E'\\000' - SELECT E'\\000'::bytea; - \000 - - - - 39 - single quote - '''' or E'\\047' - SELECT E'\''::bytea; - ' - - - - 92 - backslash - E'\\\\' or E'\\134' - SELECT E'\\\\'::bytea; - \\ - - - - 0 to 31 and 127 to 255 - non-printable octets - E'\\xxx' (octal value) - SELECT E'\\001'::bytea; - \001 - - - - -
- - - The requirement to escape non-printable octets - varies depending on locale settings. In some instances you can get away - with leaving them unescaped. Note that the result in each of the examples - in was exactly one octet in - length, even though the output representation is sometimes - more than one character. - - - - The reason multiple backslashes are required, as shown - in , is that an input - string written as a string literal must pass through two parse - - phases in the PostgreSQL server. - - - phases in the Postgres-XC server. - - - phases in the Postgres-XL server. - - The first backslash of each pair is interpreted as an escape - character by the string-literal parser (assuming escape string - syntax is used) and is therefore consumed, leaving the second backslash of the - pair. (Dollar-quoted strings can be used to avoid this level - of escaping.) The remaining backslash is then recognized by the - bytea input function as starting either a three - digit octal value or escaping another backslash. For example, - a string literal passed to the server as E'\\001' - becomes \001 after passing through the - escape string parser. The \001 is then sent - to the bytea input function, where it is converted - to a single octet with a decimal value of 1. Note that the - single-quote character is not treated specially by bytea, - so it follows the normal rules for string literals. (See also - .) - - - - Bytea octets are sometimes escaped when output. In general, each - non-printable octet is converted into - its equivalent three-digit octal value and preceded by one backslash. - Most printable octets are represented by their standard - representation in the client character set. The octet with decimal - value 92 (backslash) is doubled in the output. - Details are in . - - - - <type>bytea</> Output Escaped Octets - - - - Decimal Octet Value - Description - Escaped Output Representation - Example - Output Result - - - - - - - 92 - backslash - \\ - SELECT E'\\134'::bytea; - \\ - - - - 0 to 31 and 127 to 255 - non-printable octets - \xxx (octal value) - SELECT E'\\001'::bytea; - \001 - - - - 32 to 126 - printable octets - client character set representation - SELECT E'\\176'::bytea; - ~ - - - - -
- - - - Depending on the front end to PostgreSQL you use, - - - Depending on the front end to Postgres-XC you use, - - - Depending on the front end to Postgres-XL you use, - - you might have additional work to do in terms of escaping and - unescaping bytea strings. For example, you might also - have to escape line feeds and carriage returns if your interface - automatically translates these. - - - - - - - Date/Time Types - - - date - - - time - - - time without time zone - - - time with time zone - - - timestamp - - - timestamptz - - - timestamp with time zone - - - timestamp without time zone - - - interval - - - time span - -&common; - - - PostgreSQL supports the full set of - - - Postgres-XC supports the full set of - - - Postgres-XL supports the full set of - - SQL date and time types, shown in . The operations available - on these data types are described in - . - - - - Date/Time Types - - - - Name - Storage Size - Description - Low Value - High Value - Resolution - - - - - timestamp [ (p) ] [ without time zone ] - 8 bytes - both date and time (no time zone) - 4713 BC - 294276 AD - 1 microsecond / 14 digits - - - timestamp [ (p) ] with time zone - 8 bytes - both date and time, with time zone - 4713 BC - 294276 AD - 1 microsecond / 14 digits - - - date - 4 bytes - date (no time of day) - 4713 BC - 5874897 AD - 1 day - - - time [ (p) ] [ without time zone ] - 8 bytes - time of day (no date) - 00:00:00 - 24:00:00 - 1 microsecond / 14 digits - - - time [ (p) ] with time zone - 12 bytes - times of day only, with time zone - 00:00:00+1459 - 24:00:00-1459 - 1 microsecond / 14 digits - - - interval [ fields ] [ (p) ] - 12 bytes - time interval - -178000000 years - 178000000 years - 1 microsecond / 14 digits - - - -
- - - - The SQL standard requires that writing just timestamp - be equivalent to timestamp without time - - zone, and PostgreSQL honors that - - - zone, and Postgres-XC honors that - - - zone, and Postgres-XL honors that - - behavior. (Releases prior to 7.3 treated it as timestamp - with time zone.) timestamptz is accepted as an - abbreviation for timestamp with time zone; this is a - PostgreSQL extension. - - - - - time, timestamp, and - interval accept an optional precision value - p which specifies the number of - fractional digits retained in the seconds field. By default, there - is no explicit bound on precision. The allowed range of - p is from 0 to 6 for the - timestamp and interval types. - - - - - When timestamp values are stored as eight-byte integers - (currently the default), microsecond precision is available over - the full range of values. When timestamp values are - stored as double precision floating-point numbers instead (a - deprecated compile-time option), the effective limit of precision - might be less than 6. timestamp values are stored as - seconds before or after midnight 2000-01-01. When - timestamp values are implemented using floating-point - numbers, microsecond precision is achieved for dates within a few - years of 2000-01-01, but the precision degrades for dates further - away. Note that using floating-point datetimes allows a larger - range of timestamp values to be represented than - shown above: from 4713 BC up to 5874897 AD. - - - - The same compile-time option also determines whether - time and interval values are stored as - floating-point numbers or eight-byte integers. In the - floating-point case, large interval values degrade in - precision as the size of the interval increases. - - - - - For the time types, the allowed range of - p is from 0 to 6 when eight-byte integer - storage is used, or from 0 to 10 when floating-point storage is used. - - - - The interval type has an additional option, which is - to restrict the set of stored fields by writing one of these phrases: - -YEAR -MONTH -DAY -HOUR -MINUTE -SECOND -YEAR TO MONTH -DAY TO HOUR -DAY TO MINUTE -DAY TO SECOND -HOUR TO MINUTE -HOUR TO SECOND -MINUTE TO SECOND - - Note that if both fields and - p are specified, the - fields must include SECOND, - since the precision applies only to the seconds. - - - - The type time with time zone is defined by the SQL - standard, but the definition exhibits properties which lead to - questionable usefulness. In most cases, a combination of - date, time, timestamp without time - zone, and timestamp with time zone should - provide a complete range of date/time functionality required by - any application. - - - - The types abstime - and reltime are lower precision types which are used internally. - You are discouraged from using these types in - applications; these internal types - might disappear in a future release. - - - - Date/Time Input -&common; - - Date and time input is accepted in almost any reasonable format, including - ISO 8601, SQL-compatible, - traditional POSTGRES, and others. - For some formats, ordering of day, month, and year in date input is - ambiguous and there is support for specifying the expected - ordering of these fields. Set the parameter - to MDY to select month-day-year interpretation, - DMY to select day-month-year interpretation, or - YMD to select year-month-day interpretation. - - - - - PostgreSQL is more flexible in - - - Postgres-XC is more flexible in - - - Postgres-XL is more flexible in - - handling date/time input than the - SQL standard requires. - See - for the exact parsing rules of date/time input and for the - recognized text fields including months, days of the week, and - time zones. - - - - Remember that any date or time literal input needs to be enclosed - in single quotes, like text strings. Refer to - for more - information. - SQL requires the following syntax - -type [ (p) ] 'value' - - where p is an optional precision - specification giving the number of - fractional digits in the seconds field. Precision can be - specified for time, timestamp, and - interval types. The allowed values are mentioned - above. If no precision is specified in a constant specification, - it defaults to the precision of the literal value. - - - - Dates - - - date - - -&common; - - shows some possible - inputs for the date type. - - - - Date Input - - - - Example - Description - - - - - 1999-01-08 - ISO 8601; January 8 in any mode - (recommended format) - - - January 8, 1999 - unambiguous in any datestyle input mode - - - 1/8/1999 - January 8 in MDY mode; - August 1 in DMY mode - - - 1/18/1999 - January 18 in MDY mode; - rejected in other modes - - - 01/02/03 - January 2, 2003 in MDY mode; - February 1, 2003 in DMY mode; - February 3, 2001 in YMD mode - - - - 1999-Jan-08 - January 8 in any mode - - - Jan-08-1999 - January 8 in any mode - - - 08-Jan-1999 - January 8 in any mode - - - 99-Jan-08 - January 8 in YMD mode, else error - - - 08-Jan-99 - January 8, except error in YMD mode - - - Jan-08-99 - January 8, except error in YMD mode - - - 19990108 - ISO 8601; January 8, 1999 in any mode - - - 990108 - ISO 8601; January 8, 1999 in any mode - - - 1999.008 - year and day of year - - - J2451187 - Julian day - - - January 8, 99 BC - year 99 BC - - - -
- - - - Times - - - time - - - time without time zone - - - time with time zone - -&common; - - The time-of-day types are time [ - (p) ] without time zone and - time [ (p) ] with time - zone. time alone is equivalent to - time without time zone. - - - - Valid input for these types consists of a time of day followed - by an optional time zone. (See - and .) If a time zone is - specified in the input for time without time zone, - it is silently ignored. You can also specify a date but it will - be ignored, except when you use a time zone name that involves a - daylight-savings rule, such as - America/New_York. In this case specifying the date - is required in order to determine whether standard or daylight-savings - time applies. The appropriate time zone offset is recorded in the - time with time zone value. - - - - Time Input - - - - Example - Description - - - - - 04:05:06.789 - ISO 8601 - - - 04:05:06 - ISO 8601 - - - 04:05 - ISO 8601 - - - 040506 - ISO 8601 - - - 04:05 AM - same as 04:05; AM does not affect value - - - 04:05 PM - same as 16:05; input hour must be <= 12 - - - 04:05:06.789-8 - ISO 8601 - - - 04:05:06-08:00 - ISO 8601 - - - 04:05-08:00 - ISO 8601 - - - 040506-08 - ISO 8601 - - - 04:05:06 PST - time zone specified by abbreviation - - - 2003-04-12 04:05:06 America/New_York - time zone specified by full name - - - -
- - - Time Zone Input - - - - Example - Description - - - - - PST - Abbreviation (for Pacific Standard Time) - - - America/New_York - Full time zone name - - - PST8PDT - POSIX-style time zone specification - - - -8:00 - ISO-8601 offset for PST - - - -800 - ISO-8601 offset for PST - - - -8 - ISO-8601 offset for PST - - - zulu - Military abbreviation for UTC - - - z - Short form of zulu - - - -
- - - Refer to for more information on how - to specify time zones. - - - - - Time Stamps - - - timestamp - - - - timestamp with time zone - - - - timestamp without time zone - -&common; - - Valid input for the time stamp types consists of the concatenation - of a date and a time, followed by an optional time zone, - followed by an optional AD or BC. - (Alternatively, AD/BC can appear - before the time zone, but this is not the preferred ordering.) - Thus: - - -1999-01-08 04:05:06 - - and: - -1999-01-08 04:05:06 -8:00 - - - are valid values, which follow the ISO 8601 - standard. In addition, the common format: - -January 8 04:05:06 1999 PST - - is supported. - - - - The SQL standard differentiates - timestamp without time zone - and timestamp with time zone literals by the presence of a - + or - symbol and time zone offset after - the time. Hence, according to the standard, - - TIMESTAMP '2004-10-19 10:23:54' - - is a timestamp without time zone, while - - TIMESTAMP '2004-10-19 10:23:54+02' - - is a timestamp with time zone. - - PostgreSQL never examines the content of a - - - Postgres-XC never examines the content of a - - - Postgres-XL never examines the content of a - - literal string before determining its type, and therefore will treat - both of the above as timestamp without time zone. To - ensure that a literal is treated as timestamp with time - zone, give it the correct explicit type: - - TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02' - - In a literal that has been determined to be timestamp without time - - zone, PostgreSQL will silently ignore - - - zone, Postgres-XC will silently ignore - - - zone, Postgres-XL will silently ignore - - any time zone indication. - That is, the resulting value is derived from the date/time - fields in the input value, and is not adjusted for time zone. - - - - For timestamp with time zone, the internally stored - value is always in UTC (Universal - Coordinated Time, traditionally known as Greenwich Mean Time, - GMT). An input value that has an explicit - time zone specified is converted to UTC using the appropriate offset - for that time zone. If no time zone is stated in the input string, - then it is assumed to be in the time zone indicated by the system's - parameter, and is converted to UTC using the - offset for the timezone zone. - - - - When a timestamp with time - zone value is output, it is always converted from UTC to the - current timezone zone, and displayed as local time in that - zone. To see the time in another time zone, either change - timezone or use the AT TIME ZONE construct - (see ). - - - - Conversions between timestamp without time zone and - timestamp with time zone normally assume that the - timestamp without time zone value should be taken or given - as timezone local time. A different time zone can - be specified for the conversion using AT TIME ZONE. - - - - - Special Values - - - time - constants - - - - date - constants - -&common; - - - PostgreSQL supports several - - - Postgres-XC supports several - - - Postgres-XL supports several - - special date/time input values for convenience, as shown in . The values - infinity and -infinity - are specially represented inside the system and will be displayed - unchanged; but the others are simply notational shorthands - that will be converted to ordinary date/time values when read. - (In particular, now and related strings are converted - to a specific time value as soon as they are read.) - All of these values need to be enclosed in single quotes when used - as constants in SQL commands. - - - - Special Date/Time Inputs - - - - Input String - Valid Types - Description - - - - - epoch - date, timestamp - 1970-01-01 00:00:00+00 (Unix system time zero) - - - infinity - date, timestamp - later than all other time stamps - - - -infinity - date, timestamp - earlier than all other time stamps - - - now - date, time, timestamp - current transaction's start time - - - today - date, timestamp - midnight today - - - tomorrow - date, timestamp - midnight tomorrow - - - yesterday - date, timestamp - midnight yesterday - - - allballs - time - 00:00:00.00 UTC - - - -
- - - The following SQL-compatible functions can also - be used to obtain the current time value for the corresponding data - type: - CURRENT_DATE, CURRENT_TIME, - CURRENT_TIMESTAMP, LOCALTIME, - LOCALTIMESTAMP. The latter four accept an - optional subsecond precision specification. (See .) Note that these are - SQL functions and are not recognized in data input strings. - - - - - - - Date/Time Output - - - date - output format - formatting - - - - time - output format - formatting - -&common; - - The output format of the date/time types can be set to one of the four - styles ISO 8601, - SQL (Ingres), traditional POSTGRES - (Unix date format), or - German. The default - is the ISO format. (The - SQL standard requires the use of the ISO 8601 - format. The name of the SQL output format is a - historical accident.) shows examples of each - output style. The output of the date and - time types is of course only the date or time part - in accordance with the given examples. - - - - Date/Time Output Styles - - - - Style Specification - Description - Example - - - - - ISO - ISO 8601/SQL standard - 1997-12-17 07:37:16-08 - - - SQL - traditional style - 12/17/1997 07:37:16.00 PST - - - POSTGRES - original style - Wed Dec 17 07:37:16 1997 PST - - - German - regional style - 17.12.1997 07:37:16.00 PST - - - -
- - - In the SQL and POSTGRES styles, day appears before - month if DMY field ordering has been specified, otherwise month appears - before day. - (See - for how this setting also affects interpretation of input values.) - shows an - example. - - - - Date Order Conventions - - - - datestyle Setting - Input Ordering - Example Output - - - - - SQL, DMY - day/month/year - 17/12/1997 15:37:16.00 CET - - - SQL, MDY - month/day/year - 12/17/1997 07:37:16.00 PST - - - Postgres, DMY - day/month/year - Wed 17 Dec 07:37:16 1997 PST - - - -
- - - The date/time styles can be selected by the user using the - SET datestyle command, the parameter in the - postgresql.conf configuration file, or the - PGDATESTYLE environment variable on the server or - client. The formatting function to_char - (see ) is also available as - a more flexible way to format date/time output. - - - - - Time Zones - - - time zone - -&common; - - Time zones, and time-zone conventions, are influenced by - political decisions, not just earth geometry. Time zones around the - world became somewhat standardized during the 1900's, - but continue to be prone to arbitrary changes, particularly with - respect to daylight-savings rules. - - PostgreSQL uses the widely-used - - - Postgres-XC uses the widely-used - - - Postgres-XL uses the widely-used - - zoneinfo time zone database for information about - historical time zone rules. For times in the future, the assumption - is that the latest known rules for a given time zone will - continue to be observed indefinitely far into the future. - - - - - PostgreSQL endeavors to be compatible with - - - Postgres-XC endeavors to be compatible with - - - Postgres-XL endeavors to be compatible with - - the SQL standard definitions for typical usage. - However, the SQL standard has an odd mix of date and - time types and capabilities. Two obvious problems are: - - - - - Although the date type - cannot have an associated time zone, the - time type can. - Time zones in the real world have little meaning unless - associated with a date as well as a time, - since the offset can vary through the year with daylight-saving - time boundaries. - - - - - - The default time zone is specified as a constant numeric offset - from UTC. It is therefore impossible to adapt to - daylight-saving time when doing date/time arithmetic across - DST boundaries. - - - - - - - - To address these difficulties, we recommend using date/time types - that contain both date and time when using time zones. We - do not recommend using the type time with - time zone (though it is supported by - - PostgreSQL for legacy applications and - for compliance with the SQL standard). - PostgreSQL assumes - - - Postgres-XC for legacy applications and - for compliance with the SQL standard). - Postgres-XC assumes - - - Postgres-XL for legacy applications and - for compliance with the SQL standard). - Postgres-XL assumes - - your local time zone for any type containing only date or time. - - - - All timezone-aware dates and times are stored internally in - UTC. They are converted to local time - in the zone specified by the configuration - parameter before being displayed to the client. - - - - - PostgreSQL allows you to specify time zones in - - - Postgres-XC allows you to specify time zones in - - - Postgres-XL allows you to specify time zones in - - three different forms: - - - - A full time zone name, for example America/New_York. - The recognized time zone names are listed in the - pg_timezone_names view (see ). - - PostgreSQL uses the widely-used - - - Postgres-XC uses the widely-used - - - Postgres-XL uses the widely-used - - zoneinfo time zone data for this purpose, so the same - names are also recognized by much other software. - - - - - A time zone abbreviation, for example PST. Such a - specification merely defines a particular offset from UTC, in - contrast to full time zone names which can imply a set of daylight - savings transition-date rules as well. The recognized abbreviations - are listed in the pg_timezone_abbrevs view (see ). You cannot set the - configuration parameters or - to a time - zone abbreviation, but you can use abbreviations in - date/time input values and with the AT TIME ZONE - operator. - - - - - In addition to the timezone names and abbreviations, - - PostgreSQL will accept POSIX-style time zone - - - Postgres-XC will accept POSIX-style time zone - - - Postgres-XL will accept POSIX-style time zone - - specifications of the form STDoffset or - STDoffsetDST, where - STD is a zone abbreviation, offset is a - numeric offset in hours west from UTC, and DST is an - optional daylight-savings zone abbreviation, assumed to stand for one - hour ahead of the given offset. For example, if EST5EDT - were not already a recognized zone name, it would be accepted and would - be functionally equivalent to United States East Coast time. When a - daylight-savings zone name is present, it is assumed to be used - according to the same daylight-savings transition rules used in the - zoneinfo time zone database's posixrules entry. - - In a standard PostgreSQL installation, - - - In a standard Postgres-XC installation, - - - In a standard Postgres-XL installation, - - posixrules is the same as US/Eastern, so - that POSIX-style time zone specifications follow USA daylight-savings - rules. If needed, you can adjust this behavior by replacing the - posixrules file. - - - - - In short, this is the difference between abbreviations - and full names: abbreviations always represent a fixed offset from - UTC, whereas most of the full names imply a local daylight-savings time - rule, and so have two possible UTC offsets. - - - - One should be wary that the POSIX-style time zone feature can - lead to silently accepting bogus input, since there is no check on the - reasonableness of the zone abbreviations. For example, SET - TIMEZONE TO FOOBAR0 will work, leaving the system effectively using - a rather peculiar abbreviation for UTC. - Another issue to keep in mind is that in POSIX time zone names, - positive offsets are used for locations west of Greenwich. - - Everywhere else, PostgreSQL follows the - - - Everywhere else, Postgres-XC follows the - - - Everywhere else, Postgres-XL follows the - - ISO-8601 convention that positive timezone offsets are east - of Greenwich. - - - - In all cases, timezone names are recognized case-insensitively. - (This is a change from PostgreSQL versions - prior to 8.2, which were case-sensitive in some contexts but not others.) - - - - Neither full names nor abbreviations are hard-wired into the server; - they are obtained from configuration files stored under - .../share/timezone/ and .../share/timezonesets/ - of the installation directory - (see ). - - - - The configuration parameter can - be set in the file postgresql.conf, or in any of the - other standard ways described in . - There are also several special ways to set it: - - - - - If timezone is not specified in - postgresql.conf or as a server command-line option, - the server attempts to use the value of the TZ - environment variable as the default time zone. If TZ - is not defined or is not any of the time zone names known to - - PostgreSQL, the server attempts to - - - Postgres-XC, the server attempts to - - - Postgres-XL, the server attempts to - - determine the operating system's default time zone by checking the - behavior of the C library function localtime(). The - default time zone is selected as the closest match among - - PostgreSQL's known time zones. - - - Postgres-XC's known time zones. - - - Postgres-XL's known time zones. - - (These rules are also used to choose the default value of - , if not specified.) - - - - - - The SQL command SET TIME ZONE - sets the time zone for the session. This is an alternative spelling - of SET TIMEZONE TO with a more SQL-spec-compatible syntax. - - - - - - The PGTZ environment variable is used by - libpq clients - to send a SET TIME ZONE - command to the server upon connection. - - - - - - - - Interval Input - - - interval - -&common; - - interval values can be written using the following - verbose syntax: - - -@ quantity unit quantity unit... direction - - - where quantity is a number (possibly signed); - unit is microsecond, - millisecond, second, - minute, hour, day, - week, month, year, - decade, century, millennium, - or abbreviations or plurals of these units; - direction can be ago or - empty. The at sign (@) is optional noise. The amounts - of the different units are implicitly added with appropriate - sign accounting. ago negates all the fields. - This syntax is also used for interval output, if - is set to - postgres_verbose. - - - - Quantities of days, hours, minutes, and seconds can be specified without - explicit unit markings. For example, '1 12:59:10' is read - the same as '1 day 12 hours 59 min 10 sec'. Also, - a combination of years and months can be specified with a dash; - for example '200-10' is read the same as '200 years - 10 months'. (These shorter forms are in fact the only ones allowed - by the SQL standard, and are used for output when - IntervalStyle is set to sql_standard.) - - - - Interval values can also be written as ISO 8601 time intervals, using - either the format with designators of the standard's section - 4.4.3.2 or the alternative format of section 4.4.3.3. The - format with designators looks like this: - -P quantity unit quantity unit ... T quantity unit ... - - The string must start with a P, and may include a - T that introduces the time-of-day units. The - available unit abbreviations are given in . Units may be - omitted, and may be specified in any order, but units smaller than - a day must appear after T. In particular, the meaning of - M depends on whether it is before or after - T. - - - - ISO 8601 Interval Unit Abbreviations - - - - Abbreviation - Meaning - - - - - Y - Years - - - M - Months (in the date part) - - - W - Weeks - - - D - Days - - - H - Hours - - - M - Minutes (in the time part) - - - S - Seconds - - - -
- - - In the alternative format: - -P years-months-days T hours:minutes:seconds - - the string must begin with P, and a - T separates the date and time parts of the interval. - The values are given as numbers similar to ISO 8601 dates. - - - - When writing an interval constant with a fields - specification, or when assigning a string to an interval column that was - defined with a fields specification, the interpretation of - unmarked quantities depends on the fields. For - example INTERVAL '1' YEAR is read as 1 year, whereas - INTERVAL '1' means 1 second. Also, field values - to the right of the least significant field allowed by the - fields specification are silently discarded. For - example, writing INTERVAL '1 day 2:03:04' HOUR TO MINUTE - results in dropping the seconds field, but not the day field. - - - - According to the SQL standard all fields of an interval - value must have the same sign, so a leading negative sign applies to all - fields; for example the negative sign in the interval literal - '-1 2:03:04' applies to both the days and hour/minute/second - - parts. PostgreSQL allows the fields to have different - - - parts. Postgres-XC allows the fields to have different - - - parts. Postgres-XL allows the fields to have different - - signs, and traditionally treats each field in the textual representation - as independently signed, so that the hour/minute/second part is - considered positive in this example. If IntervalStyle is - set to sql_standard then a leading sign is considered - to apply to all fields (but only if no additional signs appear). - - Otherwise the traditional PostgreSQL interpretation is - - - Otherwise the traditional Postgres-XC interpretation is - - - Otherwise the traditional Postgres-XL interpretation is - - used. To avoid ambiguity, it's recommended to attach an explicit sign - to each field if any field is negative. - - - - Internally interval values are stored as months, days, - and seconds. This is done because the number of days in a month - varies, and a day can have 23 or 25 hours if a daylight savings - time adjustment is involved. The months and days fields are integers - while the seconds field can store fractions. Because intervals are - usually created from constant strings or timestamp subtraction, - this storage method works well in most cases. Functions - justify_days and justify_hours are - available for adjusting days and hours that overflow their normal - ranges. - - - - In the verbose input format, and in some fields of the more compact - input formats, field values can have fractional parts; for example - '1.5 week' or '01:02:03.45'. Such input is - converted to the appropriate number of months, days, and seconds - for storage. When this would result in a fractional number of - months or days, the fraction is added to the lower-order fields - using the conversion factors 1 month = 30 days and 1 day = 24 hours. - For example, '1.5 month' becomes 1 month and 15 days. - Only seconds will ever be shown as fractional on output. - - - - shows some examples - of valid interval input. - - - - Interval Input - - - - Example - Description - - - - - 1-2 - SQL standard format: 1 year 2 months - - - 3 4:05:06 - SQL standard format: 3 days 4 hours 5 minutes 6 seconds - - - 1 year 2 months 3 days 4 hours 5 minutes 6 seconds - Traditional Postgres format: 1 year 2 months 3 days 4 hours 5 minutes 6 seconds - - - P1Y2M3DT4H5M6S - ISO 8601 format with designators: same meaning as above - - - P0001-02-03T04:05:06 - ISO 8601 alternative format: same meaning as above - - - -
- - - - - Interval Output - - - interval - output format - formatting - -&common; - - The output format of the interval type can be set to one of the - four styles sql_standard, postgres, - postgres_verbose, or iso_8601, - using the command SET intervalstyle. - The default is the postgres format. - shows examples of each - output style. - - - - The sql_standard style produces output that conforms to - the SQL standard's specification for interval literal strings, if - the interval value meets the standard's restrictions (either year-month - only or day-time only, with no mixing of positive - and negative components). Otherwise the output looks like a standard - year-month literal string followed by a day-time literal string, - with explicit signs added to disambiguate mixed-sign intervals. - - - - The output of the postgres style matches the output of - PostgreSQL releases prior to 8.4 when the - parameter was set to ISO. - - - - The output of the postgres_verbose style matches the output of - PostgreSQL releases prior to 8.4 when the - DateStyle parameter was set to non-ISO output. - - - - The output of the iso_8601 style matches the format - with designators described in section 4.4.3.2 of the - ISO 8601 standard. - - - - Interval Output Style Examples - - - - Style Specification - Year-Month Interval - Day-Time Interval - Mixed Interval - - - - - sql_standard - 1-2 - 3 4:05:06 - -1-2 +3 -4:05:06 - - - postgres - 1 year 2 mons - 3 days 04:05:06 - -1 year -2 mons +3 days -04:05:06 - - - postgres_verbose - @ 1 year 2 mons - @ 3 days 4 hours 5 mins 6 secs - @ 1 year 2 mons -3 days 4 hours 5 mins 6 secs ago - - - iso_8601 - P1Y2M - P3DT4H5M6S - P-1Y-2M3DT-4H-5M-6S - - - -
- - - - - Internals -&common; - - - PostgreSQL uses Julian dates - for all date/time calculations. This has the useful property of correctly - calculating dates from 4713 BC - to far into the future, using the assumption that the length of the - year is 365.2425 days. - - - Postgres-XC, as PostgreSQL, uses Julian dates - for all date/time calculations. This has the useful property of correctly - calculating dates from 4713 BC - to far into the future, using the assumption that the length of the - year is 365.2425 days. - - - Postgres-XL, as PostgreSQL, uses Julian dates - for all date/time calculations. This has the useful property of correctly - calculating dates from 4713 BC - to far into the future, using the assumption that the length of the - year is 365.2425 days. - - - - - Date conventions before the 19th century make for interesting reading, - but are not consistent enough to warrant coding into a date/time handler. - - - - - - - Boolean Type - - - Boolean - data type - - - - true - - - - false - -&common; - - - PostgreSQL provides the - - - Postgres-XC provides the - - - Postgres-XL provides the - - standard SQL type boolean; - see . - The boolean type can have several states: - true, false, and a third state, - unknown, which is represented by the - SQL null value. - - - - Boolean Data Type - - - - Name - Storage Size - Description - - - - - boolean - 1 byte - state of true or false - - - -
- - - Valid literal values for the true state are: - - TRUE - 't' - 'true' - 'y' - 'yes' - 'on' - '1' - - For the false state, the following values can be - used: - - FALSE - 'f' - 'false' - 'n' - 'no' - 'off' - '0' - - Leading or trailing whitespace is ignored, and case does not matter. - The key words - TRUE and FALSE are the preferred - (SQL-compliant) usage. - - - - shows that - boolean values are output using the letters - t and f. - - - - Using the <type>boolean</type> Type - - -CREATE TABLE test1 (a boolean, b text); -INSERT INTO test1 VALUES (TRUE, 'sic est'); -INSERT INTO test1 VALUES (FALSE, 'non est'); -SELECT * FROM test1; - a | b ----+--------- - t | sic est - f | non est - -SELECT * FROM test1 WHERE a; - a | b ----+--------- - t | sic est - - - - - - Enumerated Types - - - data type - enumerated (enum) - - - - enumerated types - -&common; - - Enumerated (enum) types are data types that - comprise a static, ordered set of values. - They are equivalent to the enum - types supported in a number of programming languages. An example of an enum - type might be the days of the week, or a set of status values for - a piece of data. - - - - Declaration of Enumerated Types -&common; - - Enum types are created using the command, - for example: - - -CREATE TYPE mood AS ENUM ('sad', 'ok', 'happy'); - - - Once created, the enum type can be used in table and function - definitions much like any other type: - -CREATE TYPE mood AS ENUM ('sad', 'ok', 'happy'); -CREATE TABLE person ( - name text, - current_mood mood -); -INSERT INTO person VALUES ('Moe', 'happy'); -SELECT * FROM person WHERE current_mood = 'happy'; - name | current_mood -------+-------------- - Moe | happy -(1 row) - - - - - - Ordering -&common; - - The ordering of the values in an enum type is the - order in which the values were listed when the type was created. - All standard comparison operators and related - aggregate functions are supported for enums. For example: - - -INSERT INTO person VALUES ('Larry', 'sad'); -INSERT INTO person VALUES ('Curly', 'ok'); -SELECT * FROM person WHERE current_mood > 'sad'; - name | current_mood --------+-------------- - Moe | happy - Curly | ok -(2 rows) - -SELECT * FROM person WHERE current_mood > 'sad' ORDER BY current_mood; - name | current_mood --------+-------------- - Curly | ok - Moe | happy -(2 rows) - -SELECT name -FROM person -WHERE current_mood = (SELECT MIN(current_mood) FROM person); - name -------- - Larry -(1 row) - - - - - - Type Safety -&common; - - Each enumerated data type is separate and cannot - be compared with other enumerated types. See this example: - - -CREATE TYPE happiness AS ENUM ('happy', 'very happy', 'ecstatic'); -CREATE TABLE holidays ( - num_weeks integer, - happiness happiness -); -INSERT INTO holidays(num_weeks,happiness) VALUES (4, 'happy'); -INSERT INTO holidays(num_weeks,happiness) VALUES (6, 'very happy'); -INSERT INTO holidays(num_weeks,happiness) VALUES (8, 'ecstatic'); -INSERT INTO holidays(num_weeks,happiness) VALUES (2, 'sad'); -ERROR: invalid input value for enum happiness: "sad" -SELECT person.name, holidays.num_weeks FROM person, holidays - WHERE person.current_mood = holidays.happiness; -ERROR: operator does not exist: mood = happiness - - - - - If you really need to do something like that, you can either - write a custom operator or add explicit casts to your query: - - -SELECT person.name, holidays.num_weeks FROM person, holidays - WHERE person.current_mood::text = holidays.happiness::text; - name | num_weeks -------+----------- - Moe | 4 -(1 row) - - - - - - - Implementation Details - -&common; - - An enum value occupies four bytes on disk. The length of an enum - value's textual label is limited by the NAMEDATALEN - - setting compiled into PostgreSQL; in standard - - - setting compiled into Postgres-XC; in standard - - - setting compiled into Postgres-XL; in standard - - builds this means at most 63 bytes. - - - - Enum labels are case sensitive, so - 'happy' is not the same as 'HAPPY'. - White space in the labels is significant too. - - - - The translations from internal enum values to textual labels are - kept in the system catalog - pg_enum. - Querying this catalog directly can be useful. - - - - - - - Geometric Types -&common; - - Geometric data types represent two-dimensional spatial - objects. shows the geometric - - types available in PostgreSQL. The - - - types available in Postgres-XC. The - - - types available in Postgres-XL. The - - most fundamental type, the point, forms the basis for all of the - other types. - - - - Geometric Types - - - - Name - Storage Size - Representation - Description - - - - - point - 16 bytes - Point on a plane - (x,y) - - - line - 32 bytes - Infinite line (not fully implemented) - ((x1,y1),(x2,y2)) - - - lseg - 32 bytes - Finite line segment - ((x1,y1),(x2,y2)) - - - box - 32 bytes - Rectangular box - ((x1,y1),(x2,y2)) - - - path - 16+16n bytes - Closed path (similar to polygon) - ((x1,y1),...) - - - path - 16+16n bytes - Open path - [(x1,y1),...] - - - polygon - 40+16n bytes - Polygon (similar to closed path) - ((x1,y1),...) - - - circle - 24 bytes - Circle - <(x,y),r> (center point and radius) - - - -
- - - A rich set of functions and operators is available to perform various geometric - operations such as scaling, translation, rotation, and determining - intersections. They are explained in . - - - - Points - - - point - -&common; - - Points are the fundamental two-dimensional building block for geometric - types. Values of type point are specified using either of - the following syntaxes: - - -( x , y ) - x , y - - - where x and y are the respective - coordinates, as floating-point numbers. - - - - Points are output using the first syntax. - - - - - Line Segments -&common; - - lseg - - - - line segment - - - - Line segments (lseg) are represented by pairs of points. - Values of type lseg are specified using any of the following - syntaxes: - - -[ ( x1 , y1 ) , ( x2 , y2 ) ] -( ( x1 , y1 ) , ( x2 , y2 ) ) - ( x1 , y1 ) , ( x2 , y2 ) - x1 , y1 , x2 , y2 - - - where - (x1,y1) - and - (x2,y2) - are the end points of the line segment. - - - - Line segments are output using the first syntax. - - - - - Boxes - - - box (data type) - - - - rectangle - -&common; - - Boxes are represented by pairs of points that are opposite - corners of the box. - Values of type box are specified using any of the following - syntaxes: - - -( ( x1 , y1 ) , ( x2 , y2 ) ) - ( x1 , y1 ) , ( x2 , y2 ) - x1 , y1 , x2 , y2 - - - where - (x1,y1) - and - (x2,y2) - are any two opposite corners of the box. - - - - Boxes are output using the second syntax. - - - - Any two opposite corners can be supplied on input, but the values - will be reordered as needed to store the - upper right and lower left corners, in that order. - - - - - Paths - - - path (data type) - -&common; - - Paths are represented by lists of connected points. Paths can be - open, where - the first and last points in the list are considered not connected, or - closed, - where the first and last points are considered connected. - - - - Values of type path are specified using any of the following - syntaxes: - - -[ ( x1 , y1 ) , ... , ( xn , yn ) ] -( ( x1 , y1 ) , ... , ( xn , yn ) ) - ( x1 , y1 ) , ... , ( xn , yn ) - ( x1 , y1 , ... , xn , yn ) - x1 , y1 , ... , xn , yn - - - where the points are the end points of the line segments - comprising the path. Square brackets ([]) indicate - an open path, while parentheses (()) indicate a - closed path. When the outermost parentheses are omitted, as - in the third through fifth syntaxes, a closed path is assumed. - - - - Paths are output using the first or second syntax, as appropriate. - - - - - Polygons - - - polygon - -&common; - - Polygons are represented by lists of points (the vertexes of the - polygon). Polygons are very similar to closed paths, but are - stored differently and have their own set of support routines. - - - - Values of type polygon are specified using any of the - following syntaxes: - - -( ( x1 , y1 ) , ... , ( xn , yn ) ) - ( x1 , y1 ) , ... , ( xn , yn ) - ( x1 , y1 , ... , xn , yn ) - x1 , y1 , ... , xn , yn - - - where the points are the end points of the line segments - comprising the boundary of the polygon. - - - - Polygons are output using the first syntax. - - - - - Circles - - - circle - -&common; - - Circles are represented by a center point and radius. - Values of type circle are specified using any of the - following syntaxes: - - -< ( x , y ) , r > -( ( x , y ) , r ) - ( x , y ) , r - x , y , r - - - where - (x,y) - is the center point and r is the radius of the - circle. - - - - Circles are output using the first syntax. - - - - - - - Network Address Types - - - network - data types - -&common; - - - PostgreSQL offers data types to store IPv4, IPv6, and MAC - - - PostgreSQL inherits data types to store IPv4, IPv6, and MAC - - - PostgreSQL inherits data types to store IPv4, IPv6, and MAC - - addresses, as shown in . It - is better to use these types instead of plain text types to store - network addresses, because - these types offer input error checking and specialized - operators and functions (see ). - - - - Network Address Types - - - - Name - Storage Size - Description - - - - - - cidr - 7 or 19 bytes - IPv4 and IPv6 networks - - - - inet - 7 or 19 bytes - IPv4 and IPv6 hosts and networks - - - - macaddr - 6 bytes - MAC addresses - - - - -
- - - When sorting inet or cidr data types, - IPv4 addresses will always sort before IPv6 addresses, including - IPv4 addresses encapsulated or mapped to IPv6 addresses, such as - ::10.2.3.4 or ::ffff:10.4.3.2. - - - - - <type>inet</type> - - - inet (data type) - -&common; - - The inet type holds an IPv4 or IPv6 host address, and - optionally its subnet, all in one field. - The subnet is represented by the number of network address bits - present in the host address (the - netmask). If the netmask is 32 and the address is IPv4, - then the value does not indicate a subnet, only a single host. - In IPv6, the address length is 128 bits, so 128 bits specify a - unique host address. Note that if you - want to accept only networks, you should use the - cidr type rather than inet. - - - - The input format for this type is - address/y - where - address - is an IPv4 or IPv6 address and - y - is the number of bits in the netmask. If the - /y - portion is missing, the - netmask is 32 for IPv4 and 128 for IPv6, so the value represents - just a single host. On display, the - /y - portion is suppressed if the netmask specifies a single host. - - - - - <type>cidr</> - - - cidr - -&common; - - The cidr type holds an IPv4 or IPv6 network specification. - Input and output formats follow Classless Internet Domain Routing - conventions. - The format for specifying networks is address/y where address is the network represented as an - IPv4 or IPv6 address, and y is the number of bits in the netmask. If - y is omitted, it is calculated - using assumptions from the older classful network numbering system, except - it will be at least large enough to include all of the octets - written in the input. It is an error to specify a network address - that has bits set to the right of the specified netmask. - - - - shows some examples. - - - - <type>cidr</> Type Input Examples - - - - cidr Input - cidr Output - abbrev(cidr) - - - - - 192.168.100.128/25 - 192.168.100.128/25 - 192.168.100.128/25 - - - 192.168/24 - 192.168.0.0/24 - 192.168.0/24 - - - 192.168/25 - 192.168.0.0/25 - 192.168.0.0/25 - - - 192.168.1 - 192.168.1.0/24 - 192.168.1/24 - - - 192.168 - 192.168.0.0/24 - 192.168.0/24 - - - 128.1 - 128.1.0.0/16 - 128.1/16 - - - 128 - 128.0.0.0/16 - 128.0/16 - - - 128.1.2 - 128.1.2.0/24 - 128.1.2/24 - - - 10.1.2 - 10.1.2.0/24 - 10.1.2/24 - - - 10.1 - 10.1.0.0/16 - 10.1/16 - - - 10 - 10.0.0.0/8 - 10/8 - - - 10.1.2.3/32 - 10.1.2.3/32 - 10.1.2.3/32 - - - 2001:4f8:3:ba::/64 - 2001:4f8:3:ba::/64 - 2001:4f8:3:ba::/64 - - - 2001:4f8:3:ba:2e0:81ff:fe22:d1f1/128 - 2001:4f8:3:ba:2e0:81ff:fe22:d1f1/128 - 2001:4f8:3:ba:2e0:81ff:fe22:d1f1 - - - ::ffff:1.2.3.0/120 - ::ffff:1.2.3.0/120 - ::ffff:1.2.3/120 - - - ::ffff:1.2.3.0/128 - ::ffff:1.2.3.0/128 - ::ffff:1.2.3.0/128 - - - -
- - - - <type>inet</type> vs. <type>cidr</type> -&common; - - The essential difference between inet and cidr - data types is that inet accepts values with nonzero bits to - the right of the netmask, whereas cidr does not. - - - - - If you do not like the output format for inet or - cidr values, try the functions host, - text, and abbrev. - - - - - - <type>macaddr</type> - - - macaddr (data type) - - - - MAC address - macaddr - -&common; - - The macaddr type stores MAC addresses, known for example - from Ethernet card hardware addresses (although MAC addresses are - used for other purposes as well). Input is accepted in the - following formats: - - - '08:00:2b:01:02:03' - '08-00-2b-01-02-03' - '08002b:010203' - '08002b-010203' - '0800.2b01.0203' - '08002b010203' - - - These examples would all specify the same address. Upper and - lower case is accepted for the digits - a through f. Output is always in the - first of the forms shown. - - - - IEEE Std 802-2001 specifies the second shown form (with hyphens) - as the canonical form for MAC addresses, and specifies the first - form (with colons) as the bit-reversed notation, so that - 08-00-2b-01-02-03 = 01:00:4D:08:04:0C. This convention is widely - ignored nowadays, and it is only relevant for obsolete network - - protocols (such as Token Ring). PostgreSQL makes no provisions - - - protocols (such as Token Ring). Postgres-XC makes no provisions - - - protocols (such as Token Ring). Postgres-XL makes no provisions - - for bit reversal, and all accepted formats use the canonical LSB - order. - - - - The remaining four input formats are not part of any standard. - - - - - - - Bit String Types - - - bit string - data type - -&common; - - Bit strings are strings of 1's and 0's. They can be used to store - or visualize bit masks. There are two SQL bit types: - bit(n) and bit - varying(n), where - n is a positive integer. - - - - bit type data must match the length - n exactly; it is an error to attempt to - store shorter or longer bit strings. bit varying data is - of variable length up to the maximum length - n; longer strings will be rejected. - Writing bit without a length is equivalent to - bit(1), while bit varying without a length - specification means unlimited length. - - - - - If one explicitly casts a bit-string value to - bit(n), it will be truncated or - zero-padded on the right to be exactly n bits, - without raising an error. Similarly, - if one explicitly casts a bit-string value to - bit varying(n), it will be truncated - on the right if it is more than n bits. - - - - - Refer to for information about the syntax - of bit string constants. Bit-logical operators and string - manipulation functions are available; see . - - - - Using the Bit String Types - - -CREATE TABLE test (a BIT(3), b BIT VARYING(5)); -INSERT INTO test VALUES (B'101', B'00'); -INSERT INTO test VALUES (B'10', B'101'); - -ERROR: bit string length 2 does not match type bit(3) - -INSERT INTO test VALUES (B'10'::bit(3), B'101'); -SELECT * FROM test; - - a | b ------+----- - 101 | 00 - 100 | 101 - - - - - - A bit string value requires 1 byte for each group of 8 bits, plus - 5 or 8 bytes overhead depending on the length of the string - (but long values may be compressed or moved out-of-line, as explained - in for character strings). - - - - - Text Search Types - - - full text search - data types - - - - text search - data types - -&common; - - - PostgreSQL provides two data types that - - - Postgres-XC inherits two data types that - - are designed to support full text search, which is the activity of - searching through a collection of natural-language documents - to locate those that best match a query. - The tsvector type represents a document in a form optimized - for text search; the tsquery type similarly represents - a text query. - provides a detailed explanation of this - facility, and summarizes the - related functions and operators. - - - - <type>tsvector</type> - - - tsvector (data type) - -&common; - - A tsvector value is a sorted list of distinct - lexemes, which are words that have been - normalized to merge different variants of the same word - (see for details). Sorting and - duplicate-elimination are done automatically during input, as shown in - this example: - - -SELECT 'a fat cat sat on a mat and ate a fat rat'::tsvector; - tsvector ----------------------------------------------------- - 'a' 'and' 'ate' 'cat' 'fat' 'mat' 'on' 'rat' 'sat' - - - To represent - lexemes containing whitespace or punctuation, surround them with quotes: - - -SELECT $$the lexeme ' ' contains spaces$$::tsvector; - tsvector -------------------------------------------- - ' ' 'contains' 'lexeme' 'spaces' 'the' - - - (We use dollar-quoted string literals in this example and the next one - to avoid the confusion of having to double quote marks within the - literals.) Embedded quotes and backslashes must be doubled: - - -SELECT $$the lexeme 'Joe''s' contains a quote$$::tsvector; - tsvector ------------------------------------------------- - 'Joe''s' 'a' 'contains' 'lexeme' 'quote' 'the' - - - Optionally, integer positions - can be attached to lexemes: - - -SELECT 'a:1 fat:2 cat:3 sat:4 on:5 a:6 mat:7 and:8 ate:9 a:10 fat:11 rat:12'::tsvector; - tsvector -------------------------------------------------------------------------------- - 'a':1,6,10 'and':8 'ate':9 'cat':3 'fat':2,11 'mat':7 'on':5 'rat':12 'sat':4 - - - A position normally indicates the source word's location in the - document. Positional information can be used for - proximity ranking. Position values can - range from 1 to 16383; larger numbers are silently set to 16383. - Duplicate positions for the same lexeme are discarded. - - - - Lexemes that have positions can further be labeled with a - weight, which can be A, - B, C, or D. - D is the default and hence is not shown on output: - - -SELECT 'a:1A fat:2B,4C cat:5D'::tsvector; - tsvector ----------------------------- - 'a':1A 'cat':5 'fat':2B,4C - - - Weights are typically used to reflect document structure, for example - by marking title words differently from body words. Text search - ranking functions can assign different priorities to the different - weight markers. - - - - It is important to understand that the - tsvector type itself does not perform any normalization; - it assumes the words it is given are normalized appropriately - for the application. For example, - - -select 'The Fat Rats'::tsvector; - tsvector --------------------- - 'Fat' 'Rats' 'The' - - - For most English-text-searching applications the above words would - be considered non-normalized, but tsvector doesn't care. - Raw document text should usually be passed through - to_tsvector to normalize the words appropriately - for searching: - - -SELECT to_tsvector('english', 'The Fat Rats'); - to_tsvector ------------------ - 'fat':2 'rat':3 - - - Again, see for more detail. - - - - - - <type>tsquery</type> - - - tsquery (data type) - -&common; - - A tsquery value stores lexemes that are to be - searched for, and combines them honoring the Boolean operators - & (AND), | (OR), and - ! (NOT). Parentheses can be used to enforce grouping - of the operators: - - -SELECT 'fat & rat'::tsquery; - tsquery ---------------- - 'fat' & 'rat' - -SELECT 'fat & (rat | cat)'::tsquery; - tsquery ---------------------------- - 'fat' & ( 'rat' | 'cat' ) - -SELECT 'fat & rat & ! cat'::tsquery; - tsquery ------------------------- - 'fat' & 'rat' & !'cat' - - - In the absence of parentheses, ! (NOT) binds most tightly, - and & (AND) binds more tightly than - | (OR). - - - - Optionally, lexemes in a tsquery can be labeled with - one or more weight letters, which restricts them to match only - tsvector lexemes with matching weights: - - -SELECT 'fat:ab & cat'::tsquery; - tsquery ------------------- - 'fat':AB & 'cat' - - - - - Also, lexemes in a tsquery can be labeled with * - to specify prefix matching: - -SELECT 'super:*'::tsquery; - tsquery ------------ - 'super':* - - This query will match any word in a tsvector that begins - with super. Note that prefixes are first processed by - text search configurations, which means this comparison returns - true: - -SELECT to_tsvector( 'postgraduate' ) @@ to_tsquery( 'postgres:*' ); - ?column? ----------- - t -(1 row) - - because postgres gets stemmed to postgr: - -SELECT to_tsquery('postgres:*'); - to_tsquery ------------- - 'postgr':* -(1 row) - - which then matches postgraduate. - - - - Quoting rules for lexemes are the same as described previously for - lexemes in tsvector; and, as with tsvector, - any required normalization of words must be done before converting - to the tsquery type. The to_tsquery - function is convenient for performing such normalization: - - -SELECT to_tsquery('Fat:ab & Cats'); - to_tsquery ------------------- - 'fat':AB & 'cat' - - - - - - - - - <acronym>UUID</acronym> Type - - - UUID - -&common; - - The data type uuid stores Universally Unique Identifiers - (UUID) as defined by RFC 4122, ISO/IEC 9834-8:2005, and related standards. - (Some systems refer to this data type as a globally unique identifier, or - GUID,GUID instead.) This - identifier is a 128-bit quantity that is generated by an algorithm chosen - to make it very unlikely that the same identifier will be generated by - anyone else in the known universe using the same algorithm. Therefore, - for distributed systems, these identifiers provide a better uniqueness - guarantee than sequence generators, which - are only unique within a single database. - - - - A UUID is written as a sequence of lower-case hexadecimal digits, - in several groups separated by hyphens, specifically a group of 8 - digits followed by three groups of 4 digits followed by a group of - 12 digits, for a total of 32 digits representing the 128 bits. An - example of a UUID in this standard form is: - -a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11 - - - PostgreSQL also accepts the following - - - Postgres-XC also accepts the following - - - Postgres-XL also accepts the following - - alternative forms for input: - use of upper-case digits, the standard format surrounded by - braces, omitting some or all hyphens, adding a hyphen after any - group of four digits. Examples are: - -A0EEBC99-9C0B-4EF8-BB6D-6BB9BD380A11 -{a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11} -a0eebc999c0b4ef8bb6d6bb9bd380a11 -a0ee-bc99-9c0b-4ef8-bb6d-6bb9-bd38-0a11 -{a0eebc99-9c0b4ef8-bb6d6bb9-bd380a11} - - Output is always in the standard form. - - - - - PostgreSQL provides storage and comparison - - - Postgres-XC provides storage and comparison - - - Postgres-XL provides storage and comparison - - functions for UUIDs, but the core database does not include any - function for generating UUIDs, because no single algorithm is well - suited for every application. The module - provides functions that implement several standard algorithms. - Alternatively, UUIDs could be generated by client applications or - other libraries invoked through a server-side function. - - - - - <acronym>XML</> Type - - - XML - -&common; - - The xml data type can be used to store XML data. Its - advantage over storing XML data in a text field is that it - checks the input values for well-formedness, and there are support - functions to perform type-safe operations on it; see . Use of this data type requires the - installation to have been built with configure - --with-libxml. - - - - The xml type can store well-formed - documents, as defined by the XML standard, as well - as content fragments, which are defined by the - production XMLDecl? content in the XML - standard. Roughly, this means that content fragments can have - more than one top-level element or character node. The expression - xmlvalue IS DOCUMENT - can be used to evaluate whether a particular xml - value is a full document or only a content fragment. - - - - Creating XML Values -&common; - - To produce a value of type xml from character data, - use the function - xmlparse:xmlparse - -XMLPARSE ( { DOCUMENT | CONTENT } value) - - Examples: -Manual...') -XMLPARSE (CONTENT 'abcbarfoo') -]]> - While this is the only way to convert character strings into XML - - values according to the SQL standard, the PostgreSQL-specific - - - values according to the SQL standard, the Postgres-XC-specific - - - values according to the SQL standard, the Postgres-XL-specific - - syntaxes: -bar' -'bar'::xml -]]> - can also be used. - - - - The xml type does not validate input values - against a document type declaration - (DTD),DTD - even when the input value specifies a DTD. - There is also currently no built-in support for validating against - other XML schema languages such as XML Schema. - - - - The inverse operation, producing a character string value from - xml, uses the function - xmlserialize:xmlserialize - -XMLSERIALIZE ( { DOCUMENT | CONTENT } value AS type ) - - type can be - character, character varying, or - text (or an alias for one of those). Again, according - to the SQL standard, this is the only way to convert between type - - xml and character types, but PostgreSQL also allows - - - xml and character types, but Postgres-XC also allows - - - xml and character types, but Postgres-XL also allows - - you to simply cast the value. - - - - When a character string value is cast to or from type - xml without going through XMLPARSE or - XMLSERIALIZE, respectively, the choice of - DOCUMENT versus CONTENT is - determined by the XML option - XML option - session configuration parameter, which can be set using the - standard command: - -SET XML OPTION { DOCUMENT | CONTENT }; - - - or the more PostgreSQL-like syntax - - - or the more Postgres-XC-like syntax - - - or the more Postgres-XL-like syntax - - -SET xmloption TO { DOCUMENT | CONTENT }; - - The default is CONTENT, so all forms of XML - data are allowed. - - - - - With the default XML option setting, you cannot directly cast - character strings to type xml if they contain a - document type declaration, because the definition of XML content - fragment does not accept them. If you need to do that, either - use XMLPARSE or change the XML option. - - - - - - - Encoding Handling -&common; - - Care must be taken when dealing with multiple character encodings - on the client, server, and in the XML data passed through them. - When using the text mode to pass queries to the server and query - - results to the client (which is the normal mode), PostgreSQL - - - results to the client (which is the normal mode), Postgres-XC - - - results to the client (which is the normal mode), Postgres-XL - - converts all character data passed between the client and the - server and vice versa to the character encoding of the respective - end; see . This includes string - representations of XML values, such as in the above examples. - This would ordinarily mean that encoding declarations contained in - XML data can become invalid as the character data is converted - to other encodings while traveling between client and server, - because the embedded encoding declaration is not changed. To cope - with this behavior, encoding declarations contained in - character strings presented for input to the xml type - are ignored, and content is assumed - to be in the current server encoding. Consequently, for correct - processing, character strings of XML data must be sent - from the client in the current client encoding. It is the - responsibility of the client to either convert documents to the - current client encoding before sending them to the server, or to - adjust the client encoding appropriately. On output, values of - type xml will not have an encoding declaration, and - clients should assume all data is in the current client - encoding. - - - - When using binary mode to pass query parameters to the server - and query results back to the client, no character set conversion - is performed, so the situation is different. In this case, an - encoding declaration in the XML data will be observed, and if it - is absent, the data will be assumed to be in UTF-8 (as required by - - the XML standard; note that PostgreSQL does not support UTF-16). - - - the XML standard; note that Postgres-XC does not support UTF-16). - - - the XML standard; note that Postgres-XL does not support UTF-16). - - On output, data will have an encoding declaration - specifying the client encoding, unless the client encoding is - UTF-8, in which case it will be omitted. - - - - - Needless to say, processing XML data with PostgreSQL will be less - - - Needless to say, processing XML data with Postgres-XC will be less - - - Needless to say, processing XML data with Postgres-XL will be less - - error-prone and more efficient if the XML data encoding, client encoding, - and server encoding are the same. Since XML data is internally - processed in UTF-8, computations will be most efficient if the - server encoding is also UTF-8. - - - - - Some XML-related functions may not work at all on non-ASCII data - when the server encoding is not UTF-8. This is known to be an - issue for xpath() in particular. - - - - - - Accessing XML Values -&common; - - The xml data type is unusual in that it does not - provide any comparison operators. This is because there is no - well-defined and universally useful comparison algorithm for XML - data. One consequence of this is that you cannot retrieve rows by - comparing an xml column against a search value. XML - values should therefore typically be accompanied by a separate key - field such as an ID. An alternative solution for comparing XML - values is to convert them to character strings first, but note - that character string comparison has little to do with a useful - XML comparison method. - - - - Since there are no comparison operators for the xml - data type, it is not possible to create an index directly on a - column of this type. If speedy searches in XML data are desired, - possible workarounds include casting the expression to a - character string type and indexing that, or indexing an XPath - expression. Of course, the actual query would have to be adjusted - to search by the indexed expression. - - - - - The text-search functionality in PostgreSQL can also be used to speed - - - The text-search functionality in Postgres-XC can also be used to speed - - - The text-search functionality in Postgres-XL can also be used to speed - - up full-document searches of XML data. The necessary - - preprocessing support is, however, not yet available in the PostgreSQL - - - preprocessing support is, however, not yet available in the Postgres-XC - - - preprocessing support is, however, not yet available in the Postgres-XL - - distribution. - - - - - &array; - - &rowtypes; - - - Object Identifier Types - - - object identifier - data type - - - - oid - - - - regproc - - - - regprocedure - - - - regoper - - - - regoperator - - - - regclass - - - - regtype - - - - regconfig - - - - regdictionary - - - - xid - - - - cid - - - - tid - -&common; - - Object identifiers (OIDs) are used internally by - - PostgreSQL as primary keys for various - - - Postgres-XC as primary keys for various - - - Postgres-XL as primary keys for various - - system tables. OIDs are not added to user-created tables, unless - WITH OIDS is specified when the table is - created, or the - configuration variable is enabled. Type oid represents - an object identifier. There are also several alias types for - oid: regproc, regprocedure, - regoper, regoperator, regclass, - regtype, regconfig, and regdictionary. - shows an overview. - - - - The oid type is currently implemented as an unsigned - four-byte integer. Therefore, it is not large enough to provide - database-wide uniqueness in large databases, or even in large - individual tables. So, using a user-created table's OID column as - a primary key is discouraged. OIDs are best used only for - references to system tables. - - - - The oid type itself has few operations beyond comparison. - It can be cast to integer, however, and then manipulated using the - standard integer operators. (Beware of possible - signed-versus-unsigned confusion if you do this.) - - - - The OID alias types have no operations of their own except - for specialized input and output routines. These routines are able - to accept and display symbolic names for system objects, rather than - the raw numeric value that type oid would use. The alias - types allow simplified lookup of OID values for objects. For example, - to examine the pg_attribute rows related to a table - mytable, one could write: - -SELECT * FROM pg_attribute WHERE attrelid = 'mytable'::regclass; - - rather than: - -SELECT * FROM pg_attribute - WHERE attrelid = (SELECT oid FROM pg_class WHERE relname = 'mytable'); - - While that doesn't look all that bad by itself, it's still oversimplified. - A far more complicated sub-select would be needed to - select the right OID if there are multiple tables named - mytable in different schemas. - The regclass input converter handles the table lookup according - to the schema path setting, and so it does the right thing - automatically. Similarly, casting a table's OID to - regclass is handy for symbolic display of a numeric OID. - - - - Object Identifier Types - - - - Name - References - Description - Value Example - - - - - - - oid - any - numeric object identifier - 564182 - - - - regproc - pg_proc - function name - sum - - - - regprocedure - pg_proc - function with argument types - sum(int4) - - - - regoper - pg_operator - operator name - + - - - - regoperator - pg_operator - operator with argument types - *(integer,integer) or -(NONE,integer) - - - - regclass - pg_class - relation name - pg_type - - - - regtype - pg_type - data type name - integer - - - - regconfig - pg_ts_config - text search configuration - english - - - - regdictionary - pg_ts_dict - text search dictionary - simple - - - -
- - - All of the OID alias types accept schema-qualified names, and will - display schema-qualified names on output if the object would not - be found in the current search path without being qualified. - The regproc and regoper alias types will only - accept input names that are unique (not overloaded), so they are - of limited use; for most uses regprocedure or - regoperator are more appropriate. For regoperator, - unary operators are identified by writing NONE for the unused - operand. - - - - An additional property of the OID alias types is the creation of - dependencies. If a - constant of one of these types appears in a stored expression - (such as a column default expression or view), it creates a dependency - on the referenced object. For example, if a column has a default - expression nextval('my_seq'::regclass), - - PostgreSQL - - - Postgres-XC - - - Postgres-XL - - understands that the default expression depends on the sequence - my_seq; the system will not let the sequence be dropped - without first removing the default expression. - - - - Another identifier type used by the system is xid, or transaction - (abbreviated xact) identifier. This is the data type of the system columns - xmin and xmax. Transaction identifiers are 32-bit quantities. - - - - A third identifier type used by the system is cid, or - command identifier. This is the data type of the system columns - cmin and cmax. Command identifiers are also 32-bit quantities. - - - - A final identifier type used by the system is tid, or tuple - identifier (row identifier). This is the data type of the system column - ctid. A tuple ID is a pair - (block number, tuple index within block) that identifies the - physical location of the row within its table. - - - - (The system columns are further explained in .) - - - - Please note that Postgres-XC enforces OID identity only locally. - Different object at different Coordinator or Datanode may be assigned the same - OID value. - - - - - Please note that Postgres-XL enforces OID identity only locally. - Different object at different Coordinator or Datanode may be assigned the same - OID value. - - - - - - Pseudo-Types - - - record - - - - any - - - - anyelement - - - - anyarray - - - - anynonarray - - - - anyenum - - - - void - - - - trigger - - - - language_handler - - - - fdw_handler - - - - cstring - - - - internal - - - - opaque - -&common; - - - The PostgreSQL type system contains a - - - The Postgres-XC type system contains a - - - The Postgres-XL type system contains a - - number of special-purpose entries that are collectively called - pseudo-types. A pseudo-type cannot be used as a - column data type, but it can be used to declare a function's - argument or result type. Each of the available pseudo-types is - useful in situations where a function's behavior does not - correspond to simply taking or returning a value of a specific - SQL data type. lists the existing - pseudo-types. - - - - Pseudo-Types - - - - Name - Description - - - - - - any - Indicates that a function accepts any input data type. - - - - anyarray - Indicates that a function accepts any array data type - (see ). - - - - anyelement - Indicates that a function accepts any data type - (see ). - - - - anyenum - Indicates that a function accepts any enum data type - (see and - ). - - - - anynonarray - Indicates that a function accepts any non-array data type - (see ). - - - - cstring - Indicates that a function accepts or returns a null-terminated C string. - - - - internal - Indicates that a function accepts or returns a server-internal - data type. - - - - language_handler - A procedural language call handler is declared to return language_handler. - - - - fdw_handler - A foreign-data wrapper handler is declared to return fdw_handler. - - - - record - Identifies a function returning an unspecified row type. - - - - trigger - A trigger function is declared to return trigger. - - - - void - Indicates that a function returns no value. - - - - opaque - An obsolete type name that formerly served all the above purposes. - - - -
- - - Functions coded in C (whether built-in or dynamically loaded) can be - declared to accept or return any of these pseudo data types. It is up to - the function author to ensure that the function will behave safely - when a pseudo-type is used as an argument type. - - - - Functions coded in procedural languages can use pseudo-types only as - allowed by their implementation languages. At present the procedural - languages all forbid use of a pseudo-type as argument type, and allow - only void and record as a result type (plus - trigger when the function is used as a trigger). Some also - support polymorphic functions using the types anyarray, - anyelement, anyenum, and anynonarray. - - - - The internal pseudo-type is used to declare functions - that are meant only to be called internally by the database - system, and not by direct invocation in an SQL - query. If a function has at least one internal-type - argument then it cannot be called from SQL. To - preserve the type safety of this restriction it is important to - follow this coding rule: do not create any function that is - declared to return internal unless it has at least one - internal argument. - - - - - diff --git a/doc-xc/src/sgml/datetime.sgmlin b/doc-xc/src/sgml/datetime.sgmlin deleted file mode 100644 index 41c0f9dd4c..0000000000 --- a/doc-xc/src/sgml/datetime.sgmlin +++ /dev/null @@ -1,633 +0,0 @@ - - - - Date/Time Support -&common; - - - PostgreSQL uses an internal heuristic - parser for all date/time input support. Dates and times are input as - - - Postgres-XC inherits uses an internal heuristic - parser from PostgreSQL for all date/time input support. Dates and times are input as - - - Postgres-XL inherits uses an internal heuristic - parser from PostgreSQL for all date/time input support. Dates and times are input as - - strings, and are broken up into distinct fields with a preliminary - determination of what kind of information can be in the - field. Each field is interpreted and either assigned a numeric - value, ignored, or rejected. - The parser contains internal lookup tables for all textual fields, - including months, days of the week, and time zones. - - - - This appendix includes information on the content of these - lookup tables and describes the steps used by the parser to decode - dates and times. - - - - Date/Time Input Interpretation - -&common; - - The date/time type inputs are all decoded using the following procedure. - - - - - - Break the input string into tokens and categorize each token as - a string, time, time zone, or number. - - - - - - If the numeric token contains a colon (:), this is - a time string. Include all subsequent digits and colons. - - - - - - If the numeric token contains a dash (-), slash - (/), or two or more dots (.), this is - a date string which might have a text month. If a date token has - already been seen, it is instead interpreted as a time zone - name (e.g., America/New_York). - - - - - - If the token is numeric only, then it is either a single field - or an ISO 8601 concatenated date (e.g., - 19990113 for January 13, 1999) or time - (e.g., 141516 for 14:15:16). - - - - - - If the token starts with a plus (+) or minus - (-), then it is either a numeric time zone or a special - field. - - - - - - - - If the token is a text string, match up with possible strings: - - - - - - Do a binary-search table lookup for the token as a time zone - abbreviation. - - - - - - If not found, do a similar binary-search table lookup to match - the token as either a special string (e.g., today), - day (e.g., Thursday), - month (e.g., January), - or noise word (e.g., at, on). - - - - - - If still not found, throw an error. - - - - - - - - When the token is a number or number field: - - - - - - If there are eight or six digits, - and if no other date fields have been previously read, then interpret - as a concatenated date (e.g., - 19990118 or 990118). - The interpretation is YYYYMMDD or YYMMDD. - - - - - - If the token is three digits - and a year has already been read, then interpret as day of year. - - - - - - If four or six digits and a year has already been read, then - interpret as a time (HHMM or HHMMSS). - - - - - - If three or more digits and no date fields have yet been found, - interpret as a year (this forces yy-mm-dd ordering of the remaining - date fields). - - - - - - Otherwise the date field ordering is assumed to follow the - DateStyle setting: mm-dd-yy, dd-mm-yy, or yy-mm-dd. - Throw an error if a month or day field is found to be out of range. - - - - - - - - If BC has been specified, negate the year and add one for - internal storage. (There is no year zero in the Gregorian - calendar, so numerically 1 BC becomes year zero.) - - - - - - If BC was not specified, and if the year field was two digits in length, - then adjust the year to four digits. If the field is less than 70, then - add 2000, otherwise add 1900. - - - - Gregorian years AD 1-99 can be entered by using 4 digits with leading - zeros (e.g., 0099 is AD 99). - - - - - - - - - - Date/Time Key Words - -&common; - - shows the tokens that are - recognized as names of months. - - - - Month Names - - - - Month - Abbreviations - - - - - January - Jan - - - February - Feb - - - March - Mar - - - April - Apr - - - May - - - - June - Jun - - - July - Jul - - - August - Aug - - - September - Sep, Sept - - - October - Oct - - - November - Nov - - - December - Dec - - - -
- - - shows the tokens that are - recognized as names of days of the week. - - - - Day of the Week Names - - - - Day - Abbreviations - - - - - Sunday - Sun - - - Monday - Mon - - - Tuesday - Tue, Tues - - - Wednesday - Wed, Weds - - - Thursday - Thu, Thur, Thurs - - - Friday - Fri - - - Saturday - Sat - - - -
- - - shows the tokens that serve - various modifier purposes. - - - - Date/Time Field Modifiers - - - - Identifier - Description - - - - - AM - Time is before 12:00 - - - AT - Ignored - - - JULIAN, JD, J - Next field is Julian Day - - - ON - Ignored - - - PM - Time is on or after 12:00 - - - T - Next field is time - - - -
- - - - Date/Time Configuration Files - - - time zone - input abbreviations - - -&common; - - Since timezone abbreviations are not well standardized, - - PostgreSQL provides a means to customize - - - Postgres-XC provides a means to customize - - - Postgres-XL provides a means to customize - - the set of abbreviations accepted by the server. The - run-time parameter - determines the active set of abbreviations. While this parameter - can be altered by any database user, the possible values for it - are under the control of the database administrator — they - are in fact names of configuration files stored in - .../share/timezonesets/ of the installation directory. - By adding or altering files in that directory, the administrator - can set local policy for timezone abbreviations. - - - - timezone_abbreviations can be set to any file name - found in .../share/timezonesets/, if the file's name - is entirely alphabetic. (The prohibition against non-alphabetic - characters in timezone_abbreviations prevents reading - files outside the intended directory, as well as reading editor - backup files and other extraneous files.) - - - - A timezone abbreviation file can contain blank lines and comments - beginning with #. Non-comment lines must have one of - these formats: - - -time_zone_name offset -time_zone_name offset D -@INCLUDE file_name -@OVERRIDE - - - - - A time_zone_name is just the abbreviation - being defined. The offset is the zone's - offset in seconds from UTC, positive being east from Greenwich and - negative being west. For example, -18000 would be five hours west - of Greenwich, or North American east coast standard time. D - indicates that the zone name represents local daylight-savings time - rather than standard time. Since all known time zone offsets are on - 15 minute boundaries, the number of seconds has to be a multiple of 900. - - - - The @INCLUDE syntax allows inclusion of another file in the - .../share/timezonesets/ directory. Inclusion can be nested, - to a limited depth. - - - - The @OVERRIDE syntax indicates that subsequent entries in the - file can override previous entries (i.e., entries obtained from included - files). Without this, conflicting definitions of the same timezone - abbreviation are considered an error. - - - - In an unmodified installation, the file Default contains - all the non-conflicting time zone abbreviations for most of the world. - Additional files Australia and India are - provided for those regions: these files first include the - Default file and then add or modify timezones as needed. - - - - For reference purposes, a standard installation also contains files - Africa.txt, America.txt, etc, containing - information about every time zone abbreviation known to be in use - according to the zoneinfo timezone database. The zone name - definitions found in these files can be copied and pasted into a custom - configuration file as needed. Note that these files cannot be directly - referenced as timezone_abbreviations settings, because of - the dot embedded in their names. - - - - - If an error occurs while reading the time zone data sets, no new value is - applied but the old set is kept. If the error occurs while starting the - database, startup fails. - - - - - - Time zone abbreviations defined in the configuration file override - - non-timezone meanings built into PostgreSQL. - - - non-timezone meanings built into Postgres-XC. - - - non-timezone meanings built into Postgres-XL. - - For example, the Australia configuration file defines - SAT (for South Australian Standard Time). When this - file is active, SAT will not be recognized as an abbreviation - for Saturday. - - - - - - If you modify files in .../share/timezonesets/, - it is up to you to make backups — a normal database dump - will not include this directory. - - - - - - - History of Units - -&common; - - The Julian calendar was introduced by Julius Caesar in 45 BC. - It was in common use in the Western world - until the year 1582, when countries started changing to the Gregorian - calendar. In the Julian calendar, the tropical year is - approximated as 365 1/4 days = 365.25 days. This gives an error of - about 1 day in 128 years. - - - - The accumulating calendar error prompted - Pope Gregory XIII to reform the calendar in accordance with - instructions from the Council of Trent. - In the Gregorian calendar, the tropical year is approximated as - 365 + 97 / 400 days = 365.2425 days. Thus it takes approximately 3300 - years for the tropical year to shift one day with respect to the - Gregorian calendar. - - - - The approximation 365+97/400 is achieved by having 97 leap years - every 400 years, using the following rules: - - - - Every year divisible by 4 is a leap year. - - - However, every year divisible by 100 is not a leap year. - - - However, every year divisible by 400 is a leap year after all. - - - - So, 1700, 1800, 1900, 2100, and 2200 are not leap years. But 1600, - 2000, and 2400 are leap years. - - By contrast, in the older Julian calendar all years divisible by 4 are leap - years. - - - - The papal bull of February 1582 decreed that 10 days should be dropped - from October 1582 so that 15 October should follow immediately after - 4 October. - This was observed in Italy, Poland, Portugal, and Spain. Other Catholic - countries followed shortly after, but Protestant countries were - reluctant to change, and the Greek Orthodox countries didn't change - until the start of the 20th century. - - The reform was observed by Great Britain and Dominions (including what is - now the USA) in 1752. - Thus 2 September 1752 was followed by 14 September 1752. - - This is why Unix systems have the cal program - produce the following: - - -$ cal 9 1752 - September 1752 - S M Tu W Th F S - 1 2 14 15 16 -17 18 19 20 21 22 23 -24 25 26 27 28 29 30 - - - - - The SQL standard states that Within the definition of a - datetime literal, the datetime - values are constrained by the natural rules for dates and - times according to the Gregorian calendar. Dates between - 1582-10-05 and 1582-10-14, although eliminated in some countries - by Papal fiat, conform to natural rules and are - - hence valid dates. PostgreSQL follows the SQL - - - hence valid dates. Postgres-XC follows the SQL - - - hence valid dates. Postgres-XL follows the SQL - - standard's lead by counting dates exclusively in the Gregorian - calendar, even for years before that calendar was in use. - - - - Different calendars have been developed in various parts of the - world, many predating the Gregorian system. - - For example, - the beginnings of the Chinese calendar can be traced back to the 14th - century BC. Legend has it that the Emperor Huangdi invented that - calendar in 2637 BC. - - The People's Republic of China uses the Gregorian calendar - for civil purposes. The Chinese calendar is used for determining - festivals. - - - - The Julian Date is unrelated to the Julian - calendar. - The Julian Date system was invented by the French scholar - Joseph Justus Scaliger (1540-1609) - and probably takes its name from Scaliger's father, - the Italian scholar Julius Caesar Scaliger (1484-1558). - In the Julian Date system, each day has a sequential number, starting - from JD 0 (which is sometimes called the Julian Date). - JD 0 corresponds to 1 January 4713 BC in the Julian calendar, or - 24 November 4714 BC in the Gregorian calendar. Julian Date counting - is most often used by astronomers for labeling their nightly observations, - and therefore a date runs from noon UTC to the next noon UTC, rather than - from midnight to midnight: JD 0 designates the 24 hours from noon UTC on - 1 January 4713 BC to noon UTC on 2 January 4713 BC. - - - - - Although PostgreSQL supports Julian Date notation for - - - Although Postgres-XC supports Julian Date notation for - - - Although Postgres-XL supports Julian Date notation for - - input and output of dates (and also uses them for some internal datetime - calculations), it does not observe the nicety of having dates run from - - noon to noon. PostgreSQL treats a Julian Date as running - - - noon to noon. Postgres-XC treats a Julian Date as running - - - noon to noon. Postgres-XL treats a Julian Date as running - - from midnight to midnight. - - - - diff --git a/doc-xc/src/sgml/dblink.sgmlin b/doc-xc/src/sgml/dblink.sgmlin deleted file mode 100644 index 28efce19a2..0000000000 --- a/doc-xc/src/sgml/dblink.sgmlin +++ /dev/null @@ -1,2717 +0,0 @@ - - - - dblink - - - dblink - - - -&xconly; - - dblink module has not been tested - with Postges-XC yet. Although there're no reason - that dblink does not run - in Postgres-XC, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - - -&xlonly; - - dblink module has not been tested - with Postges-XL yet. Although there're no reason - that dblink does not run - in Postgres-XL, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - - -&pgonly; - - dblink is a module which supports connections to - other PostgreSQL databases from within a database - session. - - - - - dblink_connect - 3 - - - - dblink_connect - opens a persistent connection to a remote database - - - - -dblink_connect(text connstr) returns text -dblink_connect(text connname, text connstr) returns text - - - - - Description - -&xconly; - - dblink module has not been tested - with Postges-XC yet. Although there're no reason - that dblink does not run - in Postgres-XC, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - - -&xlonly; - - dblink module has not been tested - with Postges-XL yet. Although there're no reason - that dblink does not run - in Postgres-XL, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - -&pgonly; - - dblink_connect() establishes a connection to a remote - PostgreSQL database. The server and database to - be contacted are identified through a standard libpq - connection string. Optionally, a name can be assigned to the - connection. Multiple named connections can be open at once, but - only one unnamed connection is permitted at a time. The connection - will persist until closed or until the database session is ended. - - - - The connection string may also be the name of an existing foreign - server. It is recommended to use - the postgresql_fdw_validator when defining - the corresponding foreign-data wrapper. See the example below, as - well as the following: - - - - - - - - - - - Arguments -&pgonly; - - - conname - - - The name to use for this connection; if omitted, an unnamed - connection is opened, replacing any existing unnamed connection. - - - - - - connstr - - - libpq-style connection info string, for example - hostaddr=127.0.0.1 port=5432 dbname=mydb user=postgres - password=mypasswd. - For details see PQconnectdb in - . - - - - - - - - Return Value -&pgonly; - - Returns status, which is always OK (since any error - causes the function to throw an error instead of returning). - - - - - Notes -&pgonly; - - Only superusers may use dblink_connect to create - non-password-authenticated connections. If non-superusers need this - capability, use dblink_connect_u instead. - - - - It is unwise to choose connection names that contain equal signs, - as this opens a risk of confusion with connection info strings - in other dblink functions. - - - - - Example -&pgonly; - -SELECT dblink_connect('dbname=postgres'); - dblink_connect ----------------- - OK -(1 row) - -SELECT dblink_connect('myconn', 'dbname=postgres'); - dblink_connect ----------------- - OK -(1 row) - --- FOREIGN DATA WRAPPER functionality --- Note: local connection must require password authentication for this to work properly --- Otherwise, you will receive the following error from dblink_connect(): --- ---------------------------------------------------------------------- --- ERROR: password is required --- DETAIL: Non-superuser cannot connect if the server does not request a password. --- HINT: Target server's authentication method must be changed. -CREATE USER dblink_regression_test WITH PASSWORD 'secret'; -CREATE FOREIGN DATA WRAPPER postgresql VALIDATOR postgresql_fdw_validator; -CREATE SERVER fdtest FOREIGN DATA WRAPPER postgresql OPTIONS (hostaddr '127.0.0.1', dbname 'contrib_regression'); - -CREATE USER MAPPING FOR dblink_regression_test SERVER fdtest OPTIONS (user 'dblink_regression_test', password 'secret'); -GRANT USAGE ON FOREIGN SERVER fdtest TO dblink_regression_test; -GRANT SELECT ON TABLE foo TO dblink_regression_test; - -\set ORIGINAL_USER :USER -\c - dblink_regression_test -SELECT dblink_connect('myconn', 'fdtest'); - dblink_connect ----------------- - OK -(1 row) - -SELECT * FROM dblink('myconn','SELECT * FROM foo') AS t(a int, b text, c text[]); - a | b | c -----+---+--------------- - 0 | a | {a0,b0,c0} - 1 | b | {a1,b1,c1} - 2 | c | {a2,b2,c2} - 3 | d | {a3,b3,c3} - 4 | e | {a4,b4,c4} - 5 | f | {a5,b5,c5} - 6 | g | {a6,b6,c6} - 7 | h | {a7,b7,c7} - 8 | i | {a8,b8,c8} - 9 | j | {a9,b9,c9} - 10 | k | {a10,b10,c10} -(11 rows) - -\c - :ORIGINAL_USER -REVOKE USAGE ON FOREIGN SERVER fdtest FROM dblink_regression_test; -REVOKE SELECT ON TABLE foo FROM dblink_regression_test; -DROP USER MAPPING FOR dblink_regression_test SERVER fdtest; -DROP USER dblink_regression_test; -DROP SERVER fdtest; -DROP FOREIGN DATA WRAPPER postgresql; - - - - - - - dblink_connect_u - 3 - - - - dblink_connect_u - opens a persistent connection to a remote database, insecurely - - - - -dblink_connect_u(text connstr) returns text -dblink_connect_u(text connname, text connstr) returns text - - - - - Description - -&xconly; - - dblink module has not been tested - with Postges-XC yet. Although there're no reason - that dblink does not run - in Postgres-XC, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - - -&xlonly; - - dblink module has not been tested - with Postges-XL yet. Although there're no reason - that dblink does not run - in Postgres-XL, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - -&pgonly; - - dblink_connect_u() is identical to - dblink_connect(), except that it will allow non-superusers - to connect using any authentication method. - - - - If the remote server selects an authentication method that does not - involve a password, then impersonation and subsequent escalation of - privileges can occur, because the session will appear to have - originated from the user as which the local PostgreSQL - server runs. Also, even if the remote server does demand a password, - it is possible for the password to be supplied from the server - environment, such as a ~/.pgpass file belonging to the - server's user. This opens not only a risk of impersonation, but the - possibility of exposing a password to an untrustworthy remote server. - Therefore, dblink_connect_u() is initially - installed with all privileges revoked from PUBLIC, - making it un-callable except by superusers. In some situations - it may be appropriate to grant EXECUTE permission for - dblink_connect_u() to specific users who are considered - trustworthy, but this should be done with care. It is also recommended - that any ~/.pgpass file belonging to the server's user - not contain any records specifying a wildcard host name. - - - - For further details see dblink_connect(). - - - - - - - dblink_disconnect - 3 - - - - dblink_disconnect - closes a persistent connection to a remote database - - - - -dblink_disconnect() returns text -dblink_disconnect(text connname) returns text - - - - - Description - -&xconly; - - dblink module has not been tested - with Postges-XC yet. Although there're no reason - that dblink does not run - in Postgres-XC, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - - -&xlonly; - - dblink module has not been tested - with Postges-XL yet. Although there're no reason - that dblink does not run - in Postgres-XL, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - -&pgonly; - - dblink_disconnect() closes a connection previously opened - by dblink_connect(). The form with no arguments closes - an unnamed connection. - - - - - Arguments -&pgonly; - - - conname - - - The name of a named connection to be closed. - - - - - - - - Return Value -&pgonly; - - Returns status, which is always OK (since any error - causes the function to throw an error instead of returning). - - - - - Example -&pgonly; - - -SELECT dblink_disconnect(); - dblink_disconnect -------------------- - OK -(1 row) - -SELECT dblink_disconnect('myconn'); - dblink_disconnect -------------------- - OK -(1 row) - - - - - - - dblink - 3 - - - - dblink - executes a query in a remote database - - - - -dblink(text connname, text sql [, bool fail_on_error]) returns setof record -dblink(text connstr, text sql [, bool fail_on_error]) returns setof record -dblink(text sql [, bool fail_on_error]) returns setof record - - - - - Description - -&xconly; - - dblink module has not been tested - with Postges-XC yet. Although there're no reason - that dblink does not run - in Postgres-XC, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - - -&xlonly; - - dblink module has not been tested - with Postges-XL yet. Although there're no reason - that dblink does not run - in Postgres-XL, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - -&pgonly; - - - dblink executes a query (usually a SELECT, - but it can be any SQL statement that returns rows) in a remote database. - - - - When two text arguments are given, the first one is first - looked up as a persistent connection's name; if found, the command - is executed on that connection. If not found, the first argument - is treated as a connection info string as for dblink_connect, - and the indicated connection is made just for the duration of this command. - - - - - Arguments -&pgonly; - - - - conname - - - Name of the connection to use; omit this parameter to use the - unnamed connection. - - - - - - connstr - - - A connection info string, as previously described for - dblink_connect. - - - - - - sql - - - The SQL query that you wish to execute in the remote database, - for example select * from foo. - - - - - - fail_on_error - - - If true (the default when omitted) then an error thrown on the - remote side of the connection causes an error to also be thrown - locally. If false, the remote error is locally reported as a NOTICE, - and the function returns no rows. - - - - - - - - Return Value -&pgonly; - - - The function returns the row(s) produced by the query. Since - dblink can be used with any query, it is declared - to return record, rather than specifying any particular - set of columns. This means that you must specify the expected - set of columns in the calling query — otherwise - PostgreSQL would not know what to expect. - Here is an example: - - -SELECT * - FROM dblink('dbname=mydb', 'select proname, prosrc from pg_proc') - AS t1(proname name, prosrc text) - WHERE proname LIKE 'bytea%'; - - - The alias part of the FROM clause must - specify the column names and types that the function will return. - (Specifying column names in an alias is actually standard SQL - syntax, but specifying column types is a PostgreSQL - extension.) This allows the system to understand what - * should expand to, and what proname - in the WHERE clause refers to, in advance of trying - to execute the function. At run time, an error will be thrown - if the actual query result from the remote database does not - have the same number of columns shown in the FROM clause. - The column names need not match, however, and dblink - does not insist on exact type matches either. It will succeed - so long as the returned data strings are valid input for the - column type declared in the FROM clause. - - - - - Notes -&pgonly; - - - dblink fetches the entire remote query result before - returning any of it to the local system. If the query is expected - to return a large number of rows, it's better to open it as a cursor - with dblink_open and then fetch a manageable number - of rows at a time. - - - - A convenient way to use dblink with predetermined - queries is to create a view. - This allows the column type information to be buried in the view, - instead of having to spell it out in every query. For example, - - -CREATE VIEW myremote_pg_proc AS - SELECT * - FROM dblink('dbname=postgres', 'select proname, prosrc from pg_proc') - AS t1(proname name, prosrc text); - -SELECT * FROM myremote_pg_proc WHERE proname LIKE 'bytea%'; - - - - - - Example -&pgonly; - - -SELECT * FROM dblink('dbname=postgres', 'select proname, prosrc from pg_proc') - AS t1(proname name, prosrc text) WHERE proname LIKE 'bytea%'; - proname | prosrc -------------+------------ - byteacat | byteacat - byteaeq | byteaeq - bytealt | bytealt - byteale | byteale - byteagt | byteagt - byteage | byteage - byteane | byteane - byteacmp | byteacmp - bytealike | bytealike - byteanlike | byteanlike - byteain | byteain - byteaout | byteaout -(12 rows) - -SELECT dblink_connect('dbname=postgres'); - dblink_connect ----------------- - OK -(1 row) - -SELECT * FROM dblink('select proname, prosrc from pg_proc') - AS t1(proname name, prosrc text) WHERE proname LIKE 'bytea%'; - proname | prosrc -------------+------------ - byteacat | byteacat - byteaeq | byteaeq - bytealt | bytealt - byteale | byteale - byteagt | byteagt - byteage | byteage - byteane | byteane - byteacmp | byteacmp - bytealike | bytealike - byteanlike | byteanlike - byteain | byteain - byteaout | byteaout -(12 rows) - -SELECT dblink_connect('myconn', 'dbname=regression'); - dblink_connect ----------------- - OK -(1 row) - -SELECT * FROM dblink('myconn', 'select proname, prosrc from pg_proc') - AS t1(proname name, prosrc text) WHERE proname LIKE 'bytea%'; - proname | prosrc -------------+------------ - bytearecv | bytearecv - byteasend | byteasend - byteale | byteale - byteagt | byteagt - byteage | byteage - byteane | byteane - byteacmp | byteacmp - bytealike | bytealike - byteanlike | byteanlike - byteacat | byteacat - byteaeq | byteaeq - bytealt | bytealt - byteain | byteain - byteaout | byteaout -(14 rows) - - - - - - - dblink_exec - 3 - - - - dblink_exec - executes a command in a remote database - - - - -dblink_exec(text connname, text sql [, bool fail_on_error]) returns text -dblink_exec(text connstr, text sql [, bool fail_on_error]) returns text -dblink_exec(text sql [, bool fail_on_error]) returns text - - - - - Description - -&xconly; - - dblink module has not been tested - with Postges-XC yet. Although there're no reason - that dblink does not run - in Postgres-XC, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - - -&xlonly; - - dblink module has not been tested - with Postges-XL yet. Although there're no reason - that dblink does not run - in Postgres-XL, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - -&pgonly; - - - dblink_exec executes a command (that is, any SQL statement - that doesn't return rows) in a remote database. - - - - When two text arguments are given, the first one is first - looked up as a persistent connection's name; if found, the command - is executed on that connection. If not found, the first argument - is treated as a connection info string as for dblink_connect, - and the indicated connection is made just for the duration of this command. - - - - - Arguments -&pgonly; - - - - conname - - - Name of the connection to use; omit this parameter to use the - unnamed connection. - - - - - - connstr - - - A connection info string, as previously described for - dblink_connect. - - - - - - sql - - - The SQL command that you wish to execute in the remote database, - for example - insert into foo values(0,'a','{"a0","b0","c0"}'). - - - - - - fail_on_error - - - If true (the default when omitted) then an error thrown on the - remote side of the connection causes an error to also be thrown - locally. If false, the remote error is locally reported as a NOTICE, - and the function's return value is set to ERROR. - - - - - - - - Return Value -&pgonly; - - - Returns status, either the command's status string or ERROR. - - - - - Example -&pgonly; - - -SELECT dblink_connect('dbname=dblink_test_standby'); - dblink_connect ----------------- - OK -(1 row) - -SELECT dblink_exec('insert into foo values(21,''z'',''{"a0","b0","c0"}'');'); - dblink_exec ------------------ - INSERT 943366 1 -(1 row) - -SELECT dblink_connect('myconn', 'dbname=regression'); - dblink_connect ----------------- - OK -(1 row) - -SELECT dblink_exec('myconn', 'insert into foo values(21,''z'',''{"a0","b0","c0"}'');'); - dblink_exec ------------------- - INSERT 6432584 1 -(1 row) - -SELECT dblink_exec('myconn', 'insert into pg_class values (''foo'')',false); -NOTICE: sql error -DETAIL: ERROR: null value in column "relnamespace" violates not-null constraint - - dblink_exec -------------- - ERROR -(1 row) - - - - - - - dblink_open - 3 - - - - dblink_open - opens a cursor in a remote database - - - - -dblink_open(text cursorname, text sql [, bool fail_on_error]) returns text -dblink_open(text connname, text cursorname, text sql [, bool fail_on_error]) returns text - - - - - Description - -&xconly; - - dblink module has not been tested - with Postges-XC yet. Although there're no reason - that dblink does not run - in Postgres-XC, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - - -&xlonly; - - dblink module has not been tested - with Postges-XL yet. Although there're no reason - that dblink does not run - in Postgres-XL, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - -&pgonly; - - - dblink_open() opens a cursor in a remote database. - The cursor can subsequently be manipulated with - dblink_fetch() and dblink_close(). - - - - - Arguments -&pgonly; - - - - conname - - - Name of the connection to use; omit this parameter to use the - unnamed connection. - - - - - - cursorname - - - The name to assign to this cursor. - - - - - - sql - - - The SELECT statement that you wish to execute in the remote - database, for example select * from pg_class. - - - - - - fail_on_error - - - If true (the default when omitted) then an error thrown on the - remote side of the connection causes an error to also be thrown - locally. If false, the remote error is locally reported as a NOTICE, - and the function's return value is set to ERROR. - - - - - - - - Return Value -&pgonly; - - - Returns status, either OK or ERROR. - - - - - Notes -&pgonly; - - - Since a cursor can only persist within a transaction, - dblink_open starts an explicit transaction block - (BEGIN) on the remote side, if the remote side was - not already within a transaction. This transaction will be - closed again when the matching dblink_close is - executed. Note that if - you use dblink_exec to change data between - dblink_open and dblink_close, - and then an error occurs or you use dblink_disconnect before - dblink_close, your change will be - lost because the transaction will be aborted. - - - - - Example -&pgonly; - - -SELECT dblink_connect('dbname=postgres'); - dblink_connect ----------------- - OK -(1 row) - -SELECT dblink_open('foo', 'select proname, prosrc from pg_proc'); - dblink_open -------------- - OK -(1 row) - - - - - - - dblink_fetch - 3 - - - - dblink_fetch - returns rows from an open cursor in a remote database - - - - -dblink_fetch(text cursorname, int howmany [, bool fail_on_error]) returns setof record -dblink_fetch(text connname, text cursorname, int howmany [, bool fail_on_error]) returns setof record - - - - - Description - -&xconly; - - dblink module has not been tested - with Postges-XC yet. Although there're no reason - that dblink does not run - in Postgres-XC, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - - -&xlonly; - - dblink module has not been tested - with Postges-XL yet. Although there're no reason - that dblink does not run - in Postgres-XL, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - -&pgonly; - - - dblink_fetch fetches rows from a cursor previously - established by dblink_open. - - - - - Arguments -&pgonly; - - - - conname - - - Name of the connection to use; omit this parameter to use the - unnamed connection. - - - - - - cursorname - - - The name of the cursor to fetch from. - - - - - - howmany - - - The maximum number of rows to retrieve. The next howmany - rows are fetched, starting at the current cursor position, moving - forward. Once the cursor has reached its end, no more rows are produced. - - - - - - fail_on_error - - - If true (the default when omitted) then an error thrown on the - remote side of the connection causes an error to also be thrown - locally. If false, the remote error is locally reported as a NOTICE, - and the function returns no rows. - - - - - - - - Return Value -&pgonly; - - - The function returns the row(s) fetched from the cursor. To use this - function, you will need to specify the expected set of columns, - as previously discussed for dblink. - - - - - Notes -&pgonly; - - - On a mismatch between the number of return columns specified in the - FROM clause, and the actual number of columns returned by the - remote cursor, an error will be thrown. In this event, the remote cursor - is still advanced by as many rows as it would have been if the error had - not occurred. The same is true for any other error occurring in the local - query after the remote FETCH has been done. - - - - - Example -&pgonly; - - -SELECT dblink_connect('dbname=postgres'); - dblink_connect ----------------- - OK -(1 row) - -SELECT dblink_open('foo', 'select proname, prosrc from pg_proc where proname like ''bytea%'''); - dblink_open -------------- - OK -(1 row) - -SELECT * FROM dblink_fetch('foo', 5) AS (funcname name, source text); - funcname | source -----------+---------- - byteacat | byteacat - byteacmp | byteacmp - byteaeq | byteaeq - byteage | byteage - byteagt | byteagt -(5 rows) - -SELECT * FROM dblink_fetch('foo', 5) AS (funcname name, source text); - funcname | source ------------+----------- - byteain | byteain - byteale | byteale - bytealike | bytealike - bytealt | bytealt - byteane | byteane -(5 rows) - -SELECT * FROM dblink_fetch('foo', 5) AS (funcname name, source text); - funcname | source -------------+------------ - byteanlike | byteanlike - byteaout | byteaout -(2 rows) - -SELECT * FROM dblink_fetch('foo', 5) AS (funcname name, source text); - funcname | source -----------+-------- -(0 rows) - - - - - - - dblink_close - 3 - - - - dblink_close - closes a cursor in a remote database - - - - -dblink_close(text cursorname [, bool fail_on_error]) returns text -dblink_close(text connname, text cursorname [, bool fail_on_error]) returns text - - - - - Description - -&xconly; - - dblink module has not been tested - with Postges-XC yet. Although there're no reason - that dblink does not run - in Postgres-XC, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - - -&xlonly; - - dblink module has not been tested - with Postges-XL yet. Although there're no reason - that dblink does not run - in Postgres-XL, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - -&pgonly; - - - dblink_close closes a cursor previously opened with - dblink_open. - - - - - Arguments -&pgonly; - - - - conname - - - Name of the connection to use; omit this parameter to use the - unnamed connection. - - - - - - cursorname - - - The name of the cursor to close. - - - - - - fail_on_error - - - If true (the default when omitted) then an error thrown on the - remote side of the connection causes an error to also be thrown - locally. If false, the remote error is locally reported as a NOTICE, - and the function's return value is set to ERROR. - - - - - - - - Return Value -&pgonly; - - - Returns status, either OK or ERROR. - - - - - Notes -&pgonly; - - - If dblink_open started an explicit transaction block, - and this is the last remaining open cursor in this connection, - dblink_close will issue the matching COMMIT. - - - - - Example -&pgonly; - - -SELECT dblink_connect('dbname=postgres'); - dblink_connect ----------------- - OK -(1 row) - -SELECT dblink_open('foo', 'select proname, prosrc from pg_proc'); - dblink_open -------------- - OK -(1 row) - -SELECT dblink_close('foo'); - dblink_close --------------- - OK -(1 row) - - - - - - - dblink_get_connections - 3 - - - - dblink_get_connections - returns the names of all open named dblink connections - - - - -dblink_get_connections() returns text[] - - - - - Description - -&xconly; - - dblink module has not been tested - with Postges-XC yet. Although there're no reason - that dblink does not run - in Postgres-XC, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - - -&xlonly; - - dblink module has not been tested - with Postges-XL yet. Although there're no reason - that dblink does not run - in Postgres-XL, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - -&pgonly; - - - dblink_get_connections returns an array of the names - of all open named dblink connections. - - - - - Return Value -&pgonly; - - Returns a text array of connection names, or NULL if none. - - - - Example -&pgonly; - - -SELECT dblink_get_connections(); - - - - - - - dblink_error_message - 3 - - - - dblink_error_message - gets last error message on the named connection - - - - -dblink_error_message(text connname) returns text - - - - - Description - -&xconly; - - dblink module has not been tested - with Postges-XC yet. Although there're no reason - that dblink does not run - in Postgres-XC, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - - -&xlonly; - - dblink module has not been tested - with Postges-XL yet. Although there're no reason - that dblink does not run - in Postgres-XL, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - -&pgonly; - - - dblink_error_message fetches the most recent remote - error message for a given connection. - - - - - Arguments -&pgonly; - - - - conname - - - Name of the connection to use. - - - - - - - - Return Value -&pgonly; - - - Returns last error message, or an empty string if there has been - no error in this connection. - - - - - Example -&pgonly; - - -SELECT dblink_error_message('dtest1'); - - - - - - - dblink_send_query - 3 - - - - dblink_send_query - sends an async query to a remote database - - - - -dblink_send_query(text connname, text sql) returns int - - - - - Description - -&xconly; - - dblink module has not been tested - with Postges-XC yet. Although there're no reason - that dblink does not run - in Postgres-XC, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - - -&xlonly; - - dblink module has not been tested - with Postges-XL yet. Although there're no reason - that dblink does not run - in Postgres-XL, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - -&pgonly; - - - dblink_send_query sends a query to be executed - asynchronously, that is, without immediately waiting for the result. - There must not be an async query already in progress on the - connection. - - - - After successfully dispatching an async query, completion status - can be checked with dblink_is_busy, and the results - are ultimately collected with dblink_get_result. - It is also possible to attempt to cancel an active async query - using dblink_cancel_query. - - - - - Arguments -&pgonly; - - - - conname - - - Name of the connection to use. - - - - - - sql - - - The SQL statement that you wish to execute in the remote database, - for example select * from pg_class. - - - - - - - - Return Value - -&pgonly; - - Returns 1 if the query was successfully dispatched, 0 otherwise. - - - - - Example -&pgonly; - - -SELECT dblink_send_query('dtest1', 'SELECT * FROM foo WHERE f1 < 3'); - - - - - - - dblink_is_busy - 3 - - - - dblink_is_busy - checks if connection is busy with an async query - - - - -dblink_is_busy(text connname) returns int - - - - - Description - -&xconly; - - dblink module has not been tested - with Postges-XC yet. Although there're no reason - that dblink does not run - in Postgres-XC, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - - -&xlonly; - - dblink module has not been tested - with Postges-XL yet. Although there're no reason - that dblink does not run - in Postgres-XL, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - -&pgonly; - - - dblink_is_busy tests whether an async query is in progress. - - - - - Arguments - - - - conname - - - Name of the connection to check. - - - - - - - - Return Value -&pgonly; - - - Returns 1 if connection is busy, 0 if it is not busy. - If this function returns 0, it is guaranteed that - dblink_get_result will not block. - - - - - Example -&pgonly; - - -SELECT dblink_is_busy('dtest1'); - - - - - - - dblink_get_notify - 3 - - - - dblink_get_notify - retrieve async notifications on a connection - - - - -dblink_get_notify() returns setof (notify_name text, be_pid int, extra text) -dblink_get_notify(text connname) returns setof (notify_name text, be_pid int, extra text) - - - - - Description - - -&xconly; - - dblink module has not been tested - with Postges-XC yet. Although there're no reason - that dblink does not run - in Postgres-XC, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - - -&xlonly; - - dblink module has not been tested - with Postges-XL yet. Although there're no reason - that dblink does not run - in Postgres-XL, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - -&pgonly; - - dblink_get_notify retrieves notifications on either - the unnamed connection, or on a named connection if specified. - To receive notifications via dblink, LISTEN must - first be issued, using dblink_exec. - For details see and . - - - - - - Arguments -&pgonly; - - - - conname - - - The name of a named connection to get notifications on. - - - - - - - - Return Value -&pgonly; - Returns setof (notify_name text, be_pid int, extra text), or an empty set if none. - - - - Example -&pgonly; - - -SELECT dblink_exec('LISTEN virtual'); - dblink_exec -------------- - LISTEN -(1 row) - -SELECT * FROM dblink_get_notify(); - notify_name | be_pid | extra --------------+--------+------- -(0 rows) - -NOTIFY virtual; -NOTIFY - -SELECT * FROM dblink_get_notify(); - notify_name | be_pid | extra --------------+--------+------- - virtual | 1229 | -(1 row) - - - - - - - dblink_get_result - 3 - - - - dblink_get_result - gets an async query result - - - - -dblink_get_result(text connname [, bool fail_on_error]) returns setof record - - - - - Description - -&xconly; - - dblink module has not been tested - with Postges-XC yet. Although there're no reason - that dblink does not run - in Postgres-XC, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - - -&xlonly; - - dblink module has not been tested - with Postges-XL yet. Although there're no reason - that dblink does not run - in Postgres-XL, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - -&pgonly; - - - dblink_get_result collects the results of an - asynchronous query previously sent with dblink_send_query. - If the query is not already completed, dblink_get_result - will wait until it is. - - - - - Arguments - - - - conname - - - Name of the connection to use. - - - - - - fail_on_error - - - If true (the default when omitted) then an error thrown on the - remote side of the connection causes an error to also be thrown - locally. If false, the remote error is locally reported as a NOTICE, - and the function returns no rows. - - - - - - - - Return Value -&pgonly; - - - For an async query (that is, a SQL statement returning rows), - the function returns the row(s) produced by the query. To use this - function, you will need to specify the expected set of columns, - as previously discussed for dblink. - - - - For an async command (that is, a SQL statement not returning rows), - the function returns a single row with a single text column containing - the command's status string. It is still necessary to specify that - the result will have a single text column in the calling FROM - clause. - - - - - Notes -&pgonly; - - - This function must be called if - dblink_send_query returned 1. - It must be called once for each query - sent, and one additional time to obtain an empty set result, - before the connection can be used again. - - - - - Example -&pgonly; - - -contrib_regression=# SELECT dblink_connect('dtest1', 'dbname=contrib_regression'); - dblink_connect ----------------- - OK -(1 row) - -contrib_regression=# SELECT * FROM -contrib_regression-# dblink_send_query('dtest1', 'select * from foo where f1 < 3') AS t1; - t1 ----- - 1 -(1 row) - -contrib_regression=# SELECT * FROM dblink_get_result('dtest1') AS t1(f1 int, f2 text, f3 text[]); - f1 | f2 | f3 -----+----+------------ - 0 | a | {a0,b0,c0} - 1 | b | {a1,b1,c1} - 2 | c | {a2,b2,c2} -(3 rows) - -contrib_regression=# SELECT * FROM dblink_get_result('dtest1') AS t1(f1 int, f2 text, f3 text[]); - f1 | f2 | f3 -----+----+---- -(0 rows) - -contrib_regression=# SELECT * FROM -contrib_regression-# dblink_send_query('dtest1', 'select * from foo where f1 < 3; select * from foo where f1 > 6') AS t1; - t1 ----- - 1 -(1 row) - -contrib_regression=# SELECT * FROM dblink_get_result('dtest1') AS t1(f1 int, f2 text, f3 text[]); - f1 | f2 | f3 -----+----+------------ - 0 | a | {a0,b0,c0} - 1 | b | {a1,b1,c1} - 2 | c | {a2,b2,c2} -(3 rows) - -contrib_regression=# SELECT * FROM dblink_get_result('dtest1') AS t1(f1 int, f2 text, f3 text[]); - f1 | f2 | f3 -----+----+--------------- - 7 | h | {a7,b7,c7} - 8 | i | {a8,b8,c8} - 9 | j | {a9,b9,c9} - 10 | k | {a10,b10,c10} -(4 rows) - -contrib_regression=# SELECT * FROM dblink_get_result('dtest1') AS t1(f1 int, f2 text, f3 text[]); - f1 | f2 | f3 -----+----+---- -(0 rows) - - - - - - - dblink_cancel_query - 3 - - - - dblink_cancel_query - cancels any active query on the named connection - - - - -dblink_cancel_query(text connname) returns text - - - - - Description - -&xconly; - - dblink module has not been tested - with Postges-XC yet. Although there're no reason - that dblink does not run - in Postgres-XC, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - - -&xlonly; - - dblink module has not been tested - with Postges-XL yet. Although there're no reason - that dblink does not run - in Postgres-XL, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - -&pgonly; - - - dblink_cancel_query attempts to cancel any query that - is in progress on the named connection. Note that this is not - certain to succeed (since, for example, the remote query might - already have finished). A cancel request simply improves the - odds that the query will fail soon. You must still complete the - normal query protocol, for example by calling - dblink_get_result. - - - - - Arguments - - - - conname - - - Name of the connection to use. - - - - - - - - Return Value - - - Returns OK if the cancel request has been sent, or - the text of an error message on failure. - - - - - Example -&pgonly; - - -SELECT dblink_cancel_query('dtest1'); - - - - - - - dblink_get_pkey - 3 - - - - dblink_get_pkey - returns the positions and field names of a relation's - primary key fields - - - - - -dblink_get_pkey(text relname) returns setof dblink_pkey_results - - - - - Description - -&xconly; - - dblink module has not been tested - with Postges-XC yet. Although there're no reason - that dblink does not run - in Postgres-XC, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - - -&xlonly; - - dblink module has not been tested - with Postges-XL yet. Although there're no reason - that dblink does not run - in Postgres-XL, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - -&pgonly; - - - dblink_get_pkey provides information about the primary - key of a relation in the local database. This is sometimes useful - in generating queries to be sent to remote databases. - - - - - Arguments -&pgonly; - - - - relname - - - Name of a local relation, for example foo or - myschema.mytab. Include double quotes if the - name is mixed-case or contains special characters, for - example "FooBar"; without quotes, the string - will be folded to lower case. - - - - - - - - Return Value -&pgonly; - - - Returns one row for each primary key field, or no rows if the relation - has no primary key. The result row type is defined as - - -CREATE TYPE dblink_pkey_results AS (position int, colname text); - - - The position column simply runs from 1 to N; - it is the number of the field within the primary key, not the number - within the table's columns. - - - - - Example -&pgonly; - - -CREATE TABLE foobar ( - f1 int, - f2 int, - f3 int, - PRIMARY KEY (f1, f2, f3) -); -CREATE TABLE - -SELECT * FROM dblink_get_pkey('foobar'); - position | colname -----------+--------- - 1 | f1 - 2 | f2 - 3 | f3 -(3 rows) - - - - - - - dblink_build_sql_insert - 3 - - - - dblink_build_sql_insert - - builds an INSERT statement using a local tuple, replacing the - primary key field values with alternative supplied values - - - - - -dblink_build_sql_insert(text relname, - int2vector primary_key_attnums, - integer num_primary_key_atts, - text[] src_pk_att_vals_array, - text[] tgt_pk_att_vals_array) returns text - - - - - Description - -&xconly; - - dblink module has not been tested - with Postges-XC yet. Although there're no reason - that dblink does not run - in Postgres-XC, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - - -&xlonly; - - dblink module has not been tested - with Postges-XL yet. Although there're no reason - that dblink does not run - in Postgres-XL, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - -&pgonly; - - - dblink_build_sql_insert can be useful in doing selective - replication of a local table to a remote database. It selects a row - from the local table based on primary key, and then builds a SQL - INSERT command that will duplicate that row, but with - the primary key values replaced by the values in the last argument. - (To make an exact copy of the row, just specify the same values for - the last two arguments.) - - - - - Arguments -&pgonly; - - - - relname - - - Name of a local relation, for example foo or - myschema.mytab. Include double quotes if the - name is mixed-case or contains special characters, for - example "FooBar"; without quotes, the string - will be folded to lower case. - - - - - - primary_key_attnums - - - Attribute numbers (1-based) of the primary key fields, - for example 1 2. - - - - - - num_primary_key_atts - - - The number of primary key fields. - - - - - - src_pk_att_vals_array - - - Values of the primary key fields to be used to look up the - local tuple. Each field is represented in text form. - An error is thrown if there is no local row with these - primary key values. - - - - - - tgt_pk_att_vals_array - - - Values of the primary key fields to be placed in the resulting - INSERT command. Each field is represented in text form. - - - - - - - - Return Value -&pgonly; - - Returns the requested SQL statement as text. - - - - Notes -&pgonly; - - - As of PostgreSQL 9.0, the attribute numbers in - primary_key_attnums are interpreted as logical - column numbers, corresponding to the column's position in - SELECT * FROM relname. Previous versions interpreted the - numbers as physical column positions. There is a difference if any - column(s) to the left of the indicated column have been dropped during - the lifetime of the table. - - - - - Example -&pgonly; - - -SELECT dblink_build_sql_insert('foo', '1 2', 2, '{"1", "a"}', '{"1", "b''a"}'); - dblink_build_sql_insert --------------------------------------------------- - INSERT INTO foo(f1,f2,f3) VALUES('1','b''a','1') -(1 row) - - - - - - - dblink_build_sql_delete - 3 - - - - dblink_build_sql_delete - builds a DELETE statement using supplied values for primary - key field values - - - - - -dblink_build_sql_delete(text relname, - int2vector primary_key_attnums, - integer num_primary_key_atts, - text[] tgt_pk_att_vals_array) returns text - - - - - Description - -&xconly; - - dblink module has not been tested - with Postges-XC yet. Although there're no reason - that dblink does not run - in Postgres-XC, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - - -&xlonly; - - dblink module has not been tested - with Postges-XL yet. Although there're no reason - that dblink does not run - in Postgres-XL, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - -&pgonly; - - - dblink_build_sql_delete can be useful in doing selective - replication of a local table to a remote database. It builds a SQL - DELETE command that will delete the row with the given - primary key values. - - - - - Arguments -&pgonly; - - - - relname - - - Name of a local relation, for example foo or - myschema.mytab. Include double quotes if the - name is mixed-case or contains special characters, for - example "FooBar"; without quotes, the string - will be folded to lower case. - - - - - - primary_key_attnums - - - Attribute numbers (1-based) of the primary key fields, - for example 1 2. - - - - - - num_primary_key_atts - - - The number of primary key fields. - - - - - - tgt_pk_att_vals_array - - - Values of the primary key fields to be used in the resulting - DELETE command. Each field is represented in text form. - - - - - - - - Return Value -&pgonly; - - Returns the requested SQL statement as text. - - - - Notes - - - As of PostgreSQL 9.0, the attribute numbers in - primary_key_attnums are interpreted as logical - column numbers, corresponding to the column's position in - SELECT * FROM relname. Previous versions interpreted the - numbers as physical column positions. There is a difference if any - column(s) to the left of the indicated column have been dropped during - the lifetime of the table. - - - - - Example -&pgonly; - - -SELECT dblink_build_sql_delete('"MyFoo"', '1 2', 2, '{"1", "b"}'); - dblink_build_sql_delete ---------------------------------------------- - DELETE FROM "MyFoo" WHERE f1='1' AND f2='b' -(1 row) - - - - - - - dblink_build_sql_update - 3 - - - - dblink_build_sql_update - builds an UPDATE statement using a local tuple, replacing - the primary key field values with alternative supplied values - - - - - -dblink_build_sql_update(text relname, - int2vector primary_key_attnums, - integer num_primary_key_atts, - text[] src_pk_att_vals_array, - text[] tgt_pk_att_vals_array) returns text - - - - - Description - -&xconly; - - dblink module has not been tested - with Postges-XC yet. Although there're no reason - that dblink does not run - in Postgres-XC, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - - -&xlonly; - - dblink module has not been tested - with Postges-XL yet. Although there're no reason - that dblink does not run - in Postgres-XL, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - -&pgonly; - - - dblink_build_sql_update can be useful in doing selective - replication of a local table to a remote database. It selects a row - from the local table based on primary key, and then builds a SQL - UPDATE command that will duplicate that row, but with - the primary key values replaced by the values in the last argument. - (To make an exact copy of the row, just specify the same values for - the last two arguments.) The UPDATE command always assigns - all fields of the row — the main difference between this and - dblink_build_sql_insert is that it's assumed that - the target row already exists in the remote table. - - - - - Arguments - -&xconly; - - dblink module has not been tested - with Postges-XC yet. Although there're no reason - that dblink does not run - in Postgres-XC, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - - -&xlonly; - - dblink module has not been tested - with Postges-XL yet. Although there're no reason - that dblink does not run - in Postgres-XL, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - - -&pgonly; - - - - relname - - - Name of a local relation, for example foo or - myschema.mytab. Include double quotes if the - name is mixed-case or contains special characters, for - example "FooBar"; without quotes, the string - will be folded to lower case. - - - - - - primary_key_attnums - - - Attribute numbers (1-based) of the primary key fields, - for example 1 2. - - - - - - num_primary_key_atts - - - The number of primary key fields. - - - - - - src_pk_att_vals_array - - - Values of the primary key fields to be used to look up the - local tuple. Each field is represented in text form. - An error is thrown if there is no local row with these - primary key values. - - - - - - tgt_pk_att_vals_array - - - Values of the primary key fields to be placed in the resulting - UPDATE command. Each field is represented in text form. - - - - - - - - Return Value -&pgonly; - - Returns the requested SQL statement as text. - - - - Notes - -&xconly; - - dblink module has not been tested - with Postges-XC yet. Although there're no reason - that dblink does not run - in Postgres-XC, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - - -&xlonly; - - dblink module has not been tested - with Postges-XL yet. Although there're no reason - that dblink does not run - in Postgres-XL, the development team leaves the test - and the use of this module entirely to users. - - - This section is identical to the - corresponding PostgreSQL reference manual. - - -&pgonly; - - - As of PostgreSQL 9.0, the attribute numbers in - primary_key_attnums are interpreted as logical - column numbers, corresponding to the column's position in - SELECT * FROM relname. Previous versions interpreted the - numbers as physical column positions. There is a difference if any - column(s) to the left of the indicated column have been dropped during - the lifetime of the table. - - - - - Example -&pgonly; - - -SELECT dblink_build_sql_update('foo', '1 2', 2, '{"1", "a"}', '{"1", "b"}'); - dblink_build_sql_update -------------------------------------------------------------- - UPDATE foo SET f1='1',f2='b',f3='1' WHERE f1='1' AND f2='b' -(1 row) - - - - - diff --git a/doc-xc/src/sgml/ddl.sgmlin b/doc-xc/src/sgml/ddl.sgmlin deleted file mode 100644 index f30f53915e..0000000000 --- a/doc-xc/src/sgml/ddl.sgmlin +++ /dev/null @@ -1,3837 +0,0 @@ - - - - Data Definition -&common; - - - This chapter covers how one creates the database structures that - will hold one's data. In a relational database, the raw data is - stored in tables, so the majority of this chapter is devoted to - explaining how tables are created and modified and what features are - available to control what data is stored in the tables. - Subsequently, we discuss how tables can be organized into - schemas, and how privileges can be assigned to tables. Finally, - we will briefly look at other features that affect the data storage, - such as inheritance, views, functions, and triggers. - - - - Table Basics - - - table - - - - row - - - - column - -&common; - - - A table in a relational database is much like a table on paper: It - consists of rows and columns. The number and order of the columns - is fixed, and each column has a name. The number of rows is - variable — it reflects how much data is stored at a given moment. - SQL does not make any guarantees about the order of the rows in a - table. When a table is read, the rows will appear in an unspecified order, - unless sorting is explicitly requested. This is covered in . Furthermore, SQL does not assign unique - identifiers to rows, so it is possible to have several completely - identical rows in a table. This is a consequence of the - mathematical model that underlies SQL but is usually not desirable. - Later in this chapter we will see how to deal with this issue. - - - - Each column has a data type. The data type constrains the set of - possible values that can be assigned to a column and assigns - semantics to the data stored in the column so that it can be used - for computations. For instance, a column declared to be of a - numerical type will not accept arbitrary text strings, and the data - stored in such a column can be used for mathematical computations. - By contrast, a column declared to be of a character string type - will accept almost any kind of data but it does not lend itself to - mathematical calculations, although other operations such as string - concatenation are available. - - - - - PostgreSQL includes a sizable set of - - - Postgres-XC includes a sizable set of - - - Postgres-XL includes a sizable set of - - built-in data types that fit many applications. Users can also - define their own data types. Most built-in data types have obvious - names and semantics, so we defer a detailed explanation to . Some of the frequently used data types are - integer for whole numbers, numeric for - possibly fractional numbers, text for character - strings, date for dates, time for - time-of-day values, and timestamp for values - containing both date and time. - - - - table - creating - - - - To create a table, you use the aptly named command. - In this command you specify at least a name for the new table, the - names of the columns and the data type of each column. For - example: - -CREATE TABLE my_first_table ( - first_column text, - second_column integer -); - - This creates a table named my_first_table with - two columns. The first column is named - first_column and has a data type of - text; the second column has the name - second_column and the type integer. - The table and column names follow the identifier syntax explained - in . The type names are - usually also identifiers, but there are some exceptions. Note that the - column list is comma-separated and surrounded by parentheses. - - - - Of course, the previous example was heavily contrived. Normally, - you would give names to your tables and columns that convey what - kind of data they store. So let's look at a more realistic - example: - -CREATE TABLE products ( - product_no integer, - name text, - price numeric -); - - (The numeric type can store fractional components, as - would be typical of monetary amounts.) - - - - - When you create many interrelated tables it is wise to choose a - consistent naming pattern for the tables and columns. For - instance, there is a choice of using singular or plural nouns for - table names, both of which are favored by some theorist or other. - - - - - There is a limit on how many columns a table can contain. - Depending on the column types, it is between 250 and 1600. - However, defining a table with anywhere near this many columns is - highly unusual and often a questionable design. - - - - - table - - - table - replication - - -&xconly; - - - In Postgres-XC, each table can be distributed or replicated - among Datanodes. By distributing tables, each query, if the target is - determined from the incoming statement, can be handled by single or small - number of Datanodes and more transactions can be handled in parallel. - If you replicate tables, and if they're more read than written, transactions - reading such tables can be handled in parallel. - - - - When you distribute a table, you can choose almost any column of a fundamental data type as distribution - column. - For details, please refer to . - Datanode for specific row is determined based upon the value of the distribution - column. - By default, distribution column is the first column you specified in - CREATE TABLE statement and the column value is used to - generate hash value as an index for Datanode which accommodate the - row. - You can choose another distribution method such as MODULO and - ROUNDROBIN. - To specify what column to choose as the distribution column and what value test to - choose, you can do as follows: - -CREATE TABLE products ( - product_no integer, - name text, - price numeric -) DISTRIBUTE BY HASH(product_no); - - In this case, the column product_no is chosen as the distribute column and - the target Datanode of each row is determined based upon the hash value of the column. - You can use MODULO to specify modulo to test and determine the target Datanode. - You can also specify ROUNDROBIN to determine the Datanode by the order each - row is inserted. - - - - Please note that with HASH and MODULO, Coordinator have a chance to determine the - location of target row from incoming statement. This reduces the number of involved Datanodes - and can increase the number of transaction handled in parallel. - - - - On the other hand, if exact value cannot be obtained from incoming statement, for example, - in the case of floating point number, Postgres-XC may fail to find precise - target Datanode and it is not recommended to use such column as a distribution column. - - - - To replicate a table into all the Datanodes, specify DISTRIBUTE BY REPLICATION as - follows: - -CREATE TABLE products ( - product_no integer, - name text, - price numeric -) DISTRIBUTE BY REPLICATION; - - - - - - - table - - - table - replication - - -&xlonly; - - - In Postgres-XL, each table can be distributed or replicated - among Datanodes. By distributing tables each query - has the potential to be handled by a single or small - subset of the Datanodes and more transactions can be handled in parallel. - If you replicate tables, they can be read from just a single location, though - all writes will need to take place on all nodes. - - - - When you distribute a table, you can choose almost any column of a fundamental data type as distribution - column. - For details, please refer to . - The Datanode for a particular row is determined based upon the value of the distribution - column, chosen if DISTRIBUTE BY HASH was used. - If not used, the first column of a primary key or unique constraint is used - if present in the CREATE TABLE clause. - If neither of those are present, the first column of a foreign key constraint - is used, the idea being that child data can be col-located on the same node - as the parent table. - If no such constraint is defined, Postgres-XL will choose the first reasonable - column it can find, that is the first column that has a deterministically - distributable data type. - - You may also choose another distribution method such as MODULO and - ROUNDROBIN. - To specify what column to choose as the distribution column and what value test to - choose, you can do as follows: - -CREATE TABLE products ( - product_no integer, - name text, - price numeric -) DISTRIBUTE BY HASH(product_no); - - In this case, the column product_no is chosen as the distribute column and - the target Datanode of each row is determined based upon the hash value of the column. - You can use MODULO to specify modulo to test and determine the target Datanode. - You can also specify ROUNDROBIN to determine the Datanode by the order each - row is inserted. - - - - Please note that with HASH and MODULO, the Coordinator may be able to determine the - exact location of target row from incoming statement. This reduces the number of involved Datanodes - and can increase the number of transaction handled in parallel. - - - - On the other hand, if exact location cannot be obtained from incoming statement, the - Coordinator will have to involve all of the Datanodes on which the involved table - is distributed. - - - - To replicate a table into all the Datanodes, specify DISTRIBUTE BY REPLICATION as - follows: - -CREATE TABLE products ( - product_no integer, - name text, - price numeric -) DISTRIBUTE BY REPLICATION; - - - - - - - table - removing - - -&common; - - If you no longer need a table, you can remove it using the command. - For example: - -DROP TABLE my_first_table; -DROP TABLE products; - - Attempting to drop a table that does not exist is an error. - Nevertheless, it is common in SQL script files to unconditionally - try to drop each table before creating it, ignoring any error - messages, so that the script works whether or not the table exists. - (If you like, you can use the DROP TABLE IF EXISTS variant - to avoid the error messages, but this is not standard SQL.) - - - - If you need to modify a table that already exists, see later in this chapter. - - - - With the tools discussed so far you can create fully functional - tables. The remainder of this chapter is concerned with adding - features to the table definition to ensure data integrity, - security, or convenience. If you are eager to fill your tables with - data now you can skip ahead to and read the - rest of this chapter later. - - - - - Default Values - - - default value - -&common; - - - A column can be assigned a default value. When a new row is - created and no values are specified for some of the columns, those - columns will be filled with their respective default values. A - data manipulation command can also request explicitly that a column - be set to its default value, without having to know what that value is. - (Details about data manipulation commands are in .) - - - - null valuedefault value - If no default value is declared explicitly, the default value is the - null value. This usually makes sense because a null value can - be considered to represent unknown data. - - - - In a table definition, default values are listed after the column - data type. For example: - -CREATE TABLE products ( - product_no integer, - name text, - price numeric DEFAULT 9.99 -); - - - - - - The default value can be an expression, which will be - evaluated whenever the default value is inserted - (not when the table is created). A common example - is for a timestamp column to have a default of CURRENT_TIMESTAMP, - so that it gets set to the time of row insertion. Another common - example is generating a serial number for each row. - In PostgreSQL this is typically done by - something like: - -CREATE TABLE products ( - product_no integer DEFAULT nextval('products_product_no_seq'), - ... -); - - where the nextval() function supplies successive values - from a sequence object (see ). This arrangement is sufficiently common - that there's a special shorthand for it: - -CREATE TABLE products ( - product_no SERIAL, - ... -); - - The SERIAL shorthand is discussed further in . - - - - - Constraints - - - constraint - -&common; - - - Data types are a way to limit the kind of data that can be stored - in a table. For many applications, however, the constraint they - provide is too coarse. For example, a column containing a product - price should probably only accept positive values. But there is no - standard data type that accepts only positive numbers. Another issue is - that you might want to constrain column data with respect to other - columns or rows. For example, in a table containing product - information, there should be only one row for each product number. - - - - To that end, SQL allows you to define constraints on columns and - tables. Constraints give you as much control over the data in your - tables as you wish. If a user attempts to store data in a column - that would violate a constraint, an error is raised. This applies - even if the value came from the default value definition. - - - - Check Constraints - - - check constraint - - - - constraint - check - -&common; - - - A check constraint is the most generic constraint type. It allows - you to specify that the value in a certain column must satisfy a - Boolean (truth-value) expression. For instance, to require positive - product prices, you could use: - -CREATE TABLE products ( - product_no integer, - name text, - price numeric CHECK (price > 0) -); - - - - - As you see, the constraint definition comes after the data type, - just like default value definitions. Default values and - constraints can be listed in any order. A check constraint - consists of the key word CHECK followed by an - expression in parentheses. The check constraint expression should - involve the column thus constrained, otherwise the constraint - would not make too much sense. - - - - constraint - name - -&common; - - You can also give the constraint a separate name. This clarifies - error messages and allows you to refer to the constraint when you - need to change it. The syntax is: - -CREATE TABLE products ( - product_no integer, - name text, - price numeric CONSTRAINT positive_price CHECK (price > 0) -); - - So, to specify a named constraint, use the key word - CONSTRAINT followed by an identifier followed - by the constraint definition. (If you don't specify a constraint - name in this way, the system chooses a name for you.) - - - - A check constraint can also refer to several columns. Say you - store a regular price and a discounted price, and you want to - ensure that the discounted price is lower than the regular price: - -CREATE TABLE products ( - product_no integer, - name text, - price numeric CHECK (price > 0), - discounted_price numeric CHECK (discounted_price > 0), - CHECK (price > discounted_price) -); - - - - - The first two constraints should look familiar. The third one - uses a new syntax. It is not attached to a particular column, - instead it appears as a separate item in the comma-separated - column list. Column definitions and these constraint - definitions can be listed in mixed order. - - - - We say that the first two constraints are column constraints, whereas the - third one is a table constraint because it is written separately - from any one column definition. Column constraints can also be - written as table constraints, while the reverse is not necessarily - possible, since a column constraint is supposed to refer to only the - column it is attached to. (PostgreSQL doesn't - enforce that rule, but you should follow it if you want your table - definitions to work with other database systems.) The above example could - also be written as: - -CREATE TABLE products ( - product_no integer, - name text, - price numeric, - CHECK (price > 0), - discounted_price numeric, - CHECK (discounted_price > 0), - CHECK (price > discounted_price) -); - - or even: - -CREATE TABLE products ( - product_no integer, - name text, - price numeric CHECK (price > 0), - discounted_price numeric, - CHECK (discounted_price > 0 AND price > discounted_price) -); - - It's a matter of taste. - - - - Names can be assigned to table constraints in the same way as - column constraints: - -CREATE TABLE products ( - product_no integer, - name text, - price numeric, - CHECK (price > 0), - discounted_price numeric, - CHECK (discounted_price > 0), - CONSTRAINT valid_discount CHECK (price > discounted_price) -); - - - - - null value - with check constraints - -&common; - - It should be noted that a check constraint is satisfied if the - check expression evaluates to true or the null value. Since most - expressions will evaluate to the null value if any operand is null, - they will not prevent null values in the constrained columns. To - ensure that a column does not contain null values, the not-null - constraint described in the next section can be used. - - - - - Not-Null Constraints - - - not-null constraint - - - - constraint - NOT NULL - -&common; - - - A not-null constraint simply specifies that a column must not - assume the null value. A syntax example: - -CREATE TABLE products ( - product_no integer NOT NULL, - name text NOT NULL, - price numeric -); - - - - - A not-null constraint is always written as a column constraint. A - not-null constraint is functionally equivalent to creating a check - constraint CHECK (column_name - IS NOT NULL), but in - PostgreSQL creating an explicit - not-null constraint is more efficient. The drawback is that you - cannot give explicit names to not-null constraints created this - way. - - - - Of course, a column can have more than one constraint. Just write - the constraints one after another: - -CREATE TABLE products ( - product_no integer NOT NULL, - name text NOT NULL, - price numeric NOT NULL CHECK (price > 0) -); - - The order doesn't matter. It does not necessarily determine in which - order the constraints are checked. - - - - The NOT NULL constraint has an inverse: the - NULL constraint. This does not mean that the - column must be null, which would surely be useless. Instead, this - simply selects the default behavior that the column might be null. - The NULL constraint is not present in the SQL - standard and should not be used in portable applications. (It was - only added to PostgreSQL to be - compatible with some other database systems.) Some users, however, - like it because it makes it easy to toggle the constraint in a - script file. For example, you could start with: - -CREATE TABLE products ( - product_no integer NULL, - name text NULL, - price numeric NULL -); - - and then insert the NOT key word where desired. - - - - - In most database designs the majority of columns should be marked - not null. - - - - - - Unique Constraints - - - unique constraint - - - - constraint - unique - -&common; - - - Unique constraints ensure that the data contained in a column or a - group of columns is unique with respect to all the rows in the - table. The syntax is: - -CREATE TABLE products ( - product_no integer UNIQUE, - name text, - price numeric -); - - when written as a column constraint, and: - -CREATE TABLE products ( - product_no integer, - name text, - price numeric, - UNIQUE (product_no) -); - - when written as a table constraint. - - - - If a unique constraint refers to a group of columns, the columns - are listed separated by commas: - -CREATE TABLE example ( - a integer, - b integer, - c integer, - UNIQUE (a, c) -); - - This specifies that the combination of values in the indicated columns - is unique across the whole table, though any one of the columns - need not be (and ordinarily isn't) unique. - - - - You can assign your own name for a unique constraint, in the usual way: - -CREATE TABLE products ( - product_no integer CONSTRAINT must_be_different UNIQUE, - name text, - price numeric -); - - - - - Adding a unique constraint will automatically create a unique tree - index on the column or group of columns used in the constraint. - - - - null value - with unique constraints - - - - In general, a unique constraint is violated when there is more than - one row in the table where the values of all of the - columns included in the constraint are equal. - However, two null values are not considered equal in this - comparison. That means even in the presence of a - unique constraint it is possible to store duplicate - rows that contain a null value in at least one of the constrained - columns. This behavior conforms to the SQL standard, but we have - heard that other SQL databases might not follow this rule. So be - careful when developing applications that are intended to be - portable. - - - -&xconly; - - In Postgres-XC, in distributed - tables, UNIQUE constraints must include the - distribution column of the table. If the table is distributed - by ROUNDROBIN, you cannot enforce UNIQUE - constraint because it does not have a distribution column. - There's no restriction in UNIQUE constraint in replicated - tables. When an expression is used on a UNIQUE constraint, - this expression must contain the distribution column of its parent - table. It cannot use other columns as well. - - - -&xlonly; - - In Postgres-XL, in distributed - tables, UNIQUE constraints must include the - distribution column of the table. - This is because Postgres-XL currently only allows that it can - push down to the Datanodes to be enforced locally. If we include - the distribution column in unique constraints, it stands to - reason that it can be enforced locally. - - If a table is distributed - by ROUNDROBIN, we cannot enforce UNIQUE - constraints because it does not have a distribution column; - it is possible that the same value for a column exists on - multiple nodes. - - There's no restriction in UNIQUE constraint in replicated - tables. When an expression is used on a UNIQUE constraint, - this expression must contain the distribution column of its parent - table. It cannot use other columns as well. - - - - - - Primary Keys - - - primary key - - - - constraint - primary key - -&common; - - - Technically, a primary key constraint is simply a combination of a - unique constraint and a not-null constraint. So, the following - two table definitions accept the same data: - -CREATE TABLE products ( - product_no integer UNIQUE NOT NULL, - name text, - price numeric -); - - - -CREATE TABLE products ( - product_no integer PRIMARY KEY, - name text, - price numeric -); - - - - - Primary keys can also constrain more than one column; the syntax - is similar to unique constraints: - -CREATE TABLE example ( - a integer, - b integer, - c integer, - PRIMARY KEY (a, c) -); - - - - - A primary key indicates that a column or group of columns can be - used as a unique identifier for rows in the table. (This is a - direct consequence of the definition of a primary key. Note that - a unique constraint does not, by itself, provide a unique identifier - because it does not exclude null values.) This is useful both for - documentation purposes and for client applications. For example, - a GUI application that allows modifying row values probably needs - to know the primary key of a table to be able to identify rows - uniquely. - - - - Adding a primary key will automatically create a unique btree index - on the column or group of columns used in the primary key. - - - - A table can have at most one primary key. (There can be any number - of unique and not-null constraints, which are functionally the same - thing, but only one can be identified as the primary key.) - Relational database theory - dictates that every table must have a primary key. This rule is - not enforced by PostgreSQL, but it is - usually best to follow it. - - -&xconly; - - As mentioned in UNIQUE constraint, distribution column - must be included in PRIMARY KEY. Other restrictions - apply to PRIMARY KEY too. When an expression is used on - a PRIMARY KEY constraint, this expression must contain - the distribution column of its parent table. It cannot use other - columns as well. - - - - - As mentioned when discussing UNIQUE constraint, the distribution column - must be included in PRIMARY KEY. Other restrictions - apply to the PRIMARY KEY as well. When an expression is used on - a PRIMARY KEY constraint, this expression must contain - the distribution column of its parent table. It cannot use other - columns as well. - - - - - - Foreign Keys - - - foreign key - - - - constraint - foreign key - - - - referential integrity - -&common; - - - A foreign key constraint specifies that the values in a column (or - a group of columns) must match the values appearing in some row - of another table. - We say this maintains the referential - integrity between two related tables. - - - - Say you have the product table that we have used several times already: - -CREATE TABLE products ( - product_no integer PRIMARY KEY, - name text, - price numeric -); - - - - Let's also assume you have a table storing orders of those - products. We want to ensure that the orders table only contains - orders of products that actually exist. So we define a foreign - key constraint in the orders table that references the products - table: - -CREATE TABLE orders ( - order_id integer PRIMARY KEY, - product_no integer REFERENCES products (product_no), - quantity integer -); - - - -&xconly - - Let's also assume you have a table storing orders of those - products. We want to ensure that the orders table only contains - orders of products that actually exist. So we define a foreign - key constraint in the orders table that references the products - table. - -CREATE TABLE orders ( - order_id integer, - product_no integer REFERENCES products (product_no), - quantity integer -) DISTRIBUTE BY HASH(product_no); - - -&xconly; - - Please note that column with REFERENCE must be the distribution column. - In this case, we cannot add PRIMARY KEY to order_id - because PRIMARY KEY must be the distribution column as well. - This limitation is introduced because constraints are enforced only locally in each Datanode, - which will be resolved in the future. - - - - -&xlonly - - Let's also assume you have a table storing orders of those - products. We want to ensure that the orders table only contains - orders of products that actually exist. So we define a foreign - key constraint in the orders table that references the products - table. - -CREATE TABLE orders ( - order_id integer, - product_no integer REFERENCES products (product_no), - quantity integer -) DISTRIBUTE BY HASH(product_no); - - -&xlonly; - - Please note that column with REFERENCES should be the distribution column. - In this case, we cannot add PRIMARY KEY to order_id - because PRIMARY KEY must be the distribution column as well. - This limitation is introduced because constraints are enforced only locally in each Datanode. - - - -&common; - Now it is impossible to create orders with - product_no entries that do not appear in the - products table. - - - - We say that in this situation the orders table is the - referencing table and the products table is - the referenced table. Similarly, there are - referencing and referenced columns. - - - - - - You can also shorten the above command to: - -CREATE TABLE orders ( - order_id integer PRIMARY KEY, - product_no integer REFERENCES products, - quantity integer -); - - because in absence of a column list the primary key of the - referenced table is used as the referenced column(s). - - - - - - - A foreign key can also constrain and reference a group of columns. - As usual, it then needs to be written in table constraint form. - Here is a contrived syntax example: - -CREATE TABLE t1 ( - a integer PRIMARY KEY, - b integer, - c integer, - FOREIGN KEY (b, c) REFERENCES other_table (c1, c2) -); - - Of course, the number and type of the constrained columns need to - match the number and type of the referenced columns. - - - - - You can assign your own name for a foreign key constraint, - in the usual way. - - - - - - A table can contain more than one foreign key constraint. This is - used to implement many-to-many relationships between tables. Say - you have tables about products and orders, but now you want to - allow one order to contain possibly many products (which the - structure above did not allow). You could use this table structure: - -CREATE TABLE products ( - product_no integer PRIMARY KEY, - name text, - price numeric -); - -CREATE TABLE orders ( - order_id integer PRIMARY KEY, - shipping_address text, - ... -); - -CREATE TABLE order_items ( - product_no integer REFERENCES products, - order_id integer REFERENCES orders, - quantity integer, - PRIMARY KEY (product_no, order_id) -); - - Notice that the primary key overlaps with the foreign keys in - the last table. - - - -&xconly; - - Because a column with REFERENCES integrity needs to be - the distribution column, it is Postgres-XC's - restriction that we cannot specify more than one columns - with REFERENCES constraint. - - - - - CASCADE - foreign key action - - - - RESTRICT - foreign key action - - - - - - We know that the foreign keys disallow creation of orders that - do not relate to any products. But what if a product is removed - after an order is created that references it? SQL allows you to - handle that as well. Intuitively, we have a few options: - - Disallow deleting a referenced product - Delete the orders as well - Something else? - - - - -&xconly; - - We know that the foreign keys disallow creation of orders that - do not relate to any products. But what if a product is removed - after an order is created that references it? SQL allows you to - handle that as well. Intuitively, we have a few options: - - Disallow deleting a referenced order - Delete the order line as well - Something else? - - - - -&xlonly; - - We know that the foreign keys disallow creation of orders that - do not relate to any products. But what if a product is removed - after an order is created that references it? SQL allows you to - handle that as well. Intuitively, we have a few options: - - Disallow deleting a referenced order - Delete the order line as well - Something else? - - - -&common; - - To illustrate this, let's implement the following policy on the - many-to-many relationship example above: when someone wants to - remove a product that is still referenced by an order (via - order_items), we disallow it. If someone - removes an order, the order items are removed as well: - - -CREATE TABLE products ( - product_no integer PRIMARY KEY, - name text, - price numeric -); - -CREATE TABLE orders ( - order_id integer PRIMARY KEY, - shipping_address text, - ... -); - -CREATE TABLE order_items ( - product_no integer REFERENCES products ON DELETE RESTRICT, - order_id integer REFERENCES orders ON DELETE CASCADE, - quantity integer, - PRIMARY KEY (product_no, order_id) -); - - - - -CREATE TABLE products ( - product_no integer PRIMARY KEY, - name text, - price numeric -); - -CREATE TABLE orders ( - order_id integer PRIMARY KEY, - shipping_address text, - ... -); - -CREATE TABLE order_items ( - product_no integer, - order_id integer REFERENCES orders ON DELETE CASCADE, - quantity integer, - PRIMARY KEY (product_no, order_id) -) DISTRIBUTE BY HASH(order_id); - - - - -CREATE TABLE products ( - product_no integer PRIMARY KEY, - name text, - price numeric -); - -CREATE TABLE orders ( - order_id integer PRIMARY KEY, - shipping_address text, - ... -); - -CREATE TABLE order_items ( - product_no integer, - order_id integer REFERENCES orders ON DELETE CASCADE, - quantity integer, - PRIMARY KEY (product_no, order_id) -) DISTRIBUTE BY HASH(order_id); - - - - - - Restricting and cascading deletes are the two most common options. - RESTRICT prevents deletion of a - referenced row. NO ACTION means that if any - referencing rows still exist when the constraint is checked, an error - is raised; this is the default behavior if you do not specify anything. - (The essential difference between these two choices is that - NO ACTION allows the check to be deferred until - later in the transaction, whereas RESTRICT does not.) - CASCADE specifies that when a referenced row is deleted, - row(s) referencing it should be automatically deleted as well. - There are two other options: - SET NULL and SET DEFAULT. - These cause the referencing columns to be set to nulls or default - values, respectively, when the referenced row is deleted. - Note that these do not excuse you from observing any constraints. - For example, if an action specifies SET DEFAULT - but the default value would not satisfy the foreign key, the - operation will fail. - - - - Analogous to ON DELETE there is also - ON UPDATE which is invoked when a referenced - column is changed (updated). The possible actions are the same. - - - - Since a DELETE of a row from the referenced table - or an UPDATE of a referenced column will require - a scan of the referencing table for rows matching the old value, it - is often a good idea to index the referencing columns. Because this - is not always needed, and there are many choices available on how - to index, declaration of a foreign key constraint does not - automatically create an index on the referencing columns. - - - - More information about updating and deleting data is in . - - - - Finally, we should mention that a foreign key must reference - columns that either are a primary key or form a unique constraint. - If the foreign key references a unique constraint, there are some - additional possibilities regarding how null values are matched. - These are explained in the reference documentation for - . - - - - - - - Exclusion Constraints - - - exclusion constraint - - - - constraint - exclusion - - - - Exclusion constraints ensure that if any two rows are compared on - the specified columns or expressions using the specified operators, - at least one of these operator comparisons will return false or null. - The syntax is: - -CREATE TABLE circles ( - c circle, - EXCLUDE USING gist (c WITH &&) -); - - - - - See also CREATE - TABLE ... CONSTRAINT ... EXCLUDE for details. - - - - Adding an exclusion constraint will automatically create an index - of the type specified in the constraint declaration. - -$xc-constraint; - - - - - - System Columns -&common; - - Every table has several system columns that are - implicitly defined by the system. Therefore, these names cannot be - used as names of user-defined columns. (Note that these - restrictions are separate from whether the name is a key word or - not; quoting a name will not allow you to escape these - restrictions.) You do not really need to be concerned about these - columns; just know they exist. - - - - column - system column - - - - - oid - - - - OID - column - - The object identifier (object ID) of a row. This column is only - present if the table was created using WITH - OIDS, or if the - configuration variable was set at the time. This column is of type - oid (same name as the column); see for more information about the type. - - -&xconly; - - Please note that Postgres-XC does not enforce - OID integrity among the cluster. OID is assigned locally in - each Coordinator and Datanode. You can use this in expressions - but you should not expect OID value is the same throughout the - XC cluster. - - - -&xlonly; - - Please note that Postgres-XL does not enforce - OID integrity among the cluster. OIDs are assigned locally in - each Coordinator and Datanode. You can use this in expressions - but you should not expect OID values are the same throughout the - XL cluster. - - - - - - - tableoid - - - tableoid - - - - The OID of the table containing this row. This column is - particularly handy for queries that select from inheritance - hierarchies (see ), since without it, - it's difficult to tell which individual table a row came from. The - tableoid can be joined against the - oid column of - pg_class to obtain the table name. - - -&xconly; - - Please note that Postgres-XC does not enforce - OID integrity among the cluster. OID is assigned locally in - each Coordinator and Datanode. You can use this in expressions - but you should not expect OID value is the same throughout the - XC cluster. - - - -&xlonly; - - Please note that Postgres-XL does not enforce - OID integrity among the cluster. OIDs are assigned locally in - each Coordinator and Datanode. You can use this in expressions, - but you should not expect OID values are the same throughout the - XL cluster. - - - - - - - xmin - - - xmin - -&common; - - The identity (transaction ID) of the inserting transaction for - this row version. (A row version is an individual state of a - row; each update of a row creates a new row version for the same - logical row.) - - - - - - cmin - - - cmin - - - - The command identifier (starting at zero) within the inserting - transaction. - - - - - - xmax - - - xmax - -&common; - - The identity (transaction ID) of the deleting transaction, or - zero for an undeleted row version. It is possible for this column to - be nonzero in a visible row version. That usually indicates that the - deleting transaction hasn't committed yet, or that an attempted - deletion was rolled back. - - - - - - cmax - - - cmax - - - - The command identifier within the deleting transaction, or zero. - - - - - - ctid - - - ctid - - - - The physical location of the row version within its table. Note that - although the ctid can be used to - locate the row version very quickly, a row's - ctid will change if it is - updated or moved by VACUUM FULL. Therefore - ctid is useless as a long-term row - identifier. The OID, or even better a user-defined serial - number, should be used to identify logical rows. - - -&xconly; - - In Postgres-XC, ctid is local to Coordinators - and Datanodes. It is not a good practice to use this value in - SQL statements. In very restricted situation, for example, when - you query the database specifying the target Coordinator or - Datanode using EXECUTE DIRECT statement, you may use - this value. - - - -&xlonly; - - In Postgres-XL, ctid is local to Coordinators - and Datanodes. It is not good practice to use this value in - SQL statements and can be very dangerous when using it to update - data. - - - - - -&common; - - OIDs are 32-bit quantities and are assigned from a single - cluster-wide counter. In a large or long-lived database, it is - possible for the counter to wrap around. Hence, it is bad - practice to assume that OIDs are unique, unless you take steps to - ensure that this is the case. If you need to identify the rows in - a table, using a sequence generator is strongly recommended. - However, OIDs can be used as well, provided that a few additional - precautions are taken: - - - - - A unique constraint should be created on the OID column of each - table for which the OID will be used to identify rows. When such - a unique constraint (or unique index) exists, the system takes - care not to generate an OID matching an already-existing row. - (Of course, this is only possible if the table contains fewer - than 232 (4 billion) rows, and in practice the - table size had better be much less than that, or performance - might suffer.) - - - - - OIDs should never be assumed to be unique across tables; use - the combination of tableoid and row OID if you - need a database-wide identifier. - - - - - Of course, the tables in question must be created WITH - OIDS. As of PostgreSQL 8.1, - WITHOUT OIDS is the default. - - - - - - - Transaction identifiers are also 32-bit quantities. In a - long-lived database it is possible for transaction IDs to wrap - around. This is not a fatal problem given appropriate maintenance - procedures; see for details. It is - unwise, however, to depend on the uniqueness of transaction IDs - over the long term (more than one billion transactions). - - - -&xconly; - - Again, Postgres-XC does not enforce - OID integrity among the cluster. OID is assigned locally in - each Coordinator and Datanode. You can use this in expressions - but you should not expect OID value is the same throughout the - XC cluster. - - - -&xlonly; - - Again, Postgres-XL does not enforce - OID integrity among the cluster. OIDs are assigned locally in - each Coordinator and Datanode. You can use this in expressions - but you should not expect OIDs values to refer to the same object throughout the - XL cluster. - - -&common; - - Command identifiers are also 32-bit quantities. This creates a hard limit - of 232 (4 billion) SQL commands - within a single transaction. In practice this limit is not a - problem — note that the limit is on the number of - SQL commands, not the number of rows processed. - Also, as of PostgreSQL 8.3, only commands - that actually modify the database contents will consume a command - identifier. - - - - - Modifying Tables - - - table - modifying - -&common; - - When you create a table and you realize that you made a mistake, or - the requirements of the application change, you can drop the - table and create it again. But this is not a convenient option if - the table is already filled with data, or if the table is - referenced by other database objects (for instance a foreign key - constraint). Therefore PostgreSQL - provides a family of commands to make modifications to existing - tables. Note that this is conceptually distinct from altering - the data contained in the table: here we are interested in altering - the definition, or structure, of the table. - - - - You can: - - - Add columns - - - Remove columns - - - Add constraints - - - Remove constraints - - - Change default values - - - Change column data types - - - Rename columns - - - Rename tables - - - - All these actions are performed using the - - command, whose reference page contains details beyond those given - here. - - - -&xconly; - - In Postgres-XC the following are not allowed: - - - Modifying distribution columns definition - - - Modifying distribution column values - - - - - -&xlonly; - - In addition to these actions, in Postgres-XL you -can also use ALTER TABLE command to: - - - Change distribution strategy - - - Add a node to existing distribution target - - - Remove a node from existing distribution target - - - - - In Postgres-XL the following are not allowed: - - - Modifying distribution columns definition - - - Modifying distribution column values - - - - - - Adding a Column - - - column - adding - -&common; - - To add a column, use a command like: - -ALTER TABLE products ADD COLUMN description text; - - The new column is initially filled with whatever default - value is given (null if you don't specify a DEFAULT clause). - - - - You can also define constraints on the column at the same time, - using the usual syntax: - -ALTER TABLE products ADD COLUMN description text CHECK (description <> ''); - - In fact all the options that can be applied to a column description - in CREATE TABLE can be used here. Keep in mind however - that the default value must satisfy the given constraints, or the - ADD will fail. Alternatively, you can add - constraints later (see below) after you've filled in the new column - correctly. - - - - - Adding a column with a default requires updating each row of the - table (to store the new column value). However, if no default is - specified, PostgreSQL is able to avoid - the physical update. So if you intend to fill the column with - mostly nondefault values, it's best to add the column with no default, - insert the correct values using UPDATE, and then add any - desired default as described below. - - - - - - Removing a Column - - - column - removing - -&common; - - - To remove a column, use a command like: - -ALTER TABLE products DROP COLUMN description; - - Whatever data was in the column disappears. Table constraints involving - the column are dropped, too. However, if the column is referenced by a - foreign key constraint of another table, - PostgreSQL will not silently drop that - constraint. You can authorize dropping everything that depends on - the column by adding CASCADE: - -ALTER TABLE products DROP COLUMN description CASCADE; - - See for a description of the general - mechanism behind this. - - - - - Adding a Constraint - - - constraint - adding - -&common; - - - To add a constraint, the table constraint syntax is used. For example: - -ALTER TABLE products ADD CHECK (name <> ''); -ALTER TABLE products ADD CONSTRAINT some_name UNIQUE (product_no); -ALTER TABLE products ADD FOREIGN KEY (product_group_id) REFERENCES product_groups; - - To add a not-null constraint, which cannot be written as a table - constraint, use this syntax: - -ALTER TABLE products ALTER COLUMN product_no SET NOT NULL; - - - - - The constraint will be checked immediately, so the table data must - satisfy the constraint before it can be added. - - -&xconly; - - Please remember that distribution column has to be included in UNIQUE and REFERENCE constraints. - -&xc-constraint; - - -&xlonly; - - Please remember that the distribution column has to be included in UNIQUE and REFERENCE constraints. - -&xc-constraint; - - - - - Removing a Constraint - - - constraint - removing - -&common; - - - To remove a constraint you need to know its name. If you gave it - a name then that's easy. Otherwise the system assigned a - generated name, which you need to find out. The - psql command \d - tablename can be helpful - here; other interfaces might also provide a way to inspect table - details. Then the command is: - -ALTER TABLE products DROP CONSTRAINT some_name; - - (If you are dealing with a generated constraint name like $2, - don't forget that you'll need to double-quote it to make it a valid - identifier.) - - - - As with dropping a column, you need to add CASCADE if you - want to drop a constraint that something else depends on. An example - is that a foreign key constraint depends on a unique or primary key - constraint on the referenced column(s). - - - - This works the same for all constraint types except not-null - constraints. To drop a not null constraint use: - -ALTER TABLE products ALTER COLUMN product_no DROP NOT NULL; - - (Recall that not-null constraints do not have names.) - - - - - Changing a Column's Default Value - - - default value - changing - -&common; - - - To set a new default for a column, use a command like: - -ALTER TABLE products ALTER COLUMN price SET DEFAULT 7.77; - - Note that this doesn't affect any existing rows in the table, it - just changes the default for future INSERT commands. - - - - To remove any default value, use: - -ALTER TABLE products ALTER COLUMN price DROP DEFAULT; - - This is effectively the same as setting the default to null. - As a consequence, it is not an error - to drop a default where one hadn't been defined, because the - default is implicitly the null value. - - - - - Changing a Column's Data Type - - - column data type - changing - -&common; - - - To convert a column to a different data type, use a command like: - -ALTER TABLE products ALTER COLUMN price TYPE numeric(10,2); - - This will succeed only if each existing entry in the column can be - converted to the new type by an implicit cast. If a more complex - conversion is needed, you can add a USING clause that - specifies how to compute the new values from the old. - - - - - PostgreSQL will attempt to convert the column's - default value (if any) to the new type, as well as any constraints - that involve the column. But these conversions might fail, or might - produce surprising results. It's often best to drop any constraints - on the column before altering its type, and then add back suitably - modified constraints afterwords. - - - Postgres-XC will attempt to convert the column's - default value (if any) to the new type, as well as any constraints - that involve the column. But these conversions might fail, or might - produce surprising results. It's often best to drop any constraints - on the column before altering its type, and then add back suitably - modified constraints afterwards. - - - Postgres-XL will attempt to convert the column's - default value (if any) to the new type, as well as any constraints - that involve the column. But these conversions might fail, or might - produce surprising results. It's often best to drop any constraints - on the column before altering its type, and then add back suitably - modified constraints afterwards. - - - -&xconly; - - It is Postgres-XC's restriction that you cannot change the - type of distribution column. - - - -&xlonly; - - It is Postgres-XL's restriction that you cannot change the - type of distribution column. - - - - - - Renaming a Column - - - column - renaming - -&common; - - To rename a column: - -ALTER TABLE products RENAME COLUMN product_no TO product_number; - - - - - - Renaming a Table - - - table - renaming - -&common; - - To rename a table: - -ALTER TABLE products RENAME TO items; - - - - - - - Adding a Node to Distribution Target - - - table - distribution - - - To add a new node to existing distribution: - -ALTER TABLE products ADD NODE (datanode_3); - - The datanode must be a valid datanode name. If its a new datanode, then it -must have been added to the cluster by appropriate mechanism. To learn how to -add a node to the cluster, please see . - - - This command will redistribute the existing table data so as to include the -new node. For example, in case of DISTRIBUTE BY HASH strategy, hash -value for each row must be recomputed and the row must be moved to the selected -node based on the new count of datanodes in the distribution list. This -operation requires an exclusive lock on the table and hence all read and write -access to the table is temporarily blocked. This can be important especially if -the table is large and requires considerable time for -redistribution. - - - - Removing a Node from Distribution Target - - - table - distribution - -&common; - - To remove a node from existing distribution: - -ALTER TABLE products DELETE NODE (datanode_3); - - It must be noted that if you want to remove a node from the cluster, its -important that you first remove such node from all existing tables using that -node and then only remove the node from the cluster. - - - Like the previous command, this also takes an exclusive lock on the table, -blocking all read and write access to the table. - - - - Changing Distribution Strategy - - - table - distribution - -&common; - - To change distribution strategy for a table: - -ALTER TABLE products DISSTRIBUTE BY REPLICATION; - -You can change distribution strategy for a table with this command. For -example, a table which was previously distributed by HASH can now be -distributed by REPLICATION. - - - Like the previous command, this also takes an exclusive lock on the table, -blocking all read and write access to the table. - - - - - - - - Privileges - - - privilege - - - - permission - privilege - - - - owner - - - - GRANT - - - - REVOKE - -&common; - - When an object is created, it is assigned an owner. The - owner is normally the role that executed the creation statement. - For most kinds of objects, the initial state is that only the owner - (or a superuser) can do anything with the object. To allow - other roles to use it, privileges must be - granted. - - - - There are different kinds of privileges: SELECT, - INSERT, UPDATE, DELETE, - TRUNCATE, REFERENCES, TRIGGER, - CREATE, CONNECT, TEMPORARY, - EXECUTE, and USAGE. - The privileges applicable to a particular - object vary depending on the object's type (table, function, etc). - For complete information on the different types of privileges - supported by PostgreSQL, refer to the - reference - page. The following sections and chapters will also show you how - those privileges are used. - - - - The right to modify or destroy an object is always the privilege of - the owner only. - - - - An object can be assigned to a new owner with an ALTER - command of the appropriate kind for the object, e.g. . Superusers can always do - this; ordinary roles can only do it if they are both the current owner - of the object (or a member of the owning role) and a member of the new - owning role. - - - - To assign privileges, the GRANT command is - used. For example, if joe is an existing user, and - accounts is an existing table, the privilege to - update the table can be granted with: - -GRANT UPDATE ON accounts TO joe; - - Writing ALL in place of a specific privilege grants all - privileges that are relevant for the object type. - - - - The special user name PUBLIC can - be used to grant a privilege to every user on the system. Also, - group roles can be set up to help manage privileges when - there are many users of a database — for details see - . - - - - To revoke a privilege, use the fittingly named - REVOKE command: - -REVOKE ALL ON accounts FROM PUBLIC; - - The special privileges of the object owner (i.e., the right to do - DROP, GRANT, REVOKE, etc.) - are always implicit in being the owner, - and cannot be granted or revoked. But the object owner can choose - to revoke his own ordinary privileges, for example to make a - table read-only for himself as well as others. - - - - Ordinarily, only the object's owner (or a superuser) can grant or - revoke privileges on an object. However, it is possible to grant a - privilege with grant option, which gives the recipient - the right to grant it in turn to others. If the grant option is - subsequently revoked then all who received the privilege from that - recipient (directly or through a chain of grants) will lose the - privilege. For details see the and - reference pages. - - - - - Schemas - - - schema - -&common; - - A PostgreSQL database cluster - contains one or more named databases. Users and groups of users are - shared across the entire cluster, but no other data is shared across - databases. Any given client connection to the server can access - only the data in a single database, the one specified in the connection - request. - - - - - Users of a cluster do not necessarily have the privilege to access every - database in the cluster. Sharing of user names means that there - cannot be different users named, say, joe in two databases - in the same cluster; but the system can be configured to allow - joe access to only some of the databases. - - - - - A database contains one or more named schemas, which - in turn contain tables. Schemas also contain other kinds of named - objects, including data types, functions, and operators. The same - object name can be used in different schemas without conflict; for - example, both schema1 and myschema can - contain tables named mytable. Unlike databases, - schemas are not rigidly separated: a user can access objects in any - of the schemas in the database he is connected to, if he has - privileges to do so. - - - - There are several reasons why one might want to use schemas: - - - - - To allow many users to use one database without interfering with - each other. - - - - - - To organize database objects into logical groups to make them - more manageable. - - - - - - Third-party applications can be put into separate schemas so - they do not collide with the names of other objects. - - - - - Schemas are analogous to directories at the operating system level, - except that schemas cannot be nested. - - - - Creating a Schema - - - schema - creating - -&common; - - To create a schema, use the - command. Give the schema a name - of your choice. For example: - -CREATE SCHEMA myschema; - - - - - qualified name - - - - name - qualified - - - - To create or access objects in a schema, write a - qualified name consisting of the schema name and - table name separated by a dot: - -schema.table - - This works anywhere a table name is expected, including the table - modification commands and the data access commands discussed in - the following chapters. - (For brevity we will speak of tables only, but the same ideas apply - to other kinds of named objects, such as types and functions.) - - - - Actually, the even more general syntax - -database.schema.table - - can be used too, but at present this is just for pro - forma compliance with the SQL standard. If you write a database name, - it must be the same as the database you are connected to. - - - - So to create a table in the new schema, use: - -CREATE TABLE myschema.mytable ( - ... -); - - - - - schema - removing - - - - To drop a schema if it's empty (all objects in it have been - dropped), use: - -DROP SCHEMA myschema; - - To drop a schema including all contained objects, use: - -DROP SCHEMA myschema CASCADE; - - See for a description of the general - mechanism behind this. - - - - Often you will want to create a schema owned by someone else - (since this is one of the ways to restrict the activities of your - users to well-defined namespaces). The syntax for that is: - -CREATE SCHEMA schemaname AUTHORIZATION username; - - You can even omit the schema name, in which case the schema name - will be the same as the user name. See for how this can be useful. - - - - Schema names beginning with pg_ are reserved for - system purposes and cannot be created by users. - - - - - The Public Schema - - - schema - public - -&common; - - In the previous sections we created tables without specifying any - schema names. By default such tables (and other objects) are - automatically put into a schema named public. Every new - database contains such a schema. Thus, the following are equivalent: - -CREATE TABLE products ( ... ); - - and: - -CREATE TABLE public.products ( ... ); - - - - - - The Schema Search Path - - - search path - - - - unqualified name - - - - name - unqualified - -&common; - - Qualified names are tedious to write, and it's often best not to - wire a particular schema name into applications anyway. Therefore - tables are often referred to by unqualified names, - which consist of just the table name. The system determines which table - is meant by following a search path, which is a list - of schemas to look in. The first matching table in the search path - is taken to be the one wanted. If there is no match in the search - path, an error is reported, even if matching table names exist - in other schemas in the database. - - - - schema - current - - - - The first schema named in the search path is called the current schema. - Aside from being the first schema searched, it is also the schema in - which new tables will be created if the CREATE TABLE - command does not specify a schema name. - - - - search_path - - - - To show the current search path, use the following command: - -SHOW search_path; - - In the default setup this returns: - - search_path --------------- - "$user",public - - The first element specifies that a schema with the same name as - the current user is to be searched. If no such schema exists, - the entry is ignored. The second element refers to the - public schema that we have seen already. - - - - The first schema in the search path that exists is the default - location for creating new objects. That is the reason that by - default objects are created in the public schema. When objects - are referenced in any other context without schema qualification - (table modification, data modification, or query commands) the - search path is traversed until a matching object is found. - Therefore, in the default configuration, any unqualified access - again can only refer to the public schema. - - - - To put our new schema in the path, we use: - -SET search_path TO myschema,public; - - (We omit the $user here because we have no - immediate need for it.) And then we can access the table without - schema qualification: - -DROP TABLE mytable; - - Also, since myschema is the first element in - the path, new objects would by default be created in it. - - - - We could also have written: - -SET search_path TO myschema; - - Then we no longer have access to the public schema without - explicit qualification. There is nothing special about the public - schema except that it exists by default. It can be dropped, too. - - - - See also for other ways to manipulate - the schema search path. - - - - The search path works in the same way for data type names, function names, - and operator names as it does for table names. Data type and function - names can be qualified in exactly the same way as table names. If you - need to write a qualified operator name in an expression, there is a - special provision: you must write - -OPERATOR(schema.operator) - - This is needed to avoid syntactic ambiguity. An example is: - -SELECT 3 OPERATOR(pg_catalog.+) 4; - - In practice one usually relies on the search path for operators, - so as not to have to write anything so ugly as that. - - - - - Schemas and Privileges - - - privilege - for schemas - -&common; - - By default, users cannot access any objects in schemas they do not - own. To allow that, the owner of the schema must grant the - USAGE privilege on the schema. To allow users - to make use of the objects in the schema, additional privileges - might need to be granted, as appropriate for the object. - - - - A user can also be allowed to create objects in someone else's - schema. To allow that, the CREATE privilege on - the schema needs to be granted. Note that by default, everyone - has CREATE and USAGE privileges on - the schema - public. This allows all users that are able to - connect to a given database to create objects in its - public schema. If you do - not want to allow that, you can revoke that privilege: - -REVOKE CREATE ON SCHEMA public FROM PUBLIC; - - (The first public is the schema, the second - public means every user. In the - first sense it is an identifier, in the second sense it is a - key word, hence the different capitalization; recall the - guidelines from .) - - - - - The System Catalog Schema - - - system catalog - schema - -&common; - - In addition to public and user-created schemas, each - database contains a pg_catalog schema, which contains - the system tables and all the built-in data types, functions, and - operators. pg_catalog is always effectively part of - the search path. If it is not named explicitly in the path then - it is implicitly searched before searching the path's - schemas. This ensures that built-in names will always be - findable. However, you can explicitly place - pg_catalog at the end of your search path if you - prefer to have user-defined names override built-in names. - - - - In PostgreSQL versions before 7.3, - table names beginning with pg_ were reserved. This is - no longer true: you can create such a table name if you wish, in - any non-system schema. However, it's best to continue to avoid - such names, to ensure that you won't suffer a conflict if some - future version defines a system table named the same as your - table. (With the default search path, an unqualified reference to - your table name would then be resolved as the system table instead.) - System tables will continue to follow the convention of having - names beginning with pg_, so that they will not - conflict with unqualified user-table names so long as users avoid - the pg_ prefix. - - - - - Usage Patterns -&common; - - Schemas can be used to organize your data in many ways. There are - a few usage patterns that are recommended and are easily supported by - the default configuration: - - - - If you do not create any schemas then all users access the - public schema implicitly. This simulates the situation where - schemas are not available at all. This setup is mainly - recommended when there is only a single user or a few cooperating - users in a database. This setup also allows smooth transition - from the non-schema-aware world. - - - - - - You can create a schema for each user with the same name as - that user. Recall that the default search path starts with - $user, which resolves to the user name. - Therefore, if each user has a separate schema, they access their - own schemas by default. - - - - If you use this setup then you might also want to revoke access - to the public schema (or drop it altogether), so users are - truly constrained to their own schemas. - - - - - - To install shared applications (tables to be used by everyone, - additional functions provided by third parties, etc.), put them - into separate schemas. Remember to grant appropriate - privileges to allow the other users to access them. Users can - then refer to these additional objects by qualifying the names - with a schema name, or they can put the additional schemas into - their search path, as they choose. - - - - - - - - Portability -&common; - - In the SQL standard, the notion of objects in the same schema - being owned by different users does not exist. Moreover, some - implementations do not allow you to create schemas that have a - different name than their owner. In fact, the concepts of schema - and user are nearly equivalent in a database system that - implements only the basic schema support specified in the - standard. Therefore, many users consider qualified names to - really consist of - username.tablename. - This is how PostgreSQL will effectively - behave if you create a per-user schema for every user. - - - - Also, there is no concept of a public schema in the - SQL standard. For maximum conformance to the standard, you should - not use (perhaps even remove) the public schema. - - - - Of course, some SQL database systems might not implement schemas - at all, or provide namespace support by allowing (possibly - limited) cross-database access. If you need to work with those - systems, then maximum portability would be achieved by not using - schemas at all. - - - - - - - Inheritance - - - inheritance - - - - table - inheritance - -&common; - - PostgreSQL implements table inheritance, - which can be a useful tool for database designers. (SQL:1999 and - later define a type inheritance feature, which differs in many - respects from the features described here.) - - - - Let's start with an example: suppose we are trying to build a data - model for cities. Each state has many cities, but only one - capital. We want to be able to quickly retrieve the capital city - for any particular state. This can be done by creating two tables, - one for state capitals and one for cities that are not - capitals. However, what happens when we want to ask for data about - a city, regardless of whether it is a capital or not? The - inheritance feature can help to resolve this problem. We define the - capitals table so that it inherits from - cities: - - -CREATE TABLE cities ( - name text, - population float, - altitude int -- in feet -); - -CREATE TABLE capitals ( - state char(2) -) INHERITS (cities); - - - In this case, the capitals table inherits - all the columns of its parent table, cities. State - capitals also have an extra column, state, that shows - their state. - - - - In PostgreSQL, a table can inherit from - zero or more other tables, and a query can reference either all - rows of a table or all rows of a table plus all of its descendant tables. - The latter behavior is the default. - For example, the following query finds the names of all cities, - including state capitals, that are located at an altitude over - 500 feet: - - -SELECT name, altitude - FROM cities - WHERE altitude > 500; - - - Given the sample data from the PostgreSQL - tutorial (see ), this returns: - - - name | altitude ------------+---------- - Las Vegas | 2174 - Mariposa | 1953 - Madison | 845 - - - - - On the other hand, the following query finds all the cities that - are not state capitals and are situated at an altitude over 500 feet: - - -SELECT name, altitude - FROM ONLY cities - WHERE altitude > 500; - - name | altitude ------------+---------- - Las Vegas | 2174 - Mariposa | 1953 - - - - - Here the ONLY keyword indicates that the query - should apply only to cities, and not any tables - below cities in the inheritance hierarchy. Many - of the commands that we have already discussed — - SELECT, UPDATE and - DELETE — support the - ONLY keyword. - - - - In some cases you might wish to know which table a particular row - originated from. There is a system column called - tableoid in each table which can tell you the - originating table: - - -SELECT c.tableoid, c.name, c.altitude -FROM cities c -WHERE c.altitude > 500; - - - which returns: - - - tableoid | name | altitude -----------+-----------+---------- - 139793 | Las Vegas | 2174 - 139793 | Mariposa | 1953 - 139798 | Madison | 845 - - - - - (If you try to reproduce this example, you will probably get - different numeric OIDs.) By doing a join with - pg_class you can see the actual table names: - - -SELECT p.relname, c.name, c.altitude -FROM cities c, pg_class p -WHERE c.altitude > 500 AND c.tableoid = p.oid; - - - which returns: - - - relname | name | altitude -----------+-----------+---------- - cities | Las Vegas | 2174 - cities | Mariposa | 1953 - capitals | Madison | 845 - - - - - - Inheritance does not automatically propagate data from - INSERT or COPY commands to - other tables in the inheritance hierarchy. In our example, the - following INSERT statement will fail: - -INSERT INTO cities (name, population, altitude, state) -VALUES ('New York', NULL, NULL, 'NY'); - - We might hope that the data would somehow be routed to the - capitals table, but this does not happen: - INSERT always inserts into exactly the table - specified. In some cases it is possible to redirect the insertion - using a rule (see ). However that does not - help for the above case because the cities table - does not contain the column state, and so the - command will be rejected before the rule can be applied. - - - - All check constraints and not-null constraints on a parent table are - automatically inherited by its children. Other types of constraints - (unique, primary key, and foreign key constraints) are not inherited. - - - - A table can inherit from more than one parent table, in which case it has - the union of the columns defined by the parent tables. Any columns - declared in the child table's definition are added to these. If the - same column name appears in multiple parent tables, or in both a parent - table and the child's definition, then these columns are merged - so that there is only one such column in the child table. To be merged, - columns must have the same data types, else an error is raised. The - merged column will have copies of all the check constraints coming from - any one of the column definitions it came from, and will be marked not-null - if any of them are. - - - - Table inheritance is typically established when the child table is - created, using the INHERITS clause of the - - statement. - Alternatively, a table which is already defined in a compatible way can - have a new parent relationship added, using the INHERIT - variant of . - To do this the new child table must already include columns with - the same names and types as the columns of the parent. It must also include - check constraints with the same names and check expressions as those of the - parent. Similarly an inheritance link can be removed from a child using the - NO INHERIT variant of ALTER TABLE. - - - Dynamically adding and removing inheritance links like this can be useful - when the inheritance relationship is being used for table - partitioning (see ). - - - - - One convenient way to create a compatible table that will later be made - a new child is to use the LIKE clause in CREATE - TABLE. This creates a new table with the same columns as - the source table. If there are any CHECK - constraints defined on the source table, the INCLUDING - CONSTRAINTS option to LIKE should be - specified, as the new child must have constraints matching the parent - to be considered compatible. - - - - A parent table cannot be dropped while any of its children remain. Neither - can columns or check constraints of child tables be dropped or altered - if they are inherited - from any parent tables. If you wish to remove a table and all of its - descendants, one easy way is to drop the parent table with the - CASCADE option. - - - - will - propagate any changes in column data definitions and check - constraints down the inheritance hierarchy. Again, dropping - columns that are depended on by other tables is only possible when using - the CASCADE option. ALTER - TABLE follows the same rules for duplicate column merging - and rejection that apply during CREATE TABLE. - - - - Note how table access permissions are handled. Querying a parent - table can automatically access data in child tables without further - access privilege checking. This preserves the appearance that the - data is (also) in the parent table. Accessing the child tables - directly is, however, not automatically allowed and would require - further privileges to be granted. - - - - Caveats -&common; - - Note that not all SQL commands are able to work on - inheritance hierarchies. Commands that are used for data querying, - data modification, or schema modification - (e.g., SELECT, UPDATE, DELETE, - most variants of ALTER TABLE, but - not INSERT and ALTER TABLE ... - RENAME) typically default to including child tables and - support the ONLY notation to exclude them. - Commands that do database maintenance and tuning - (e.g., REINDEX, VACUUM) - typically only work on individual, physical tables and do no - support recursing over inheritance hierarchies. The respective - behavior of each individual command is documented in the reference - part (). - - - - A serious limitation of the inheritance feature is that indexes (including - unique constraints) and foreign key constraints only apply to single - tables, not to their inheritance children. This is true on both the - referencing and referenced sides of a foreign key constraint. Thus, - in the terms of the above example: - - - - - If we declared cities.name to be - UNIQUE or a PRIMARY KEY, this would not stop the - capitals table from having rows with names duplicating - rows in cities. And those duplicate rows would by - default show up in queries from cities. In fact, by - default capitals would have no unique constraint at all, - and so could contain multiple rows with the same name. - You could add a unique constraint to capitals, but this - would not prevent duplication compared to cities. - - - - - - Similarly, if we were to specify that - cities.name REFERENCES some - other table, this constraint would not automatically propagate to - capitals. In this case you could work around it by - manually adding the same REFERENCES constraint to - capitals. - - - - - - Specifying that another table's column REFERENCES - cities(name) would allow the other table to contain city names, but - not capital names. There is no good workaround for this case. - - - - - These deficiencies will probably be fixed in some future release, - but in the meantime considerable care is needed in deciding whether - inheritance is useful for your application. - - - - Deprecated - - In releases of PostgreSQL prior to 7.1, the - default behavior was not to include child tables in queries. This was - found to be error prone and also in violation of the SQL - standard. You can get the pre-7.1 behavior by turning off the - configuration - option. - - - - - - - - - - - Partitioning - - - partitioning - - - - table - partitioning - - - - PostgreSQL supports basic table - partitioning. This section describes why and how to implement - partitioning as part of your database design. - - - - Overview - - - Partitioning refers to splitting what is logically one large table - into smaller physical pieces. - Partitioning can provide several benefits: - - - - Query performance can be improved dramatically in certain situations, - particularly when most of the heavily accessed rows of the table are in a - single partition or a small number of partitions. The partitioning - substitutes for leading columns of indexes, reducing index size and - making it more likely that the heavily-used parts of the indexes - fit in memory. - - - - - - When queries or updates access a large percentage of a single - partition, performance can be improved by taking advantage - of sequential scan of that partition instead of using an - index and random access reads scattered across the whole table. - - - - - - Bulk loads and deletes can be accomplished by adding or removing - partitions, if that requirement is planned into the partitioning design. - ALTER TABLE is far faster than a bulk operation. - It also entirely avoids the VACUUM - overhead caused by a bulk DELETE. - - - - - - Seldom-used data can be migrated to cheaper and slower storage media. - - - - - The benefits will normally be worthwhile only when a table would - otherwise be very large. The exact point at which a table will - benefit from partitioning depends on the application, although a - rule of thumb is that the size of the table should exceed the physical - memory of the database server. - - - - Currently, PostgreSQL supports partitioning - via table inheritance. Each partition must be created as a child - table of a single parent table. The parent table itself is normally - empty; it exists just to represent the entire data set. You should be - familiar with inheritance (see ) before - attempting to set up partitioning. - - - - The following forms of partitioning can be implemented in - PostgreSQL: - - - - Range Partitioning - - - - The table is partitioned into ranges defined - by a key column or set of columns, with no overlap between - the ranges of values assigned to different partitions. For - example one might partition by date ranges, or by ranges of - identifiers for particular business objects. - - - - - - List Partitioning - - - - The table is partitioned by explicitly listing which key values - appear in each partition. - - - - - - - - - Implementing Partitioning - - - To set up a partitioned table, do the following: - - - - Create the master table, from which all of the - partitions will inherit. - - - This table will contain no data. Do not define any check - constraints on this table, unless you intend them to - be applied equally to all partitions. There is no point - in defining any indexes or unique constraints on it, either. - - - - - - Create several child tables that each inherit from - the master table. Normally, these tables will not add any columns - to the set inherited from the master. - - - - We will refer to the child tables as partitions, though they - are in every way normal PostgreSQL tables. - - - - - - Add table constraints to the partition tables to define the - allowed key values in each partition. - - - - Typical examples would be: - -CHECK ( x = 1 ) -CHECK ( county IN ( 'Oxfordshire', 'Buckinghamshire', 'Warwickshire' )) -CHECK ( outletID >= 100 AND outletID < 200 ) - - Ensure that the constraints guarantee that there is no overlap - between the key values permitted in different partitions. A common - mistake is to set up range constraints like: - -CHECK ( outletID BETWEEN 100 AND 200 ) -CHECK ( outletID BETWEEN 200 AND 300 ) - - This is wrong since it is not clear which partition the key value - 200 belongs in. - - - - Note that there is no difference in - syntax between range and list partitioning; those terms are - descriptive only. - - - - - - For each partition, create an index on the key column(s), - as well as any other indexes you might want. (The key index is - not strictly necessary, but in most scenarios it is helpful. - If you intend the key values to be unique then you should - always create a unique or primary-key constraint for each - partition.) - - - - - - Optionally, define a trigger or rule to redirect data inserted into - the master table to the appropriate partition. - - - - - - Ensure that the - configuration parameter is not disabled in - postgresql.conf. - If it is, queries will not be optimized as desired. - - - - - - - - For example, suppose we are constructing a database for a large - ice cream company. The company measures peak temperatures every - day as well as ice cream sales in each region. Conceptually, - we want a table like: - - -CREATE TABLE measurement ( - city_id int not null, - logdate date not null, - peaktemp int, - unitsales int -); - - - We know that most queries will access just the last week's, month's or - quarter's data, since the main use of this table will be to prepare - online reports for management. - To reduce the amount of old data that needs to be stored, we - decide to only keep the most recent 3 years worth of data. At the - beginning of each month we will remove the oldest month's data. - - - - In this situation we can use partitioning to help us meet all of our - different requirements for the measurements table. Following the - steps outlined above, partitioning can be set up as follows: - - - - - - - The master table is the measurement table, declared - exactly as above. - - - - - - Next we create one partition for each active month: - - -CREATE TABLE measurement_y2006m02 ( ) INHERITS (measurement); -CREATE TABLE measurement_y2006m03 ( ) INHERITS (measurement); -... -CREATE TABLE measurement_y2007m11 ( ) INHERITS (measurement); -CREATE TABLE measurement_y2007m12 ( ) INHERITS (measurement); -CREATE TABLE measurement_y2008m01 ( ) INHERITS (measurement); - - - Each of the partitions are complete tables in their own right, - but they inherit their definitions from the - measurement table. - - - - This solves one of our problems: deleting old data. Each - month, all we will need to do is perform a DROP - TABLE on the oldest child table and create a new - child table for the new month's data. - - - - - - We must provide non-overlapping table constraints. Rather than - just creating the partition tables as above, the table creation - script should really be: - - -CREATE TABLE measurement_y2006m02 ( - CHECK ( logdate >= DATE '2006-02-01' AND logdate < DATE '2006-03-01' ) -) INHERITS (measurement); -CREATE TABLE measurement_y2006m03 ( - CHECK ( logdate >= DATE '2006-03-01' AND logdate < DATE '2006-04-01' ) -) INHERITS (measurement); -... -CREATE TABLE measurement_y2007m11 ( - CHECK ( logdate >= DATE '2007-11-01' AND logdate < DATE '2007-12-01' ) -) INHERITS (measurement); -CREATE TABLE measurement_y2007m12 ( - CHECK ( logdate >= DATE '2007-12-01' AND logdate < DATE '2008-01-01' ) -) INHERITS (measurement); -CREATE TABLE measurement_y2008m01 ( - CHECK ( logdate >= DATE '2008-01-01' AND logdate < DATE '2008-02-01' ) -) INHERITS (measurement); - - - - - - - We probably need indexes on the key columns too: - - -CREATE INDEX measurement_y2006m02_logdate ON measurement_y2006m02 (logdate); -CREATE INDEX measurement_y2006m03_logdate ON measurement_y2006m03 (logdate); -... -CREATE INDEX measurement_y2007m11_logdate ON measurement_y2007m11 (logdate); -CREATE INDEX measurement_y2007m12_logdate ON measurement_y2007m12 (logdate); -CREATE INDEX measurement_y2008m01_logdate ON measurement_y2008m01 (logdate); - - - We choose not to add further indexes at this time. - - - - - - We want our application to be able to say INSERT INTO - measurement ... and have the data be redirected into the - appropriate partition table. We can arrange that by attaching - a suitable trigger function to the master table. - If data will be added only to the latest partition, we can - use a very simple trigger function: - - -CREATE OR REPLACE FUNCTION measurement_insert_trigger() -RETURNS TRIGGER AS $$ -BEGIN - INSERT INTO measurement_y2008m01 VALUES (NEW.*); - RETURN NULL; -END; -$$ -LANGUAGE plpgsql; - - - After creating the function, we create a trigger which - calls the trigger function: - - -CREATE TRIGGER insert_measurement_trigger - BEFORE INSERT ON measurement - FOR EACH ROW EXECUTE PROCEDURE measurement_insert_trigger(); - - - We must redefine the trigger function each month so that it always - points to the current partition. The trigger definition does - not need to be updated, however. - - - - We might want to insert data and have the server automatically - locate the partition into which the row should be added. We - could do this with a more complex trigger function, for example: - - -CREATE OR REPLACE FUNCTION measurement_insert_trigger() -RETURNS TRIGGER AS $$ -BEGIN - IF ( NEW.logdate >= DATE '2006-02-01' AND - NEW.logdate < DATE '2006-03-01' ) THEN - INSERT INTO measurement_y2006m02 VALUES (NEW.*); - ELSIF ( NEW.logdate >= DATE '2006-03-01' AND - NEW.logdate < DATE '2006-04-01' ) THEN - INSERT INTO measurement_y2006m03 VALUES (NEW.*); - ... - ELSIF ( NEW.logdate >= DATE '2008-01-01' AND - NEW.logdate < DATE '2008-02-01' ) THEN - INSERT INTO measurement_y2008m01 VALUES (NEW.*); - ELSE - RAISE EXCEPTION 'Date out of range. Fix the measurement_insert_trigger() function!'; - END IF; - RETURN NULL; -END; -$$ -LANGUAGE plpgsql; - - - The trigger definition is the same as before. - Note that each IF test must exactly match the - CHECK constraint for its partition. - - - - While this function is more complex than the single-month case, - it doesn't need to be updated as often, since branches can be - added in advance of being needed. - - - - - In practice it might be best to check the newest partition first, - if most inserts go into that partition. For simplicity we have - shown the trigger's tests in the same order as in other parts - of this example. - - - - - - - - As we can see, a complex partitioning scheme could require a - substantial amount of DDL. In the above example we would be - creating a new partition each month, so it might be wise to write a - script that generates the required DDL automatically. - - - - - - Managing Partitions - - - Normally the set of partitions established when initially - defining the table are not intended to remain static. It is - common to want to remove old partitions of data and periodically - add new partitions for new data. One of the most important - advantages of partitioning is precisely that it allows this - otherwise painful task to be executed nearly instantaneously by - manipulating the partition structure, rather than physically moving large - amounts of data around. - - - - The simplest option for removing old data is simply to drop the partition - that is no longer necessary: - -DROP TABLE measurement_y2006m02; - - This can very quickly delete millions of records because it doesn't have - to individually delete every record. - - - - Another option that is often preferable is to remove the partition from - the partitioned table but retain access to it as a table in its own - right: - -ALTER TABLE measurement_y2006m02 NO INHERIT measurement; - - This allows further operations to be performed on the data before - it is dropped. For example, this is often a useful time to back up - the data using COPY, pg_dump, or - similar tools. It might also be a useful time to aggregate data - into smaller formats, perform other data manipulations, or run - reports. - - - - Similarly we can add a new partition to handle new data. We can create an - empty partition in the partitioned table just as the original partitions - were created above: - - -CREATE TABLE measurement_y2008m02 ( - CHECK ( logdate >= DATE '2008-02-01' AND logdate < DATE '2008-03-01' ) -) INHERITS (measurement); - - - As an alternative, it is sometimes more convenient to create the - new table outside the partition structure, and make it a proper - partition later. This allows the data to be loaded, checked, and - transformed prior to it appearing in the partitioned table: - - -CREATE TABLE measurement_y2008m02 - (LIKE measurement INCLUDING DEFAULTS INCLUDING CONSTRAINTS); -ALTER TABLE measurement_y2008m02 ADD CONSTRAINT y2008m02 - CHECK ( logdate >= DATE '2008-02-01' AND logdate < DATE '2008-03-01' ); -\copy measurement_y2008m02 from 'measurement_y2008m02' --- possibly some other data preparation work -ALTER TABLE measurement_y2008m02 INHERIT measurement; - - - - - - Partitioning and Constraint Exclusion - - - constraint exclusion - - - - Constraint exclusion is a query optimization technique - that improves performance for partitioned tables defined in the - fashion described above. As an example: - - -SET constraint_exclusion = on; -SELECT count(*) FROM measurement WHERE logdate >= DATE '2008-01-01'; - - - Without constraint exclusion, the above query would scan each of - the partitions of the measurement table. With constraint - exclusion enabled, the planner will examine the constraints of each - partition and try to prove that the partition need not - be scanned because it could not contain any rows meeting the query's - WHERE clause. When the planner can prove this, it - excludes the partition from the query plan. - - - - You can use the EXPLAIN command to show the difference - between a plan with constraint_exclusion on and a plan - with it off. A typical unoptimized plan for this type of table setup is: - - -SET constraint_exclusion = off; -EXPLAIN SELECT count(*) FROM measurement WHERE logdate >= DATE '2008-01-01'; - - QUERY PLAN ------------------------------------------------------------------------------------------------ - Aggregate (cost=158.66..158.68 rows=1 width=0) - -> Append (cost=0.00..151.88 rows=2715 width=0) - -> Seq Scan on measurement (cost=0.00..30.38 rows=543 width=0) - Filter: (logdate >= '2008-01-01'::date) - -> Seq Scan on measurement_y2006m02 measurement (cost=0.00..30.38 rows=543 width=0) - Filter: (logdate >= '2008-01-01'::date) - -> Seq Scan on measurement_y2006m03 measurement (cost=0.00..30.38 rows=543 width=0) - Filter: (logdate >= '2008-01-01'::date) -... - -> Seq Scan on measurement_y2007m12 measurement (cost=0.00..30.38 rows=543 width=0) - Filter: (logdate >= '2008-01-01'::date) - -> Seq Scan on measurement_y2008m01 measurement (cost=0.00..30.38 rows=543 width=0) - Filter: (logdate >= '2008-01-01'::date) - - - Some or all of the partitions might use index scans instead of - full-table sequential scans, but the point here is that there - is no need to scan the older partitions at all to answer this query. - When we enable constraint exclusion, we get a significantly - cheaper plan that will deliver the same answer: - - -SET constraint_exclusion = on; -EXPLAIN SELECT count(*) FROM measurement WHERE logdate >= DATE '2008-01-01'; - QUERY PLAN ------------------------------------------------------------------------------------------------ - Aggregate (cost=63.47..63.48 rows=1 width=0) - -> Append (cost=0.00..60.75 rows=1086 width=0) - -> Seq Scan on measurement (cost=0.00..30.38 rows=543 width=0) - Filter: (logdate >= '2008-01-01'::date) - -> Seq Scan on measurement_y2008m01 measurement (cost=0.00..30.38 rows=543 width=0) - Filter: (logdate >= '2008-01-01'::date) - - - - - Note that constraint exclusion is driven only by CHECK - constraints, not by the presence of indexes. Therefore it isn't - necessary to define indexes on the key columns. Whether an index - needs to be created for a given partition depends on whether you - expect that queries that scan the partition will generally scan - a large part of the partition or just a small part. An index will - be helpful in the latter case but not the former. - - - - The default (and recommended) setting of - is actually neither - on nor off, but an intermediate setting - called partition, which causes the technique to be - applied only to queries that are likely to be working on partitioned - tables. The on setting causes the planner to examine - CHECK constraints in all queries, even simple ones that - are unlikely to benefit. - - - - - - Alternative Partitioning Methods - - - A different approach to redirecting inserts into the appropriate - partition table is to set up rules, instead of a trigger, on the - master table. For example: - - -CREATE RULE measurement_insert_y2006m02 AS -ON INSERT TO measurement WHERE - ( logdate >= DATE '2006-02-01' AND logdate < DATE '2006-03-01' ) -DO INSTEAD - INSERT INTO measurement_y2006m02 VALUES (NEW.*); -... -CREATE RULE measurement_insert_y2008m01 AS -ON INSERT TO measurement WHERE - ( logdate >= DATE '2008-01-01' AND logdate < DATE '2008-02-01' ) -DO INSTEAD - INSERT INTO measurement_y2008m01 VALUES (NEW.*); - - - A rule has significantly more overhead than a trigger, but the overhead - is paid once per query rather than once per row, so this method might be - advantageous for bulk-insert situations. In most cases, however, the - trigger method will offer better performance. - - - - Be aware that COPY ignores rules. If you want to - use COPY to insert data, you'll need to copy into the correct - partition table rather than into the master. COPY does fire - triggers, so you can use it normally if you use the trigger approach. - - - - Another disadvantage of the rule approach is that there is no simple - way to force an error if the set of rules doesn't cover the insertion - date; the data will silently go into the master table instead. - - - - Partitioning can also be arranged using a UNION ALL - view, instead of table inheritance. For example, - - -CREATE VIEW measurement AS - SELECT * FROM measurement_y2006m02 -UNION ALL SELECT * FROM measurement_y2006m03 -... -UNION ALL SELECT * FROM measurement_y2007m11 -UNION ALL SELECT * FROM measurement_y2007m12 -UNION ALL SELECT * FROM measurement_y2008m01; - - - However, the need to recreate the view adds an extra step to adding and - dropping individual partitions of the data set. In practice this - method has little to recommend it compared to using inheritance. - - - - - - Caveats - - - The following caveats apply to partitioned tables: - - - - There is no automatic way to verify that all of the - CHECK constraints are mutually - exclusive. It is safer to create code that generates - partitions and creates and/or modifies associated objects than - to write each by hand. - - - - - - The schemes shown here assume that the partition key column(s) - of a row never change, or at least do not change enough to require - it to move to another partition. An UPDATE that attempts - to do that will fail because of the CHECK constraints. - If you need to handle such cases, you can put suitable update triggers - on the partition tables, but it makes management of the structure - much more complicated. - - - - - - If you are using manual VACUUM or - ANALYZE commands, don't forget that - you need to run them on each partition individually. A command like: - -ANALYZE measurement; - - will only process the master table. - - - - - - - - The following caveats apply to constraint exclusion: - - - - - Constraint exclusion only works when the query's WHERE - clause contains constants. A parameterized query will not be - optimized, since the planner cannot know which partitions the - parameter value might select at run time. For the same reason, - stable functions such as CURRENT_DATE - must be avoided. - - - - - - Keep the partitioning constraints simple, else the planner may not be - able to prove that partitions don't need to be visited. Use simple - equality conditions for list partitioning, or simple - range tests for range partitioning, as illustrated in the preceding - examples. A good rule of thumb is that partitioning constraints should - contain only comparisons of the partitioning column(s) to constants - using B-tree-indexable operators. - - - - - - All constraints on all partitions of the master table are examined - during constraint exclusion, so large numbers of partitions are likely - to increase query planning time considerably. Partitioning using - these techniques will work well with up to perhaps a hundred partitions; - don't try to use many thousands of partitions. - - - - - - - - - - Foreign Data - - - foreign data - - - foreign table - - - - PostgreSQL implements portions of the SQL/MED - specification, allowing you to access data that resides outside - PostgreSQL using regular SQL queries. Such data is referred to as - foreign data. (Note that this usage is not to be confused - with foreign keys, which are a type of constraint within the database.) - - - - Foreign data is accessed with help from a - foreign data wrapper. A foreign data wrapper is a - library that can communicate with an external data source, hiding the - details of connecting to the data source and fetching data from it. There - are several foreign data wrappers available, which can for example read - plain data files residing on the server, or connect to another PostgreSQL - instance. If none of the existing foreign data wrappers suit your needs, - you can write your own; see . - - - - To access foreign data, you need to create a foreign server - object, which defines how to connect to a particular external data source, - according to the set of options used by a particular foreign data - wrapper. Then you need to create one or more foreign - tables, which define the structure of the remote data. A - foreign table can be used in queries just like a normal table, but a - foreign table has no storage in the PostgreSQL server. Whenever it is - used, PostgreSQL asks the foreign data wrapper to fetch the data from the - external source. - - - - Currently, foreign tables are read-only. This limitation may be fixed - in a future release. - - - - - - - - Other Database Objects -&common; - - Tables are the central objects in a relational database structure, - because they hold your data. But they are not the only objects - that exist in a database. Many other kinds of objects can be - created to make the use and management of the data more efficient - or convenient. They are not discussed in this chapter, but we give - you a list here so that you are aware of what is possible: - - - - - - Views - - - - - - Functions and operators - - - - - - Data types and domains - - - - - - Triggers and rewrite rules - - - - - - Detailed information on - these topics appears in . - - - - - Dependency Tracking - - - CASCADE - with DROP - - - - RESTRICT - with DROP - -&common; - - When you create complex database structures involving many tables - with foreign key constraints, views, triggers, functions, etc. you - implicitly create a net of dependencies between the objects. - For instance, a table with a foreign key constraint depends on the - table it references. - - - - To ensure the integrity of the entire database structure, - PostgreSQL makes sure that you cannot - drop objects that other objects still depend on. For example, - attempting to drop the products table we had considered in , with the orders table depending on - it, would result in an error message such as this: - -DROP TABLE products; - -NOTICE: constraint orders_product_no_fkey on table orders depends on table products -ERROR: cannot drop table products because other objects depend on it -HINT: Use DROP ... CASCADE to drop the dependent objects too. - - The error message contains a useful hint: if you do not want to - bother deleting all the dependent objects individually, you can run: - -DROP TABLE products CASCADE; - - and all the dependent objects will be removed. In this case, it - doesn't remove the orders table, it only removes the foreign key - constraint. (If you want to check what DROP ... CASCADE will do, - run DROP without CASCADE and read the NOTICE messages.) - - - - All drop commands in PostgreSQL support - specifying CASCADE. Of course, the nature of - the possible dependencies varies with the type of the object. You - can also write RESTRICT instead of - CASCADE to get the default behavior, which is to - prevent the dropping of objects that other objects depend on. - - - - - According to the SQL standard, specifying either - RESTRICT or CASCADE is - required. No database system actually enforces that rule, but - whether the default behavior is RESTRICT or - CASCADE varies across systems. - - - - - - Foreign key constraint dependencies and serial column dependencies - from PostgreSQL versions prior to 7.3 - are not maintained or created during the - upgrade process. All other dependency types will be properly - created during an upgrade from a pre-7.3 database. - - - - - diff --git a/doc-xc/src/sgml/dfunc.sgmlin b/doc-xc/src/sgml/dfunc.sgmlin deleted file mode 100644 index 16a2b1809e..0000000000 --- a/doc-xc/src/sgml/dfunc.sgmlin +++ /dev/null @@ -1,368 +0,0 @@ - - - - Compiling and Linking Dynamically-loaded Functions - -&common; - - - Before you are able to use your - - PostgreSQL extension functions written in - - - Postgres-XC extension functions written in - - - Postgres-XL extension functions written in - - C, they must be compiled and linked in a special way to produce a - file that can be dynamically loaded by the server. To be precise, a - shared library needs to be - created.shared library - - - - - 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 - - - In addition, the Postgres-XC source code - - - In addition, the Postgres-XL source code - - contains several working examples in the - contrib directory. If you rely on these - examples you will make your modules dependent on the availability - - of the PostgreSQL source code, however. - - - of the Postgres-XC source code, however. - - - of the Postgres-XL source code, however. - - - - - Creating shared libraries is generally analogous to linking - executables: first the source files are compiled into object files, - then the object files are linked together. The object files need to - be created as position-independent code - (PIC),PIC which - conceptually means that they can be placed at an arbitrary location - in memory when they are loaded by the executable. (Object files - intended for executables are usually not compiled that way.) The - command to link a shared library contains special flags to - distinguish it from linking an executable (at least in theory - — on some systems the practice is much uglier). - - - - In the following examples we assume that your source code is in a - file foo.c and we will create a shared library - foo.so. The intermediate object file will be - called foo.o unless otherwise noted. A shared - library can contain more than one object file, but we only use one - here. - - - - - - - - - - - BSD/OS - BSD/OSshared library - - - The compiler flag to create PIC is - . The linker flag to create shared - libraries is . - -gcc -fpic -c foo.c -ld -shared -o foo.so foo.o - - This is applicable as of version 4.0 of - BSD/OS. - - - - - - - FreeBSD - FreeBSDshared library - - - The compiler flag to create PIC is - . To create shared libraries the compiler - flag is . - -gcc -fpic -c foo.c -gcc -shared -o foo.so foo.o - - This is applicable as of version 3.0 of - FreeBSD. - - - - - - - HP-UX - HP-UXshared library - - - The compiler flag of the system compiler to create - PIC is . When using - GCC it's . The - linker flag for shared libraries is . So: - -cc +z -c foo.c - - or: - -gcc -fpic -c foo.c - - and then: - -ld -b -o foo.sl foo.o - - HP-UX uses the extension - .sl for shared libraries, unlike most other - systems. - - - - - - - - IRIX - IRIXshared library - - - PIC is the default, no special compiler - options are necessary. The linker option to produce shared - libraries is . - -cc -c foo.c -ld -shared -o foo.so foo.o - - - - - - - Linux - Linuxshared library - - - The compiler flag to create PIC is - . On some platforms in some situations - must be used if - does not work. Refer to the GCC manual for more information. - The compiler flag to create a shared library is - . A complete example looks like this: - -cc -fpic -c foo.c -cc -shared -o foo.so foo.o - - - - - - - - - MacOS X - MacOS Xshared library - - - 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 - - - - - - - NetBSD - NetBSDshared library - - - The compiler flag to create PIC is - . For ELF systems, the - compiler with the flag is used to link - shared libraries. On the older non-ELF systems, ld - -Bshareable is used. - -gcc -fpic -c foo.c -gcc -shared -o foo.so foo.o - - - - - - - - - OpenBSD - OpenBSDshared library - - - The compiler flag to create PIC is - . ld -Bshareable is - used to link shared libraries. - -gcc -fpic -c foo.c -ld -Bshareable -o foo.so foo.o - - - - - - - Solaris - Solarisshared library - - - The compiler flag to create PIC is - with the Sun compiler and - with GCC. To - link shared libraries, the compiler option is - with either compiler or alternatively - with GCC. - -cc -KPIC -c foo.c -cc -G -o foo.so foo.o - - or - -gcc -fpic -c foo.c -gcc -G -o foo.so foo.o - - - - - - - - - Tru64 UNIX - Tru64 UNIXshared library - Digital UNIXTru64 UNIX - - - PIC is the default, so the compilation command - is the usual one. ld with special options is - used to do the linking. - -cc -c foo.c -ld -shared -expect_unresolved '*' -o foo.so foo.o - - The same procedure is used with GCC instead of the system - compiler; no special options are required. - - - - - - UnixWare - UnixWareshared library - - - The compiler flag to create PIC is with the SCO compiler and - with GCC. To link shared libraries, - the compiler option is with the SCO compiler - and with - GCC. - -cc -K PIC -c foo.c -cc -G -o foo.so foo.o - - or - -gcc -fpic -c foo.c -gcc -shared -o foo.so foo.o - - - - - - - - - - - - - If this is too complicated for you, you should consider using - - GNU Libtool, - which hides the platform differences behind a uniform interface. - - - - - The resulting shared library file can then be loaded into - - PostgreSQL. When specifying the file name - - - Postgres-XC. When specifying the file name - - - Postgres-XL. When specifying the file name - - to the CREATE FUNCTION command, one must give it - the name of the shared library file, not the intermediate object file. - Note that the system's standard shared-library extension (usually - .so or .sl) can be omitted from - the CREATE FUNCTION command, and normally should - be omitted for best portability. - - - - Refer back to about where the - server expects to find the shared library files. - - - - - diff --git a/doc-xc/src/sgml/dict-int.sgmlin b/doc-xc/src/sgml/dict-int.sgmlin deleted file mode 100644 index 132be1ac2b..0000000000 --- a/doc-xc/src/sgml/dict-int.sgmlin +++ /dev/null @@ -1,94 +0,0 @@ - - - - dict_int - - - dict_int - - -&pgnotice; - - - - dict_int is an example of an add-on dictionary template - for full-text search. The motivation for this example dictionary is to - control the indexing of integers (signed and unsigned), allowing such - numbers to be indexed while preventing excessive growth in the number of - unique words, which greatly affects the performance of searching. - - - - Configuration - -&pgnotice; - - - - The dictionary accepts two options: - - - - - - The maxlen parameter specifies the maximum number of - digits allowed in an integer word. The default value is 6. - - - - - The rejectlong parameter specifies whether an overlength - integer should be truncated or ignored. If rejectlong is - false (the default), the dictionary returns the first - maxlen digits of the integer. If rejectlong is - true, the dictionary treats an overlength integer as a stop - word, so that it will not be indexed. Note that this also means that - such an integer cannot be searched for. - - - - - - - Usage - -&pgnotice; - - - - Installing the dict_int extension creates a text search - template intdict_template and a dictionary intdict - based on it, with the default parameters. You can alter the - parameters, for example - - -mydb# ALTER TEXT SEARCH DICTIONARY intdict (MAXLEN = 4, REJECTLONG = true); -ALTER TEXT SEARCH DICTIONARY - - - or create new dictionaries based on the template. - - - - To test the dictionary, you can try - - -mydb# select ts_lexize('intdict', '12345678'); - ts_lexize ------------ - {123456} - - - but real-world usage will involve including it in a text search - configuration as described in . - That might look like this: - - -ALTER TEXT SEARCH CONFIGURATION english - ALTER MAPPING FOR int, uint WITH intdict; - - - - - - diff --git a/doc-xc/src/sgml/dict-xsyn.sgmlin b/doc-xc/src/sgml/dict-xsyn.sgmlin deleted file mode 100644 index 242d30760f..0000000000 --- a/doc-xc/src/sgml/dict-xsyn.sgmlin +++ /dev/null @@ -1,158 +0,0 @@ - - - - dict_xsyn - - - dict_xsyn - - -&pgnotice; - - - - dict_xsyn (Extended Synonym Dictionary) is an example of an - add-on dictionary template for full-text search. This dictionary type - replaces words with groups of their synonyms, and so makes it possible to - search for a word using any of its synonyms. - - - - Configuration - -&pgnotice; - - - - A dict_xsyn dictionary accepts the following options: - - - - - matchorig controls whether the original word is accepted by - the dictionary. Default is true. - - - - - matchsynonyms controls whether the synonyms are - accepted by the dictionary. Default is false. - - - - - keeporig controls whether the original word is included in - the dictionary's output. Default is true. - - - - - keepsynonyms controls whether the synonyms are included in - the dictionary's output. Default is true. - - - - - rules is the base name of the file containing the list of - synonyms. This file must be stored in - $SHAREDIR/tsearch_data/ (where $SHAREDIR means - the PostgreSQL installation's shared-data directory). - Its name must end in .rules (which is not to be included in - the rules parameter). - - - - - The rules file has the following format: - - - - - Each line represents a group of synonyms for a single word, which is - given first on the line. Synonyms are separated by whitespace, thus: - -word syn1 syn2 syn3 - - - - - - The sharp (#) sign is a comment delimiter. It may appear at - any position in a line. The rest of the line will be skipped. - - - - - - Look at xsyn_sample.rules, which is installed in - $SHAREDIR/tsearch_data/, for an example. - - - - - Usage - -&pgnotice; - - - - Installing the dict_xsyn extension creates a text search - template xsyn_template and a dictionary xsyn - based on it, with default parameters. You can alter the - parameters, for example - - -mydb# ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=false); -ALTER TEXT SEARCH DICTIONARY - - - or create new dictionaries based on the template. - - - - To test the dictionary, you can try - - -mydb=# SELECT ts_lexize('xsyn', 'word'); - ts_lexize ------------------------ - {syn1,syn2,syn3} - -mydb# ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=true); -ALTER TEXT SEARCH DICTIONARY - -mydb=# SELECT ts_lexize('xsyn', 'word'); - ts_lexize ------------------------ - {word,syn1,syn2,syn3} - -mydb# ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=false, MATCHSYNONYMS=true); -ALTER TEXT SEARCH DICTIONARY - -mydb=# SELECT ts_lexize('xsyn', 'syn1'); - ts_lexize ------------------------ - {syn1,syn2,syn3} - -mydb# ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=true, MATCHORIG=false, KEEPSYNONYMS=false); -ALTER TEXT SEARCH DICTIONARY - -mydb=# SELECT ts_lexize('xsyn', 'syn1'); - ts_lexize ------------------------ - {word} - - - Real-world usage will involve including it in a text search - configuration as described in . - That might look like this: - - -ALTER TEXT SEARCH CONFIGURATION english - ALTER MAPPING FOR word, asciiword WITH xsyn, english_stem; - - - - - - diff --git a/doc-xc/src/sgml/diskusage.sgmlin b/doc-xc/src/sgml/diskusage.sgmlin deleted file mode 100644 index 6f5595bc93..0000000000 --- a/doc-xc/src/sgml/diskusage.sgmlin +++ /dev/null @@ -1,147 +0,0 @@ - - - - Monitoring Disk Usage - -&pgnotice; - - - This chapter discusses how to monitor the disk usage of a - PostgreSQL database system. - - - - Determining Disk Usage - - - disk usage - - - - Each table has a primary heap disk file where most of the data is - stored. If the table has any columns with potentially-wide values, - there also might be a TOAST file associated with the table, - which is used to store values too wide to fit comfortably in the main - table (see ). There will be one index on the - TOAST table, if present. There also might be indexes associated - with the base table. Each table and index is stored in a separate disk - file — possibly more than one file, if the file would exceed one - gigabyte. Naming conventions for these files are described in . - - - - You can monitor disk space in three ways: - using the SQL functions listed in , - using the module, or - using manual inspection of the system catalogs. - The SQL functions are the easiest to use and are generally recommended. - The remainder of this section shows how to do it by inspection of the - system catalogs. - - - - Using psql on a recently vacuumed or analyzed database, - you can issue queries to see the disk usage of any table: - -SELECT pg_relation_filepath(oid), relpages FROM pg_class WHERE relname = 'customer'; - - pg_relation_filepath | relpages -----------------------+---------- - base/16384/16806 | 60 -(1 row) - - Each page is typically 8 kilobytes. (Remember, relpages - is only updated by VACUUM, ANALYZE, and - a few DDL commands such as CREATE INDEX.) The file path name - is of interest if you want to examine the table's disk file directly. - - - - To show the space used by TOAST tables, use a query - like the following: - -SELECT relname, relpages -FROM pg_class, - (SELECT reltoastrelid - FROM pg_class - WHERE relname = 'customer') AS ss -WHERE oid = ss.reltoastrelid OR - oid = (SELECT reltoastidxid - FROM pg_class - WHERE oid = ss.reltoastrelid) -ORDER BY relname; - - relname | relpages -----------------------+---------- - pg_toast_16806 | 0 - pg_toast_16806_index | 1 - - - - - You can easily display index sizes, too: - -SELECT c2.relname, c2.relpages -FROM pg_class c, pg_class c2, pg_index i -WHERE c.relname = 'customer' AND - c.oid = i.indrelid AND - c2.oid = i.indexrelid -ORDER BY c2.relname; - - relname | relpages -----------------------+---------- - customer_id_indexdex | 26 - - - - - It is easy to find your largest tables and indexes using this - information: - -SELECT relname, relpages -FROM pg_class -ORDER BY relpages DESC; - - relname | relpages -----------------------+---------- - bigtable | 3290 - customer | 3144 - - - - - - Disk Full Failure -&pgnotice; - - - The most important disk monitoring task of a database administrator - is to make sure the disk doesn't become full. A filled data disk will - not result in data corruption, but it might prevent useful activity - from occurring. If the disk holding the WAL files grows full, database - server panic and consequent shutdown might occur. - - - - If you cannot free up additional space on the disk by deleting - other things, you can move some of the database files to other file - systems by making use of tablespaces. See for more information about that. - - - - - Some file systems perform badly when they are almost full, so do - not wait until the disk is completely full to take action. - - - - - If your system supports per-user disk quotas, then the database - will naturally be subject to whatever quota is placed on the user - the server runs as. Exceeding the quota will have the same bad - effects as running out of disk space entirely. - - - diff --git a/doc-xc/src/sgml/dml.sgmlin b/doc-xc/src/sgml/dml.sgmlin deleted file mode 100644 index 8c4507c732..0000000000 --- a/doc-xc/src/sgml/dml.sgmlin +++ /dev/null @@ -1,278 +0,0 @@ - - - - Data Manipulation - - - This chapter is still quite incomplete. - - - - The previous chapter discussed how to create tables and other - structures to hold your data. Now it is time to fill the tables - with data. This chapter covers how to insert, update, and delete - table data. The chapter - after this will finally explain how to extract your long-lost data - from the database. - - - - Inserting Data - - - inserting - - - - INSERT - -&common; - - When a table is created, it contains no data. The first thing to - do before a database can be of much use is to insert data. Data is - conceptually inserted one row at a time. Of course you can also - insert more than one row, but there is no way to insert less than - one row. Even if you know only some column values, a - complete row must be created. - - - - To create a new row, use the - command. The command requires the - table name and column values. For - example, consider the products table from : - -CREATE TABLE products ( - product_no integer, - name text, - price numeric -); - - An example command to insert a row would be: - -INSERT INTO products VALUES (1, 'Cheese', 9.99); - - The data values are listed in the order in which the columns appear - in the table, separated by commas. Usually, the data values will - be literals (constants), but scalar expressions are also allowed. - - - - The above syntax has the drawback that you need to know the order - of the columns in the table. To avoid this you can also list the - columns explicitly. For example, both of the following commands - have the same effect as the one above: - -INSERT INTO products (product_no, name, price) VALUES (1, 'Cheese', 9.99); -INSERT INTO products (name, price, product_no) VALUES ('Cheese', 9.99, 1); - - Many users consider it good practice to always list the column - names. - - - - If you don't have values for all the columns, you can omit some of - them. In that case, the columns will be filled with their default - values. For example: - -INSERT INTO products (product_no, name) VALUES (1, 'Cheese'); -INSERT INTO products VALUES (1, 'Cheese'); - - - The second form is a PostgreSQL - - - The second form is a Postgres-XC - - - The second form is a Postgres-XL - - extension. It fills the columns from the left with as many values - as are given, and the rest will be defaulted. - - - - For clarity, you can also request default values explicitly, for - individual columns or for the entire row: - -INSERT INTO products (product_no, name, price) VALUES (1, 'Cheese', DEFAULT); -INSERT INTO products DEFAULT VALUES; - - - - - You can insert multiple rows in a single command: - -INSERT INTO products (product_no, name, price) VALUES - (1, 'Cheese', 9.99), - (2, 'Bread', 1.99), - (3, 'Milk', 2.99); - - - - - - When inserting a lot of data at the same time, considering using - the command. - It is not as flexible as the - command, but is more efficient. Refer - to for more information on improving - bulk loading performance. - - - - - - Updating Data - - - updating - - - - UPDATE - -&common; - - The modification of data that is already in the database is - referred to as updating. You can update individual rows, all the - rows in a table, or a subset of all rows. Each column can be - updated separately; the other columns are not affected. - - - - To update existing rows, use the - command. This requires - three pieces of information: - - - The name of the table and column to update - - - - The new value of the column - - - - Which row(s) to update - - - - - - Recall from that SQL does not, in general, - provide a unique identifier for rows. Therefore it is not - always possible to directly specify which row to update. - Instead, you specify which conditions a row must meet in order to - be updated. Only if you have a primary key in the table (independent of - whether you declared it or not) can you reliably address individual rows - by choosing a condition that matches the primary key. - Graphical database access tools rely on this fact to allow you to - update rows individually. - - - - For example, this command updates all products that have a price of - 5 to have a price of 10: - -UPDATE products SET price = 10 WHERE price = 5; - - This might cause zero, one, or many rows to be updated. It is not - an error to attempt an update that does not match any rows. - - - - Let's look at that command in detail. First is the key word - UPDATE followed by the table name. As usual, - the table name can be schema-qualified, otherwise it is looked up - in the path. Next is the key word SET followed - by the column name, an equal sign, and the new column value. The - new column value can be any scalar expression, not just a constant. - For example, if you want to raise the price of all products by 10% - you could use: - -UPDATE products SET price = price * 1.10; - - As you see, the expression for the new value can refer to the existing - value(s) in the row. We also left out the WHERE clause. - If it is omitted, it means that all rows in the table are updated. - If it is present, only those rows that match the - WHERE condition are updated. Note that the equals - sign in the SET clause is an assignment while - the one in the WHERE clause is a comparison, but - this does not create any ambiguity. Of course, the - WHERE condition does - not have to be an equality test. Many other operators are - available (see ). But the expression - needs to evaluate to a Boolean result. - - - - You can update more than one column in an - UPDATE command by listing more than one - assignment in the SET clause. For example: - -UPDATE mytable SET a = 5, b = 3, c = 1 WHERE a > 0; - - - - -&xconly; - - Please remember that Postgres-XC does not allow to - modify the value of distribution column. - - - -&xlonly; - - Please remember that Postgres-XL does not allow to - modify the value of distribution column. - - - - - - Deleting Data - - - deleting - - - - DELETE - -&common; - - So far we have explained how to add data to tables and how to - change data. What remains is to discuss how to remove data that is - no longer needed. Just as adding data is only possible in whole - rows, you can only remove entire rows from a table. In the - previous section we explained that SQL does not provide a way to - directly address individual rows. Therefore, removing rows can - only be done by specifying conditions that the rows to be removed - have to match. If you have a primary key in the table then you can - specify the exact row. But you can also remove groups of rows - matching a condition, or you can remove all rows in the table at - once. - - - - You use the - command to remove rows; the syntax is very similar to the - UPDATE command. For instance, to remove all - rows from the products table that have a price of 10, use: - -DELETE FROM products WHERE price = 10; - - - - - If you simply write: - -DELETE FROM products; - - then all rows in the table will be deleted! Caveat programmer. - - - diff --git a/doc-xc/src/sgml/docguide.sgmlin b/doc-xc/src/sgml/docguide.sgmlin deleted file mode 100644 index 04e8005d11..0000000000 --- a/doc-xc/src/sgml/docguide.sgmlin +++ /dev/null @@ -1,1482 +0,0 @@ - - - - Documentation - -&common; - - - - PostgreSQL has four primary documentation - - - Postgres-XC has four primary documentation - - - Postgres-XL has four primary documentation - - formats: - - - - - Plain text, for pre-installation information - - - - - HTML, for on-line browsing and reference - - - - - PDF or PostScript, for printing - - - - - man pages, for quick reference. - - - - - Additionally, a number of plain-text README files can - - be found throughout the PostgreSQL source tree, - - - be found throughout the Postgres-XC source tree, - - - be found throughout the Postgres-XL source tree, - - documenting various implementation issues. - - - - HTML documentation and man pages are part of a - standard distribution and are installed by default. PDF and - PostScript format documentation is available separately for - download. - - - - DocBook -&common; - - The documentation sources are written in - DocBook, which is a markup language - superficially similar to HTML. Both of these - languages are applications of the Standard Generalized - Markup Language, SGML, which is - essentially a language for describing other languages. In what - follows, the terms DocBook and SGML are both - used, but technically they are not interchangeable. - - - - DocBook allows an author to specify the - structure and content of a technical document without worrying - about presentation details. A document style defines how that - content is rendered into one of several final forms. DocBook is - maintained by the - OASIS group. The - official DocBook site has good introductory and reference documentation and - a complete O'Reilly book for your online reading pleasure. The - - NewbieDoc Docbook Guide is very helpful for beginners. - The - FreeBSD Documentation Project also uses DocBook and has some good - information, including a number of style guidelines that might be - worth considering. - - - -&xconly; - - To make it simpler to compare original PostgreSQL - documentation with Postgres-XC, we decided to - generate DocBook file from new file prefixed - as sgmlin. sgmlin file is - essentially DocBook file with additional - tags <!## tag> and <!## end>. - The former is a start tag and the latter is the stop tag. These - tags should occupy whole line. No other tags or CCDATA should - appear in the same line. The tool makesgml takes these - file, filter only Postgres-XC specific contents and - generate target sgml files. - - - Makefile has been modified to accommodate these changes. - - - -&xlonly; - - To make it simpler to compare original PostgreSQL - documentation with Postgres-XL, we decided to - generate DocBook file from new file prefixed - as sgmlin. sgmlin file is - essentially DocBook file with additional - tags <!## tag> and <!## end>. - The former is a start tag and the latter is the stop tag. These - tags should occupy whole line. No other tags or CCDATA should - appear in the same line. The tool makesgml takes these - file, filter only Postgres-XL specific contents and - generate target sgml files. - - - Makefile has been modified to accommodate these changes. - - - - - - - Tool Sets - -&common; - - The following tools are used to process the documentation. Some - might be optional, as noted. - - - - DocBook DTD - - - This is the definition of DocBook itself. We currently use - version 4.2; you cannot use later or earlier versions. You - need the SGML variant of the DocBook DTD, - but to build man pages you also need the XML - variant of the same version. - - - - - - ISO 8879 character entities - - - These are required by DocBook but are distributed separately - because they are maintained by ISO. - - - - - - DocBook DSSSL Stylesheets - - - These contain the processing instructions for converting the - DocBook sources to other formats, such as - HTML. - - - - - - DocBook XSL Stylesheets - - - This is another stylesheet for converting DocBook to other - formats. We currently use this to produce man pages and - optionally HTMLHelp. You can also use this toolchain to - - produce HTML or PDF output, but official PostgreSQL releases - - - produce HTML or PDF output, but official Postgres-XC releases - - - produce HTML or PDF output, but official Postgres-XL releases - - use the DSSSL stylesheets for that. - - - - - - OpenJade - - - This is the base package of SGML processing. - It contains an SGML parser, a - DSSSL processor (that is, a program to - convert SGML to other formats using - DSSSL stylesheets), as well as a number of - related tools. Jade is now being - maintained by the OpenJade group, no longer by James Clark. - - - - - - Libxslt for xsltproc - - - This is the processing tool to use with the XSLT stylesheets - (like jade is the processing tool for DSSSL - stylesheets). - - - - - - JadeTeX - - - If you want to, you can also install - JadeTeX to use - TeX as a formatting backend for - Jade. - JadeTeX can create PostScript or - PDF files (the latter with bookmarks). - - - - However, the output from JadeTeX is - inferior to what you get from the RTF - backend. Particular problem areas are tables and various - artifacts of vertical and horizontal spacing. Also, there is - no opportunity to manually polish the results. - - - - - - - makesgml - - -&xconly; - - makesgml is Postgres-XC specific - tool to generate sgml file from sgmlin - file. As described above, sgmlin file contains - both PostgreSQL and Postgres-XC - documentation source to make it simpler to deal with future - revision of original PostgreSQL documentation. - - - makesgml source is included in the document source. - Build the binary and place this to appropriate path. - - - - - - - - - makesgml - - -&xlonly; - - makesgml is Postgres-XL specific - tool to generate sgml file from sgmlin - file. As described above, sgmlin file contains - both PostgreSQL and Postgres-XL - documentation source to make it simpler to deal with future - revision of original PostgreSQL documentation. - - - makesgml source is included in the document source. - Build the binary and place this to appropriate path. - - - - - - - - - - - - We have documented experience with several installation methods for - the various tools that are needed to process the documentation. - These will be described below. There might be some other packaged - distributions for these tools. Please report package status to the - documentation mailing list, and we will include that information - here. - - - - <productname>Linux</productname> <acronym>RPM</acronym> Installation - -&common; - - Most vendors provide a complete RPM set for DocBook processing in - their distribution. Look for an SGML option while - installing, or the following packages: - sgml-common, docbook, - stylesheets, openjade - (or jade). Possibly - sgml-tools will be needed as well. If your - distributor does not provide these then you should be able to make - use of the packages from some other, reasonably compatible vendor. - - - - - - FreeBSD Installation - -&common; - - The FreeBSD Documentation Project is itself a heavy user of - DocBook, so it comes as no surprise that there is a full set of - ports of the documentation tools available on - FreeBSD. The following ports need to be installed to build the - documentation on FreeBSD. - - - textproc/sp - - - textproc/openjade - - - textproc/iso8879 - - - textproc/dsssl-docbook-modular - - - textproc/docbook-420 - - - - - - A number of things from /usr/ports/print - (tex, jadetex) might - also be of interest. - - - - It's possible that the ports do not update the main catalog file - in /usr/local/share/sgml/catalog.ports or order - isn't proper . Be sure to have the following lines in beginning of file: - -CATALOG "openjade/catalog" -CATALOG "iso8879/catalog" -CATALOG "docbook/dsssl/modular/catalog" -CATALOG "docbook/4.2/catalog" - - If you do not want to edit the file you can also set the - environment variable SGML_CATALOG_FILES to a - colon-separated list of catalog files (such as the one above). - - - - More information about the FreeBSD documentation tools can be - found in the - FreeBSD Documentation Project's instructions. - - - - - - - Debian Packages - -&common; - - There is a full set of packages of the documentation tools - available for Debian GNU/Linux. - To install, simply use: - -apt-get install docbook docbook-dsssl docbook-xsl openjade1.3 xsltproc - - - - - - - Manual Installation from Source - -&common; - - The manual installation process of the DocBook tools is somewhat - complex, so if you have pre-built packages available, use them. - We describe here only a standard setup, with reasonably standard - installation paths, and no fancy features. For - details, you should study the documentation of the respective - package, and read SGML introductory material. - - - - Installing OpenJade - - - -&common; - - The installation of OpenJade offers a GNU-style - ./configure; make; make install build - process. Details can be found in the OpenJade source - distribution. In a nutshell: - -./configure --enable-default-catalog=/usr/local/share/sgml/catalog -make -make install - - Be sure to remember where you put the default - catalog; you will need it below. You can also leave - it off, but then you will have to set the environment variable - SGML_CATALOG_FILES to point to the file - whenever you use jade later on. - (This method is also an option if OpenJade is already - installed and you want to install the rest of the toolchain - locally.) - - - - - Some users have reported encountering a segmentation fault using - openjade 1.4devel to build the PDFs, with a message like: - -openjade:./stylesheet.dsl:664:2:E: flow object not accepted by port; only display flow objects accepted -make: *** [postgres-A4.tex-pdf] Segmentation fault - - Downgrading to openjade 1.3 should get rid of this error. - - - - - - - - Additionally, you should install the files - dsssl.dtd, fot.dtd, - style-sheet.dtd, and - catalog from the - dsssl directory somewhere, perhaps into - /usr/local/share/sgml/dsssl. It's - probably easiest to copy the entire directory: - -cp -R dsssl /usr/local/share/sgml - - - - - - - Finally, create the file - /usr/local/share/sgml/catalog and add - this line to it: - -CATALOG "dsssl/catalog" - - (This is a relative path reference to the file installed in - . Be sure to adjust it - if you chose your installation layout differently.) - - - - - - - Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit - - - -&common; - - Obtain the - DocBook V4.2 distribution. - - - - - - Create the directory - /usr/local/share/sgml/docbook-4.2 and change - to it. (The exact location is irrelevant, but this one is - reasonable within the layout we are following here.) - -$ mkdir /usr/local/share/sgml/docbook-4.2 -$ cd /usr/local/share/sgml/docbook-4.2 - - - - - - - Unpack the archive: - -$ unzip -a ...../docbook-4.2.zip - - (The archive will unpack its files into the current directory.) - - - - - - Edit the file - /usr/local/share/sgml/catalog (or whatever - you told jade during installation) and put a line like this - into it: - -CATALOG "docbook-4.2/docbook.cat" - - - - - - - Download the - ISO 8879 character entities archive, unpack it, and put the - files in the same directory you put the DocBook files in: - -$ cd /usr/local/share/sgml/docbook-4.2 -$ unzip ...../ISOEnts.zip - - - - - - - Run the following command in the directory with the DocBook and ISO files: - -perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat - - (This fixes a mixup between the names used in the DocBook - catalog file and the actual names of the ISO character entity - files.) - - - - - - - Installing the DocBook <acronym>DSSSL</acronym> Style Sheets - -&common; - - To install the style sheets, unzip and untar the distribution and - move it to a suitable place, for example - /usr/local/share/sgml. (The archive will - automatically create a subdirectory.) - -$ gunzip docbook-dsssl-1.xx.tar.gz -$ tar -C /usr/local/share/sgml -xf docbook-dsssl-1.xx.tar - - - - - The usual catalog entry in - /usr/local/share/sgml/catalog can also be - made: - -CATALOG "docbook-dsssl-1.xx/catalog" - - Because stylesheets change rather often, and it's sometimes - beneficial to try out alternative versions, - - PostgreSQL doesn't use this catalog - - - Postgres-XC doesn't use this catalog - - - Postgres-XL doesn't use this catalog - - entry. See for - information about how to select the stylesheets instead. - - - - - Installing <productname>JadeTeX</productname> - -&common; - - To install and use JadeTeX, you will - need a working installation of TeX and - LaTeX2e, including the supported - tools and - graphics packages, - Babel, - AMS fonts and - AMS-LaTeX, the - PSNFSS extension - and companion kit of the 35 fonts, the - dvips program for generating - PostScript, the macro packages - fancyhdr, - hyperref, - minitoc, - url and - ot2enc. All of these can be found on - your friendly neighborhood - CTAN site. - The installation of the TeX base - system is far beyond the scope of this introduction. Binary - packages should be available for any system that can run - TeX. - - - - Before you can use JadeTeX with the - - PostgreSQL documentation sources, you - - - Postgres-XC documentation sources, you - - - Postgres-XL documentation sources, you - - will need to increase the size of - TeX's internal data structures. - Details on this can be found in the JadeTeX - installation instructions. - - - - Once that is finished you can install JadeTeX: - -$ gunzip jadetex-xxx.tar.gz -$ tar xf jadetex-xxx.tar -$ cd jadetex -$ make install -$ mktexlsr - - The last two need to be done as root. - - - - - - - - Detection by <command>configure</command> - -&common; - - Before you can build the documentation you need to run the - configure script as you would when building - - the PostgreSQL programs themselves. - - - the Postgres-XC programs themselves. - - - the Postgres-XL programs themselves. - - Check the output near the end of the run, it should look something - like this: - - -checking for onsgmls... onsgmls -checking for openjade... openjade -checking for DocBook V4.2... yes -checking for DocBook stylesheets... /usr/share/sgml/docbook/stylesheet/dsssl/modular -checking for collateindex.pl... /usr/bin/collateindex.pl -checking for xsltproc... xsltproc -checking for osx... osx - - - If neither onsgmls nor - nsgmls were found then some of the following tests - will be skipped. nsgmls is part of the Jade - package. You can pass the environment variables - JADE and NSGMLS to configure to point - to the programs if they are not found automatically. If - DocBook V4.2 was not found then you did not install - the DocBook DTD kit in a place where Jade can find it, or you have - not set up the catalog files correctly. See the installation hints - above. The DocBook stylesheets are looked for in a number of - relatively standard places, but if you have them some other place - then you should set the environment variable - DOCBOOKSTYLE to the location and rerun - configure afterwards. - - - - - - - Building The Documentation - -&common; - - Once you have everything set up, change to the directory - doc/src/sgml and run one of the commands - described in the following subsections to build the - documentation. (Remember to use GNU make.) - - - - HTML - -&common; - - To build the HTML version of the documentation: - -doc/src/sgml$ gmake html - - This is also the default target. The output appears in the - subdirectory html. - - - - To create a proper index, the build might process several identical - stages. If you do not care about the index, and just want to - proof-read the output, use draft: - -doc/src/sgml$ gmake draft - - - - - To build the documentation as a single HTML page, use: - -doc/src/sgml$ gmake postgres.html - - - - - - Manpages - -&common; - - We use the DocBook XSL stylesheets to - convert DocBook - refentry pages to *roff output suitable for man - pages. The man pages are also distributed as a tar archive, - similar to the HTML version. To create the man - pages, use the commands: - -cd doc/src/sgml -gmake man - - - - - - Print Output via <application>JadeTeX</application> - -&common; - - If you want to use JadeTex to produce a - printable rendition of the documentation, you can use one of the - following commands: - - - - - To generate PostScript via DVI in A4 format: - -doc/src/sgml$ gmake postgres-A4.ps - - In U.S. letter format: - -doc/src/sgml$ gmake postgres-US.ps - - - - - - - To make a PDF: - -doc/src/sgml$ gmake postgres-A4.pdf - - or: - -doc/src/sgml$ gmake postgres-US.pdf - - (Of course you can also make a PDF version - from the PostScript, but if you generate PDF - directly, it will have hyperlinks and other enhanced features.) - - - - - - - - When using JadeTeX to build the PostgreSQL documentation, you will - - - When using JadeTeX to build the Postgres-XC documentation, you will - - - When using JadeTeX to build the Postgres-XL documentation, you will - - probably need to increase some of TeX's internal parameters. These - can be set in the file texmf.cnf. The following - settings worked at the time of this writing: - -hash_extra.jadetex = 200000 -hash_extra.pdfjadetex = 200000 -pool_size.jadetex = 2000000 -pool_size.pdfjadetex = 2000000 -string_vacancies.jadetex = 150000 -string_vacancies.pdfjadetex = 150000 -max_strings.jadetex = 300000 -max_strings.pdfjadetex = 300000 -save_size.jadetex = 15000 -save_size.pdfjadetex = 15000 - - - - - - - Overflow Text - -&common; - - Occasionally text is too wide for the printed margins, and in - extreme cases, too wide for the printed page, e.g. non-wrapped - text, wide tables. Overly wide text generates Overfull - hbox messages in the TeX log output file, e.g. - postgres-US.log or postgres-A4.log. - There are 72 points in an inch so anything reported as over 72 - points too wide will probably not fit on the printed page (assuming - one inch margins). To find the SGML text - causing the overflow, find the first page number mentioned above - the overflow message, e.g. [50 ###] (page 50), and - look at the page after that (e.g. page 51) in the PDF - file to see the overflow text and adjust the SGML - accordingly. - - - - - Print Output via <acronym>RTF</acronym> - -&common; - - - You can also create a printable version of the PostgreSQL - - - You can also create a printable version of the Postgres-XC - - - You can also create a printable version of the Postgres-XL - - documentation by converting it to RTF and - applying minor formatting corrections using an office suite. - Depending on the capabilities of the particular office suite, you - can then convert the documentation to PostScript of - PDF. The procedure below illustrates this - process using Applixware. - - - - - - It appears that current versions of the PostgreSQL documentation - - - It appears that current versions of the Postgres-XC documentation - - - It appears that current versions of the Postgres-XL documentation - - trigger some bug in or exceed the size limit of OpenJade. If the - build process of the RTF version hangs for a - long time and the output file still has size 0, then you might have - hit that problem. (But keep in mind that a normal build takes 5 - to 10 minutes, so don't abort too soon.) - - - - - <productname>Applixware</productname> <acronym>RTF</acronym> Cleanup - - - OpenJade omits specifying a default - style for body text. In the past, this undiagnosed problem led to - a long process of table of contents generation. However, with - great help from the Applixware folks - the symptom was diagnosed and a workaround is available. - - - - - Generate the RTF version by typing: - -doc/src/sgml$ gmake postgres.rtf - - - - - - - Repair the RTF file to correctly specify all styles, in - particular the default style. If the document contains - refentry sections, one must also replace - formatting hints which tie a preceding paragraph to the current - paragraph, and instead tie the current paragraph to the - following one. A utility, fixrtf, is - available in doc/src/sgml to accomplish - these repairs: - -doc/src/sgml$ ./fixrtf --refentry postgres.rtf - - - - - The script adds {\s0 Normal;} as the zeroth - style in the document. According to - Applixware, the RTF standard would - prohibit adding an implicit zeroth style, though Microsoft Word - happens to handle this case. For repairing - refentry sections, the script replaces - \keepn tags with \keep. - - - - - - Open a new document in Applixware Words and - then import the RTF file. - - - - - - Generate a new table of contents (ToC) using - Applixware. - - - - - - Select the existing ToC lines, from the beginning of the first - character on the first line to the last character of the last - line. - - - - - - Build a new ToC using - ToolsBook - BuildingCreate Table of - Contents. Select the first three - levels of headers for inclusion in the ToC. This will replace - the existing lines imported in the RTF with a native - Applixware ToC. - - - - - - Adjust the ToC formatting by using - FormatStyle, - selecting each of the three ToC styles, and adjusting the - indents for First and - Left. Use the following values: - - - - - - Style - First Indent (inches) - Left Indent (inches) - - - - - - TOC-Heading 1 - 0.4 - 0.4 - - - - TOC-Heading 2 - 0.8 - 0.8 - - - - TOC-Heading 3 - 1.2 - 1.2 - - - - - - - - - - - - Work through the document to: - - - - - Adjust page breaks. - - - - - - Adjust table column widths. - - - - - - - - - Replace the right-justified page numbers in the Examples and - Figures portions of the ToC with correct values. This only takes - a few minutes. - - - - - - Delete the index section from the document if it is empty. - - - - - - Regenerate and adjust the table of contents. - - - - - - Select the ToC field. - - - - - - Select ToolsBook - BuildingCreate Table of - Contents. - - - - - - Unbind the ToC by selecting - ToolsField - EditingUnprotect. - - - - - - Delete the first line in the ToC, which is an entry for the - ToC itself. - - - - - - - - Save the document as native Applixware - Words format to allow easier last minute editing - later. - - - - - - Print the document - to a file in PostScript format. - - - - - - - Plain Text Files - -&common; - - Several files are distributed as plain text, for reading during - the installation process. The INSTALL file - corresponds to , with some minor - changes to account for the different context. To recreate the - file, change to the directory doc/src/sgml - and enter gmake INSTALL. This will create - a file INSTALL.html that can be saved as text - with Netscape Navigator and put into - the place of the existing file. - Netscape seems to offer the best - quality for HTML to text conversions (over - lynx and - w3m). - - - - The file HISTORY can be created similarly, - using the command gmake HISTORY. For the - file src/test/regress/README the command is - gmake regress_README. - - - - - Syntax Check - -&common; - - Building the documentation can take very long. But there is a - method to just check the correct syntax of the documentation - files, which only takes a few seconds: - -doc/src/sgml$ gmake check - - - - - - - - Documentation Authoring - -&common; - - SGML and DocBook do - not suffer from an oversupply of open-source authoring tools. The - most common tool set is the - Emacs/XEmacs - editor with appropriate editing mode. On some systems - these tools are provided in a typical full installation. - - - - Emacs/PSGML - -&common; - - PSGML is the most common and most - powerful mode for editing SGML documents. - When properly configured, it will allow you to use - Emacs to insert tags and check markup - consistency. You could use it for HTML as - well. Check the - PSGML web site for downloads, installation instructions, and - detailed documentation. - - - - There is one important thing to note with - PSGML: its author assumed that your - main SGML DTD directory - would be /usr/local/lib/sgml. If, as in the - examples in this chapter, you use - /usr/local/share/sgml, you have to - compensate for this, either by setting - SGML_CATALOG_FILES environment variable, or you - can customize your PSGML installation - (its manual tells you how). - - - - Put the following in your ~/.emacs - environment file (adjusting the path names to be appropriate for - your system): - - -; ********** for SGML mode (psgml) - -(setq sgml-omittag t) -(setq sgml-shorttag t) -(setq sgml-minimize-attributes nil) -(setq sgml-always-quote-attributes t) -(setq sgml-indent-step 1) -(setq sgml-indent-data t) -(setq sgml-parent-document nil) -(setq sgml-exposed-tags nil) -(setq sgml-catalog-files '("/usr/local/share/sgml/catalog")) - -(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t ) - - - and in the same file add an entry for SGML - into the (existing) definition for - auto-mode-alist: - -(setq - auto-mode-alist - '(("\\.sgml$" . sgml-mode) - )) - - - - - You might find that when using PSGML, a - comfortable way of working with these separate files of book - parts is to insert a proper DOCTYPE - declaration while you're editing them. If you are working on - this source, for instance, it is an appendix chapter, so you - would specify the document as an appendix instance - of a DocBook document by making the first line look like this: - - -<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.2//EN"> - - - This means that anything and everything that reads - SGML will get it right, and I can verify the - document with nsgmls -s docguide.sgml. (But - you need to take out that line before building the entire - documentation set.) - - - - - Other Emacs Modes - -&common; - - GNU Emacs ships with a different - SGML mode, which is not quite as powerful as - PSGML, but it's less confusing and - lighter weight. Also, it offers syntax highlighting (font lock), - which can be very helpful. - src/tools/editors/emacs.samples contains - sample settings for this mode. - - - - Norm Walsh offers a - major mode - specifically for DocBook which also has font-lock and a number of features to - reduce typing. - - - - - - - - Style Guide - - - Reference Pages - -&common; - - Reference pages should follow a standard layout. This allows - users to find the desired information more quickly, and it also - encourages writers to document all relevant aspects of a command. - Consistency is not only desired among - - PostgreSQL reference pages, but also - - - Postgres-XC reference pages, but also - - - Postgres-XL reference pages, but also - - with reference pages provided by the operating system and other - packages. Hence the following guidelines have been developed. - They are for the most part consistent with similar guidelines - established by various operating systems. - - - - Reference pages that describe executable commands should contain - the following sections, in this order. Sections that do not apply - can be omitted. Additional top-level sections should only be used - in special circumstances; often that information belongs in the - Usage section. - - - - Name - - - This section is generated automatically. It contains the - command name and a half-sentence summary of its functionality. - - - - - - Synopsis - - - This section contains the syntax diagram of the command. The - synopsis should normally not list each command-line option; - that is done below. Instead, list the major components of the - command line, such as where input and output files go. - - - - - - Description - - - Several paragraphs explaining what the command does. - - - - - - Options - - - A list describing each command-line option. If there are a - lot of options, subsections can be used. - - - - - - Exit Status - - - If the program uses 0 for success and non-zero for failure, - then you do not need to document it. If there is a meaning - behind the different non-zero exit codes, list them here. - - - - - - Usage - - - Describe any sublanguage or run-time interface of the program. - If the program is not interactive, this section can usually be - omitted. Otherwise, this section is a catch-all for - describing run-time features. Use subsections if appropriate. - - - - - - Environment - - - List all environment variables that the program might use. - Try to be complete; even seemingly trivial variables like - SHELL might be of interest to the user. - - - - - - Files - - - List any files that the program might access implicitly. That - is, do not list input and output files that were specified on - the command line, but list configuration files, etc. - - - - - - Diagnostics - - - Explain any unusual output that the program might create. - Refrain from listing every possible error message. This is a - lot of work and has little use in practice. But if, say, the - error messages have a standard format that the user can parse, - this would be the place to explain it. - - - - - - Notes - - - Anything that doesn't fit elsewhere, but in particular bugs, - implementation flaws, security considerations, compatibility - issues. - - - - - - Examples - - - Examples - - - - - - History - - - If there were some major milestones in the history of the - program, they might be listed here. Usually, this section can - be omitted. - - - - - - See Also - - - Cross-references, listed in the following order: other - - PostgreSQL command reference pages, - PostgreSQL SQL command reference - pages, citation of PostgreSQL - - - Postgres-XC command reference pages, - Postgres-XC SQL command reference - pages, citation of Postgres-XC - - - Postgres-XL command reference pages, - Postgres-XL SQL command reference - pages, citation of Postgres-XL - - manuals, other reference pages (e.g., operating system, other - packages), other documentation. Items in the same group are - listed alphabetically. - - - - - - - - - Reference pages describing SQL commands should contain the - following sections: Name, Synopsis, Description, Parameters, - Outputs, Notes, Examples, Compatibility, History, See - Also. The Parameters section is like the Options section, but - there is more freedom about which clauses of the command can be - listed. The Outputs section is only needed if the command returns - something other than a default command-completion tag. The Compatibility - section should explain to what extent - this command conforms to the SQL standard(s), or to which other - database system it is compatible. The See Also section of SQL - commands should list SQL commands before cross-references to - programs. - - - - - diff --git a/doc-xc/src/sgml/dummy-seclabel.sgmlin b/doc-xc/src/sgml/dummy-seclabel.sgmlin deleted file mode 100644 index 28d19d2409..0000000000 --- a/doc-xc/src/sgml/dummy-seclabel.sgmlin +++ /dev/null @@ -1,74 +0,0 @@ - - - - dummy_seclabel - - - dummy_seclabel - - - - The dummy_seclabel module exists only to support regression - testing of the SECURITY LABEL statement. It is not intended - to be used in production. - - - - Rationale - - - The SECURITY LABEL statement allows the user to assign security - labels to database objects; however, security labels can only be assigned - when specifically allowed by a loadable module, so this module is provided - to allow proper regression testing. - - - - Security label providers intended to be used in production will typically be - dependent on a platform-specific feature such as - SE-Linux. This module is platform-independent, - and therefore better-suited to regression testing. - - - - - Usage - - - Here's a simple example of usage: - - - -# postgresql.conf -shared_preload_libraries = 'dummy_label' - - - -postgres=# CREATE TABLE t (a int, b text); -CREATE TABLE -postgres=# SECURITY LABEL ON TABLE t IS 'classified'; -SECURITY LABEL - - - - The dummy_seclabel module provides only four hardcoded - labels: unclassified, classified, - secret, and top secret. - It does not allow any other strings as security labels. - - - These labels are not used to enforce access controls. They are only used - to check whether the SECURITY LABEL statement works as expected, - or not. - - - - - Author - - - KaiGai Kohei kaigai@ak.jp.nec.com - - - - diff --git a/doc-xc/src/sgml/earthdistance.sgmlin b/doc-xc/src/sgml/earthdistance.sgmlin deleted file mode 100644 index 7930f0bfca..0000000000 --- a/doc-xc/src/sgml/earthdistance.sgmlin +++ /dev/null @@ -1,201 +0,0 @@ - - - - earthdistance - - - earthdistance - - -&pgnotice; - - - The earthdistance module provides two different approaches to - calculating great circle distances on the surface of the Earth. The one - described first depends on the cube module (which - must be installed before earthdistance can be - installed). The second one is based on the built-in point data type, - using longitude and latitude for the coordinates. - - - - In this module, the Earth is assumed to be perfectly spherical. - (If that's too inaccurate for you, you might want to look at the - PostGIS - project.) - - - - Cube-based Earth Distances - -&pgnotice; - - - - Data is stored in cubes that are points (both corners are the same) using 3 - coordinates representing the x, y, and z distance from the center of the - Earth. A domain earth over cube is provided, which - includes constraint checks that the value meets these restrictions and - is reasonably close to the actual surface of the Earth. - - - - The radius of the Earth is obtained from the earth() - function. It is given in meters. But by changing this one function you can - change the module to use some other units, or to use a different value of - the radius that you feel is more appropriate. - - - - This package has applications to astronomical databases as well. - Astronomers will probably want to change earth() to return a - radius of 180/pi() so that distances are in degrees. - - - - Functions are provided to support input in latitude and longitude (in - degrees), to support output of latitude and longitude, to calculate - the great circle distance between two points and to easily specify a - bounding box usable for index searches. - - - - The provided functions are shown - in . - - - - Cube-based Earthdistance Functions - - - - Function - Returns - Description - - - - - earth() - float8 - Returns the assumed radius of the Earth. - - - sec_to_gc(float8) - float8 - Converts the normal straight line - (secant) distance between between two points on the surface of the Earth - to the great circle distance between them. - - - - gc_to_sec(float8) - float8 - Converts the great circle distance between two points on the - surface of the Earth to the normal straight line (secant) distance - between them. - - - - ll_to_earth(float8, float8) - earth - Returns the location of a point on the surface of the Earth given - its latitude (argument 1) and longitude (argument 2) in degrees. - - - - latitude(earth) - float8 - Returns the latitude in degrees of a point on the surface of the - Earth. - - - - longitude(earth) - float8 - Returns the longitude in degrees of a point on the surface of the - Earth. - - - - earth_distance(earth, earth) - float8 - Returns the great circle distance between two points on the - surface of the Earth. - - - - earth_box(earth, float8) - cube - Returns a box suitable for an indexed search using the cube - @> - operator for points within a given great circle distance of a location. - Some points in this box are further than the specified great circle - distance from the location, so a second check using - earth_distance should be included in the query. - - - - -
- - - - - Point-based Earth Distances - -&pgnotice; - - - - The second part of the module relies on representing Earth locations as - values of type point, in which the first component is taken to - represent longitude in degrees, and the second component is taken to - represent latitude in degrees. Points are taken as (longitude, latitude) - and not vice versa because longitude is closer to the intuitive idea of - x-axis and latitude to y-axis. - - - - A single operator is provided, shown - in . - - - - Point-based Earthdistance Operators - - - - Operator - Returns - Description - - - - - point <@> point - float8 - Gives the distance in statute miles between - two points on the Earth's surface. - - - - -
- - - Note that unlike the cube-based part of the module, units - are hardwired here: changing the earth() function will - not affect the results of this operator. - - - - One disadvantage of the longitude/latitude representation is that - you need to be careful about the edge conditions near the poles - and near +/- 180 degrees of longitude. The cube-based - representation avoids these discontinuities. - - - - - diff --git a/doc-xc/src/sgml/ecpg.sgmlin b/doc-xc/src/sgml/ecpg.sgmlin deleted file mode 100644 index 9004dbab23..0000000000 --- a/doc-xc/src/sgml/ecpg.sgmlin +++ /dev/null @@ -1,9736 +0,0 @@ - - - - <application>ECPG</application> - Embedded <acronym>SQL</acronym> in C - - embedded SQLin C - C - ECPG - - - This chapter describes the embedded SQL package - for PostgreSQL. It was written by - Linus Tolke (linus@epact.se) and Michael Meskes - (meskes@postgresql.org). Originally it was written to work with - C. It also works with C++, but - it does not recognize all C++ constructs yet. - - - - This documentation is quite incomplete. But since this - interface is standardized, additional information can be found in - many resources about SQL. - - - - The Concept - -&common; - - An embedded SQL program consists of code written in an ordinary - programming language, in this case C, mixed with SQL commands in - specially marked sections. To build the program, the source code (*.pgc) - is first passed through the embedded SQL preprocessor, which converts it - to an ordinary C program (*.c), and afterwards it can be processed by a C - compiler. (For details about the compiling and linking see ). - Converted ECPG applications call functions in the libpq library - through the embedded SQL library (ecpglib), and communicate with - the PostgreSQL server using the normal frontend-backend protocol. - - - - Embedded SQL has advantages over other methods - for handling SQL commands from C code. First, it - takes care of the tedious passing of information to and from - variables in your C program. Second, the SQL - code in the program is checked at build time for syntactical - correctness. Third, embedded SQL in C is - specified in the SQL standard and supported by - many other SQL database systems. The - PostgreSQL implementation is designed to match this - standard as much as possible, and it is usually possible to port - embedded SQL programs written for other SQL - databases to PostgreSQL with relative - ease. - - - - As already stated, programs written for the embedded - SQL interface are normal C programs with special - code inserted to perform database-related actions. This special - code always has the form: - -EXEC SQL ...; - - These statements syntactically take the place of a C statement. - Depending on the particular statement, they can appear at the - global level or within a function. Embedded - SQL statements follow the case-sensitivity rules - of normal SQL code, and not those of C. - - - - The following sections explain all the embedded SQL statements. - - - - - Managing Database Connections - -&common; - - This section describes how to open, close, and switch database - connections. - - - - Connecting to the Database Server - -&common; - - One connects to a database using the following statement: - -EXEC SQL CONNECT TO target AS connection-name USER user-name; - - The target can be specified in the - following ways: - - - - - dbname@hostname:port - - - - - - tcp:postgresql://hostname:port/dbname?options - - - - - - unix:postgresql://hostname:port/dbname?options - - - - - - an SQL string literal containing one of the above forms - - - - - - a reference to a character variable containing one of the above forms (see examples) - - - - - - DEFAULT - - - - - If you specify the connection target literally (that is, not - through a variable reference) and you don't quote the value, then - the case-insensitivity rules of normal SQL are applied. In that - case you can also double-quote the individual parameters separately - as needed. In practice, it is probably less error-prone to use a - (single-quoted) string literal or a variable reference. The - connection target DEFAULT initiates a connection - to the default database under the default user name. No separate - user name or connection name can be specified in that case. - - - - There are also different ways to specify the user name: - - - - - username - - - - - - username/password - - - - - - username IDENTIFIED BY password - - - - - - username USING password - - - - - As above, the parameters username and - password can be an SQL identifier, an - SQL string literal, or a reference to a character variable. - - - - The connection-name is used to handle - multiple connections in one program. It can be omitted if a - program uses only one connection. The most recently opened - connection becomes the current connection, which is used by default - when an SQL statement is to be executed (see later in this - chapter). - - - - Here are some examples of CONNECT statements: - -EXEC SQL CONNECT TO mydb@sql.mydomain.com; - -EXEC SQL CONNECT TO unix:postgresql://sql.mydomain.com/mydb AS myconnection USER john; - -EXEC SQL BEGIN DECLARE SECTION; -const char *target = "mydb@sql.mydomain.com"; -const char *user = "john"; -EXEC SQL END DECLARE SECTION; - ... -EXEC SQL CONNECT TO :target USER :user; - - The last form makes use of the variant referred to above as - character variable reference. You will see in later sections how C - variables can be used in SQL statements when you prefix them with a - colon. - - - - Be advised that the format of the connection target is not - specified in the SQL standard. So if you want to develop portable - applications, you might want to use something based on the last - example above to encapsulate the connection target string - somewhere. - - - - - Choosing a Connection - -&common; - - SQL statements in embedded SQL programs are by default executed on - the current connection, that is, the most recently opened one. If - an application needs to manage multiple connections, then there are - two ways to handle this. - - - - The first option is to explicitly choose a connection for each SQL - statement, for example: - -EXEC SQL AT connection-name SELECT ...; - - This option is particularly suitable if the application needs to - use several connections in mixed order. - - - - If your application uses multiple threads of execution, they cannot share a - connection concurrently. You must either explicitly control access to the connection - (using mutexes) or use a connection for each thread. If each thread uses its own connection, - you will need to use the AT clause to specify which connection the thread will use. - - - - The second option is to execute a statement to switch the current - connection. That statement is: - -EXEC SQL SET CONNECTION connection-name; - - This option is particularly convenient if many statements are to be - executed on the same connection. It is not thread-aware. - - - - Here is an example program managing multiple database connections: - - -EXEC SQL BEGIN DECLARE SECTION; - char dbname[1024]; -EXEC SQL END DECLARE SECTION; - -int -main() -{ - EXEC SQL CONNECT TO testdb1 AS con1 USER testuser; - EXEC SQL CONNECT TO testdb2 AS con2 USER testuser; - EXEC SQL CONNECT TO testdb3 AS con3 USER testuser; - - /* This query would be executed in the last opened database "testdb3". */ - EXEC SQL SELECT current_database() INTO :dbname; - printf("current=%s (should be testdb3)\n", dbname); - - /* Using "AT" to run a query in "testdb2" */ - EXEC SQL AT con2 SELECT current_database() INTO :dbname; - printf("current=%s (should be testdb2)\n", dbname); - - /* Switch the current connection to "testdb1". */ - EXEC SQL SET CONNECTION con1; - - EXEC SQL SELECT current_database() INTO :dbname; - printf("current=%s (should be testdb1)\n", dbname); - - EXEC SQL DISCONNECT ALL; - return 0; -} -]]> - - This example would produce this output: - -current=testdb3 (should be testdb3) -current=testdb2 (should be testdb2) -current=testdb1 (should be testdb1) - - - - - - Closing a Connection - -&common; - - To close a connection, use the following statement: - -EXEC SQL DISCONNECT connection; - - The connection can be specified - in the following ways: - - - - - connection-name - - - - - - DEFAULT - - - - - - CURRENT - - - - - - ALL - - - - - If no connection name is specified, the current connection is - closed. - - - - It is good style that an application always explicitly disconnect - from every connection it opened. - - - - - - - Running SQL Commands - -&common; - - Any SQL command can be run from within an embedded SQL application. - Below are some examples of how to do that. - - - - Executing SQL Statements - -&common; - - Creating a table: - -EXEC SQL CREATE TABLE foo (number integer, ascii char(16)); -EXEC SQL CREATE UNIQUE INDEX num1 ON foo(number); -EXEC SQL COMMIT; - - - - - Inserting rows: - -EXEC SQL INSERT INTO foo (number, ascii) VALUES (9999, 'doodad'); -EXEC SQL COMMIT; - - - - - Deleting rows: - -EXEC SQL DELETE FROM foo WHERE number = 9999; -EXEC SQL COMMIT; - - - - - Updates: - -EXEC SQL UPDATE foo - SET ascii = 'foobar' - WHERE number = 9999; -EXEC SQL COMMIT; - - - - - SELECT statements that return a single result - row can also be executed using - EXEC SQL directly. To handle result sets with - multiple rows, an application has to use a cursor; - see below. (As a special case, an - application can fetch multiple rows at once into an array host - variable; see .) - - - - Single-row select: - -EXEC SQL SELECT foo INTO :FooBar FROM table1 WHERE ascii = 'doodad'; - - - - - Also, a configuration parameter can be retrieved with the - SHOW command: - -EXEC SQL SHOW search_path INTO :var; - - - - - The tokens of the form - :something are - host variables, that is, they refer to - variables in the C program. They are explained in . - - - - - Using Cursors - -&common; - - To retrieve a result set holding multiple rows, an application has - to declare a cursor and fetch each row from the cursor. The steps - to use a cursor are the following: declare a cursor, open it, fetch - a row from the cursor, repeat, and finally close it. - - - - Select using cursors: - -EXEC SQL DECLARE foo_bar CURSOR FOR - SELECT number, ascii FROM foo - ORDER BY ascii; -EXEC SQL OPEN foo_bar; -EXEC SQL FETCH foo_bar INTO :FooBar, DooDad; -... -EXEC SQL CLOSE foo_bar; -EXEC SQL COMMIT; - - - - - For more details about declaration of the cursor, - see , and - see for FETCH command - details. - - - - - The ECPG DECLARE command does not actually - cause a statement to be sent to the PostgreSQL backend. The - cursor is opened in the backend (using the - backend's DECLARE command) at the point when - the OPEN command is executed. - - - - - - Managing Transactions - -&common; - - In the default mode, statements are committed only when - EXEC SQL COMMIT is issued. The embedded SQL - interface also supports autocommit of transactions (similar to - libpq behavior) via the - command-line option to ecpg (see ) or via the EXEC SQL SET AUTOCOMMIT TO - ON statement. In autocommit mode, each command is - automatically committed unless it is inside an explicit transaction - block. This mode can be explicitly turned off using EXEC - SQL SET AUTOCOMMIT TO OFF. - - - - The following transaction management commands are available: - - - - EXEC SQL COMMIT - - - Commit an in-progress transaction. - - - - - - EXEC SQL ROLLBACK - - - Roll back an in-progress transaction. - - - - - - EXEC SQL SET AUTOCOMMIT TO ON - - - Enable autocommit mode. - - - - - - SET AUTOCOMMIT TO OFF - - - Disable autocommit mode. This is the default. - - - - - - - - - Prepared Statements - -&common; - - When the values to be passed to an SQL statement are not known at - compile time, or the same statement is going to be used many - times, then prepared statements can be useful. - - - - The statement is prepared using the - command PREPARE. For the values that are not - known yet, use the - placeholder ?: - -EXEC SQL PREPARE stmt1 FROM "SELECT oid, datname FROM pg_database WHERE oid = ?"; - - - - - If a statement returns a single row, the application can - call EXECUTE after - PREPARE to execute the statement, supplying the - actual values for the placeholders with a USING - clause: - -EXEC SQL EXECUTE stmt1 INTO :dboid, :dbname USING 1; - - - - - If a statement returns multiple rows, the application can use a - cursor declared based on the prepared statement. To bind input - parameters, the cursor must be opened with - a USING clause: - -EXEC SQL PREPARE stmt1 FROM "SELECT oid,datname FROM pg_database WHERE oid > ?"; -EXEC SQL DECLARE foo_bar CURSOR FOR stmt1; - -/* when end of result set reached, break out of while loop */ -EXEC SQL WHENEVER NOT FOUND DO BREAK; - -EXEC SQL OPEN foo_bar USING 100; -... -while (1) -{ - EXEC SQL FETCH NEXT FROM foo_bar INTO :dboid, :dbname; - ... -} -EXEC SQL CLOSE foo_bar; - - - - - When you don't need the prepared statement anymore, you should - deallocate it: - -EXEC SQL DEALLOCATE PREPARE name; - - - - - For more details about PREPARE, - see . Also - see for more details about using - placeholders and input parameters. - - - - - - Using Host Variables - -&common; - - In you saw how you can execute SQL - statements from an embedded SQL program. Some of those statements - only used fixed values and did not provide a way to insert - user-supplied values into statements or have the program process - the values returned by the query. Those kinds of statements are - not really useful in real applications. This section explains in - detail how you can pass data between your C program and the - embedded SQL statements using a simple mechanism called - host variables. In an embedded SQL program we - consider the SQL statements to be guests in the C - program code which is the host language. Therefore - the variables of the C program are called host - variables. - - - - Another way to exchange values between PostgreSQL backends and ECPG - applications is the use of SQL descriptors, described - in . - - - - Overview - -&common; - - Passing data between the C program and the SQL statements is - particularly simple in embedded SQL. Instead of having the - program paste the data into the statement, which entails various - complications, such as properly quoting the value, you can simply - write the name of a C variable into the SQL statement, prefixed by - a colon. For example: - -EXEC SQL INSERT INTO sometable VALUES (:v1, 'foo', :v2); - - This statements refers to two C variables named - v1 and v2 and also uses a - regular SQL string literal, to illustrate that you are not - restricted to use one kind of data or the other. - - - - This style of inserting C variables in SQL statements works - anywhere a value expression is expected in an SQL statement. - - - - - Declare Sections - -&common; - - To pass data from the program to the database, for example as - parameters in a query, or to pass data from the database back to - the program, the C variables that are intended to contain this - data need to be declared in specially marked sections, so the - embedded SQL preprocessor is made aware of them. - - - - This section starts with: - -EXEC SQL BEGIN DECLARE SECTION; - - and ends with: - -EXEC SQL END DECLARE SECTION; - - Between those lines, there must be normal C variable declarations, - such as: - -int x = 4; -char foo[16], bar[16]; - - As you can see, you can optionally assign an initial value to the variable. - The variable's scope is determined by the location of its declaring - section within the program. - You can also declare variables with the following syntax which implicitly - creates a declare section: - -EXEC SQL int i = 4; - - You can have as many declare sections in a program as you like. - - - - The declarations are also echoed to the output file as normal C - variables, so there's no need to declare them again. Variables - that are not intended to be used in SQL commands can be declared - normally outside these special sections. - - - - The definition of a structure or union also must be listed inside - a DECLARE section. Otherwise the preprocessor cannot - handle these types since it does not know the definition. - - - - - Retrieving Query Results - -&common; - - Now you should be able to pass data generated by your program into - an SQL command. But how do you retrieve the results of a query? - For that purpose, embedded SQL provides special variants of the - usual commands SELECT and - FETCH. These commands have a special - INTO clause that specifies which host variables - the retrieved values are to be stored in. - SELECT is used for a query that returns only - single row, and FETCH is used for a query that - returns multiple rows, using a cursor. - - - - Here is an example: - -/* - * assume this table: - * CREATE TABLE test1 (a int, b varchar(50)); - */ - -EXEC SQL BEGIN DECLARE SECTION; -int v1; -VARCHAR v2; -EXEC SQL END DECLARE SECTION; - - ... - -EXEC SQL SELECT a, b INTO :v1, :v2 FROM test; - - So the INTO clause appears between the select - list and the FROM clause. The number of - elements in the select list and the list after - INTO (also called the target list) must be - equal. - - - - Here is an example using the command FETCH: - -EXEC SQL BEGIN DECLARE SECTION; -int v1; -VARCHAR v2; -EXEC SQL END DECLARE SECTION; - - ... - -EXEC SQL DECLARE foo CURSOR FOR SELECT a, b FROM test; - - ... - -do -{ - ... - EXEC SQL FETCH NEXT FROM foo INTO :v1, :v2; - ... -} while (...); - - Here the INTO clause appears after all the - normal clauses. - - - - Both of these methods only allow retrieving one row at a time. If - you need to process result sets that potentially contain more than - one row, you need to use a cursor, as shown in the second example. - - - - - Type Mapping - -&common; - - When ECPG applications exchange values between the PostgreSQL - server and the C application, such as when retrieving query - results from the server or executing SQL statements with input - parameters, the values need to be converted between PostgreSQL - data types and host language variable types (C language data - types, concretely). One of the main points of ECPG is that it - takes care of this automatically in most cases. - - - - In this respect, there are two kinds of data types: Some simple - PostgreSQL data types, such as integer - and text, can be read and written by the application - directly. Other PostgreSQL data types, such - as timestamp and numeric can only be - accessed through special library functions; see - . - - - - shows which PostgreSQL - data types correspond to which C data types. When you wish to - send or receive a value of a given PostgreSQL data type, you - should declare a C variable of the corresponding C data type in - the declare section. - - - - Mapping Between PostgreSQL Data Types and C Variable Types - - - - PostgreSQL data type - Host variable type - - - - - - smallint - short - - - - integer - int - - - - bigint - long long int - - - - decimal - decimalThis type can only be accessed through special library functions; see . - - - - numeric - numeric - - - - real - float - - - - double precision - double - - - - serial - int - - - - bigserial - long long int - - - - oid - unsigned int - - - - character(n), varchar(n), text - char[n+1], VARCHAR[n+1]declared in ecpglib.h - - - - name - char[NAMEDATALEN] - - - - timestamp - timestamp - - - - interval - interval - - - - date - date - - - - boolean - booldeclared in ecpglib.h if not native - - - -
- - - Handling Character Strings - -&common; - - To handle SQL character string data types, such - as varchar and text, there are two - possible ways to declare the host variables. - - - - One way is using char[], an array - of char, which is the most common way to handle - character data in C. - -EXEC SQL BEGIN DECLARE SECTION; - char str[50]; -EXEC SQL END DECLARE SECTION; - - Note that you have to take care of the length yourself. If you - use this host variable as the target variable of a query which - returns a string with more than 49 characters, a buffer overflow - occurs. - - - - The other way is using the VARCHAR type, which is a - special type provided by ECPG. The definition on an array of - type VARCHAR is converted into a - named struct for every variable. A declaration like: - -VARCHAR var[180]; - - is converted into: - -struct varchar_var { int len; char arr[180]; } var; - - The member arr hosts the string - including a terminating zero byte. Thus, to store a string in - a VARCHAR host variable, the host variable has to be - declared with the length including the zero byte terminator. The - member len holds the length of the - string stored in the arr without the - terminating zero byte. When a host variable is used as input for - a query, if strlen(arr) - and len are different, the shorter one - is used. - - - - Two or more VARCHAR host variables cannot be defined - in single line statement. The following code will confuse - the ecpg preprocessor: - -VARCHAR v1[128], v2[128]; /* WRONG */ - - Two variables should be defined in separate statements like this: - -VARCHAR v1[128]; -VARCHAR v2[128]; - - - - - VARCHAR can be written in upper or lower case, but - not in mixed case. - - - - char and VARCHAR host variables can - also hold values of other SQL types, which will be stored in - their string forms. - - - - - Accessing Special Data Types - -&common; - - ECPG contains some special types that help you to interact easily - with some special data types from the PostgreSQL server. In - particular, it has implemented support for the - numeric, decimal, date, timestamp, - and interval types. These data types cannot usefully be - mapped to primitive host variable types (such - as int, long long int, - or char[]), because they have a complex internal - structure. Applications deal with these types by declaring host - variables in special types and accessing them using functions in - the pgtypes library. The pgtypes library, described in detail - in contains basic functions to deal - with those types, such that you do not need to send a query to - the SQL server just for adding an interval to a time stamp for - example. - - - - The follow subsections describe these special data types. For - more details about pgtypes library functions, - see . - - - - timestamp, date - -&common; - - Here is a pattern for handling timestamp variables - in the ECPG host application. - - - - First, the program has to include the header file for the - timestamp type: - -#include <pgtypes_timestamp.h> - - - - - Next, declare a host variable as type timestamp in - the declare section: - -EXEC SQL BEGIN DECLARE SECTION; -timestamp ts; -EXEC SQL END DECLARE SECTION; - - - - - And after reading a value into the host variable, process it - using pgtypes library functions. In following example, the - timestamp value is converted into text (ASCII) form - with the PGTYPEStimestamp_to_asc() - function: - -EXEC SQL SELECT now()::timestamp INTO :ts; - -printf("ts = %s\n", PGTYPEStimestamp_to_asc(ts)); - - This example will show some result like following: - -ts = 2010-06-27 18:03:56.949343 - - - - - In addition, the DATE type can be handled in the same way. The - program has to include pg_types_date.h, declare a host variable - as the date type and convert a DATE value into a text form using - PGTYPESdate_to_asc() function. For more details about the - pgtypes library functions, see . - - - - - interval - -&common; - - The handling of the interval type is also similar - to the timestamp and date types. It - is required, however, to allocate memory for - an interval type value explicitly. In other words, - the memory space for the variable has to be allocated in the - heap memory, not in the stack memory. - - - - Here is an example program: - -#include <stdio.h> -#include <stdlib.h> -#include <pgtypes_interval.h> - -int -main(void) -{ -EXEC SQL BEGIN DECLARE SECTION; - interval *in; -EXEC SQL END DECLARE SECTION; - - EXEC SQL CONNECT TO testdb; - - in = PGTYPESinterval_new(); - EXEC SQL SELECT '1 min'::interval INTO :in; - printf("interval = %s\n", PGTYPESinterval_to_asc(in)); - PGTYPESinterval_free(in); - - EXEC SQL COMMIT; - EXEC SQL DISCONNECT ALL; - return 0; -} - - - - - - numeric, decimal - -&common; - - The handling of the numeric - and decimal types is similar to the - interval type: It requires defining a pointer, - allocating some memory space on the heap, and accessing the - variable using the pgtypes library functions. For more details - about the pgtypes library functions, - see . - - - - No functions are provided specifically for - the decimal type. An application has to convert it - to a numeric variable using a pgtypes library - function to do further processing. - - - - Here is an example program handling numeric - and decimal type variables. - -#include <stdio.h> -#include <stdlib.h> -#include <pgtypes_numeric.h> - -EXEC SQL WHENEVER SQLERROR STOP; - -int -main(void) -{ -EXEC SQL BEGIN DECLARE SECTION; - numeric *num; - numeric *num2; - decimal *dec; -EXEC SQL END DECLARE SECTION; - - EXEC SQL CONNECT TO testdb; - - num = PGTYPESnumeric_new(); - dec = PGTYPESdecimal_new(); - - EXEC SQL SELECT 12.345::numeric(4,2), 23.456::decimal(4,2) INTO :num, :dec; - - printf("numeric = %s\n", PGTYPESnumeric_to_asc(num, 0)); - printf("numeric = %s\n", PGTYPESnumeric_to_asc(num, 1)); - printf("numeric = %s\n", PGTYPESnumeric_to_asc(num, 2)); - - /* Convert decimal to numeric to show a decimal value. */ - num2 = PGTYPESnumeric_new(); - PGTYPESnumeric_from_decimal(dec, num2); - - printf("decimal = %s\n", PGTYPESnumeric_to_asc(num2, 0)); - printf("decimal = %s\n", PGTYPESnumeric_to_asc(num2, 1)); - printf("decimal = %s\n", PGTYPESnumeric_to_asc(num2, 2)); - - PGTYPESnumeric_free(num2); - PGTYPESdecimal_free(dec); - PGTYPESnumeric_free(num); - - EXEC SQL COMMIT; - EXEC SQL DISCONNECT ALL; - return 0; -} - - - - - - - Host Variables with Nonprimitive Types - -&common; - - As a host variable you can also use arrays, typedefs, structs, and - pointers. - - - - Arrays - -&common; - - There are two use cases for arrays as host variables. The first - is a way to store some text string in char[] - or VARCHAR[], as - explained . The second use case is to - retrieve multiple rows from a query result without using a - cursor. Without an array, to process a query result consisting - of multiple rows, it is required to use a cursor and - the FETCH command. But with array host - variables, multiple rows can be received at once. The length of - the array has to be defined to be able to accommodate all rows, - otherwise a buffer overflow will likely occur. - - - - Following example scans the pg_database - system table and shows all OIDs and names of the available - databases: - -int -main(void) -{ -EXEC SQL BEGIN DECLARE SECTION; - int dbid[8]; - char dbname[8][16]; - int i; -EXEC SQL END DECLARE SECTION; - - memset(dbname, 0, sizeof(char)* 16 * 8); - memset(dbid, 0, sizeof(int) * 8); - - EXEC SQL CONNECT TO testdb; - - /* Retrieve multiple rows into arrays at once. */ - EXEC SQL SELECT oid,datname INTO :dbid, :dbname FROM pg_database; - - for (i = 0; i < 8; i++) - printf("oid=%d, dbname=%s\n", dbid[i], dbname[i]); - - EXEC SQL COMMIT; - EXEC SQL DISCONNECT ALL; - return 0; -} - - - This example shows following result. (The exact values depend on - local circumstances.) - -oid=1, dbname=template1 -oid=11510, dbname=template0 -oid=11511, dbname=postgres -oid=313780, dbname=testdb -oid=0, dbname= -oid=0, dbname= -oid=0, dbname= - - - - - - Structures - -&common; - - A structure whose member names match the column names of a query - result, can be used to retrieve multiple columns at once. The - structure enables handling multiple column values in a single - host variable. - - - - The following example retrieves OIDs, names, and sizes of the - available databases from the pg_database - system table and using - the pg_database_size() function. In this - example, a structure variable dbinfo_t with - members whose names match each column in - the SELECT result is used to retrieve one - result row without putting multiple host variables in - the FETCH statement. - -EXEC SQL BEGIN DECLARE SECTION; - typedef struct - { - int oid; - char datname[65]; - long long int size; - } dbinfo_t; - - dbinfo_t dbval; -EXEC SQL END DECLARE SECTION; - - memset(&dbval, 0, sizeof(dbinfo_t)); - - EXEC SQL DECLARE cur1 CURSOR FOR SELECT oid, datname, pg_database_size(oid) AS size FROM pg_database; - EXEC SQL OPEN cur1; - - /* when end of result set reached, break out of while loop */ - EXEC SQL WHENEVER NOT FOUND DO BREAK; - - while (1) - { - /* Fetch multiple columns into one structure. */ - EXEC SQL FETCH FROM cur1 INTO :dbval; - - /* Print members of the structure. */ - printf("oid=%d, datname=%s, size=%lld\n", dbval.oid, dbval.datname, dbval.size); - } - - EXEC SQL CLOSE cur1; - - - - - This example shows following result. (The exact values depend on - local circumstances.) - -oid=1, datname=template1, size=4324580 -oid=11510, datname=template0, size=4243460 -oid=11511, datname=postgres, size=4324580 -oid=313780, datname=testdb, size=8183012 - - - - - Structure host variables absorb as many columns - as the structure as fields. Additional columns can be assigned - to other host variables. For example, the above program could - also be restructured like this, with the size - variable outside the structure: - -EXEC SQL BEGIN DECLARE SECTION; - typedef struct - { - int oid; - char datname[65]; - } dbinfo_t; - - dbinfo_t dbval; - long long int size; -EXEC SQL END DECLARE SECTION; - - memset(&dbval, 0, sizeof(dbinfo_t)); - - EXEC SQL DECLARE cur1 CURSOR FOR SELECT oid, datname, pg_database_size(oid) AS size FROM pg_database; - EXEC SQL OPEN cur1; - - /* when end of result set reached, break out of while loop */ - EXEC SQL WHENEVER NOT FOUND DO BREAK; - - while (1) - { - /* Fetch multiple columns into one structure. */ - EXEC SQL FETCH FROM cur1 INTO :dbval, :size; - - /* Print members of the structure. */ - printf("oid=%d, datname=%s, size=%lld\n", dbval.oid, dbval.datname, size); - } - - EXEC SQL CLOSE cur1; - - - - - - Typedefs - -&common; - - Use the typedef keyword to map new types to already - existing types. - -EXEC SQL BEGIN DECLARE SECTION; - typedef char mychartype[40]; - typedef long serial_t; -EXEC SQL END DECLARE SECTION; - - Note that you could also use: - -EXEC SQL TYPE serial_t IS long; - - This declaration does not need to be part of a declare section. - - - - - Pointers - -&common; - - You can declare pointers to the most common types. Note however - that you cannot use pointers as target variables of queries - without auto-allocation. See - for more information on auto-allocation. - - - - -EXEC SQL BEGIN DECLARE SECTION; - int *intp; - char **charp; -EXEC SQL END DECLARE SECTION; - - - - - - - - Handling Nonprimitive SQL Data Types - -&common; - - This section contains information on how to handle nonscalar and - user-defined SQL-level data types in ECPG applications. Note that - this is distinct from the handling of host variables of - nonprimitive types, described in the previous section. - - - - Arrays - -&common; - - SQL-level arrays are not directly supported in ECPG. It is not - possible to simply map an SQL array into a C array host variable. - This will result in undefined behavior. Some workarounds exist, - however. - - - - If a query accesses elements of an array - separately, then this avoids the use of arrays in ECPG. Then, a - host variable with a type that can be mapped to the element type - should be used. For example, if a column type is array of - integer, a host variable of type int - can be used. Also if the element type is varchar - or text, a host variable of type char[] - or VARCHAR[] can be used. - - - - Here is an example. Assume the following table: - -CREATE TABLE t3 ( - ii integer[] -); - -testdb=> SELECT * FROM t3; - ii -------------- - {1,2,3,4,5} -(1 row) - - - The following example program retrieves the 4th element of the - array and stores it into a host variable of - type int: - -EXEC SQL BEGIN DECLARE SECTION; -int ii; -EXEC SQL END DECLARE SECTION; - -EXEC SQL DECLARE cur1 CURSOR FOR SELECT ii[4] FROM t3; -EXEC SQL OPEN cur1; - -EXEC SQL WHENEVER NOT FOUND DO BREAK; - -while (1) -{ - EXEC SQL FETCH FROM cur1 INTO :ii ; - printf("ii=%d\n", ii); -} - -EXEC SQL CLOSE cur1; - - - This example shows the following result: - -ii=4 - - - - - To map multiple array elements to the multiple elements in an - array type host variables each element of array column and each - element of the host variable array have to be managed separately, - for example: - -EXEC SQL BEGIN DECLARE SECTION; -int ii_a[8]; -EXEC SQL END DECLARE SECTION; - -EXEC SQL DECLARE cur1 CURSOR FOR SELECT ii[1], ii[2], ii[3], ii[4] FROM t3; -EXEC SQL OPEN cur1; - -EXEC SQL WHENEVER NOT FOUND DO BREAK; - -while (1) -{ - EXEC SQL FETCH FROM cur1 INTO :ii_a[0], :ii_a[1], :ii_a[2], :ii_a[3]; - ... -} - - - - - Note again that - -EXEC SQL BEGIN DECLARE SECTION; -int ii_a[8]; -EXEC SQL END DECLARE SECTION; - -EXEC SQL DECLARE cur1 CURSOR FOR SELECT ii FROM t3; -EXEC SQL OPEN cur1; - -EXEC SQL WHENEVER NOT FOUND DO BREAK; - -while (1) -{ - /* WRONG */ - EXEC SQL FETCH FROM cur1 INTO :ii_a; - ... -} - - would not work correctly in this case, because you cannot map an - array type column to an array host variable directly. - - - - Another workaround is to store arrays in their external string - representation in host variables of type char[] - or VARCHAR[]. For more details about this - representation, see . Note that - this means that the array cannot be accessed naturally as an - array in the host program (without further processing that parses - the text representation). - - - - - Composite Types - -&common; - - Composite types are not directly supported in ECPG, but an easy workaround is possible. - The - available workarounds are similar to the ones described for - arrays above: Either access each attribute separately or use the - external string representation. - - - - For the following examples, assume the following type and table: - -CREATE TYPE comp_t AS (intval integer, textval varchar(32)); -CREATE TABLE t4 (compval comp_t); -INSERT INTO t4 VALUES ( (256, 'PostgreSQL') ); - - - The most obvious solution is to access each attribute separately. - The following program retrieves data from the example table by - selecting each attribute of the type comp_t - separately: - -EXEC SQL BEGIN DECLARE SECTION; -int intval; -varchar textval[33]; -EXEC SQL END DECLARE SECTION; - -/* Put each element of the composite type column in the SELECT list. */ -EXEC SQL DECLARE cur1 CURSOR FOR SELECT (compval).intval, (compval).textval FROM t4; -EXEC SQL OPEN cur1; - -EXEC SQL WHENEVER NOT FOUND DO BREAK; - -while (1) -{ - /* Fetch each element of the composite type column into host variables. */ - EXEC SQL FETCH FROM cur1 INTO :intval, :textval; - - printf("intval=%d, textval=%s\n", intval, textval.arr); -} - -EXEC SQL CLOSE cur1; - - - - - To enhance this example, the host variables to store values in - the FETCH command can be gathered into one - structure. For more details about the host variable in the - structure form, see . - To switch to the structure, the example can be modified as below. - The two host variables, intval - and textval, become members of - the comp_t structure, and the structure - is specified on the FETCH command. - -EXEC SQL BEGIN DECLARE SECTION; -typedef struct -{ - int intval; - varchar textval[33]; -} comp_t; - -comp_t compval; -EXEC SQL END DECLARE SECTION; - -/* Put each element of the composite type column in the SELECT list. */ -EXEC SQL DECLARE cur1 CURSOR FOR SELECT (compval).intval, (compval).textval FROM t4; -EXEC SQL OPEN cur1; - -EXEC SQL WHENEVER NOT FOUND DO BREAK; - -while (1) -{ - /* Put all values in the SELECT list into one structure. */ - EXEC SQL FETCH FROM cur1 INTO :compval; - - printf("intval=%d, textval=%s\n", compval.intval, compval.textval.arr); -} - -EXEC SQL CLOSE cur1; - - - Although a structure is used in the FETCH - command, the attribute names in the SELECT - clause are specified one by one. This can be enhanced by using - a * to ask for all attributes of the composite - type value. - -... -EXEC SQL DECLARE cur1 CURSOR FOR SELECT (compval).* FROM t4; -EXEC SQL OPEN cur1; - -EXEC SQL WHENEVER NOT FOUND DO BREAK; - -while (1) -{ - /* Put all values in the SELECT list into one structure. */ - EXEC SQL FETCH FROM cur1 INTO :compval; - - printf("intval=%d, textval=%s\n", compval.intval, compval.textval.arr); -} -... - - This way, composite types can be mapped into structures almost - seamlessly, even though ECPG does not understand the composite - type itself. - - - - Finally, it is also possible to store composite type values in - their external string representation in host variables of - type char[] or VARCHAR[]. But that - way, it is not easily possible to access the fields of the value - from the host program. - - - - - User-defined Base Types - -&common; - - New user-defined base types are not directly supported by ECPG. - You can use the external string representation and host variables - of type char[] or VARCHAR[], and this - solution is indeed appropriate and sufficient for many types. - - - - Here is an example using the data type complex from - the example in . The external string - representation of that type is (%lf,%lf), - which is defined in the - functions complex_in() - and complex_out() functions - in . The following example inserts the - complex type values (1,1) - and (3,3) into the - columns a and b, and select - them from the table after that. - - -EXEC SQL BEGIN DECLARE SECTION; - varchar a[64]; - varchar b[64]; -EXEC SQL END DECLARE SECTION; - - EXEC SQL INSERT INTO test_complex VALUES ('(1,1)', '(3,3)'); - - EXEC SQL DECLARE cur1 CURSOR FOR SELECT a, b FROM test_complex; - EXEC SQL OPEN cur1; - - EXEC SQL WHENEVER NOT FOUND DO BREAK; - - while (1) - { - EXEC SQL FETCH FROM cur1 INTO :a, :b; - printf("a=%s, b=%s\n", a.arr, b.arr); - } - - EXEC SQL CLOSE cur1; - - - This example shows following result: - -a=(1,1), b=(3,3) - - - - - Another workaround is avoiding the direct use of the user-defined - types in ECPG and instead create a function or cast that converts - between the user-defined type and a primitive type that ECPG can - handle. Note, however, that type casts, especially implicit - ones, should be introduced into the type system very carefully. - - - - For example, - -CREATE FUNCTION create_complex(r double, i double) RETURNS complex -LANGUAGE SQL -IMMUTABLE -AS $$ SELECT $1 * complex '(1,0')' + $2 * complex '(0,1)' $$; - - After this definition, the following - -EXEC SQL BEGIN DECLARE SECTION; -double a, b, c, d; -EXEC SQL END DECLARE SECTION; - -a = 1; -b = 2; -c = 3; -d = 4; - -EXEC SQL INSERT INTO test_complex VALUES (create_complex(:a, :b), create_complex(:c, :d)); - - has the same effect as - -EXEC SQL INSERT INTO test_complex VALUES ('(1,2)', '(3,4)'); - - - - - - - Indicators - -&common; - - The examples above do not handle null values. In fact, the - retrieval examples will raise an error if they fetch a null value - from the database. To be able to pass null values to the database - or retrieve null values from the database, you need to append a - second host variable specification to each host variable that - contains data. This second host variable is called the - indicator and contains a flag that tells - whether the datum is null, in which case the value of the real - host variable is ignored. Here is an example that handles the - retrieval of null values correctly: - -EXEC SQL BEGIN DECLARE SECTION; -VARCHAR val; -int val_ind; -EXEC SQL END DECLARE SECTION: - - ... - -EXEC SQL SELECT b INTO :val :val_ind FROM test1; - - The indicator variable val_ind will be zero if - the value was not null, and it will be negative if the value was - null. - - - - The indicator has another function: if the indicator value is - positive, it means that the value is not null, but it was - truncated when it was stored in the host variable. - - - - If the argument -r no_indicator is passed to - the preprocessor ecpg, it works in - no-indicator mode. In no-indicator mode, if no - indicator variable is specified, null values are signaled (on - input and output) for character string types as empty string and - for integer types as the lowest possible value for type (for - example, INT_MIN for int). - - - - - - Dynamic SQL - -&common; - - In many cases, the particular SQL statements that an application - has to execute are known at the time the application is written. - In some cases, however, the SQL statements are composed at run time - or provided by an external source. In these cases you cannot embed - the SQL statements directly into the C source code, but there is a - facility that allows you to call arbitrary SQL statements that you - provide in a string variable. - - - - Executing Statements without a Result Set - -&common; - - The simplest way to execute an arbitrary SQL statement is to use - the command EXECUTE IMMEDIATE. For example: - -EXEC SQL BEGIN DECLARE SECTION; -const char *stmt = "CREATE TABLE test1 (...);"; -EXEC SQL END DECLARE SECTION; - -EXEC SQL EXECUTE IMMEDIATE :stmt; - - EXECUTE IMMEDIATE can be used for SQL - statements that do not return a result set (e.g., - DDL, INSERT, UPDATE, - DELETE). You cannot execute statements that - retrieve data (e.g., SELECT) this way. The - next section describes how to do that. - - - - - Executing a Statement with Input Parameters - -&common; - - A more powerful way to execute arbitrary SQL statements is to - prepare them once and execute the prepared statement as often as - you like. It is also possible to prepare a generalized version of - a statement and then execute specific versions of it by - substituting parameters. When preparing the statement, write - question marks where you want to substitute parameters later. For - example: - -EXEC SQL BEGIN DECLARE SECTION; -const char *stmt = "INSERT INTO test1 VALUES(?, ?);"; -EXEC SQL END DECLARE SECTION; - -EXEC SQL PREPARE mystmt FROM :stmt; - ... -EXEC SQL EXECUTE mystmt USING 42, 'foobar'; - - - - - When you don't need the prepared statement anymore, you should - deallocate it: - -EXEC SQL DEALLOCATE PREPARE name; - - - - - - Executing a Statement with a Result Set - -&common; - - To execute an SQL statement with a single result row, - EXECUTE can be used. To save the result, add - an INTO clause. - ?"; -int v1, v2; -VARCHAR v3[50]; -EXEC SQL END DECLARE SECTION; - -EXEC SQL PREPARE mystmt FROM :stmt; - ... -EXEC SQL EXECUTE mystmt INTO :v1, :v2, :v3 USING 37; -]]> - - An EXECUTE command can have an - INTO clause, a USING clause, - both, or neither. - - - - If a query is expected to return more than one result row, a - cursor should be used, as in the following example. - (See for more details about the - cursor.) - -EXEC SQL BEGIN DECLARE SECTION; -char dbaname[128]; -char datname[128]; -char *stmt = "SELECT u.usename as dbaname, d.datname " - " FROM pg_database d, pg_user u " - " WHERE d.datdba = u.usesysid"; -EXEC SQL END DECLARE SECTION; - -EXEC SQL CONNECT TO testdb AS con1 USER testuser; - -EXEC SQL PREPARE stmt1 FROM :stmt; - -EXEC SQL DECLARE cursor1 CURSOR FOR stmt1; -EXEC SQL OPEN cursor1; - -EXEC SQL WHENEVER NOT FOUND DO BREAK; - -while (1) -{ - EXEC SQL FETCH cursor1 INTO :dbaname,:datname; - printf("dbaname=%s, datname=%s\n", dbaname, datname); -} - -EXEC SQL CLOSE cursor1; - -EXEC SQL COMMIT; -EXEC SQL DISCONNECT ALL; - - - - - - - pgtypes Library - -&common; - - The pgtypes library maps PostgreSQL database - types to C equivalents that can be used in C programs. It also offers - functions to do basic calculations with those types within C, i.e., without - the help of the PostgreSQL server. See the - following example: - - - - - - The numeric Type -&common; - - The numeric type offers to do calculations with arbitrary precision. See - for the equivalent type in the - PostgreSQL server. Because of the arbitrary precision this - variable needs to be able to expand and shrink dynamically. That's why you - can only create numeric variables on the heap, by means of the - PGTYPESnumeric_new and PGTYPESnumeric_free - functions. The decimal type, which is similar but limited in precision, - can be created on the stack as well as on the heap. - - - The following functions can be used to work with the numeric type: - - - PGTYPESnumeric_new - - - Request a pointer to a newly allocated numeric variable. - -numeric *PGTYPESnumeric_new(void); - - - - - - - PGTYPESnumeric_free - - - Free a numeric type, release all of its memory. - -void PGTYPESnumeric_free(numeric *var); - - - - - - - PGTYPESnumeric_from_asc - - - Parse a numeric type from its string notation. - -numeric *PGTYPESnumeric_from_asc(char *str, char **endptr); - - Valid formats are for example: - -2, - .794, - +3.44, - 592.49E07 or - -32.84e-4. - If the value could be parsed successfully, a valid pointer is returned, - else the NULL pointer. At the moment ECPG always parses the complete - string and so it currently does not support to store the address of the - first invalid character in *endptr. You can safely - set endptr to NULL. - - - - - - PGTYPESnumeric_to_asc - - - Returns a pointer to a string allocated by malloc that contains the string - representation of the numeric type num. - -char *PGTYPESnumeric_to_asc(numeric *num, int dscale); - - The numeric value will be printed with dscale decimal - digits, with rounding applied if necessary. - - - - - - PGTYPESnumeric_add - - - Add two numeric variables into a third one. - -int PGTYPESnumeric_add(numeric *var1, numeric *var2, numeric *result); - - The function adds the variables var1 and - var2 into the result variable - result. - The function returns 0 on success and -1 in case of error. - - - - - - PGTYPESnumeric_sub - - - Subtract two numeric variables and return the result in a third one. - -int PGTYPESnumeric_sub(numeric *var1, numeric *var2, numeric *result); - - The function subtracts the variable var2 from - the variable var1. The result of the operation is - stored in the variable result. - The function returns 0 on success and -1 in case of error. - - - - - - PGTYPESnumeric_mul - - - Multiply two numeric variables and return the result in a third one. - -int PGTYPESnumeric_mul(numeric *var1, numeric *var2, numeric *result); - - The function multiplies the variables var1 and - var2. The result of the operation is stored in the - variable result. - The function returns 0 on success and -1 in case of error. - - - - - - PGTYPESnumeric_div - - - Divide two numeric variables and return the result in a third one. - -int PGTYPESnumeric_div(numeric *var1, numeric *var2, numeric *result); - - The function divides the variables var1 by - var2. The result of the operation is stored in the - variable result. - The function returns 0 on success and -1 in case of error. - - - - - - PGTYPESnumeric_cmp - - - Compare two numeric variables. - -int PGTYPESnumeric_cmp(numeric *var1, numeric *var2) - - This function compares two numeric variables. In case of error, - INT_MAX is returned. On success, the function - returns one of three possible results: - - - - 1, if var1 is bigger than var2 - - - - - -1, if var1 is smaller than var2 - - - - - 0, if var1 and var2 are equal - - - - - - - - - PGTYPESnumeric_from_int - - - Convert an int variable to a numeric variable. - -int PGTYPESnumeric_from_int(signed int int_val, numeric *var); - - This function accepts a variable of type signed int and stores it - in the numeric variable var. Upon success, 0 is returned and - -1 in case of a failure. - - - - - - PGTYPESnumeric_from_long - - - Convert a long int variable to a numeric variable. - -int PGTYPESnumeric_from_long(signed long int long_val, numeric *var); - - This function accepts a variable of type signed long int and stores it - in the numeric variable var. Upon success, 0 is returned and - -1 in case of a failure. - - - - - - PGTYPESnumeric_copy - - - Copy over one numeric variable into another one. - -int PGTYPESnumeric_copy(numeric *src, numeric *dst); - - This function copies over the value of the variable that - src points to into the variable that dst - points to. It returns 0 on success and -1 if an error occurs. - - - - - - PGTYPESnumeric_from_double - - - Convert a variable of type double to a numeric. - -int PGTYPESnumeric_from_double(double d, numeric *dst); - - This function accepts a variable of type double and stores the result - in the variable that dst points to. It returns 0 on success - and -1 if an error occurs. - - - - - - PGTYPESnumeric_to_double - - - Convert a variable of type numeric to double. - -int PGTYPESnumeric_to_double(numeric *nv, double *dp) - - The function converts the numeric value from the variable that - nv points to into the double variable that dp points - to. It returns 0 on success and -1 if an error occurs, including - overflow. On overflow, the global variable errno will be set - to PGTYPES_NUM_OVERFLOW additionally. - - - - - - PGTYPESnumeric_to_int - - - Convert a variable of type numeric to int. - -int PGTYPESnumeric_to_int(numeric *nv, int *ip); - - The function converts the numeric value from the variable that - nv points to into the integer variable that ip - points to. It returns 0 on success and -1 if an error occurs, including - overflow. On overflow, the global variable errno will be set - to PGTYPES_NUM_OVERFLOW additionally. - - - - - - PGTYPESnumeric_to_long - - - Convert a variable of type numeric to long. - -int PGTYPESnumeric