title: po4a(7)

text:
# po4a(7)

## NAME
po4a - framework to translate documentation and other materials

## Introduction
po4a (PO for anything) eases the maintenance of documentation translation using the classical gettext tools. The main feature of po4a is that it decouples the translation of content from its document structure.

This document serves as an introduction to the po4a project with a focus on potential users considering whether to use this tool and on the curious wanting to understand why things are the way they are.

## Why po4a?
The philosophy of Free Software is to make the technology truly available to everyone. But licensing is not the only consideration: untranslated free software is useless for non-English speakers. Therefore, we still have some work to do to make software available to everybody.

This situation is well understood by most projects and everybody is now convinced of the necessity to translate everything. Yet, the actual translations represent a huge effort of many individuals, crippled by small technical difficulties.

Thankfully, Open Source software is actually very well translated using the gettext tool suite. These tools are used to extract the strings to translate from a program and present the strings to translate in a standardized format (called PO files, or translation catalogs). A whole ecosystem of tools has emerged to help the translators actually translate these PO files. The result is then used by gettext at run time to display translated messages to the end users.

Regarding documentation, however, the situation still somewhat disappointing. At first translating documentation may seem to be easier than translating a program as it would seem that you just have to copy the documentation source file and start translating the content. However, when the original documentation is modified, keeping track of the modifications quickly turns into a nightmare for the translators. If done manually, this task is unpleasant and error prone.

Outdated translations are often worse than no translation at all. End-users can be tricked by documentation describing an old behavior of the program. Furthermore, they cannot interact directly with the maintainers since they don't speak English. Additionally, the maintainer cannot fix the problem as they don't know every language in which their documentation is translated. These difficulties, often caused by poor tooling, can undermine the motivation of volunteer translators, further aggravating the problem.

The goal of the po4a project is to ease the work of documentation translators. In particular, it makes documentation translations maintainable.

The idea is to reuse and adapt the gettext approach to this field. As with gettext, texts are extracted from their original locations and presented to translators as PO translation catalogs. The translators can leverage the classical gettext tools to monitor the work to do, collaborate and organize as teams. po4a then injects the translations directly into the documentation structure to produce translated source files that can be processed and distributed just like the English files. Any paragraph that is not translated is left in English in the resulting document, ensuring that the end users never see an outdated translation in the documentation.

This automates most of the grunt work of the translation maintenance. Discovering the paragraphs needing an update becomes very easy, and the process is completely automated when elements are reordered without further modification. Specific verification can also be used to reduce the chance of formatting errors that would result in a broken document.

Please also see the FAQ below in this document for a more complete list of the advantages and disadvantages of this approach.

### Supported formats
Currently, this approach has been successfully implemented to several kinds of text formatting formats:

man (mature parser)

The good old manual pages' format, used by so many programs out there. po4a support is very welcome here since this format is somewhat difficult to use and not really friendly to newbies. The Locale::Po4a::Man(3pm) module also supports the mdoc format, used by the BSD man pages (they are also quite common on Linux).

AsciiDoc (mature parser)

This format is a lightweight markup format intended to ease the authoring of documentation. It is for example used to document the git system. Those manpages are translated using po4a. See Locale::Po4a::AsciiDoc for details.

pod (mature parser)

This is the Perl Online Documentation format. The language and extensions themselves are documented using this format in addition to most existing Perl scripts. It makes easy to keep the documentation close to the actual code by embedding them both in the same file. It makes programmer's life easier, but unfortunately, not the translator's, until you use po4a. See Locale::Po4a::Pod for details.

sgml (mature parser)

Even if superseded by XML nowadays, this format is still used for documents which are more than a few screens long. It can even be used for complete books. Documents of this length can be very challenging to update. diff often reveals useless when the original text was re-indented after update. Fortunately, po4a can help you after that process. Currently, only DebianDoc and DocBook DTD are supported, but adding support for a new one is really easy. It is even possible to use po4a on an unknown SGML DTD without changing the code by providing the needed information on the command line. See Locale::Po4a::Sgml(3pm) for details.

TeX / LaTeX (mature parser)

The LaTeX format is a major documentation format used in the Free Software world and for publications. The Locale::Po4a::LaTeX(3pm) module was tested with the Python documentation, a book and some presentations.

text (mature parser)

The Text format is the base format for many formats that include long blocks of text, including Markdown, fortunes, YAML front matter section, debian/changelog, and debian/control. This supports the common format used in Static Site Generators, READMEs, and other documentation systems. See Locale::Po4a::Text(3pm) for details.

xml and XHMTL (probably mature parser)

The XML format is a base format for many documentation formats. Currently, the DocBook DTD (see Locale::Po4a::Docbook(3pm) for details) and XHTML are supported by po4a.

BibTex (probably mature parser)

The BibTex format is used alongside LaTex for formatting lists of references (bibliographies). See Locale::Po4a::BibTex for details.

Docbook (probably mature parser)

A XML-based markup language that uses semantic tags to describe documents. See Locale::Po4a:Docbook for greater details.

Guide XML (probably mature parser)

A XML documentation format. This module was developed specifically to help with supporting and maintaining translations of Gentoo Linux documentation up until at least March 2016 (Based on the Wayback Machine). Gentoo have since moved to the DevBook XML format. See Locale::Po4a:Guide for greater details.

Wml (probably mature parser)

The Web Markup Language, do not mixup WML with the WAP stuff used on cell phones. This module relies on the Xhtml module, which itself relies on the XmL module. See Locale::Po4a::Wml for greater details.

Yaml (probably mature parser)

A strict superset of JSON. YAML is often used as systems or configuration projects. YAML is at the core of Red Hat's Ansible. See Locale::Po4a::Yaml for greater details.

RubyDoc (probably mature parser)

The Ruby Document (RD) format, originally the default documentation format for Ruby and Ruby projects before converted to RDoc in 2002. Though apparently the Japanese version of the Ruby Reference Manual still use RD. See Locale::Po4a::RubyDoc for greater details.

Halibut (probably experimental parser)

A documentation production system, with elements similar to TeX, debiandoc-sgml, TeXinfo, and others, developed by Simon Tatham, the developer of PuTTY. See Locale::Po4a:Halibut for greater details.

Ini (probably experimental parser)

Configuration file format popularized by MS-DOS. See Locale::Po4a::Ini for greater details.

texinfo (very highly experimental parser)

All of the GNU documentation is written in this format (it's even one of the requirements to become an official GNU project). The support for Locale::Po4a::Texinfo(3pm) in po4a is still at the beginning. Please report bugs and feature requests.

Others supported formats

Po4a can also handle some more rare or specialized formats, such as the documentation of compilation options for the 2.4+ Linux kernels (Locale::Po4a::KernelHelp) or the diagrams produced by the dia tool (Locale::Po4a:Dia). Adding a new format is often very easy and the main task is to come up with a parser for your target format. See Locale::Po4a::TransTractor(3pm) for more information about this.

Unsupported formats

Unfortunately, po4a still lacks support for several documentation formats. Many of them would be easy to support in po4a. This includes formats not just used for documentation, such as, package descriptions (deb and rpm), package installation scripts questions, package changelogs, and all the specialized file formats used by programs such as game scenarios or wine resource files.

## Using po4a
Historically, po4a was built around four scripts, each fulfilling a specific task. po4a-gettextize(1) helps bootstrapping translations and optionally converting existing translation projects to po4a. po4a-updatepo(1) reflects the changes to the original documentation into the corresponding po files. po4a-translate(1) builds translated source file from the original file and the corresponding PO file. In addition, po4a-normalize(1) is mostly useful to debug the po4a parsers, as it produces an untranslated document from the original one. It makes it easier to spot the glitches introduced by the parsing process.

Most projects only require the features of po4a-updatepo(1) and po4a-translate(1), but these scripts proved to be cumbersome and error prone to use. If the documentation to translate is split over several source files, it is difficult to keep the PO files up to date and build the documentation files correctly. As an answer, a all-in-one tool was provided: po4a(1). This tool takes a configuration file describing the structure of the translation project: the location of the PO files, the list of files to translate, and the options to use, and it fully automatizes the process. When you invoke po4a(1), it both updates the PO files and regenerate the translation files that need to. If everything is already up to date, po4a(1) does not change any file.

The rest of this section gives an overview of how use the scripts' interface of po4a. Most users will probably prefer to use the all-in-one tool, that is described in the documentation of po4a(1).

### Graphical overview of the po4a scripts
The following schema gives an overview of how each po4a script can be used. Here, master.doc is an example name for the documentation to be translated; XX.doc is the same document translated in the language XX while doc.XX.po is the translation catalog for that document in the XX language. Documentation authors will mostly be concerned with master.doc (which can be a manpage, an XML document, an asciidoc file or similar); the translators will be mostly concerned with the PO file, while the end users will only see the XX.doc file.

```
                                   master.doc
                                       |
                                       V
     +<-----<----+<-----<-----<--------+------->-------->-------+
     :           |                     |                        :
{translation}    |         { update of master.doc }             :
     :           |                     |                        :
   XX.doc        |                     V                        V
 (optional)      |                 master.doc ->-------->------>+
     :           |                   (new)                      |
     V           V                     |                        |
  [po4a-gettextize]   doc.XX.po -->+   |                        |
          |            (old)       |   |                        |
          |              ^         V   V                        |
          |              |     [po4a-updatepo]                  |
          V              |           |                          V
   translation.pot       ^           V                          |
          |              |        doc.XX.po                     |
          |              |         (fuzzy)                      |
   { translation }       |           |                          |
          |              ^           V                          V
          |              |     {manual editing}                 |
          |              |           |                          |
          V              |           V                          V
      doc.XX.po --->---->+<---<-- doc.XX.po    addendum     master.doc
      (initial)                 (up-to-date)  (optional)   (up-to-date)
          :                          |            |             |
          :                          V            |             |
          +----->----->----->------> +            |             |
                                     |            |             |
                                     V            V             V
                                     +------>-----+------<------+
                                                  |
                                                  V
                                           [po4a-translate]
                                                  |
                                                  V
                                                XX.doc
                                             (up-to-date)
```

This schema is complicated, but in practice only the right part (involving po4a-updatepo(1) and po4a-translate(1)) is used once the project is setup and configured.

The left part depicts how po4a-gettextize(1) can be used to convert an existing translation project to the po4a infrastructure. This script takes an original document and its translated counterpart, and tries to build the corresponding PO file. Such manual conversion is rather cumbersome (see the po4a-gettextize(1) documentation for more details), but it is only needed once to convert your existing translations. If you don't have any translation to convert, you can forget about this and focus on the right part of the schema.

On the top right part, the action of the original author is depicted, updating the documentation. The middle right part depicts the automatic actions of po4a-updatepo(1). The new material is extracted and compared against the exiting translation. The previous translation is used for the parts that didn't change, while partially modified parts are connected to the previous translation with a "fuzzy" marker indicating that the translation must be updated. New or heavily modified material is left untranslated.

Then, the manual editing reported depicts the action of the translators, that modify the PO files to provide translations to every original string and paragraph. This can be done using either a specific editor such as the GNOME Translation Editor, KDE's Lokalize or poedit, or using an online localization platform such as weblate or pootle. The translation result is a set of PO files, one per language. Please refer to the gettext documentation for more details.

The bottom part of the figure shows how po4a-translate(1) creates a translated source document from the master.doc original document and the doc.XX.po translation catalog that was updated by the translators. The structure of the document is reused, while the original content is replaced by its translated counterpart. Optionally, an addendum can be used to add some extra text to the translation. This is often used to add the name of the translator to the final document. See below for details.

As noted before, the po4a(1) program combines the effects of the separated scripts, updating the PO files and the translated document in one invocation. The underlying logic remains the same.

### Starting a new translation
If you use po4a(1), there is no specific step to start a translation. You just have to list the languages in the configuration file, and the missing PO files are automatically created. Naturally, the translator then have to provide translations for every content used in your documents. po4a(1) also creates a POT file, that is a PO template file. Potential translators can translate your project into a new language by renaming this file and providing the translations in their language.

If you prefer to use the individual scripts separately, you should use po4a-gettextize(1) as follows to create the POT file. This file can then be copied into XX.po to initiate a new translation.

```
  $ po4a-gettextize --format <format> --master <master.doc> --po <translation.pot>
```

The master document is used in input, while the POT file is the output of this process.

### Integrating changes to the original document
The script to use for that is po4a-updatepo(1) (please refer to its documentation for details):

```
  $ po4a-updatepo --format <format> --master <new_master.doc> --po <old_doc.XX.po>
```

The master document is used in input, while the PO file is updated: it is used both in input and output.

### Generating a translated document
Once you're done with the translation, you want to get the translated documentation and distribute it to users along with the original one. For that, use the po4a-translate(1) program as follows:

```
  $ po4a-translate --format <format> --master <master.doc> --po <doc.XX.po> --localized <XX.doc>
```

Both the master and PO files are used in input, while the localized file is the output of this process.

### Using addenda to add extra text to translations
Adding new text to the translation is probably the only thing that is easier in the long run when you translate files manually :). This happens when you want to add an extra section to the translated document, not corresponding to any content in the original document. The classical use case is to give credits to the translation team, and to indicate how to report translation-specific issues.

With po4a, you have to specify addendum files, that can be conceptually viewed as patches applied to the localized document after processing. Each addendum must be provided as a separate file, which format is however very different from the classical patches. The first line is a header line, defining the insertion point of the addendum (with an unfortunately cryptic syntax -- see below) while the rest of the file is added verbatim at the determined position.

The header line must begin with the string PO4A-HEADER:, followed by a semi-colon separated list of key=value fields.

For example, the following header declares an addendum that must be placed at the very end of the translation.

```
 PO4A-HEADER: mode=eof
```

Things are more complex when you want to add your extra content in the middle of the document. The following header declares an addendum that must be placed after the XML section containing the string "About this document" in translation.

```
 PO4A-HEADER: position=About this document; mode=after; endboundary=</section>
```

In practice, when trying to apply an addendum, po4a searches for the first line matching the "position" argument (this can be a regexp). Do not forget that po4a considers the translated document here. This documentation is in English, but your line should probably read as follows if you intend your addendum to apply to the French translation of the document.

```
 PO4A-HEADER: position=À propos de ce document; mode=after; endboundary=</section>
```

Once the "position" is found in the target document, po4a searches for the next line after the "position" that matches the provided "endboundary". The addendum is added right after that line (because we provided an endboundary, i.e. a boundary ending the current section).

The exact same effect could be obtained with the following header, that is equivalent:

```
 PO4A-HEADER: position=About this document; mode=after; beginboundary=<section>
```

Here, po4a searches for the first line matching "<section"> after the line matching "About this document" in the translation, and add the addendum before that line since we provided a beginboundary, i.e. a boundary marking the beginning of the next section. So this header line requires to place the addendum after the section containing "About this document", and instruct po4a that a section starts with a line containing the "<section"> tag. This is equivalent to the previous example because what you really want is to add this addendum either after "/section"> or before "<section">.

You can also set the insertion mode to the value "before", with a similar semantic: combining "mode=before" with an "endboundary" will put the addendum just after the matched boundary, that the last potential boundary line before the "position". Combining "mode=before" with an "beginboundary" will put the addendum just before the matched boundary, that the last potential boundary line before the "position".

```
  Mode   | Boundary kind |     Used boundary      | Insertion point compared to the boundary
 ========|===============|========================|=========================================
 'before'| 'endboundary' | last before 'position' | Right after the selected boundary
 'before'|'beginboundary'| last before 'position' | Right before the selected boundary
 'after' | 'endboundary' | first after 'position' | Right after the selected boundary
 'after' |'beginboundary'| first after 'position' | Right before the selected boundary
 'eof'   |   (none)      |  n/a                   | End of file
```

Hint and tricks about addenda

- Remember that these are regexp. For example, if you want to match the end of a nroff section ending with the line ".fi", do not use ".fi" as endboundary, because it will match with "the[ fi]le", which is obviously not what you expect. The correct endboundary in that case is: "^\.fi$".

- White spaces ARE important in the content of the "position" and boundaries. So the two following lines are different. The second one will only be found if there is enough trailing spaces in the translated document.

```
 PO4A-HEADER: position=About this document; mode=after; beginboundary=<section>
 PO4A-HEADER: position=About this document ; mode=after; beginboundary=<section>

```

- Although this context search may be considered to operate roughly on each line of the translated document, it actually operates on the internal data string of the translated document. This internal data string may be a text spanning a paragraph containing multiple lines or may be a XML tag itself alone. The exact insertion point of the addendum must be before or after the internal data string and can not be within the internal data string.

- Pass the -vv argument to po4a to understand how the addenda are added to the translation. It may also help to run po4a in debug mode to see the actual internal data string when your addendum does not apply.

Addenda examples

- If you want to add something after the following nroff section:

```
  .SH "AUTHORS"

```

You should select a two step approach by setting mode=after. Then you should narrow down search to the line after AUTHORS with the position argument regex. Then, you should match the beginning of the next section (i.e., ^\.SH) with the beginboundary argument regex. That is to say:

```
 PO4A-HEADER:mode=after;position=AUTHORS;beginboundary=\.SH

```

- If you want to add something right after a given line (e.g. after the line "Copyright Big Dude"), use a position matching this line, mode=after and give a beginboundary matching any line.

```
 PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^

```

- If you want to add something at the end of the document, give a position matching any line of your document (but only one line. Po4a won't proceed if it's not unique), and give an endboundary matching nothing. Don't use simple strings here like "EOF", but prefer those which have less chance to be in your document.

```
 PO4A-HEADER:mode=after;position=About this document;beginboundary=FakePo4aBoundary

```

More detailed example

Original document (POD formatted):

```
 |=head1 NAME
 |
 |dummy - a dummy program
 |
 |=head1 AUTHOR
 |
 |me
```

Then, the following addendum will ensure that a section (in French) about the translator is added at the end of the file (in French, "TRADUCTEUR" means "TRANSLATOR", and "moi" means "me").

```
 |PO4A-HEADER:mode=after;position=AUTEUR;beginboundary=^=head
 |
 |=head1 TRADUCTEUR
 |
 |moi
 |
```

To put your addendum before the AUTHOR, use the following header:

```
 PO4A-HEADER:mode=after;position=NOM;beginboundary=^=head1
```

This works because the next line matching the beginboundary /^=head1/ after the section "NAME" (translated to "NOM" in French), is the one declaring the authors. So, the addendum will be put between both sections. Note that if another section is added between NAME and AUTHOR sections later, po4a will wrongfully put the addenda before the new section.

To avoid this you may accomplish the same using mode=before:

```
 PO4A-HEADER:mode=before;position=^=head1 AUTEUR
```

## How does it work?
This chapter gives you a brief overview of the po4a internals, so that you may feel more confident to help us maintaining and improving it. It may also help you understanding why it does not do what you expected, and how to solve your problems.

The po4a architecture is object oriented. The Locale::Po4a::TransTractor(3pm) class is the common ancestor to all po4a parsers. This strange name comes from the fact that it is at the same time in charge of translating document and extracting strings.

More formally, it takes a document to translate plus a PO file containing the translations to use as input while producing two separate outputs: Another PO file (resulting of the extraction of translatable strings from the input document), and a translated document (with the same structure than the input one, but with all translatable strings replaced with content of the input PO). Here is a graphical representation of this:

```
   Input document --\                             /---> Output document
                     \      TransTractor::       /       (translated)
                      +-->--   parse()  --------+
                     /                           \
   Input PO --------/                             \---> Output PO
                                                         (extracted)
```

This little bone is the core of all the po4a architecture. If you omit the input PO and the output document, you get po4a-gettextize. If you provide both input and disregard the output PO, you get po4a-translate. The po4a calls TransTractor twice and calls msgmerge -U between these TransTractor invocations to provide one-stop solution with a single configuration file. Please see Locale::Po4a::TransTractor(3pm) for more details.

## Open-source projects using po4a
Here is a very partial list of projects that use po4a in production for their documentation. If you want to add your project to the list, just drop us an email (or a Merge Request).

- adduser (man): users and groups management tool.

- apt (man, docbook): Debian package manager.

- aptitude (docbook, svg): terminal-based package manager for Debian

- F-Droid website <https://gitlab.com/fdroid/fdroid-website> (markdown): installable catalogue of FOSS (Free and Open Source Software) applications for the Android platform.

- git <https://github.com/jnavila/git-manpages-l10n> (asciidoc): distributed version-control system for tracking changes in source code.

- Linux manpages <https://salsa.debian.org/manpages-l10n-team/manpages-l10n> (man) This project provides an infrastructure for translating many manpages to different languages, ready for integration into several major distributions (Arch Linux, Debian and derivatives, Fedora).

- Stellarium <https://github.com/Stellarium/stellarium> (HTML): a free open source planetarium for your computer. po4a is used to translate the sky culture descriptions.

- Other item to sort out: <https://gitlab.com/fdroid/fdroid-website/> <https://github.com/fsfe/reuse-docs/pull/61>

## FAQ

### How do you pronounce po4a?
I personally vocalize it as pouah <https://en.wiktionary.org/wiki/pouah>, which is a French onomatopoetic that we use in place of yuck :) I may have a strange sense of humor :)

### What about the other translation tools for documentation using gettext?
As far as I know, there are only two of them:

poxml

This is the tool developed by KDE people to handle DocBook XML. AFAIK, it was the first program to extract strings to translate from documentation to PO files, and inject them back after translation. It can only handle XML, and only a particular DTD. I'm quite unhappy with the handling of lists, which end in one big msgid. When the list become big, the chunk becomes harder to swallow.

po-debiandoc

This program done by Denis Barbier is a sort of precursor of the po4a SGML module, which more or less deprecates it. As the name says, it handles only the DebianDoc DTD, which is more or less a deprecated DTD.

The main advantages of po4a over them are the ease of extra content addition (which is even worse there) and the ability to achieve gettextization.

### SUMMARY of the advantages of the gettext based approach

- The translations are not stored along with the original, which makes it possible to detect if translations become out of date.

- The translations are stored in separate files from each other, which prevents translators of different languages from interfering, both when submitting their patch and at the file encoding level.

- It is based internally on gettext (but po4a offers a very simple interface so that you don't need to understand the internals to use it). That way, we don't have to re-implement the wheel, and because of their wide use, we can think that these tools are more or less bug free.

- Nothing changed for the end-user (beside the fact translations will hopefully be better maintained). The resulting documentation file distributed is exactly the same.

- No need for translators to learn a new file syntax and their favorite PO file editor (like Emacs' PO mode, Lokalize or Gtranslator) will work just fine.

- gettext offers a simple way to get statistics about what is done, what should be reviewed and updated, and what is still to do. Some example can be found at those addresses:

```
 - https://docs.kde.org/stable5/en/kdesdk/lokalize/project-view.html
 - http://www.debian.org/intl/l10n/

```

But everything isn't green, and this approach also has some disadvantages we have to deal with.

- Addenda are… strange at the first glance.

- You can't adapt the translated text to your preferences, like splitting a paragraph here, and joining two other ones there. But in some sense, if there is an issue with the original, it should be reported as a bug anyway.

- Even with an easy interface, it remains a new tool people have to learn. One of my dreams would be to integrate somehow po4a to Gtranslator or Lokalize. When a documentation file is opened, the strings are automatically extracted, and a translated file + po file can be written to disk. If we manage to do an MS Word (TM) module (or at least RTF) professional translators may even use it.

## SEE ALSO

- The documentation of the all-in-one tool that you should use: po4a(1).

- The documentation of the individual po4a scripts: po4a-gettextize(1), po4a-updatepo(1), po4a-translate(1), po4a-normalize(1).

- The additional helping scripts: msguntypot(1), po4a-display-man(1), po4a-display-pod(1).

- The parsers of each formats, in particular to see the options accepted by each of them: Locale::Po4a::AsciiDoc(3pm) Locale::Po4a::Dia(3pm), Locale::Po4a::Guide(3pm), Locale::Po4a::Ini(3pm), Locale::Po4a::KernelHelp(3pm), Locale::Po4a::Man(3pm), Locale::Po4a::RubyDoc(3pm), Locale::Po4a::Texinfo(3pm), Locale::Po4a::Text(3pm), Locale::Po4a::Xhtml(3pm), Locale::Po4a::Yaml(3pm), Locale::Po4a::BibTeX(3pm), Locale::Po4a::Docbook(3pm), Locale::Po4a::Halibut(3pm), Locale::Po4a::LaTeX(3pm), Locale::Po4a::Pod(3pm), Locale::Po4a::Sgml(3pm), Locale::Po4a::TeX(3pm), Locale::Po4a::Wml(3pm), Locale::Po4a::Xml(3pm).

- The implementation of the core infrastructure: Locale::Po4a::TransTractor(3pm) (particularly important to understand the code organization), Locale::Po4a::Chooser(3pm), Locale::Po4a::Po(3pm), Locale::Po4a::Common(3pm). Please also check the CONTRIBUTING.md file in the source tree.

## AUTHORS

```
 Denis Barbier <barbier,linuxfr.org>
 Martin Quinson (mquinson#debian.org)
```


ABORT

title: ABORT(7)

summary: abort the current transaction

text:
# ABORT(7)

## NAME
ABORT - abort the current transaction

## SYNOPSIS

```
ABORT [ WORK | TRANSACTION ] [ AND [ NO ] CHAIN ]
```

## DESCRIPTION
ABORT rolls back the current transaction and causes all the updates made by the transaction to be discarded. This command is identical in behavior to the standard SQL command ROLLBACK(7), and is present only for historical reasons.

## PARAMETERS
WORK

TRANSACTION

Optional key words. They have no effect.

AND CHAIN

If AND CHAIN is specified, a new transaction is immediately started with the same transaction characteristics (see SET TRANSACTION (SET_TRANSACTION(7))) as the just finished one. Otherwise, no new transaction is started.

## NOTES
Use COMMIT(7) to successfully terminate a transaction.

Issuing ABORT outside of a transaction block emits a warning and otherwise has no effect.

## EXAMPLES
To abort all changes:

```
ABORT;
```

## COMPATIBILITY
This command is a PostgreSQL extension present for historical reasons. ROLLBACK is the equivalent standard SQL command.

## SEE ALSO
BEGIN(7), COMMIT(7), ROLLBACK(7)


title: ALTER_AGGREGATE(7)

text:
# ALTER_AGGREGATE(7)

## NAME
ALTER_AGGREGATE - change the definition of an aggregate function

## SYNOPSIS

```
ALTER AGGREGATE name ( aggregate_signature ) RENAME TO new_name
ALTER AGGREGATE name ( aggregate_signature )

                OWNER TO { new_owner | CURRENT_USER | SESSION_USER }
ALTER AGGREGATE name ( aggregate_signature ) SET SCHEMA new_schema
where aggregate_signature is:
* |
[ argmode ] [ argname ] argtype [ , ... ] |
[ [ argmode ] [ argname ] argtype [ , ... ] ] ORDER BY [ argmode ] [ argname ] argtype [ , ... ]
```

## DESCRIPTION
ALTER AGGREGATE changes the definition of an aggregate function.

You must own the aggregate function to use ALTER AGGREGATE. To change the schema of an aggregate function, you must also have CREATE privilege on the new schema. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have CREATE privilege on the aggregate function's schema. (These restrictions enforce that altering the owner doesn't do anything you couldn't do by dropping and recreating the aggregate function. However, a superuser can alter ownership of any aggregate function anyway.)

## PARAMETERS
name

The name (optionally schema-qualified) of an existing aggregate function.

argmode

The mode of an argument: IN or VARIADIC. If omitted, the default is IN.

argname

The name of an argument. Note that ALTER AGGREGATE does not actually pay any attention to argument names, since only the argument data types are needed to determine the aggregate function's identity.

argtype

An input data type on which the aggregate function operates. To reference a zero-argument aggregate function, write * in place of the list of argument specifications. To reference an ordered-set aggregate function, write ORDER BY between the direct and aggregated argument specifications.

new_name

The new name of the aggregate function.

new_owner

The new owner of the aggregate function.

new_schema

The new schema for the aggregate function.

## NOTES
The recommended syntax for referencing an ordered-set aggregate is to write ORDER BY between the direct and aggregated argument specifications, in the same style as in CREATE AGGREGATE (CREATE_AGGREGATE(7)). However, it will also work to omit ORDER BY and just run the direct and aggregated argument specifications into a single list. In this abbreviated form, if VARIADIC "any" was used in both the direct and aggregated argument lists, write VARIADIC "any" only once.

## EXAMPLES
To rename the aggregate function myavg for type integer to my_average:

```
ALTER AGGREGATE myavg(integer) RENAME TO my_average;
```

To change the owner of the aggregate function myavg for type integer to joe:

```
ALTER AGGREGATE myavg(integer) OWNER TO joe;
```

To move the ordered-set aggregate mypercentile with direct argument of type float8 and aggregated argument of type integer into schema myschema:

```
ALTER AGGREGATE mypercentile(float8 ORDER BY integer) SET SCHEMA myschema;
```

This will work too:

```
ALTER AGGREGATE mypercentile(float8, integer) SET SCHEMA myschema;
```

## COMPATIBILITY
There is no ALTER AGGREGATE statement in the SQL standard.

## SEE ALSO
CREATE AGGREGATE (CREATE_AGGREGATE(7)), DROP AGGREGATE (DROP_AGGREGATE(7))


title: ALTER_COLLATION(7)

summary: change the definition of a collation

text:
# ALTER_COLLATION(7)

## NAME
ALTER_COLLATION - change the definition of a collation

## SYNOPSIS

```
ALTER COLLATION name REFRESH VERSION
ALTER COLLATION name RENAME TO new_name
ALTER COLLATION name OWNER TO { new_owner | CURRENT_USER | SESSION_USER }
ALTER COLLATION name SET SCHEMA new_schema
```

## DESCRIPTION
ALTER COLLATION changes the definition of a collation.

You must own the collation to use ALTER COLLATION. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have CREATE privilege on the collation's schema. (These restrictions enforce that altering the owner doesn't do anything you couldn't do by dropping and recreating the collation. However, a superuser can alter ownership of any collation anyway.)

## PARAMETERS
name

The name (optionally schema-qualified) of an existing collation.

new_name

The new name of the collation.

new_owner

The new owner of the collation.

new_schema

The new schema for the collation.

REFRESH VERSION

Update the collation's version. See Notes below.

## NOTES
When using collations provided by the ICU library, the ICU-specific version of the collator is recorded in the system catalog when the collation object is created. When the collation is used, the current version is checked against the recorded version, and a warning is issued when there is a mismatch, for example:

```
WARNING:  collation "xx-x-icu" has version mismatch
DETAIL:  The collation in the database was created using version 1.2.3.4, but the operating system provides version 2.3.4.5.
HINT:  Rebuild all objects affected by this collation and run ALTER COLLATION pg_catalog."xx-x-icu" REFRESH VERSION, or build PostgreSQL with the right library version.
```

A change in collation definitions can lead to corrupt indexes and other problems because the database system relies on stored objects having a certain sort order. Generally, this should be avoided, but it can happen in legitimate circumstances, such as when using pg_upgrade to upgrade to server binaries linked with a newer version of ICU. When this happens, all objects depending on the collation should be rebuilt, for example, using REINDEX. When that is done, the collation version can be refreshed using the command ALTER COLLATION ... REFRESH VERSION. This will update the system catalog to record the current collator version and will make the warning go away. Note that this does not actually check whether all affected objects have been rebuilt correctly.

When using collations provided by libc and PostgreSQL was built with the GNU C library, the C library's version is used as a collation version. Since collation definitions typically change only with GNU C library releases, this provides some defense against corruption, but it is not completely reliable.

Currently, there is no version tracking for the database default collation.

The following query can be used to identify all collations in the current database that need to be refreshed and the objects that depend on them:

```
SELECT pg_describe_object(refclassid, refobjid, refobjsubid) AS "Collation",

       pg_describe_object(classid, objid, objsubid) AS "Object"

  FROM pg_depend d JOIN pg_collation c

       ON refclassid = 'pg_collation'::regclass AND refobjid = c.oid

  WHERE c.collversion <> pg_collation_actual_version(c.oid)

  ORDER BY 1, 2;
```

## EXAMPLES
To rename the collation de_DE to german:

```
ALTER COLLATION "de_DE" RENAME TO german;
```

To change the owner of the collation en_US to joe:

```
ALTER COLLATION "en_US" OWNER TO joe;
```

## COMPATIBILITY
There is no ALTER COLLATION statement in the SQL standard.

## SEE ALSO
CREATE COLLATION (CREATE_COLLATION(7)), DROP COLLATION (DROP_COLLATION(7))


title: ALTER_CONVERSION(7)

summary: change the definition of a conversion

text:
# ALTER_CONVERSION(7)

## NAME
ALTER_CONVERSION - change the definition of a conversion

## SYNOPSIS

```
ALTER CONVERSION name RENAME TO new_name
ALTER CONVERSION name OWNER TO { new_owner | CURRENT_USER | SESSION_USER }
ALTER CONVERSION name SET SCHEMA new_schema
```

## DESCRIPTION
ALTER CONVERSION changes the definition of a conversion.

You must own the conversion to use ALTER CONVERSION. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have CREATE privilege on the conversion's schema. (These restrictions enforce that altering the owner doesn't do anything you couldn't do by dropping and recreating the conversion. However, a superuser can alter ownership of any conversion anyway.)

## PARAMETERS
name

The name (optionally schema-qualified) of an existing conversion.

new_name

The new name of the conversion.

new_owner

The new owner of the conversion.

new_schema

The new schema for the conversion.

## EXAMPLES
To rename the conversion iso_8859_1_to_utf8 to latin1_to_unicode:

```
ALTER CONVERSION iso_8859_1_to_utf8 RENAME TO latin1_to_unicode;
```

To change the owner of the conversion iso_8859_1_to_utf8 to joe:

```
ALTER CONVERSION iso_8859_1_to_utf8 OWNER TO joe;
```

## COMPATIBILITY
There is no ALTER CONVERSION statement in the SQL standard.

## SEE ALSO
CREATE CONVERSION (CREATE_CONVERSION(7)), DROP CONVERSION (DROP_CONVERSION(7))


title: ALTER_DATABASE(7)

summary: change a database

text:
# ALTER_DATABASE(7)

## NAME
ALTER_DATABASE - change a database

## SYNOPSIS

```
ALTER DATABASE name [ [ WITH ] option [ ... ] ]
where option can be:

    ALLOW_CONNECTIONS allowconn

    CONNECTION LIMIT connlimit

    IS_TEMPLATE istemplate
ALTER DATABASE name RENAME TO new_name
ALTER DATABASE name OWNER TO { new_owner | CURRENT_USER | SESSION_USER }
ALTER DATABASE name SET TABLESPACE new_tablespace
ALTER DATABASE name SET configuration_parameter { TO | = } { value | DEFAULT }
ALTER DATABASE name SET configuration_parameter FROM CURRENT
ALTER DATABASE name RESET configuration_parameter
ALTER DATABASE name RESET ALL
```

## DESCRIPTION
ALTER DATABASE changes the attributes of a database.

The first form changes certain per-database settings. (See below for details.) Only the database owner or a superuser can change these settings.

The second form changes the name of the database. Only the database owner or a superuser can rename a database; non-superuser owners must also have the CREATEDB privilege. The current database cannot be renamed. (Connect to a different database if you need to do that.)

The third form changes the owner of the database. To alter the owner, you must own the database and also be a direct or indirect member of the new owning role, and you must have the CREATEDB privilege. (Note that superusers have all these privileges automatically.)

The fourth form changes the default tablespace of the database. Only the database owner or a superuser can do this; you must also have create privilege for the new tablespace. This command physically moves any tables or indexes in the database's old default tablespace to the new tablespace. The new default tablespace must be empty for this database, and no one can be connected to the database. Tables and indexes in non-default tablespaces are unaffected.

The remaining forms change the session default for a run-time configuration variable for a PostgreSQL database. Whenever a new session is subsequently started in that database, the specified value becomes the session default value. The database-specific default overrides whatever setting is present in postgresql.conf or has been received from the postgres command line. Only the database owner or a superuser can change the session defaults for a database. Certain variables cannot be set this way, or can only be set by a superuser.

## PARAMETERS
name

The name of the database whose attributes are to be altered.

allowconn

If false then no one can connect to this database.

connlimit

How many concurrent connections can be made to this database. -1 means no limit.

istemplate

If true, then this database can be cloned by any user with CREATEDB privileges; if false, then only superusers or the owner of the database can clone it.

new_name

The new name of the database.

new_owner

The new owner of the database.

new_tablespace

The new default tablespace of the database. This form of the command cannot be executed inside a transaction block.

configuration_parameter

value

Set this database's session default for the specified configuration parameter to the given value. If value is DEFAULT or, equivalently, RESET is used, the database-specific setting is removed, so the system-wide default setting will be inherited in new sessions. Use RESET ALL to clear all database-specific settings. SET FROM CURRENT saves the session's current value of the parameter as the database-specific value. See SET(7) and Chapter 19 for more information about allowed parameter names and values.

## NOTES
It is also possible to tie a session default to a specific role rather than to a database; see ALTER ROLE (ALTER_ROLE(7)). Role-specific settings override database-specific ones if there is a conflict.

## EXAMPLES
To disable index scans by default in the database test:

```
ALTER DATABASE test SET enable_indexscan TO off;
```

## COMPATIBILITY
The ALTER DATABASE statement is a PostgreSQL extension.

## SEE ALSO
CREATE DATABASE (CREATE_DATABASE(7)), DROP DATABASE (DROP_DATABASE(7)), SET(7), CREATE TABLESPACE (CREATE_TABLESPACE(7))


title: ALTER_DEFAULT_PRIVILEGES(7)

summary: define default access privileges

text:
# ALTER_DEFAULT_PRIVILEGES(7)

## NAME
ALTER_DEFAULT_PRIVILEGES - define default access privileges

## SYNOPSIS

```
ALTER DEFAULT PRIVILEGES

    [ FOR { ROLE | USER } target_role [, ...] ]

    [ IN SCHEMA schema_name [, ...] ]

    abbreviated_grant_or_revoke
where abbreviated_grant_or_revoke is one of:
GRANT { { SELECT | INSERT | UPDATE | DELETE | TRUNCATE | REFERENCES | TRIGGER }

    [, ...] | ALL [ PRIVILEGES ] }

    ON TABLES

    TO { [ GROUP ] role_name | PUBLIC } [, ...] [ WITH GRANT OPTION ]
GRANT { { USAGE | SELECT | UPDATE }

    [, ...] | ALL [ PRIVILEGES ] }

    ON SEQUENCES

    TO { [ GROUP ] role_name | PUBLIC } [, ...] [ WITH GRANT OPTION ]
GRANT { EXECUTE | ALL [ PRIVILEGES ] }

    ON { FUNCTIONS | ROUTINES }

    TO { [ GROUP ] role_name | PUBLIC } [, ...] [ WITH GRANT OPTION ]
GRANT { USAGE | ALL [ PRIVILEGES ] }

    ON TYPES

    TO { [ GROUP ] role_name | PUBLIC } [, ...] [ WITH GRANT OPTION ]
GRANT { { USAGE | CREATE }

    [, ...] | ALL [ PRIVILEGES ] }

    ON SCHEMAS

    TO { [ GROUP ] role_name | PUBLIC } [, ...] [ WITH GRANT OPTION ]
REVOKE [ GRANT OPTION FOR ]

    { { SELECT | INSERT | UPDATE | DELETE | TRUNCATE | REFERENCES | TRIGGER }

    [, ...] | ALL [ PRIVILEGES ] }

    ON TABLES

    FROM { [ GROUP ] role_name | PUBLIC } [, ...]

    [ CASCADE | RESTRICT ]
REVOKE [ GRANT OPTION FOR ]

    { { USAGE | SELECT | UPDATE }

    [, ...] | ALL [ PRIVILEGES ] }

    ON SEQUENCES

    FROM { [ GROUP ] role_name | PUBLIC } [, ...]

    [ CASCADE | RESTRICT ]
REVOKE [ GRANT OPTION FOR ]

    { EXECUTE | ALL [ PRIVILEGES ] }

    ON { FUNCTIONS | ROUTINES }

    FROM { [ GROUP ] role_name | PUBLIC } [, ...]

    [ CASCADE | RESTRICT ]
REVOKE [ GRANT OPTION FOR ]

    { USAGE | ALL [ PRIVILEGES ] }

    ON TYPES

    FROM { [ GROUP ] role_name | PUBLIC } [, ...]

    [ CASCADE | RESTRICT ]
REVOKE [ GRANT OPTION FOR ]

    { { USAGE | CREATE }

    [, ...] | ALL [ PRIVILEGES ] }

    ON SCHEMAS

    FROM { [ GROUP ] role_name | PUBLIC } [, ...]

    [ CASCADE | RESTRICT ]
```

## DESCRIPTION
ALTER DEFAULT PRIVILEGES allows you to set the privileges that will be applied to objects created in the future. (It does not affect privileges assigned to already-existing objects.) Currently, only the privileges for schemas, tables (including views and foreign tables), sequences, functions, and types (including domains) can be altered. For this command, functions include aggregates and procedures. The words FUNCTIONS and ROUTINES are equivalent in this command. (ROUTINES is preferred going forward as the standard term for functions and procedures taken together. In earlier PostgreSQL releases, only the word FUNCTIONS was allowed. It is not possible to set default privileges for functions and procedures separately.)

You can change default privileges only for objects that will be created by yourself or by roles that you are a member of. The privileges can be set globally (i.e., for all objects created in the current database), or just for objects created in specified schemas.

As explained in Section 5.7, the default privileges for any object type normally grant all grantable permissions to the object owner, and may grant some privileges to PUBLIC as well. However, this behavior can be changed by altering the global default privileges with ALTER DEFAULT PRIVILEGES.

Default privileges that are specified per-schema are added to whatever the global default privileges are for the particular object type. This means you cannot revoke privileges per-schema if they are granted globally (either by default, or according to a previous ALTER DEFAULT PRIVILEGES command that did not specify a schema). Per-schema REVOKE is only useful to reverse the effects of a previous per-schema GRANT.

### Parameters
target_role

The name of an existing role of which the current role is a member. Default access privileges are not inherited, so member roles must use SET ROLE to access these privileges, or ALTER DEFAULT PRIVILEGES must be run for each member role. If FOR ROLE is omitted, the current role is assumed.

schema_name

The name of an existing schema. If specified, the default privileges are altered for objects later created in that schema. If IN SCHEMA is omitted, the global default privileges are altered. IN SCHEMA is not allowed when setting privileges for schemas, since schemas can't be nested.

role_name

The name of an existing role to grant or revoke privileges for. This parameter, and all the other parameters in abbreviated_grant_or_revoke, act as described under GRANT(7) or REVOKE(7), except that one is setting permissions for a whole class of objects rather than specific named objects.

## NOTES
Use psql(1)'s \ddp command to obtain information about existing assignments of default privileges. The meaning of the privilege display is the same as explained for \dp in Section 5.7.

If you wish to drop a role for which the default privileges have been altered, it is necessary to reverse the changes in its default privileges or use DROP OWNED BY to get rid of the default privileges entry for the role.

## EXAMPLES
Grant SELECT privilege to everyone for all tables (and views) you subsequently create in schema myschema, and allow role webuser to INSERT into them too:

```
ALTER DEFAULT PRIVILEGES IN SCHEMA myschema GRANT SELECT ON TABLES TO PUBLIC;
ALTER DEFAULT PRIVILEGES IN SCHEMA myschema GRANT INSERT ON TABLES TO webuser;
```

Undo the above, so that subsequently-created tables won't have any more permissions than normal:

```
ALTER DEFAULT PRIVILEGES IN SCHEMA myschema REVOKE SELECT ON TABLES FROM PUBLIC;
ALTER DEFAULT PRIVILEGES IN SCHEMA myschema REVOKE INSERT ON TABLES FROM webuser;
```

Remove the public EXECUTE permission that is normally granted on functions, for all functions subsequently created by role admin:

```
ALTER DEFAULT PRIVILEGES FOR ROLE admin REVOKE EXECUTE ON FUNCTIONS FROM PUBLIC;
```

Note however that you cannot accomplish that effect with a command limited to a single schema. This command has no effect, unless it is undoing a matching GRANT:

```
ALTER DEFAULT PRIVILEGES IN SCHEMA public REVOKE EXECUTE ON FUNCTIONS FROM PUBLIC;
```

That's because per-schema default privileges can only add privileges to the global setting, not remove privileges granted by it.

## COMPATIBILITY
There is no ALTER DEFAULT PRIVILEGES statement in the SQL standard.

## SEE ALSO
GRANT(7), REVOKE(7)


title: ALTER_DOMAIN(7)

summary: change the definition of a domain

text:
# ALTER_DOMAIN(7)

## NAME
ALTER_DOMAIN - change the definition of a domain

## SYNOPSIS

```
ALTER DOMAIN name

    { SET DEFAULT expression | DROP DEFAULT }
ALTER DOMAIN name

    { SET | DROP } NOT NULL
ALTER DOMAIN name

    ADD domain_constraint [ NOT VALID ]
ALTER DOMAIN name

    DROP CONSTRAINT [ IF EXISTS ] constraint_name [ RESTRICT | CASCADE ]
ALTER DOMAIN name

     RENAME CONSTRAINT constraint_name TO new_constraint_name
ALTER DOMAIN name

    VALIDATE CONSTRAINT constraint_name
ALTER DOMAIN name

    OWNER TO { new_owner | CURRENT_USER | SESSION_USER }
ALTER DOMAIN name

    RENAME TO new_name
ALTER DOMAIN name

    SET SCHEMA new_schema
where domain_constraint is:
[ CONSTRAINT constraint_name ]
{ NOT NULL | CHECK (expression) }
```

## DESCRIPTION
ALTER DOMAIN changes the definition of an existing domain. There are several sub-forms:

SET/DROP DEFAULT

These forms set or remove the default value for a domain. Note that defaults only apply to subsequent INSERT commands; they do not affect rows already in a table using the domain.

SET/DROP NOT NULL

These forms change whether a domain is marked to allow NULL values or to reject NULL values. You can only SET NOT NULL when the columns using the domain contain no null values.

ADD domain_constraint [ NOT VALID ]

This form adds a new constraint to a domain. When a new constraint is added to a domain, all columns using that domain will be checked against the newly added constraint. These checks can be suppressed by adding the new constraint using the NOT VALID option; the constraint can later be made valid using ALTER DOMAIN ... VALIDATE CONSTRAINT. Newly inserted or updated rows are always checked against all constraints, even those marked NOT VALID. NOT VALID is only accepted for CHECK constraints.

DROP CONSTRAINT [ IF EXISTS ]

This form drops constraints on a domain. If IF EXISTS is specified and the constraint does not exist, no error is thrown. In this case a notice is issued instead.

RENAME CONSTRAINT

This form changes the name of a constraint on a domain.

VALIDATE CONSTRAINT

This form validates a constraint previously added as NOT VALID, that is, it verifies that all values in table columns of the domain type satisfy the specified constraint.

OWNER

This form changes the owner of the domain to the specified user.

RENAME

This form changes the name of the domain.

SET SCHEMA

This form changes the schema of the domain. Any constraints associated with the domain are moved into the new schema as well.

You must own the domain to use ALTER DOMAIN. To change the schema of a domain, you must also have CREATE privilege on the new schema. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have CREATE privilege on the domain's schema. (These restrictions enforce that altering the owner doesn't do anything you couldn't do by dropping and recreating the domain. However, a superuser can alter ownership of any domain anyway.)

## PARAMETERS
name

The name (possibly schema-qualified) of an existing domain to alter.

domain_constraint

New domain constraint for the domain.

constraint_name

Name of an existing constraint to drop or rename.

NOT VALID

Do not verify existing stored data for constraint validity.

CASCADE

Automatically drop objects that depend on the constraint, and in turn all objects that depend on those objects (see Section 5.14).

RESTRICT

Refuse to drop the constraint if there are any dependent objects. This is the default behavior.

new_name

The new name for the domain.

new_constraint_name

The new name for the constraint.

new_owner

The user name of the new owner of the domain.

new_schema

The new schema for the domain.

## NOTES
Although ALTER DOMAIN ADD CONSTRAINT attempts to verify that existing stored data satisfies the new constraint, this check is not bulletproof, because the command cannot “see” table rows that are newly inserted or updated and not yet committed. If there is a hazard that concurrent operations might insert bad data, the way to proceed is to add the constraint using the NOT VALID option, commit that command, wait until all transactions started before that commit have finished, and then issue ALTER DOMAIN VALIDATE CONSTRAINT to search for data violating the constraint. This method is reliable because once the constraint is committed, all new transactions are guaranteed to enforce it against new values of the domain type.

Currently, ALTER DOMAIN ADD CONSTRAINT, ALTER DOMAIN VALIDATE CONSTRAINT, and ALTER DOMAIN SET NOT NULL will fail if the named domain or any derived domain is used within a container-type column (a composite, array, or range column) in any table in the database. They should eventually be improved to be able to verify the new constraint for such nested values.

## EXAMPLES
To add a NOT NULL constraint to a domain:

```
ALTER DOMAIN zipcode SET NOT NULL;
```

To remove a NOT NULL constraint from a domain:

```
ALTER DOMAIN zipcode DROP NOT NULL;
```

To add a check constraint to a domain:

```
ALTER DOMAIN zipcode ADD CONSTRAINT zipchk CHECK (char_length(VALUE) = 5);
```

To remove a check constraint from a domain:

```
ALTER DOMAIN zipcode DROP CONSTRAINT zipchk;
```

To rename a check constraint on a domain:

```
ALTER DOMAIN zipcode RENAME CONSTRAINT zipchk TO zip_check;
```

To move the domain into a different schema:

```
ALTER DOMAIN zipcode SET SCHEMA customers;
```

## COMPATIBILITY
ALTER DOMAIN conforms to the SQL standard, except for the OWNER, RENAME, SET SCHEMA, and VALIDATE CONSTRAINT variants, which are PostgreSQL extensions. The NOT VALID clause of the ADD CONSTRAINT variant is also a PostgreSQL extension.

## SEE ALSO
CREATE DOMAIN (CREATE_DOMAIN(7)), DROP DOMAIN (DROP_DOMAIN(7))


title: ALTER_EVENT_TRIGGER(7)

text:
# ALTER_EVENT_TRIGGER(7)

## NAME
ALTER_EVENT_TRIGGER - change the definition of an event trigger

## SYNOPSIS

```
ALTER EVENT TRIGGER name DISABLE
ALTER EVENT TRIGGER name ENABLE [ REPLICA | ALWAYS ]
ALTER EVENT TRIGGER name OWNER TO { new_owner | CURRENT_USER | SESSION_USER }
ALTER EVENT TRIGGER name RENAME TO new_name
```

## DESCRIPTION
ALTER EVENT TRIGGER changes properties of an existing event trigger.

You must be superuser to alter an event trigger.

## PARAMETERS
name

The name of an existing trigger to alter.

new_owner

The user name of the new owner of the event trigger.

new_name

The new name of the event trigger.

DISABLE/ENABLE [ REPLICA | ALWAYS ]

These forms configure the firing of event triggers. A disabled trigger is still known to the system, but is not executed when its triggering event occurs. See also session_replication_role.

## COMPATIBILITY
There is no ALTER EVENT TRIGGER statement in the SQL standard.

## SEE ALSO
CREATE EVENT TRIGGER (CREATE_EVENT_TRIGGER(7)), DROP EVENT TRIGGER (DROP_EVENT_TRIGGER(7))


title: ALTER_EXTENSION(7)

summary: change the definition of an extension

text:
# ALTER_EXTENSION(7)

## NAME
ALTER_EXTENSION - change the definition of an extension

## SYNOPSIS

```
ALTER EXTENSION name UPDATE [ TO new_version ]
ALTER EXTENSION name SET SCHEMA new_schema
ALTER EXTENSION name ADD member_object
ALTER EXTENSION name DROP member_object
where member_object is:

  ACCESS METHOD object_name |

  AGGREGATE aggregate_name ( aggregate_signature ) |

  CAST (source_type AS target_type) |

  COLLATION object_name |

  CONVERSION object_name |

  DOMAIN object_name |

  EVENT TRIGGER object_name |

  FOREIGN DATA WRAPPER object_name |

  FOREIGN TABLE object_name |

  FUNCTION function_name [ ( [ [ argmode ] [ argname ] argtype [, ...] ] ) ] |

  MATERIALIZED VIEW object_name |

  OPERATOR operator_name (left_type, right_type) |

  OPERATOR CLASS object_name USING index_method |

  OPERATOR FAMILY object_name USING index_method |

  [ PROCEDURAL ] LANGUAGE object_name |

  PROCEDURE procedure_name [ ( [ [ argmode ] [ argname ] argtype [, ...] ] ) ] |

  ROUTINE routine_name [ ( [ [ argmode ] [ argname ] argtype [, ...] ] ) ] |

  SCHEMA object_name |

  SEQUENCE object_name |

  SERVER object_name |

  TABLE object_name |

  TEXT SEARCH CONFIGURATION object_name |

  TEXT SEARCH DICTIONARY object_name |

  TEXT SEARCH PARSER object_name |

  TEXT SEARCH TEMPLATE object_name |

  TRANSFORM FOR type_name LANGUAGE lang_name |

  TYPE object_name |

  VIEW object_name
and aggregate_signature is:
* |
[ argmode ] [ argname ] argtype [ , ... ] |
[ [ argmode ] [ argname ] argtype [ , ... ] ] ORDER BY [ argmode ] [ argname ] argtype [ , ... ]
```

## DESCRIPTION
ALTER EXTENSION changes the definition of an installed extension. There are several subforms:

UPDATE

This form updates the extension to a newer version. The extension must supply a suitable update script (or series of scripts) that can modify the currently-installed version into the requested version.

SET SCHEMA

This form moves the extension's objects into another schema. The extension has to be relocatable for this command to succeed.

ADD member_object

This form adds an existing object to the extension. This is mainly useful in extension update scripts. The object will subsequently be treated as a member of the extension; notably, it can only be dropped by dropping the extension.

DROP member_object

This form removes a member object from the extension. This is mainly useful in extension update scripts. The object is not dropped, only disassociated from the extension.

See Section 37.17 for more information about these operations. You must own the extension to use ALTER EXTENSION. The ADD/DROP forms require ownership of the added/dropped object as well.

## PARAMETERS
name

The name of an installed extension.

new_version

The desired new version of the extension. This can be written as either an identifier or a string literal. If not specified, ALTER EXTENSION UPDATE attempts to update to whatever is shown as the default version in the extension's control file.

new_schema

The new schema for the extension.

object_name

aggregate_name

function_name

operator_name

procedure_name

routine_name

The name of an object to be added to or removed from the extension. Names of tables, aggregates, domains, foreign tables, functions, operators, operator classes, operator families, procedures, routines, sequences, text search objects, types, and views can be schema-qualified.

source_type

The name of the source data type of the cast.

target_type

The name of the target data type of the cast.

argmode

The mode of a function, procedure, or aggregate argument: IN, OUT, INOUT, or VARIADIC. If omitted, the default is IN. Note that ALTER EXTENSION does not actually pay any attention to OUT arguments, since only the input arguments are needed to determine the function's identity. So it is sufficient to list the IN, INOUT, and VARIADIC arguments.

argname

The name of a function, procedure, or aggregate argument. Note that ALTER EXTENSION does not actually pay any attention to argument names, since only the argument data types are needed to determine the function's identity.

argtype

The data type of a function, procedure, or aggregate argument.

left_type

right_type

The data type(s) of the operator's arguments (optionally schema-qualified). Write NONE for the missing argument of a prefix or postfix operator.

PROCEDURAL

This is a noise word.

type_name

The name of the data type of the transform.

lang_name

The name of the language of the transform.

## EXAMPLES
To update the hstore extension to version 2.0:

```
ALTER EXTENSION hstore UPDATE TO '2.0';
```

To change the schema of the hstore extension to utils:

```
ALTER EXTENSION hstore SET SCHEMA utils;
```

To add an existing function to the hstore extension:

```
ALTER EXTENSION hstore ADD FUNCTION populate_record(anyelement, hstore);
```

## COMPATIBILITY
ALTER EXTENSION is a PostgreSQL extension.

## SEE ALSO
CREATE EXTENSION (CREATE_EXTENSION(7)), DROP EXTENSION (DROP_EXTENSION(7))


title: ALTER_FOREIGN_DATA_WRAPPER(7)

summary: change the definition of a foreign\-data wrapper

text:
# ALTER_FOREIGN_DATA_WRAPPER(7)

## NAME
ALTER_FOREIGN_DATA_WRAPPER - change the definition of a foreign-data wrapper

## SYNOPSIS

```
ALTER FOREIGN DATA WRAPPER name

    [ HANDLER handler_function | NO HANDLER ]

    [ VALIDATOR validator_function | NO VALIDATOR ]

    [ OPTIONS ( [ ADD | SET | DROP ] option ['value'] [, ... ]) ]
ALTER FOREIGN DATA WRAPPER name OWNER TO { new_owner | CURRENT_USER | SESSION_USER }
ALTER FOREIGN DATA WRAPPER name RENAME TO new_name
```

## DESCRIPTION
ALTER FOREIGN DATA WRAPPER changes the definition of a foreign-data wrapper. The first form of the command changes the support functions or the generic options of the foreign-data wrapper (at least one clause is required). The second form changes the owner of the foreign-data wrapper.

Only superusers can alter foreign-data wrappers. Additionally, only superusers can own foreign-data wrappers.

## PARAMETERS
name

The name of an existing foreign-data wrapper.

HANDLER handler_function

Specifies a new handler function for the foreign-data wrapper.

NO HANDLER

This is used to specify that the foreign-data wrapper should no longer have a handler function. Note that foreign tables that use a foreign-data wrapper with no handler cannot be accessed.

VALIDATOR validator_function

Specifies a new validator function for the foreign-data wrapper. Note that it is possible that pre-existing options of the foreign-data wrapper, or of dependent servers, user mappings, or foreign tables, are invalid according to the new validator. PostgreSQL does not check for this. It is up to the user to make sure that these options are correct before using the modified foreign-data wrapper. However, any options specified in this ALTER FOREIGN DATA WRAPPER command will be checked using the new validator.

NO VALIDATOR

This is used to specify that the foreign-data wrapper should no longer have a validator function.

OPTIONS ( [ ADD | SET | DROP ] option ['value'] [, ... ] )

Change options for the foreign-data wrapper. ADD, SET, and DROP specify the action to be performed. ADD is assumed if no operation is explicitly specified. Option names must be unique; names and values are also validated using the foreign data wrapper's validator function, if any.

new_owner

The user name of the new owner of the foreign-data wrapper.

new_name

The new name for the foreign-data wrapper.

## EXAMPLES
Change a foreign-data wrapper dbi, add option foo, drop bar:

```
ALTER FOREIGN DATA WRAPPER dbi OPTIONS (ADD foo '1', DROP bar);
```

Change the foreign-data wrapper dbi validator to bob.myvalidator:

```
ALTER FOREIGN DATA WRAPPER dbi VALIDATOR bob.myvalidator;
```

## COMPATIBILITY
ALTER FOREIGN DATA WRAPPER conforms to ISO/IEC 9075-9 (SQL/MED), except that the HANDLER, VALIDATOR, OWNER TO, and RENAME clauses are extensions.

## SEE ALSO
CREATE FOREIGN DATA WRAPPER (CREATE_FOREIGN_DATA_WRAPPER(7)), DROP FOREIGN DATA WRAPPER (DROP_FOREIGN_DATA_WRAPPER(7))


title: ALTER_FOREIGN_TABLE(7)

text:
# ALTER_FOREIGN_TABLE(7)

## NAME
ALTER_FOREIGN_TABLE - change the definition of a foreign table

## SYNOPSIS

```
ALTER FOREIGN TABLE [ IF EXISTS ] [ ONLY ] name [ * ]

    action [, ... ]
ALTER FOREIGN TABLE [ IF EXISTS ] [ ONLY ] name [ * ]

    RENAME [ COLUMN ] column_name TO new_column_name
ALTER FOREIGN TABLE [ IF EXISTS ] name

    RENAME TO new_name
ALTER FOREIGN TABLE [ IF EXISTS ] name

    SET SCHEMA new_schema
where action is one of:

    ADD [ COLUMN ] column_name data_type [ COLLATE collation ] [ column_constraint [ ... ] ]

    DROP [ COLUMN ] [ IF EXISTS ] column_name [ RESTRICT | CASCADE ]

    ALTER [ COLUMN ] column_name [ SET DATA ] TYPE data_type [ COLLATE collation ]

    ALTER [ COLUMN ] column_name SET DEFAULT expression

    ALTER [ COLUMN ] column_name DROP DEFAULT

    ALTER [ COLUMN ] column_name { SET | DROP } NOT NULL

    ALTER [ COLUMN ] column_name SET STATISTICS integer

    ALTER [ COLUMN ] column_name SET ( attribute_option = value [, ... ] )

    ALTER [ COLUMN ] column_name RESET ( attribute_option [, ... ] )

    ALTER [ COLUMN ] column_name SET STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN }

    ALTER [ COLUMN ] column_name OPTIONS ( [ ADD | SET | DROP ] option ['value'] [, ... ])

    ADD table_constraint [ NOT VALID ]

    VALIDATE CONSTRAINT constraint_name

    DROP CONSTRAINT [ IF EXISTS ]  constraint_name [ RESTRICT | CASCADE ]

    DISABLE TRIGGER [ trigger_name | ALL | USER ]

    ENABLE TRIGGER [ trigger_name | ALL | USER ]

    ENABLE REPLICA TRIGGER trigger_name

    ENABLE ALWAYS TRIGGER trigger_name

    SET WITHOUT OIDS

    INHERIT parent_table

    NO INHERIT parent_table

    OWNER TO { new_owner | CURRENT_USER | SESSION_USER }

    OPTIONS ( [ ADD | SET | DROP ] option ['value'] [, ... ])
```

## DESCRIPTION
ALTER FOREIGN TABLE changes the definition of an existing foreign table. There are several subforms:

ADD COLUMN

This form adds a new column to the foreign table, using the same syntax as CREATE FOREIGN TABLE (CREATE_FOREIGN_TABLE(7)). Unlike the case when adding a column to a regular table, nothing happens to the underlying storage: this action simply declares that some new column is now accessible through the foreign table.

DROP COLUMN [ IF EXISTS ]

This form drops a column from a foreign table. You will need to say CASCADE if anything outside the table depends on the column; for example, views. If IF EXISTS is specified and the column does not exist, no error is thrown. In this case a notice is issued instead.

SET DATA TYPE

This form changes the type of a column of a foreign table. Again, this has no effect on any underlying storage: this action simply changes the type that PostgreSQL believes the column to have.

SET/DROP DEFAULT

These forms set or remove the default value for a column. Default values only apply in subsequent INSERT or UPDATE commands; they do not cause rows already in the table to change.

SET/DROP NOT NULL

Mark a column as allowing, or not allowing, null values.

SET STATISTICS

This form sets the per-column statistics-gathering target for subsequent ANALYZE(7) operations. See the similar form of ALTER TABLE (ALTER_TABLE(7)) for more details.

SET ( attribute_option = value [, ... ] )

RESET ( attribute_option [, ... ] )

This form sets or resets per-attribute options. See the similar form of ALTER TABLE (ALTER_TABLE(7)) for more details.

SET STORAGE

This form sets the storage mode for a column. See the similar form of ALTER TABLE (ALTER_TABLE(7)) for more details. Note that the storage mode has no effect unless the table's foreign-data wrapper chooses to pay attention to it.

ADD table_constraint [ NOT VALID ]

This form adds a new constraint to a foreign table, using the same syntax as CREATE FOREIGN TABLE (CREATE_FOREIGN_TABLE(7)). Currently only CHECK constraints are supported. Unlike the case when adding a constraint to a regular table, nothing is done to verify the constraint is correct; rather, this action simply declares that some new condition should be assumed to hold for all rows in the foreign table. (See the discussion in CREATE FOREIGN TABLE (CREATE_FOREIGN_TABLE(7)).) If the constraint is marked NOT VALID, then it isn't assumed to hold, but is only recorded for possible future use.

VALIDATE CONSTRAINT

This form marks as valid a constraint that was previously marked as NOT VALID. No action is taken to verify the constraint, but future queries will assume that it holds.

DROP CONSTRAINT [ IF EXISTS ]

This form drops the specified constraint on a foreign table. If IF EXISTS is specified and the constraint does not exist, no error is thrown. In this case a notice is issued instead.

DISABLE/ENABLE [ REPLICA | ALWAYS ] TRIGGER

These forms configure the firing of trigger(s) belonging to the foreign table. See the similar form of ALTER TABLE (ALTER_TABLE(7)) for more details.

SET WITHOUT OIDS

Backward compatibility syntax for removing the oid system column. As oid system columns cannot be added anymore, this never has an effect.

INHERIT parent_table

This form adds the target foreign table as a new child of the specified parent table. See the similar form of ALTER TABLE (ALTER_TABLE(7)) for more details.

NO INHERIT parent_table

This form removes the target foreign table from the list of children of the specified parent table.

OWNER

This form changes the owner of the foreign table to the specified user.

OPTIONS ( [ ADD | SET | DROP ] option ['value'] [, ... ] )

Change options for the foreign table or one of its columns. ADD, SET, and DROP specify the action to be performed. ADD is assumed if no operation is explicitly specified. Duplicate option names are not allowed (although it's OK for a table option and a column option to have the same name). Option names and values are also validated using the foreign data wrapper library.

RENAME

The RENAME forms change the name of a foreign table or the name of an individual column in a foreign table.

SET SCHEMA

This form moves the foreign table into another schema.

All the actions except RENAME and SET SCHEMA can be combined into a list of multiple alterations to apply in parallel. For example, it is possible to add several columns and/or alter the type of several columns in a single command.

If the command is written as ALTER FOREIGN TABLE IF EXISTS ... and the foreign table does not exist, no error is thrown. A notice is issued in this case.

You must own the table to use ALTER FOREIGN TABLE. To change the schema of a foreign table, you must also have CREATE privilege on the new schema. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have CREATE privilege on the table's schema. (These restrictions enforce that altering the owner doesn't do anything you couldn't do by dropping and recreating the table. However, a superuser can alter ownership of any table anyway.) To add a column or alter a column type, you must also have USAGE privilege on the data type.

## PARAMETERS
name

The name (possibly schema-qualified) of an existing foreign table to alter. If ONLY is specified before the table name, only that table is altered. If ONLY is not specified, the table and all its descendant tables (if any) are altered. Optionally, * can be specified after the table name to explicitly indicate that descendant tables are included.

column_name

Name of a new or existing column.

new_column_name

New name for an existing column.

new_name

New name for the table.

data_type

Data type of the new column, or new data type for an existing column.

table_constraint

New table constraint for the foreign table.

constraint_name

Name of an existing constraint to drop.

CASCADE

Automatically drop objects that depend on the dropped column or constraint (for example, views referencing the column), and in turn all objects that depend on those objects (see Section 5.14).

RESTRICT

Refuse to drop the column or constraint if there are any dependent objects. This is the default behavior.

trigger_name

Name of a single trigger to disable or enable.

ALL

Disable or enable all triggers belonging to the foreign table. (This requires superuser privilege if any of the triggers are internally generated triggers. The core system does not add such triggers to foreign tables, but add-on code could do so.)

USER

Disable or enable all triggers belonging to the foreign table except for internally generated triggers.

parent_table

A parent table to associate or de-associate with this foreign table.

new_owner

The user name of the new owner of the table.

new_schema

The name of the schema to which the table will be moved.

## NOTES
The key word COLUMN is noise and can be omitted.

Consistency with the foreign server is not checked when a column is added or removed with ADD COLUMN or DROP COLUMN, a NOT NULL or CHECK constraint is added, or a column type is changed with SET DATA TYPE. It is the user's responsibility to ensure that the table definition matches the remote side.

Refer to CREATE FOREIGN TABLE (CREATE_FOREIGN_TABLE(7)) for a further description of valid parameters.

## EXAMPLES
To mark a column as not-null:

```
ALTER FOREIGN TABLE distributors ALTER COLUMN street SET NOT NULL;
```

To change options of a foreign table:

```
ALTER FOREIGN TABLE myschema.distributors OPTIONS (ADD opt1 'value', SET opt2 'value2', DROP opt3);
```

## COMPATIBILITY
The forms ADD, DROP, and SET DATA TYPE conform with the SQL standard. The other forms are PostgreSQL extensions of the SQL standard. Also, the ability to specify more than one manipulation in a single ALTER FOREIGN TABLE command is an extension.

ALTER FOREIGN TABLE DROP COLUMN can be used to drop the only column of a foreign table, leaving a zero-column table. This is an extension of SQL, which disallows zero-column foreign tables.

## SEE ALSO
CREATE FOREIGN TABLE (CREATE_FOREIGN_TABLE(7)), DROP FOREIGN TABLE (DROP_FOREIGN_TABLE(7))


title: ALTER_FUNCTION(7)

summary: change the definition of a function

text:
# ALTER_FUNCTION(7)

## NAME
ALTER_FUNCTION - change the definition of a function

## SYNOPSIS

```
ALTER FUNCTION name [ ( [ [ argmode ] [ argname ] argtype [, ...] ] ) ]

    action [ ... ] [ RESTRICT ]
ALTER FUNCTION name [ ( [ [ argmode ] [ argname ] argtype [, ...] ] ) ]

    RENAME TO new_name
ALTER FUNCTION name [ ( [ [ argmode ] [ argname ] argtype [, ...] ] ) ]

    OWNER TO { new_owner | CURRENT_USER | SESSION_USER }
ALTER FUNCTION name [ ( [ [ argmode ] [ argname ] argtype [, ...] ] ) ]

    SET SCHEMA new_schema
ALTER FUNCTION name [ ( [ [ argmode ] [ argname ] argtype [, ...] ] ) ]

    [ NO ] DEPENDS ON EXTENSION extension_name
where action is one of:

    CALLED ON NULL INPUT | RETURNS NULL ON NULL INPUT | STRICT

    IMMUTABLE | STABLE | VOLATILE

    [ NOT ] LEAKPROOF

    [ EXTERNAL ] SECURITY INVOKER | [ EXTERNAL ] SECURITY DEFINER

    PARALLEL { UNSAFE | RESTRICTED | SAFE }

    COST execution_cost

    ROWS result_rows

    SUPPORT support_function

    SET configuration_parameter { TO | = } { value | DEFAULT }

    SET configuration_parameter FROM CURRENT

    RESET configuration_parameter

    RESET ALL
```

## DESCRIPTION
ALTER FUNCTION changes the definition of a function.

You must own the function to use ALTER FUNCTION. To change a function's schema, you must also have CREATE privilege on the new schema. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have CREATE privilege on the function's schema. (These restrictions enforce that altering the owner doesn't do anything you couldn't do by dropping and recreating the function. However, a superuser can alter ownership of any function anyway.)

## PARAMETERS
name

The name (optionally schema-qualified) of an existing function. If no argument list is specified, the name must be unique in its schema.

argmode

The mode of an argument: IN, OUT, INOUT, or VARIADIC. If omitted, the default is IN. Note that ALTER FUNCTION does not actually pay any attention to OUT arguments, since only the input arguments are needed to determine the function's identity. So it is sufficient to list the IN, INOUT, and VARIADIC arguments.

argname

The name of an argument. Note that ALTER FUNCTION does not actually pay any attention to argument names, since only the argument data types are needed to determine the function's identity.

argtype

The data type(s) of the function's arguments (optionally schema-qualified), if any.

new_name

The new name of the function.

new_owner

The new owner of the function. Note that if the function is marked SECURITY DEFINER, it will subsequently execute as the new owner.

new_schema

The new schema for the function.

DEPENDS ON EXTENSION extension_name

NO DEPENDS ON EXTENSION extension_name

This form marks the function as dependent on the extension, or no longer dependent on that extension if NO is specified. A function that's marked as dependent on an extension is dropped when the extension is dropped, even if CASCADE is not specified. A function can depend upon multiple extensions, and will be dropped when any one of those extensions is dropped.

CALLED ON NULL INPUT

RETURNS NULL ON NULL INPUT

STRICT

CALLED ON NULL INPUT changes the function so that it will be invoked when some or all of its arguments are null. RETURNS NULL ON NULL INPUT or STRICT changes the function so that it is not invoked if any of its arguments are null; instead, a null result is assumed automatically. See CREATE FUNCTION (CREATE_FUNCTION(7)) for more information.

IMMUTABLE

STABLE

VOLATILE

Change the volatility of the function to the specified setting. See CREATE FUNCTION (CREATE_FUNCTION(7)) for details.

[ EXTERNAL ] SECURITY INVOKER

[ EXTERNAL ] SECURITY DEFINER

Change whether the function is a security definer or not. The key word EXTERNAL is ignored for SQL conformance. See CREATE FUNCTION (CREATE_FUNCTION(7)) for more information about this capability.

PARALLEL

Change whether the function is deemed safe for parallelism. See CREATE FUNCTION (CREATE_FUNCTION(7)) for details.

LEAKPROOF

Change whether the function is considered leakproof or not. See CREATE FUNCTION (CREATE_FUNCTION(7)) for more information about this capability.

COST execution_cost

Change the estimated execution cost of the function. See CREATE FUNCTION (CREATE_FUNCTION(7)) for more information.

ROWS result_rows

Change the estimated number of rows returned by a set-returning function. See CREATE FUNCTION (CREATE_FUNCTION(7)) for more information.

SUPPORT support_function

Set or change the planner support function to use for this function. See Section 37.11 for details. You must be superuser to use this option. This option cannot be used to remove the support function altogether, since it must name a new support function. Use CREATE OR REPLACE FUNCTION if you need to do that.

configuration_parameter

value

Add or change the assignment to be made to a configuration parameter when the function is called. If value is DEFAULT or, equivalently, RESET is used, the function-local setting is removed, so that the function executes with the value present in its environment. Use RESET ALL to clear all function-local settings. SET FROM CURRENT saves the value of the parameter that is current when ALTER FUNCTION is executed as the value to be applied when the function is entered. See SET(7) and Chapter 19 for more information about allowed parameter names and values.

RESTRICT

Ignored for conformance with the SQL standard.

## EXAMPLES
To rename the function sqrt for type integer to square_root:

```
ALTER FUNCTION sqrt(integer) RENAME TO square_root;
```

To change the owner of the function sqrt for type integer to joe:

```
ALTER FUNCTION sqrt(integer) OWNER TO joe;
```

To change the schema of the function sqrt for type integer to maths:

```
ALTER FUNCTION sqrt(integer) SET SCHEMA maths;
```

To mark the function sqrt for type integer as being dependent on the extension mathlib:

```
ALTER FUNCTION sqrt(integer) DEPENDS ON EXTENSION mathlib;
```

To adjust the search path that is automatically set for a function:

```
ALTER FUNCTION check_password(text) SET search_path = admin, pg_temp;
```

To disable automatic setting of search_path for a function:

```
ALTER FUNCTION check_password(text) RESET search_path;
```

The function will now execute with whatever search path is used by its caller.

## COMPATIBILITY
This statement is partially compatible with the ALTER FUNCTION statement in the SQL standard. The standard allows more properties of a function to be modified, but does not provide the ability to rename a function, make a function a security definer, attach configuration parameter values to a function, or change the owner, schema, or volatility of a function. The standard also requires the RESTRICT key word, which is optional in PostgreSQL.

## SEE ALSO
CREATE FUNCTION (CREATE_FUNCTION(7)), DROP FUNCTION (DROP_FUNCTION(7)), ALTER PROCEDURE (ALTER_PROCEDURE(7)), ALTER ROUTINE (ALTER_ROUTINE(7))


title: ALTER_GROUP(7)

summary: change role name or membership

text:
# ALTER_GROUP(7)

## NAME
ALTER_GROUP - change role name or membership

## SYNOPSIS

```
ALTER GROUP role_specification ADD USER user_name [, ... ]
ALTER GROUP role_specification DROP USER user_name [, ... ]
where role_specification can be:

    role_name

  | CURRENT_USER

  | SESSION_USER
ALTER GROUP group_name RENAME TO new_name
```

## DESCRIPTION
ALTER GROUP changes the attributes of a user group. This is an obsolete command, though still accepted for backwards compatibility, because groups (and users too) have been superseded by the more general concept of roles.

The first two variants add users to a group or remove them from a group. (Any role can play the part of either a “user” or a “group” for this purpose.) These variants are effectively equivalent to granting or revoking membership in the role named as the “group”; so the preferred way to do this is to use GRANT(7) or REVOKE(7).

The third variant changes the name of the group. This is exactly equivalent to renaming the role with ALTER ROLE (ALTER_ROLE(7)).

## PARAMETERS
group_name

The name of the group (role) to modify.

user_name

Users (roles) that are to be added to or removed from the group. The users must already exist; ALTER GROUP does not create or drop users.

new_name

The new name of the group.

## EXAMPLES
Add users to a group:

```
ALTER GROUP staff ADD USER karl, john;
```

Remove a user from a group:

```
ALTER GROUP workers DROP USER beth;
```

## COMPATIBILITY
There is no ALTER GROUP statement in the SQL standard.

## SEE ALSO
GRANT(7), REVOKE(7), ALTER ROLE (ALTER_ROLE(7))


title: ALTER_INDEX(7)

summary: change the definition of an index

text:
# ALTER_INDEX(7)

## NAME
ALTER_INDEX - change the definition of an index

## SYNOPSIS

```
ALTER INDEX [ IF EXISTS ] name RENAME TO new_name
ALTER INDEX [ IF EXISTS ] name SET TABLESPACE tablespace_name
ALTER INDEX name ATTACH PARTITION index_name
ALTER INDEX name [ NO ] DEPENDS ON EXTENSION extension_name
ALTER INDEX [ IF EXISTS ] name SET ( storage_parameter [= value] [, ... ] )
ALTER INDEX [ IF EXISTS ] name RESET ( storage_parameter [, ... ] )
ALTER INDEX [ IF EXISTS ] name ALTER [ COLUMN ] column_number

    SET STATISTICS integer
ALTER INDEX ALL IN TABLESPACE name [ OWNED BY role_name [, ... ] ]

    SET TABLESPACE new_tablespace [ NOWAIT ]
```

## DESCRIPTION
ALTER INDEX changes the definition of an existing index. There are several subforms described below. Note that the lock level required may differ for each subform. An ACCESS EXCLUSIVE lock is held unless explicitly noted. When multiple subcommands are listed, the lock held will be the strictest one required from any subcommand.

RENAME

The RENAME form changes the name of the index. If the index is associated with a table constraint (either UNIQUE, PRIMARY KEY, or EXCLUDE), the constraint is renamed as well. There is no effect on the stored data. Renaming an index acquires a SHARE UPDATE EXCLUSIVE lock.

SET TABLESPACE

This form changes the index's tablespace to the specified tablespace and moves the data file(s) associated with the index to the new tablespace. To change the tablespace of an index, you must own the index and have CREATE privilege on the new tablespace. All indexes in the current database in a tablespace can be moved by using the ALL IN TABLESPACE form, which will lock all indexes to be moved and then move each one. This form also supports OWNED BY, which will only move indexes owned by the roles specified. If the NOWAIT option is specified then the command will fail if it is unable to acquire all of the locks required immediately. Note that system catalogs will not be moved by this command, use ALTER DATABASE or explicit ALTER INDEX invocations instead if desired. See also CREATE TABLESPACE (CREATE_TABLESPACE(7)).

ATTACH PARTITION index_name

Causes the named index (possibly schema-qualified) to become attached to the altered index. The named index must be on a partition of the table containing the index being altered, and have an equivalent definition. An attached index cannot be dropped by itself, and will automatically be dropped if its parent index is dropped.

DEPENDS ON EXTENSION extension_name

NO DEPENDS ON EXTENSION extension_name

This form marks the index as dependent on the extension, or no longer dependent on that extension if NO is specified. An index that's marked as dependent on an extension is automatically dropped when the extension is dropped.

SET ( storage_parameter [= value] [, ... ] )

This form changes one or more index-method-specific storage parameters for the index. See CREATE INDEX (CREATE_INDEX(7)) for details on the available parameters. Note that the index contents will not be modified immediately by this command; depending on the parameter you might need to rebuild the index with REINDEX(7) to get the desired effects.

RESET ( storage_parameter [, ... ] )

This form resets one or more index-method-specific storage parameters to their defaults. As with SET, a REINDEX might be needed to update the index entirely.

ALTER [ COLUMN ] column_number SET STATISTICS integer

This form sets the per-column statistics-gathering target for subsequent ANALYZE(7) operations, though can be used only on index columns that are defined as an expression. Since expressions lack a unique name, we refer to them using the ordinal number of the index column. The target can be set in the range 0 to 10000; alternatively, set it to -1 to revert to using the system default statistics target (default_statistics_target). For more information on the use of statistics by the PostgreSQL query planner, refer to Section 14.2.

## PARAMETERS
IF EXISTS

Do not throw an error if the index does not exist. A notice is issued in this case.

column_number

The ordinal number refers to the ordinal (left-to-right) position of the index column.

name

The name (possibly schema-qualified) of an existing index to alter.

new_name

The new name for the index.

tablespace_name

The tablespace to which the index will be moved.

extension_name

The name of the extension that the index is to depend on.

storage_parameter

The name of an index-method-specific storage parameter.

value

The new value for an index-method-specific storage parameter. This might be a number or a word depending on the parameter.

## NOTES
These operations are also possible using ALTER TABLE (ALTER_TABLE(7)). ALTER INDEX is in fact just an alias for the forms of ALTER TABLE that apply to indexes.

There was formerly an ALTER INDEX OWNER variant, but this is now ignored (with a warning). An index cannot have an owner different from its table's owner. Changing the table's owner automatically changes the index as well.

Changing any part of a system catalog index is not permitted.

## EXAMPLES
To rename an existing index:

```
ALTER INDEX distributors RENAME TO suppliers;
```

To move an index to a different tablespace:

```
ALTER INDEX distributors SET TABLESPACE fasttablespace;
```

To change an index's fill factor (assuming that the index method supports it):

```
ALTER INDEX distributors SET (fillfactor = 75);
REINDEX INDEX distributors;
```

Set the statistics-gathering target for an expression index:

```
CREATE INDEX coord_idx ON measured (x, y, (z + t));
ALTER INDEX coord_idx ALTER COLUMN 3 SET STATISTICS 1000;
```

## COMPATIBILITY
ALTER INDEX is a PostgreSQL extension.

## SEE ALSO
CREATE INDEX (CREATE_INDEX(7)), REINDEX(7)


title: ALTER_LANGUAGE(7)

text:
# ALTER_LANGUAGE(7)

## NAME
ALTER_LANGUAGE - change the definition of a procedural language

## SYNOPSIS

```
ALTER [ PROCEDURAL ] LANGUAGE name RENAME TO new_name
ALTER [ PROCEDURAL ] LANGUAGE name OWNER TO { new_owner | CURRENT_USER | SESSION_USER }
```

## DESCRIPTION
ALTER LANGUAGE changes the definition of a procedural language. The only functionality is to rename the language or assign a new owner. You must be superuser or owner of the language to use ALTER LANGUAGE.

## PARAMETERS
name

Name of a language

new_name

The new name of the language

new_owner

The new owner of the language

## COMPATIBILITY
There is no ALTER LANGUAGE statement in the SQL standard.

## SEE ALSO
CREATE LANGUAGE (CREATE_LANGUAGE(7)), DROP LANGUAGE (DROP_LANGUAGE(7))


title: ALTER_LARGE_OBJECT(7)

summary: change the definition of a large object

text:
# ALTER_LARGE_OBJECT(7)

## NAME
ALTER_LARGE_OBJECT - change the definition of a large object

## SYNOPSIS

```
ALTER LARGE OBJECT large_object_oid OWNER TO { new_owner | CURRENT_USER | SESSION_USER }
```

## DESCRIPTION
ALTER LARGE OBJECT changes the definition of a large object.

You must own the large object to use ALTER LARGE OBJECT. To alter the owner, you must also be a direct or indirect member of the new owning role. (However, a superuser can alter any large object anyway.) Currently, the only functionality is to assign a new owner, so both restrictions always apply.

## PARAMETERS
large_object_oid

OID of the large object to be altered

new_owner

The new owner of the large object

## COMPATIBILITY
There is no ALTER LARGE OBJECT statement in the SQL standard.

## SEE ALSO
Chapter 34


title: ALTER_MATERIALIZED_VIEW(7)

text:
# ALTER_MATERIALIZED_VIEW(7)

## NAME
ALTER_MATERIALIZED_VIEW - change the definition of a materialized view

## SYNOPSIS

```
ALTER MATERIALIZED VIEW [ IF EXISTS ] name

    action [, ... ]
ALTER MATERIALIZED VIEW name

    [ NO ] DEPENDS ON EXTENSION extension_name
ALTER MATERIALIZED VIEW [ IF EXISTS ] name

    RENAME [ COLUMN ] column_name TO new_column_name
ALTER MATERIALIZED VIEW [ IF EXISTS ] name

    RENAME TO new_name
ALTER MATERIALIZED VIEW [ IF EXISTS ] name

    SET SCHEMA new_schema
ALTER MATERIALIZED VIEW ALL IN TABLESPACE name [ OWNED BY role_name [, ... ] ]

    SET TABLESPACE new_tablespace [ NOWAIT ]
where action is one of:

    ALTER [ COLUMN ] column_name SET STATISTICS integer

    ALTER [ COLUMN ] column_name SET ( attribute_option = value [, ... ] )

    ALTER [ COLUMN ] column_name RESET ( attribute_option [, ... ] )

    ALTER [ COLUMN ] column_name SET STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN }

    CLUSTER ON index_name

    SET WITHOUT CLUSTER

    SET TABLESPACE new_tablespace

    SET ( storage_parameter [= value] [, ... ] )

    RESET ( storage_parameter [, ... ] )

    OWNER TO { new_owner | CURRENT_USER | SESSION_USER }
```

## DESCRIPTION
ALTER MATERIALIZED VIEW changes various auxiliary properties of an existing materialized view.

You must own the materialized view to use ALTER MATERIALIZED VIEW. To change a materialized view's schema, you must also have CREATE privilege on the new schema. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have CREATE privilege on the materialized view's schema. (These restrictions enforce that altering the owner doesn't do anything you couldn't do by dropping and recreating the materialized view. However, a superuser can alter ownership of any view anyway.)

The statement subforms and actions available for ALTER MATERIALIZED VIEW are a subset of those available for ALTER TABLE, and have the same meaning when used for materialized views. See the descriptions for ALTER TABLE (ALTER_TABLE(7)) for details.

## PARAMETERS
name

The name (optionally schema-qualified) of an existing materialized view.

column_name

Name of an existing column.

extension_name

The name of the extension that the materialized view is to depend on (or no longer dependent on, if NO is specified). A materialized view that's marked as dependent on an extension is automatically dropped when the extension is dropped.

new_column_name

New name for an existing column.

new_owner

The user name of the new owner of the materialized view.

new_name

The new name for the materialized view.

new_schema

The new schema for the materialized view.

## EXAMPLES
To rename the materialized view foo to bar:

```
ALTER MATERIALIZED VIEW foo RENAME TO bar;
```

## COMPATIBILITY
ALTER MATERIALIZED VIEW is a PostgreSQL extension.

## SEE ALSO
CREATE MATERIALIZED VIEW (CREATE_MATERIALIZED_VIEW(7)), DROP MATERIALIZED VIEW (DROP_MATERIALIZED_VIEW(7)), REFRESH MATERIALIZED VIEW (REFRESH_MATERIALIZED_VIEW(7))