Unfortunately, PostgreSQL’s method of setting the way the date and time are handled is, at first sight at least, a little strange.
There are two things you can control:
• The order in which days and months are handled, United States or European style
• The display format; for example, numbers only or more textual date output
The unfortunate part of the story is that PostgreSQL uses the same variable to handle both settings, which frankly, can be a bit confusing. The good news is that PostgreSQL defaults to using the unambiguous ISO-8601 style date and time output, which is always written in the form YYYY-MM-DD hh:mm:ss.ssTZD. This gives you the year, month, day, hours, minutes, seconds, decimal part of a second to two places, and a time zone designator, which indicates a
plus or minus number of hours difference between local time and UTC. For example, a full date and time would look like 2005-02-01 05:23:43.23+5, which equates to February 1, 2005, at 23 minutes and 43.23 seconds past five o’clock in the morning, and the time zone used is five hours ahead of UTC. If you specify the time in UTC, with no time zone, the standard says you should use a Z (pronounced “Zulu”) to indicate this, although it seems common to omit the Z.
For input in the form NN/NN/NNNN, PostgreSQL defaults to expecting the month before the day (United States style). For example, 2/1/05 is the first of February. Alternatively, you can use a format like February 1, 2005, or the ISO style 2005-02-01. If that behavior is all you need, you are in luck—you don’t need to know any more about controlling how PostgreSQL accepts and displays dates, and you can skip ahead to the next section on date and time functions.
The default style is actually controlled by the postgresql.conf file, in the data directory, which has a line of the form datestyle = 'iso, mdy'. So, you could change the default globally, if you wish.
If you need more control over how dates are handled, PostgreSQL does allow this, but it can be a little tricky. The confusing thing is that there are two independent features to control, and you set them both using datestyle. Do remember, however, that this is all to do with presentation. Internally, PostgreSQL stores dates in a way totally independent of any represen- tation that users expect when data is input or retrieved.
The syntax as a command to psql is as follows:
SET datestyle TO 'value';
To set the order in which months and days are handled, you set the datestyle value to either US, for month-first behavior (02/01/1997, for February 1) or European for day-first behavior (01/02/1997 for February 1).
To change the display format, you also set datestyle, but to one of four different values:
• ISO for the ISO-8601 standard, using - as the field separator, as in 1997-02-01
• SQL for the traditional style, as in 02/01/1997
• Postgres for the default PostgreSQL style, as in Sat Feb 01
• German for the German style, as in 01.02.1997
■Note In the current release, the Postgres format defaults to displaying in SQL style for both date and timestamps.
You set the datestyle variable to the value pair by separating the values with a comma. So, for example, to specify that we want dates shown in SQL style, but using the European convention of day before month, we use this setting:
SET datestyle TO 'European, SQL';
Rather than set the date-handling style locally in session, you can set it for an entire instal- lation, or set the default for a session. If you want to set the default style for date input for a complete installation, you can set the environment variable PGDATESTYLE before starting the
postmaster master server process. Setting the same options using the environment variable in Linux, we would use the following:
PGDATESTYLE="European, SQL"
export PGDATESTYLE
A much better way of changing the default date handling is to edit the configuration file postgresql.conf (found in the data subdirectory of your installation), and set an option such as datestyle='European, SQL' or datestyle = 'iso, mdy', depending on your preferences. You will need to restart the PostgreSQL server after making this change for it to become effective.
If you want to set the date style for individual users, you use the same environment variable, but set for the local user, before psql is invoked. A local setting will override any global setting you have made.
Before we demonstrate how this all works, it’s very handy to remember the special PostgreSQL function cast, which allows you to convert one format into another. We saw it briefly earlier in this chapter, when we looked at doing calculations in the SELECT statement, but there is much more to it than the simple conversion to integer we saw earlier. Although PostgreSQL does a pretty good job of getting types correct, and you shouldn’t need conversion functions often, they can be very useful occasionally. The conversion we need to use to investigate our date and time values is the following to get a date:
cast('string' AS date)
Alternatively, to get a value that includes a time:
cast('string' AS timestamp)
We are also going to use a little trick to demonstrate this function more easily. Almost every time you use the SELECT statement, you will be fetching data from a table. However, you can use SELECT to get data that isn’t in a table at all, as in this example:
bpsimple=> SELECT 'Fred';
?column?
--- Fred
(1 row) bpsimple=>
PostgreSQL is warning us that we haven’t selected any columns, but it is quite happy to accept the SELECT syntax without a table name, and just returns the string we specified.
We can use the same feature, in conjunction with cast, to see how PostgreSQL treats dates and time, without needing to create a temporary table to experiment with.
Try It Out: Set Date Formats
We start off with the environment variable PGDATESTYLE unset, so you can see the default behavior, and then set the date style, so you can see how things progress. We enter a date in ISO format, so this is always a safe option, and PostgreSQL outputs in the same format. There is no ambiguity in either of these statements:
bpsimple=> SELECT cast('2005-02-1' AS date);
?column?
--- 2005-02-01 (1 row) bpsimple=>
Changing the style to US and SQL format, we still enter the date in ISO style, which is unam- biguous; it’s still the first of February, but now the output shows the more conventional, but possibly ambiguous, United States style MM/DD/YYYY output:
bpsimple=> SET datestyle TO 'US, SQL';
SET VARIABLE
bpsimple=> SELECT cast('2005-02-1' AS date);
?column?
--- 02/01/2005 (1 row) bpsimple=>
Now is a good time to also ask psql what the internal variable datestyle is set to:
bpsimple=> SHOW datestyle;
DateStyle --- SQL, MDY (1 row) bpsimple=>
In older versions of PostgreSQL, the output was more verbose, so you may see something slightly different, depending on which version of PostgreSQL you are using.
Now let’s try some more formats:
bpsimple=> SET datestyle TO 'European, SQL';
SET
bpsimple=> SELECT cast('2005 02 1' AS date);
date --- 01/02/2005 (1 row) bpsimple=>
With the output set to European, the display changes to DD/MM/YYYY.
Let’s go back to ISO input and output:
bpsimple=> SET datestyle TO 'European, ISO';
SET
bpsimple=> SELECT cast('2005-02-1' AS date);
date --- 2005-02-01 (1 row) bpsimple=>
The European setting has no effect, because ISO is the same for all locales.
Now let’s consider times. We use the timestamp type, which displays time:
bpsimple=> SELECT cast('2005-02-1' AS timestamp);
?column?
--- 2005-02-01 00:00:00 (1 row)
bpsimple=>
We didn’t specify any hours or minutes, so they all default to zero.
Let’s try PostgreSQL-style output:
bpsimple=> SET datestyle TO 'European, Postgres';
SET
bpsimple=> SELECT cast('2005-02-1' AS timestamp);
timestamp
--- Tue 01 Feb 00:00:00 2005 (1 row)
bpsimple=>
This produces output that is unambiguous and rather more reader-friendly.
How It Works
As you can see, we can vary the way both dates and times are displayed, as well as how ambig- uous input strings, such as 01/02/2005, are interpreted.
Time zones are much simpler than date formats. Providing that your local environment variable TZ or configuration option in postgresql.conf is correctly set, PostgreSQL will manage time zones without further ado.