Troubleshooting Questions

For typical problems that may occur while building libpqxx, also see the Building FAQ and the mailing list archives.

I'm running into a bug. What can I do?

Take a look at the ReportingBugs page for advice on diagnosing and reporting problems.

Network timeouts take forever

Sometimes the connection to the server breaks, perhaps because a router stopped working, or a network cable was unplugged. In those cases the client can sit and wait for as long as twenty minutes before finally figuring out that the ongoing session is dead. This problem is worse with libpqxx than it is with plain libpq because libpqxx automatically attempts to re-establish your connection. Depending on your underlying libpq version (some have a bug in detecting network timeouts) it may also take extra time for libpqxx to figure out that the connection really is broken.

To reduce the time your client will wait for a connection to be (re-)established, set the PGCONNECT_TIMEOUT environment variable to the number of seconds your application should be willing to wait. Your overall wait may be a few times longer if the server is not responding, but don't set this too low (wait at least 2 seconds) or a normal, transient delay may be mistaken for an unreachable server.

Version 3.0 should fix this problem. Please let us know if it doesn't'''

Does WinZip mess up the source tree?

Sometimes. This problem occurs on Windows systems only. If you use WinZip to extract the libpqxx source tarball, be sure to disable the "tar file smart CR/LF conversion" option.

Why aren't "long long" et al. supported?

They are, but as nonstandard extensions of the C++ language. Just make sure that:

  1. your compiler will accept use of these types (you may need to add some compiler-specific option to the CXXFLAGS variable while running configure); and
  2. before including any libpqxx headers in programs that need long long support, you #define PQXX_ALLOW_LONG_LONG to enable it.

The long long types are supported by many compilers, but they're not part of the C++ language as defined by the 1998 ISO standard. It's set to be part of the upcoming C++0X version of the standard. Some compilers may complain when they see "long long," or complain only in certain configurations. That's why support for these types is "hidden" by default, and must be enabled with the PQXX_ALLOW_LONG_LONG preprocessor macro. Once the long long types become a standard language feature, de jure as well as de facto, support will be enabled by default.

(Note for language lawyers: The C++ standard nowadays does incorporate the C99 runtime library standard, and since C99 standardizes the long long type, there is some mention of the type in current versions of the C++ standard. But this does not mean that long long is now a real, standard C++ type. Not yet, anyway.)

I can't catch exceptions!

Some people report that their programs crash when an exception occurs. You're most likely to see this when logging into the database fails, because that's something you're likely to do very early on in your program.

The most likely causes seem to be build problem.

  • Were libpqxx and your program built and linked using the same compiler, and the same compiler version?
  • If your compiler environment has separate "debug" and "release" modes, were libpqxx and your program, as well as your libpq, built in the same mode?
  • Is your program being linked against the same libpqxx version whose headers you use? There may be remains of an older installation of libpqxx on your system somewhere.
  • Where you catch the exception, are you catching the right type of exception? Are you catching a reference ("catch const exception &e"—note the ampersand) to avoid "slicing" of the exception object?

Why does my program crash when a connection to the database breaks?

Sometimes connections to the database are lost even after they have been successfully established. This can happen for many reasons: a broken cable, a power outage in the wrong place, a crashed server, a change to your network configuration, or even a firewall dropping your connection because it hasn't been used for too long. It may be a very long time for this to be noticed; your operating system will typically try very hard to recover, and you'll only see an error once the system gives up.

When it does, your program (on Unix-like systems at least) may also receive the SIGPIPE signal. Your program's default response to receiving this error is to abort. That can be useful for simple, short-lived programs but many more complex applications can not afford to crash just because a network connection was lost.

All you need to do deal with broken connections in libpqxx on Unix-like systems (and that includes GNU and BSD systems) is to make your program ignore this signal. Just include something like this in your program: 

#include <signal.h>

int main()
{
  signal(SIGPIPE, SIG_IGN);
  // ...

If libpqxx finds that a connection is broken as you try to use it, the library will try to reactivate the connection automatically. If that fails also, a broken_connection exception will be thrown that can be handled by your program as a normal C++ exception.

Why does my program crash when it fails to connect to the database?

This may be for several reasons. Starting with the simplest:

  • Are you catching the exception?
  • Catch a const exception & (note the ampersand; it has to be a reference!) rather than an exception. Otherwise the exception object may get "sliced." You may want to read up on this crucial piece of C++ subtlety.
  • If you're compiling with gcc, make sure you use the g++ command (not the gcc command!) to compile both the library and your program.
  • There may be a bug in the library's throw specifications. When using gcc, this can be detected by recompiling both the library and your own code with the -fno-enforce-eh-specs option. If the problem disappears when you do that, don't sit on it—report it!
  • There may be some other bug in the library, the compiler, or your program. Notably, some gcc 3.x versions have had problems handling exceptions on PowerPC processors.
  • See "I can't catch exceptions!" above.

If this doesn't help you solve the problem, please report it and provide the following information:

  • Which compiler you're using (include version number!) to compile the library and your own software.
  • Compiler options you used to compile your software, and any nonstandard options you may have added when compiling the library.
  • Processor architecture of your machine, and the operating system it's running.
  • Which version of libpqxx you're working with.
  • Whether you're linking against libpqxx as a shared library ("DLL") or as a static library.

I get a compile/link error when I try to read/convert a field!

This may be because you're converting from/to a nonstandard type (but see the question about long long). Or the conversion may be an ambiguous one. That may happen while converting to a char type, for example: when code tries to do that, it may want to read the field as a single character, or merely as a very small integral number. And in the latter case, it's not clear whether the program expects the char type to be signed or not. That's three possible conversions that could all make sense, or it may simply have been a mistake by a programmer who meant to pass an array of characters. In such cases the link error is intentional.

If the problem is a nonstandard type and you do want to use that type, and your standard library implementation supports them, try using the standard stringstream classes to do the conversion for you.

Visual C++: "unresolved typeref token"

If you're trying to link an application in .NET "Managed Code" to libpqxx (which is in C++, not in Managed Code) you may get these warning messages from your linker, plus "LNK2028" errors for unresolved tokens: 

LNK4248: unresolved typeref token (01000018) for 'pg_result'; image may not run

As far as I understand, it's not directly possible to link a program in Managed Code to a C++ library. This is based on very limited understanding, however; I'd be happy to learn that I was wrong.

Visual C++: tests 003 and 022 crashing

This is known to happen if the compilation environment is set up incorrectly. The version of the libpq headers used while compiling libpqxx must correspond exactly to the version of the libpq DLL that you link to. For instance, if you have PostgreSQL 8.0.4 installed on your system but you have compiled libpq 8.1.3 yourself, then you might be linking to the system-installed libpq.dll (version 8.0.4) instead of the one you compiled, while you are using the headers from version 8.1.3. In order to fix this, place the directories containing the compiled libpq.dll in your PATH before the directory that contains the system-installed versions of these files.

Visual C++: enabling trace output crashes or hangs program

This is probably the same problem as tests 003 and 022 crashing. Please try the remedies given under that FAQ entry.

Visual C++: cannot build/run libpqxx "debug" library

Building libpqxx in "debug" mode requires that you have installed a "debug" version of the libpq library. libpqxx versions before 2.6.5 linked to the "release" build of libpq, which produced certain incompatibilities. Version 2.6.5 and higher link to the "debug" build of libpq, which is not built by default when you compile PostgreSQL using Visual C++. To correctly build a "debug" version of libpqxx, you must check the following things.

  1. Check your LIBPATH variable in win32/common, and add an extra /libpath: entry for the postgresql-x.y.z/src/interfaces/libpq/Debug directory (if it is not there already). The libpqxx build process will not find your debug libpq libraries if this entry is not present.
  2. Make sure you have compiled a debug build of libpq. You can do this by going to the directory src/interfaces/libpq in the PostgreSQL tree, and executing NMAKE /F win32.mak DEBUG=1.

With these changes in place, the "debug" build should work just fine. Remember: you must also make sure that the file libpqd.dll is in your PATH so that you can actually run a program that uses the libpqxx "debug" library.