One thing which went unexplained in the previous sample was the error reporting part:
if (ARR_NDIM(input_array) > 1)
ereport(ERROR,
(errcode(ERRCODE_ARRAY_SUBSCRIPT_ERROR),
errmsg("use only one-dimensional arrays!"))); All error reporting and other off-channel messaging in PostgreSQL is done using the ereport(<errorlevel>, rest) macro whose main purpose is to make error reporting look like a function call.
The only parameter which is processed directly by ereport() is the first argument error level, or perhaps more exactly, the severity level or log level. All the other parameters are actually function calls which independently generate and store additional error information in the system to be written to logs and/or be sent to the client. Being placed in the argument list of the ereport() makes sure that these other functions are called before the actual error is reported. This is important because in the case of an error level being ERROR, FATAL, or PANIC the system cleans up all current transaction states and anything after the ereport() call will never get a chance to run. Error states the end of the transaction.
In case of ERROR, the system is returned to a clean state and it will be ready to accept new commands.
Error level FATAL will clean up the backend and exit the current session.
PANIC is the most destructive one and it will not only end the current connection, but will also cause all other connections to be terminated. PANIC means that shared state (shared memory) is potentially corrupted and it is not safe to continue. It is used automatically for things like core dumps or other "hard" crashes.
WARNING is the highest non-error level. It means that something may be wrong and needs user/administrator attention. It is a good practice to periodically scan system logs for warnings. Use this only for unexpected conditions. See the next one for things happening on a regular basis. Warnings go to client and server logs by default.
NOTICE is for things which are likely of higher interest to users, like information about creating a primary key index or sequence for serial type (though these stopped to be NOTICE in the latest version of PostgreSQL). Like the previous one, NOTICE is sent both to client and server logs by default.
INFO is for things specifically requested by client, like VACUUM / ANALYSE VERBOSE. It is always sent to the client regardless of the client_min_messages GUC setting, but is not written to a server log when using default settings.
LOG and COMMERROR are for servers, operational messages, and by default are only written to the server log. The error level LOG can also be sent to the client if client_min_messages is set appropriately, but COMMERROR never is.
There are DEBUG1 to DEBUG5 in increasing order of verbosity. They are specifically meant for reporting debugging info and are not really useful in most other cases, except perhaps for curiosity. Setting higher DEBUGx levels is not recommended in production servers, as the amount logged or reported can be really huge.
While most communication from the server to the client takes place after the command completes (or even after the transaction is committed in case of LISTEN/NOTIFY), everything emitted by ereport() is sent to the client immediately, thus the mention of off-channel messaging previously. This makes ereport() a useful tool for monitoring long-running commands such as VACUUM and also a simple debugging aid to print out useful debug info.
Note
You can read a much more detailed description of error reporting at http://www.postgresql.org/docs/current/static/error-message-reporting.html.