Guide to reporting problems

Please read all the way through this document. It provides information which will help you to frame your question or state your problem in a way which will allow more helpful responses. If any of the suggested information is missing, you may need to go back-and-forth with people while they try to gather enough information to help, or they may make guesses in the absence of actual data which could lead to off-target answers. Please don't make people ask twice to figure out what version of postgres you're running.

Why were you sent this link?

Our development community is managed by volunteers. No one is being paid to answer your questions on our mailing lists.

We have limited time, and would like to spend as much of that time productively helping you as we can.

A few minutes spent reading this document will help us help you, as fast as possible. So, please -- dive in!

How to get help more quickly

When writing requests for help, think about the reader and read your message from their point of view. What questions will they have to ask? Remember, they can't see your screen. They don't know what you are trying to do. They can't tell what programs or OS you use. The people reading your question only know what you tell them. The better the information you give, the better help they can offer.

Remember that the pgsql-general mailing list is populated by people helping out in their spare time. Show that you respect the time they're spending to help you. If someone asks 6 questions about your environment and you only answer some of them, it discourages them from trying to help more.

Particular kinds of problem

Slow query? Read: Guide to Posting Slow Query Questions.

Installation problems? Read: Troubleshooting Installation and (on Windows) the Windows installation FAQ.

For (rare but nasty) suspected data/index corruption issues: What to do if you suspect your database or indexes are corrupt

Things you need to mention in problem reports

For ANY problem

To get a quick and helpful response, you must include at least the information shown in the list below. Please do not include screenshots of any kind.

We formatted this so that you can cut and paste the list below into an email and fill in the information:

A description of what you are trying to achieve and what results you expect.:

PostgreSQL version number you are running:

How you installed PostgreSQL:

Changes made to the settings in the postgresql.conf file:  see Server Configuration for a quick way to list them all.

Operating system and version:

What program you're using to connect to PostgreSQL:
 
Is there anything relevant or unusual in the PostgreSQL server logs?:
 
For questions about any kind of error:

What you were doing when the error happened / how to cause the error:

The EXACT TEXT of the error message you're getting, if there is one: (Copy and paste the message to the email, do not send a screenshot)

Here's a more detailed version, showing you where to get information if you need help finding it:

1. A description of what you are trying to achieve and what results you expect.
   1. Describe in as much detail as possible, step by step, including command lines, SQL output, etc.
2. The EXACT PostgreSQL version you are running
   1. Run "SELECT version();" in psql or PgAdmin and provide the full, exact output. Paste it
3. How you installed PostgreSQL
   1. Downloaded the EnterpriseDB One-click installer?
   2. From Linux distro package management? If so, what repository?
   3. Direct downloads of rpm/deb packages? From where?
   4. From BSD ports, MacPorts, etc?
   5. Downloaded and compiled the sources. If so, what options did you pass to configure? What compiler and version did you use?
   6. If you're having installer problems, make sure to include the installer log from the temporary folder. Windows users see Running & Installing PostgreSQL On Native Windows.
4. Changes made to the settings in the postgresql.conf file: see Server Configuration for a quick way to list them all.
5. Operating system and version
   1. Linux users:
      1. Linux distro and version
      2. Kernel details (run uname -a on the terminal)
   2. Windows users:
      1. This means your Windows OS version, variant, and service pack. For example, "Windows XP Pro Service Pack 3". You can get this from the "winver" command - "Start -> Run -> winver.exe".
      2. Whether you're running a 32-bit or 64-bit version of Windows
6. For questions about any kind of error:
   1. What you were doing when the error happened / how to cause the error.
   2. The EXACT TEXT of the error message you're getting if there is one. Copy and paste the message to the email, do not send a screenshot.
7. What program you're using to connect to PostgreSQL
   1. What version of the ODBC/JDBC/ADO/etc driver you're using, if any
   2. If you're using a connection pool, load balancer or application server, which one you're using and its version
8. Is there anything remotely unusual in the PostgreSQL server logs?
   1. On Linux this depends a bit on distro, but you'll usually find them in /var/log/postgresql/.
   2. On Windows these are in your data directory. On a default PostgreSQL install that'll be in C:\Program Files\PostgreSQL\8.4\data\pg_log (assuming you're using 8.4)
   3. Windows users should also check the Event Viewer for service startup messages.

If you leave things out, your question may not be answered or you will be sent another link to this page and told to try again. Save yourself time: do it right the first time.

For errors or problems with queries:

• The EXACT text of the query you ran, if any
• The EXACT output of that query if it's short enough to be reasonable to post, otherwise a sample of it
• The SQL definition of any tables, views and user-defined functions your query uses, or psql \d+ output for them.
• If at all possible, a self contained test case demonstrating your problem
• If you think the query result is wrong, what you think should've been produced instead and why
• For slow query problems, the information in the Guide to Posting Slow Query Questions page.

If your question relates to performance (query speed, memory use, etc) and/or data corruption

Please include information about:

• CPU manufacturer and model, eg "AMD Athlon X2" or "Intel Core 2 Duo"
• Compilation flags from SELECT * FROM pg_config();
• Amount and size of RAM installed, eg "2GB RAM"
• Storage details (important for performance and corruption questions)
  • Do you use a RAID controller? If so, what type of controller? eg "3Ware Escalade 8500-8"
    • Does it have a battery backed cache module?
    • Is write-back caching enabled?
  • Do you use software RAID? If so, what software and what version? eg "Linux software RAID (md) 2.6.18-5-686 SMP mod_unload 686 REGPARM gcc-4.1".
    • In the case of Linux software RAID you can get the details from the "modinfo md_mod" command
  • Is your PostgreSQL database on a SAN?
    • Who made it, what kind, etc? Provide what details you can.
  • How many hard disks are connected to the system and what types are they? You need to say more than just "6 disks". At least give maker, otational speed and interface type, eg "6 15,000rpm Seagate SAS disks".
  • How are your disks arranged for storage? Are you using RAID? If so, what RAID level(s)? What PostgreSQL data is on what disks / disk sets? What file system(s) are in use?
    • eg: "Two disks in RAID 1, with all PostgreSQL data and programs stored on one ext3 file system."
    • eg: "4 disks in RAID 5 holding the pg data directory on an ext3 file system. 2 disks in RAID 1 holding pg_clog, pg_xlog, the temporary tablespace, and the sort scratch space, also on ext3.".
    • eg: "Default Windows install of PostgreSQL"
  • In case of corruption data reports:
    • Have you ever set fsync=off in the postgresql config file?
    • Have you had any unexpected power loss lately? Replaced a failed RAID disk? Had an operating system crash?
    • Have you run a file system check? (chkdsk / fsck)
    • Are there any error messages in the system logs? (unix/linux: dmesg, /var/log/syslog ; Windows: Event Viewer in Control Panel -> Administrative Tools )

Things Not To Do

People who answer your questions on mailing lists aren't being paid to do so. They're doing it out of community spirit and a desire to help other PostgreSQL users, so that they can get help when they need it. As such, they have to want to help you; if you make yourself obnoxious, you won't get any assistance. Here's a number of bad practices which will make people more likely to ignore your request than answer it:

• "It's an Emergency!": community support is peer-to-peer, free, and at the helper's convenience. If it's a real emergency, get a support contract with a commercial support company. Most of them will do per-incident support without an existing contract.
• Cross-Posting: do not post the same question to 2 or more mailing lists at the same time. Not only does this annoy the people you want help from, it's likely to get your e-mails spam-filtered out. If you post it to one list, and don't get a response in 2 days or more, then it's ok to post it to another list.
• User Questions on Hacker Lists: pgsql-hackers, pgsql-committers, pgsql-testers, pgsql-www and pgsql-rrreviewers are all for people who work on the PostgreSQL database engine and our community infrastructure. Asking user questions on any of those is more liable to get you flamed than any answers. There are over 3 dozen user mailing lists, use them. Many code contributors and committers do read the -general, -bugs, etc lists, so you'll be heard if there's something wrong.
• Insist on Asking on the Wrong List: sometimes you will post a question on one mailing list and will be told that you need to post it on a different list. Don't insist on pursuing the topic on the original list to everyone's irritation.
• Send Email Directly to a List Member Without Copying the List: when someone responds on the list to try to help, any reply you make to that should normally be kept on the list. There are several reasons for this; among them are that the discussion may be useful to others who later run into the same problem, and that there may be other members of the community who can also provide help.
• Re-posting: don't repost your question multiple times to the same list. If people haven't answered, they're busy, don't know the answer, or don't want to help you. If a week goes by without a response, you might "reply" to your own post, with an "Help? Anyone?", but more likely you should ask about what other list might be more appropriate for the question. If you re-post, sometimes discussion gets split across the threads under your different posts, confusing everybody and making it harder to help you.
• Comparisons with Other DBMSes are generally not helpful, unless your request is highly technical and is the result of serious comparison testing. We're generally not interested in replicating exactly how Oracle or MySQL do things; if we were, we'd work on those databases instead. Furthermore, many readers of the -general list may not be familiar with the database system you're talking about, so saying "it's like <blah>" doesn't help much. Explain what you're trying to do, not how you did it in some other database. (That said, if you notice an issue where Pg supports something, but not with quite the same syntax as another major database, it's worth mentioning that since sometimes the other syntax can be easily added for compatibility).
• "Postgres Is Broken!" as well as variations on "I'm going to abandon Postgres if you don't help me" will not usually get you help, and certainly don't get you help any faster. The general reaction you get will be: "Nobody is forcing you to use PostgreSQL, feel free to use MySQL/Oracle/CouchDB". Similarly, starting off your discussion by accusing PostgreSQL of having a bug because it doesn't work the way you expect is also not a good way to begin.
• Insist That Someone's Answer is Wrong (without testing): if you think you know better than they do, why are you asking for help? Usually what you actually mean is thanks for your suggestion, but you seem to have misunderstood my question. Perhaps I explained it poorly, let me try again. Or, perhaps, That doesn't quite achieve what I'm trying to do, because it doesn't blah - is there anything that might?. Think about how you say things.