17.7. Platform-Specific Notes#
This section documents additional platform-specific issues regarding the installation and setup of PostgreSQL. Be sure to read the installation instructions, and in particularSection 17.1 as well. Also, checkChapter 31 regarding the interpretation of regression test results.
Platforms that are not covered here have no known platform-specific installation issues.
17.7.1. Cygwin#
PostgreSQL can be built using Cygwin, a Linux-like environment for Windows, but that method is inferior to the native Windows build and running a server under Cygwin is no longer recommended.
When building from source, proceed according to the Unix-style installation procedure (i.e.,./configure; make
; etc.), noting the following Cygwin-specific differences:
Set your path to use the Cygwin bin directory before the Windows utilities. This will help prevent problems with compilation.
The
adduser
command is not supported; use the appropriate user management application on Windows. Otherwise, skip this step.The
su
command is not supported; use ssh to simulate su on Windows. Otherwise, skip this step.OpenSSL is not supported.
Start
cygserver
for shared memory support. To do this, enter the command/usr/sbin/cygserver &
. This program needs to be running anytime you start the PostgreSQL server or initialize a database cluster (initdb
). The defaultcygserver
configuration may need to be changed (e.g., increaseSEMMNS
) to prevent PostgreSQL from failing due to a lack of system resources.Building might fail on some systems where a locale other than C is in use. To fix this, set the locale to C by doing
export LANG=C.utf8
before building, and then setting it back to the previous setting after you have installed PostgreSQL.The parallel regression tests (
make check
) can generate spurious regression test failures due to overflowing thelisten()
backlog queue which causes connection refused errors or hangs. You can limit the number of connections using the make variableMAX_CONNECTIONS
thus:make MAX_CONNECTIONS=5 check
(On some systems you can have up to about 10 simultaneous connections.)
It is possible to installcygserver
and the PostgreSQL server as Windows NT services. For information on how to do this, please refer to theREADME
document included with the PostgreSQL binary package on Cygwin. It is installed in the directory/usr/share/doc/Cygwin
.
17.7.2. macOS#
To buildPostgreSQL from source onmacOS, you will need to install Apple's command line developer tools, which can be done by issuing
xcode-select --install
(note that this will pop up a GUI dialog window for confirmation). You may or may not wish to also install Xcode.
On recentmacOS releases, it's necessary to embed the“sysroot” path in the include switches used to find some system header files. This results in the outputs of theconfigure script varying depending on which SDK version was used duringconfigure. That shouldn't pose any problem in simple scenarios, but if you are trying to do something like building an extension on a different machine than the server code was built on, you may need to force use of a different sysroot path. To do that, setPG_SYSROOT
, for example
make PG_SYSROOT=/desired/path
all
To find out the appropriate path on your machine, run
xcrun --show-sdk-path
Note that building an extension using a different sysroot version than was used to build the core server is not really recommended; in the worst case it could result in hard-to-debug ABI inconsistencies.
You can also select a non-default sysroot path when configuring, by specifyingPG_SYSROOT
toconfigure:
./configure ... PG_SYSROOT=/desired/path
This would primarily be useful to cross-compile for some other macOS version. There is no guarantee that the resulting executables will run on the current host.
To suppress the-isysroot
options altogether, use
./configure ... PG_SYSROOT=none
(any nonexistent pathname will work). This might be useful if you wish to build with a non-Apple compiler, but beware that that case is not tested or supported by the PostgreSQL developers.
macOS's“System Integrity Protection” (SIP) feature breaksmake check
, because it prevents passing the needed setting ofDYLD_LIBRARY_PATH
down to the executables being tested. You can work around that by doingmake install
beforemake check
. Most PostgreSQL developers just turn off SIP, though.
17.7.3. MinGW#
PostgreSQL for Windows can be built using MinGW, a Unix-like build environment for Microsoft operating systems. The MinGW build procedure uses the normal build system described in this chapter.
MinGW, the Unix-like build tools, and MSYS, a collection of Unix tools required to run shell scripts likeconfigure
, can be downloaded fromhttp://www.mingw.org/. Neither is required to run the resulting binaries; they are needed only for creating the binaries.
To build 64 bit binaries using MinGW, install the 64 bit tool set fromhttps://mingw-w64.org/, put its bin directory in thePATH
, and runconfigure
with the--host=x86_64-w64-mingw32
option.
After you have everything installed, it is suggested that you runpsql underCMD.EXE
, as the MSYS console has buffering issues.
17.7.3.1. Collecting Crash Dumps#
If PostgreSQL on Windows crashes, it has the ability to generateminidumps that can be used to track down the cause for the crash, similar to core dumps on Unix. These dumps can be read using theWindows Debugger Tools or usingVisual Studio. To enable the generation of dumps on Windows, create a subdirectory namedcrashdumps
inside the cluster data directory. The dumps will then be written into this directory with a unique name based on the identifier of the crashing process and the current time of the crash.
17.7.4. Solaris#
PostgreSQL is well-supported on Solaris. The more up to date your operating system, the fewer issues you will experience.
17.7.4.1. Required Tools#
You can build with either GCC or Sun's compiler suite. For better code optimization, Sun's compiler is strongly recommended on the SPARC architecture. If you are using Sun's compiler, be careful not to select/usr/ucb/cc
; use/opt/SUNWspro/bin/cc
.
You can download Sun Studio fromhttps://www.oracle.com/technetwork/server-storage/solarisstudio/downloads/. Many GNU tools are integrated into Solaris 10, or they are present on the Solaris companion CD. If you need packages for older versions of Solaris, you can find these tools athttp://www.sunfreeware.com. If you prefer sources, look athttps://www.gnu.org/prep/ftp.
17.7.4.2. configure Complains About a Failed Test Program#
Ifconfigure
complains about a failed test program, this is probably a case of the run-time linker being unable to find some library, probably libz, libreadline or some other non-standard library such as libssl. To point it to the right location, set theLDFLAGS
environment variable on theconfigure
command line, e.g.,
configure ... LDFLAGS="-R /usr/sfw/lib:/opt/sfw/lib:/usr/local/lib"
See theld man page for more information.
17.7.4.3. Compiling for Optimal Performance#
On the SPARC architecture, Sun Studio is strongly recommended for compilation. Try using the-xO5
optimization flag to generate significantly faster binaries. Do not use any flags that modify behavior of floating-point operations anderrno
processing (e.g.,-fast
).
If you do not have a reason to use 64-bit binaries on SPARC, prefer the 32-bit version. The 64-bit operations are slower and 64-bit binaries are slower than the 32-bit variants. On the other hand, 32-bit code on the AMD64 CPU family is not native, so 32-bit code is significantly slower on that CPU family.
17.7.4.4. Using DTrace for Tracing PostgreSQL#
Yes, using DTrace is possible. SeeSection 27.5 for further information.
If you see the linking of thepostgres
executable abort with an error message like:
Undefined first referenced symbol in fileAbortTransaction utils/probes.oCommitTransaction utils/probes.old: fatal: Symbol referencing errors. No output written to postgrescollect2: ld returned 1 exit statusmake: *** [postgres] Error 1
your DTrace installation is too old to handle probes in static functions. You need Solaris 10u4 or newer to use DTrace.
17.7.5. Visual Studio#
It is recommended that most users download the binary distribution for Windows, available as a graphical installer package from thePostgreSQL website athttps://www.postgresql.org/download/. Building from source is only intended for people developingPostgreSQL or extensions.
PostgreSQL for Windows with Visual Studio can be built using Meson, as described inSection 17.4. The native Windows port requires a 32 or 64-bit version of Windows 10 or later.
Native builds ofpsql don't support command line editing. TheCygwin build does support command line editing, so it should be used where psql is needed for interactive use onWindows.
PostgreSQL can be built using the Visual C++ compiler suite from Microsoft. These compilers can be either fromVisual Studio,Visual Studio Express or some versions of theMicrosoft Windows SDK. If you do not already have aVisual Studio environment set up, the easiest ways are to use the compilers fromVisual Studio 2022 or those in theWindows SDK 10, which are both free downloads from Microsoft.
Both 32-bit and 64-bit builds are possible with the Microsoft Compiler suite. 32-bit PostgreSQL builds are possible withVisual Studio 2015 toVisual Studio 2022, as well as standalone Windows SDK releases 10 and above. 64-bit PostgreSQL builds are supported withMicrosoft Windows SDK version 10 and above orVisual Studio 2015 and above.
If your build environment doesn't ship with a supported version of theMicrosoft Windows SDK it is recommended that you upgrade to the latest version (currently version 10), available for download fromhttps://www.microsoft.com/download.
You must always include theWindows Headers and Libraries part of the SDK. If you install aWindows SDK including theVisual C++ Compilers, you don't needVisual Studio to build. Note that as of Version 8.0a the Windows SDK no longer ships with a complete command-line build environment.
17.7.5.1. Requirements#
The following additional products are required to buildPostgreSQL on Windows.
- Strawberry Perl
Strawberry Perl is required to run the build generation scripts. MinGW or Cygwin Perl will not work. It must also be present in the PATH. Binaries can be downloaded fromhttps://strawberryperl.com.
- Bison andFlex
Bison andFlex are required. OnlyBison versions 2.3 and later will work.Flex must be version 2.5.35 or later.
BothBison andFlex are included in themsys tool suite, available fromhttp://www.mingw.org/wiki/MSYS as part of theMinGW compiler suite.
You will need to add the directory containing
flex.exe
andbison.exe
to the PATH environment variable. In the case of MinGW, the directory is the\msys\1.0\bin
subdirectory of your MinGW installation directory.Note
The Bison distribution from GnuWin32 appears to have a bug that causes Bison to malfunction when installed in a directory with spaces in the name, such as the default location on English installations
C:\Program Files\GnuWin32
. Consider installing intoC:\GnuWin32
or use the NTFS short name path to GnuWin32 in your PATH environment setting (e.g.,C:\PROGRA~1\GnuWin32
).
The following additional products are not required to get started, but are required to build the complete package.
- Magicsplat Tcl
Required for buildingPL/Tcl. Binaries can be downloaded fromhttps://www.magicsplat.com/tcl-installer/index.html.
- Diff
Diff is required to run the regression tests, and can be downloaded fromhttp://gnuwin32.sourceforge.net.
- Gettext
Gettext is required to build with NLS support, and can be downloaded fromhttp://gnuwin32.sourceforge.net. Note that binaries, dependencies and developer files are all needed.
- MIT Kerberos
Required for GSSAPI authentication support. MIT Kerberos can be downloaded fromhttps://web.mit.edu/Kerberos/dist/index.html.
- libxml2 andlibxslt
Required for XML support. Binaries can be downloaded fromhttps://zlatkovic.com/pub/libxml or source fromhttp://xmlsoft.org. Note that libxml2 requires iconv, which is available from the same download location.
- LZ4
Required for supportingLZ4 compression. Binaries and source can be downloaded fromhttps://github.com/lz4/lz4/releases.
- Zstandard
Required for supportingZstandard compression. Binaries and source can be downloaded fromhttps://github.com/facebook/zstd/releases.
- OpenSSL
Required for SSL support. Binaries can be downloaded fromhttps://slproweb.com/products/Win32OpenSSL.html or source fromhttps://www.openssl.org.
- ossp-uuid
Required for UUID-OSSP support (contrib only). Source can be downloaded fromhttp://www.ossp.org/pkg/lib/uuid/.
- Python
Required for buildingPL/Python. Binaries can be downloaded fromhttps://www.python.org.
- zlib
Required for compression support inpg_dump andpg_restore. Binaries can be downloaded fromhttps://www.zlib.net.
17.7.5.2. Special Considerations for 64-Bit Windows#
PostgreSQL will only build for the x64 architecture on 64-bit Windows.
Mixing 32- and 64-bit versions in the same build tree is not supported. The build system will automatically detect if it's running in a 32- or 64-bit environment, and build PostgreSQL accordingly. For this reason, it is important to start the correct command prompt before building.
To use a server-side third party library such asPython orOpenSSL, this librarymust also be 64-bit. There is no support for loading a 32-bit library in a 64-bit server. Several of the third party libraries that PostgreSQL supports may only be available in 32-bit versions, in which case they cannot be used with 64-bit PostgreSQL.
17.7.5.3. Collecting Crash Dumps#
If PostgreSQL on Windows crashes, it has the ability to generateminidumps that can be used to track down the cause for the crash, similar to core dumps on Unix. These dumps can be read using theWindows Debugger Tools or usingVisual Studio. To enable the generation of dumps on Windows, create a subdirectory namedcrashdumps
inside the cluster data directory. The dumps will then be written into this directory with a unique name based on the identifier of the crashing process and the current time of the crash.