How do IMMUTABLE, STABLE and VOLATILE keywords effect behaviour of function?

Question

We wrote a function get_timestamp() defined as

CREATE OR REPLACE FUNCTION get_timestamp()
  RETURNS integer AS
$$
SELECT (FLOOR(EXTRACT(EPOCH FROM clock_timestamp()) * 10) - 13885344000)::int;
$$
LANGUAGE SQL;

This was used on INSERT and UPDATE to enter or edit a value in a created and modified field in the database record. However, we found when adding or updating records consecutively it was returning the same value.

On inspecting the function in pgAdmin III we noted that on running the SQL to build the function the key word IMMUTABLE had been injected after the LANGUAGE SQL statement. The documentation states that the default is VOLATILE (If none of these appear, VOLATILE is the default assumption) so I am not sure why IMMUTABLE was injected, however, changing this to STABLE has solved the issue of repeated values.

NOTE: As stated in the accepted answer, IMMUTABLE is never added to a function by pgAdmin or Postgres and must have been added during development.

I am guessing what was happening was that this function was being evaluated and the result was being cached for optimization, as it was marked IMMUTABLE indicating to the Postgres engine that the return value should not change given the same (empty) parameter list. However, when not used within a trigger, when used directly in the INSERT statement, the function would return a distinct value FIVE times before then returning the same value from then on. Is this due to some optimisation algorithm that says something like "If an IMMUTABLE function is used more that 5 times in a session, cache the result for future calls"?

Any clarification on how these keywords should be used in Postgres functions would be appreciated. Is STABLE the correct option for us given that we use this function in triggers, or is there something more to consider, for example the docs say:

(It is inappropriate for AFTER triggers that wish to query rows modified by the current command.)

But I am not altogether clear on why.

Answer 1

The key word IMMUTABLE is never added automatically by pgAdmin or Postgres. Who ever created or replaced the function did that.

The correct function volatility (read the manual) setting for the given function is VOLATILE, not STABLE - or it wouldn't make sense to use clock_timestamp() which is VOLATILE as opposed to now() or CURRENT_TIMESTAMP, which are defined STABLE: those return the same timestamp within the same transaction, per documentation:

clock_timestamp() returns the actual current time, and therefore its value changes even within a single SQL command.

The manual warns that function volatility STABLE ...

is inappropriate for AFTER triggers that wish to query rows modified by the current command.

.. because the repeated evaluation of the trigger function for the same row can return different results. So, not STABLE. I don't think the warning is even needed there, since it's rather obvious.

And you ask:

Do you have an idea as to why the function returned correctly five times before sticking on the fifth value when set as IMMUTABLE?

Quoting the Postgres Wiki:

With 9.2, the planner will use specific plans regarding to the parameters sent (the query will be planned at execution), except if the query is executed several times and the planner decides that the generic plan is not too much more expensive than the specific plans.

Bold emphasis mine. Doesn't seem to make sense for an IMMUTABLE function (doesn't do harm either), but maybe the use of a VOLATILE function within still triggers initial re-planing. (The last bit is just my speculation.)
More explanation here:

• PostgreSQL Stored Procedure Performance

Aside

trunc() is slightly faster than floor() and does the same here, since positive numbers are guaranteed:

SELECT (trunc(EXTRACT(EPOCH FROM clock_timestamp()) * 10) - 13885344000)::int