2 Developer's Frequently Asked Questions (FAQ) for PostgreSQL
4 Last updated: Tue Aug 9 00:56:51 EDT 2005
6 Current maintainer: Bruce Momjian (pgman@candle.pha.pa.us)
8 The most recent version of this document can be viewed at
9 http://www.postgresql.org/files/documentation/faqs/FAQ_DEV.html.
10 _________________________________________________________________
14 1.1) How do I get involved in PostgreSQL development?
15 1.2) What development environment is required to develop code?
16 1.3) What areas need work?
17 1.4) What do I do after choosing an item to work on?
18 1.5) I've developed a patch, what next?
19 1.6) Where can I learn more about the code?
20 1.7) How do I download/update the current source tree?
21 1.8) How do I test my changes?
22 1.9) What tools are available for developers?
23 1.10) What books are good for developers?
24 1.11) What is configure all about?
25 1.12) How do I add a new port?
26 1.13) Why don't you use threads, raw devices, async-I/O, <insert your
27 favorite wizz-bang feature here>?
28 1.14) How are RPM's packaged?
29 1.15) How are CVS branches handled?
30 1.16) Where can I get a copy of the SQL standards?
31 1.17) Where can I get technical assistance?
32 1.18) How do I get involved in PostgreSQL web site development?
36 2.1) How do I efficiently access information in tables from the
38 2.2) Why are table, column, type, function, view names sometimes
39 referenced as Name or NameData, and sometimes as char *?
40 2.3) Why do we use Node and List to make data structures?
41 2.4) I just added a field to a structure. What else should I do?
42 2.5) Why do we use palloc() and pfree() to allocate memory?
43 2.6) What is ereport()?
44 2.7) What is CommandCounterIncrement()?
45 2.8) What debugging features are available?
46 _________________________________________________________________
50 1.1) How do I get involved in PostgreSQL development?
52 Download the code and have a look around. See 1.7.
54 Subscribe to and read the pgsql-hackers mailing list (often termed
55 'hackers'). This is where the major contributors and core members of
56 the project discuss development.
58 1.2) What development environment is required to develop code?
60 PostgreSQL is developed mostly in the C programming language. It also
61 makes use of Yacc and Lex.
63 The source code is targeted at most of the popular Unix platforms and
64 the Windows environment (XP, Windows 2000, and up).
66 Most developers make use of the open source development tool chain. If
67 you have contributed to open source software before, you will probably
68 be familiar with these tools. They include: GCC (http://gcc.gnu.org,
69 GDB (www.gnu.org/software/gdb/gdb.html), autoconf
70 (www.gnu.org/software/autoconf/) AND GNU make
71 (www.gnu.org/software/make/make.html.
73 Developers using this tool chain on Windows make use of MingW (see
74 http://www.mingw.org/).
76 Some developers use compilers from other software vendors with mixed
79 Developers who are regularly rebuilding the source often pass the
80 --enable-depend flag to configure. The result is that when you make a
81 modification to a C header file, all files depend upon that file are
84 1.3) What areas need work?
86 Outstanding features are detailed in the TODO list. This is located in
87 doc/TODO in the source distribution or at
88 http://www.postgresql.org/docs/faqs.TODO.html.
90 You can learn more about these features by consulting the archives,
91 the SQL standards and the recommend texts (see 1.10).
93 1.4) What do I do after choosing an item to work on?
95 Send an email to pgsql-hackers with a proposal for what you want to do
96 (assuming your contribution is not trivial). Working in isolation is
97 not advisable because others might be working on the same TODO item,
98 or you might have misunderstood the TODO item. In the email, discuss
99 both the internal implementation method you plan to use, and any
100 user-visible changes (new syntax, etc). For complex patches, it is
101 important to get community feeback on your proposal before starting
102 work. Failure to do so might mean your patch is rejected.
104 A web site is maintained for patches awaiting review,
105 http://momjian.postgresql.org/cgi-bin/pgpatches, and those that are
106 being kept for the next release,
107 http://momjian.postgresql.org/cgi-bin/pgpatches2.
109 1.5) I've developed a patch, what next?
111 Generate the patch in contextual diff format. If you are unfamiliar
112 with this, you might find the script src/tools/makediff/difforig
115 Ensure that your patch is generated against the most recent version of
116 the code. If it is a patch adding new functionality, the most recent
117 version is CVS HEAD; if it is a bug fix, this will be the most
118 recently version of the branch which suffers from the bug (for more on
119 branches in PostgreSQL, see 1.15).
121 Finally, submit the patch to pgsql-patches@postgresql.org. It will be
122 reviewed by other contributors to the project and will be either
123 accepted or sent back for further work. Also, please try to include
124 documentation changes as part of the patch. If you can't do that, let
125 us know and we will manually update the documentation when the patch
128 1.6) Where can I learn more about the code?
130 Other than documentation in the source tree itself, you can find some
131 papers/presentations discussing the code at
132 http://www.postgresql.org/developer.
134 1.7) How do I download/update the current source tree?
136 There are several ways to obtain the source tree. Occasional
137 developers can just get the most recent source tree snapshot from
138 ftp://ftp.postgresql.org.
140 Regular developers might want to take advantage of anonymous access to
141 our source code management system. The source tree is currently hosted
142 in CVS. For details of how to obtain the source from CVS see
143 http://developer.postgresql.org/docs/postgres/cvs.html.
145 1.8) How do I test my changes?
149 The easiest way to test your code is to ensure that it builds against
150 the latest version of the code and that it does not generate compiler
153 It is worth advised that you pass --enable-cassert to configure. This
154 will turn on assertions with in the source which will often show us
155 bugs because they cause data corruption of segmentation violations.
156 This generally makes debugging much easier.
158 Then, perform run time testing via psql.
160 Regression test suite
162 The next step is to test your changes against the existing regression
163 test suite. To do this, issue "make check" in the root directory of
164 the source tree. If any tests failure, investigate.
166 If you've deliberately changed existing behavior, this change might
167 cause a regression test failure but not any actual regression. If so,
168 you should also patch the regression test suite.
170 Other run time testing
172 Some developers make use of tools such as valgrind
173 (http://valgrind.kde.org) for memory testing, gprof (which comes with
174 the GNU binutils suite) and oprofile
175 (http://oprofile.sourceforge.net/) for profiling and other related
178 What about unit testing, static analysis, model checking...?
180 There have been a number of discussions about other testing frameworks
181 and some developers are exploring these ideas.
183 Keep in mind the Makefiles do not have the proper dependencies for
184 include files. You have to do a make clean and then another make. If
185 you are using GCC you can use the --enable-depend option of configure
186 to have the compiler compute the dependencies automatically.
188 1.9) What tools are available for developers?
190 First, all the files in the src/tools directory are designed for
192 RELEASE_CHANGES changes we have to make for each release
193 backend description/flowchart of the backend directories
194 ccsym find standard defines made by your compiler
195 copyright fixes copyright notices
197 entab converts tabs to spaces, used by pgindent
198 find_static finds functions that could be made static
199 find_typedef finds typedefs in the source code
200 find_badmacros finds macros that use braces incorrectly
201 fsync a script to provide information about the cost of cache
203 make_ctags make vi 'tags' file in each directory
204 make_diff make *.orig and diffs of source
205 make_etags make emacs 'etags' files
206 make_keywords make comparison of our keywords and SQL'92
207 make_mkid make mkid ID files
208 pgcvslog used to generate a list of changes for each release
209 pginclude scripts for adding/removing include files
210 pgindent indents source files
211 pgtest a semi-automated build system
212 thread a thread testing script
214 In src/include/catalog:
215 unused_oids a script which generates unused OIDs for use in system
217 duplicate_oids finds duplicate OIDs in system catalog definitions
219 If you point your browser at the tools/backend/index.html file, you
220 will see few paragraphs describing the data flow, the backend
221 components in a flow chart, and a description of the shared memory
222 area. You can click on any flowchart box to see a description. If you
223 then click on the directory name, you will be taken to the source
224 directory, to browse the actual source code behind it. We also have
225 several README files in some source directories to describe the
226 function of the module. The browser will display these when you enter
227 the directory also. The tools/backend directory is also contained on
228 our web page under the title How PostgreSQL Processes a Query.
230 Second, you really should have an editor that can handle tags, so you
231 can tag a function call to see the function definition, and then tag
232 inside that function to see an even lower-level function, and then
233 back out twice to return to the original function. Most editors
234 support this via tags or etags files.
236 Third, you need to get id-utils from ftp://ftp.gnu.org/gnu/id-utils/
238 By running tools/make_mkid, an archive of source symbols can be
239 created that can be rapidly queried.
241 Some developers make use of cscope, which can be found at
242 http://cscope.sf.net/. Others use glimpse, which can be found at
243 http://webglimpse.net/.
245 tools/make_diff has tools to create patch diff files that can be
246 applied to the distribution. This produces context diffs, which is our
249 Our standard format is to indent each code level with one tab, where
250 each tab is four spaces. You will need to set your editor to display
260 M-x set-variable tab-width
266 (indent-tabs-mode . t)
272 nil ) ; t = set this style, nil = don't
274 (defun pgsql-c-mode ()
276 (c-set-style "pgsql")
279 and add this to your autoload list (modify file path in macro):
281 (setq auto-mode-alist
282 (cons '("\\`/home/andrew/pgsql/.*\\.[chyl]\\'" . pgsql-c-mode)
293 pgindent will the format code by specifying flags to your operating
294 system's utility indent. This article describes the value of a
295 consistent coding style.
297 pgindent is run on all source files just before each beta test period.
298 It auto-formats all source files to make them consistent. Comment
299 blocks that need specific line breaks should be formatted as block
300 comments, where the comment starts as /*------. These comments will
301 not be reformatted in any way.
303 pginclude contains scripts used to add needed #include's to include
304 files, and removed unneeded #include's.
306 When adding system types, you will need to assign oids to them. There
307 is also a script called unused_oids in pgsql/src/include/catalog that
308 shows the unused oids.
310 1.10) What books are good for developers?
312 I have four good books, An Introduction to Database Systems, by C.J.
313 Date, Addison, Wesley, A Guide to the SQL Standard, by C.J. Date, et.
314 al, Addison, Wesley, Fundamentals of Database Systems, by Elmasri and
315 Navathe, and Transaction Processing, by Jim Gray, Morgan, Kaufmann
317 There is also a database performance site, with a handbook on-line
318 written by Jim Gray at http://www.benchmarkresources.com..
320 1.11) What is configure all about?
322 The files configure and configure.in are part of the GNU autoconf
323 package. Configure allows us to test for various capabilities of the
324 OS, and to set variables that can then be tested in C programs and
325 Makefiles. Autoconf is installed on the PostgreSQL main server. To add
326 options to configure, edit configure.in, and then run autoconf to
329 When configure is run by the user, it tests various OS capabilities,
330 stores those in config.status and config.cache, and modifies a list of
331 *.in files. For example, if there exists a Makefile.in, configure
332 generates a Makefile that contains substitutions for all @var@
333 parameters found by configure.
335 When you need to edit files, make sure you don't waste time modifying
336 files generated by configure. Edit the *.in file, and re-run configure
337 to recreate the needed file. If you run make distclean from the
338 top-level source directory, all files derived by configure are
339 removed, so you see only the file contained in the source
342 1.12) How do I add a new port?
344 There are a variety of places that need to be modified to add a new
345 port. First, start in the src/template directory. Add an appropriate
346 entry for your OS. Also, use src/config.guess to add your OS to
347 src/template/.similar. You shouldn't match the OS version exactly. The
348 configure test will look for an exact OS version number, and if not
349 found, find a match without version number. Edit src/configure.in to
350 add your new OS. (See configure item above.) You will need to run
351 autoconf, or patch src/configure too.
353 Then, check src/include/port and add your new OS file, with
354 appropriate values. Hopefully, there is already locking code in
355 src/include/storage/s_lock.h for your CPU. There is also a
356 src/makefiles directory for port-specific Makefile handling. There is
357 a backend/port directory if you need special files for your OS.
359 1.13) Why don't you use threads, raw devices, async-I/O, <insert your
360 favorite wizz-bang feature here>?
362 There is always a temptation to use the newest operating system
363 features as soon as they arrive. We resist that temptation.
365 First, we support 15+ operating systems, so any new feature has to be
366 well established before we will consider it. Second, most new
367 wizz-bang features don't provide dramatic improvements. Third, they
368 usually have some downside, such as decreased reliability or
369 additional code required. Therefore, we don't rush to use new features
370 but rather wait for the feature to be established, then ask for
371 testing to show that a measurable improvement is possible.
373 As an example, threads are not currently used in the backend code
375 * Historically, threads were unsupported and buggy.
376 * An error in one backend can corrupt other backends.
377 * Speed improvements using threads are small compared to the
378 remaining backend startup time.
379 * The backend code would be more complex.
381 So, we are not ignorant of new features. It is just that we are
382 cautious about their adoption. The TODO list often contains links to
383 discussions showing our reasoning in these areas.
385 1.14) How are RPMs packaged?
387 This was written by Lamar Owen:
391 As to how the RPMs are built -- to answer that question sanely
392 requires me to know how much experience you have with the whole RPM
393 paradigm. 'How is the RPM built?' is a multifaceted question. The
394 obvious simple answer is that I maintain:
395 1. A set of patches to make certain portions of the source tree
396 'behave' in the different environment of the RPMset;
398 3. Any other ancillary scripts and files;
399 4. A README.rpm-dist document that tries to adequately document both
400 the differences between the RPM build and the WHY of the
401 differences, as well as useful RPM environment operations (like,
402 using syslog, upgrading, getting postmaster to start at OS boot,
404 5. The spec file that throws it all together. This is not a trivial
405 undertaking in a package of this size.
407 I then download and build on as many different canonical distributions
408 as I can -- currently I am able to build on Red Hat 6.2, 7.0, and 7.1
409 on my personal hardware. Occasionally I receive opportunity from
410 certain commercial enterprises such as Great Bridge and PostgreSQL,
411 Inc. to build on other distributions.
413 I test the build by installing the resulting packages and running the
414 regression tests. Once the build passes these tests, I upload to the
415 postgresql.org ftp server and make a release announcement. I am also
416 responsible for maintaining the RPM download area on the ftp site.
418 You'll notice I said 'canonical' distributions above. That simply
419 means that the machine is as stock 'out of the box' as practical --
420 that is, everything (except select few programs) on these boxen are
421 installed by RPM; only official Red Hat released RPMs are used (except
422 in unusual circumstances involving software that will not alter the
423 build -- for example, installing a newer non-RedHat version of the Dia
424 diagramming package is OK -- installing Python 2.1 on the box that has
425 Python 1.5.2 installed is not, as that alters the PostgreSQL build).
426 The RPM as uploaded is built to as close to out-of-the-box pristine as
427 is possible. Only the standard released 'official to that release'
428 compiler is used -- and only the standard official kernel is used as
431 For a time I built on Mandrake for RedHat consumption -- no more.
432 Nonstandard RPM building systems are worse than useless. Which is not
433 to say that Mandrake is useless! By no means is Mandrake useless --
434 unless you are building Red Hat RPMs -- and Red Hat is useless if
435 you're trying to build Mandrake or SuSE RPMs, for that matter. But I
436 would be foolish to use 'Lamar Owen's Super Special RPM Blend Distro
437 0.1.2' to build for public consumption! :-)
439 I _do_ attempt to make the _source_ RPM compatible with as many
440 distributions as possible -- however, since I have limited resources
441 (as a volunteer RPM maintainer) I am limited as to the amount of
442 testing said build will get on other distributions, architectures, or
445 And, while I understand people's desire to immediately upgrade to the
446 newest version, realize that I do this as a side interest -- I have a
447 regular, full-time job as a broadcast
448 engineer/webmaster/sysadmin/Technical Director which occasionally
449 prevents me from making timely RPM releases. This happened during the
450 early part of the 7.1 beta cycle -- but I believe I was pretty much on
451 the ball for the Release Candidates and the final release.
453 I am working towards a more open RPM distribution -- I would dearly
454 love to more fully document the process and put everything into CVS --
455 once I figure out how I want to represent things such as the spec file
456 in a CVS form. It makes no sense to maintain a changelog, for
457 instance, in the spec file in CVS when CVS does a better job of
458 changelogs -- I will need to write a tool to generate a real spec file
459 from a CVS spec-source file that would add version numbers, changelog
460 entries, etc to the result before building the RPM. IOW, I need to
461 rethink the process -- and then go through the motions of putting my
462 long RPM history into CVS one version at a time so that version
463 history information isn't lost.
465 As to why all these files aren't part of the source tree, well, unless
466 there was a large cry for it to happen, I don't believe it should.
467 PostgreSQL is very platform-agnostic -- and I like that. Including the
468 RPM stuff as part of the Official Tarball (TM) would, IMHO, slant that
469 agnostic stance in a negative way. But maybe I'm too sensitive to
470 that. I'm not opposed to doing that if that is the consensus of the
471 core group -- and that would be a sneaky way to get the stuff into CVS
472 :-). But if the core group isn't thrilled with the idea (and my
473 instinct says they're not likely to be), I am opposed to the idea --
474 not to keep the stuff to myself, but to not hinder the
475 platform-neutral stance. IMHO, of course.
477 Of course, there are many projects that DO include all the files
478 necessary to build RPMs from their Official Tarball (TM).
480 1.15) How are CVS branches managed?
482 This was written by Tom Lane:
486 If you just do basic "cvs checkout", "cvs update", "cvs commit", then
487 you'll always be dealing with the HEAD version of the files in CVS.
488 That's what you want for development, but if you need to patch past
489 stable releases then you have to be able to access and update the
490 "branch" portions of our CVS repository. We normally fork off a branch
491 for a stable release just before starting the development cycle for
494 The first thing you have to know is the branch name for the branch you
495 are interested in getting at. To do this, look at some long-lived
496 file, say the top-level HISTORY file, with "cvs status -v" to see what
497 the branch names are. (Thanks to Ian Lance Taylor for pointing out
498 that this is the easiest way to do it.) Typical branch names are:
503 OK, so how do you do work on a branch? By far the best way is to
504 create a separate checkout tree for the branch and do your work in
505 that. Not only is that the easiest way to deal with CVS, but you
506 really need to have the whole past tree available anyway to test your
507 work. (And you *better* test your work. Never forget that dot-releases
508 tend to go out with very little beta testing --- so whenever you
509 commit an update to a stable branch, you'd better be doubly sure that
512 Normally, to checkout the head branch, you just cd to the place you
513 want to contain the toplevel "pgsql" directory and say
514 cvs ... checkout pgsql
516 To get a past branch, you cd to wherever you want it and say
517 cvs ... checkout -r BRANCHNAME pgsql
519 For example, just a couple days ago I did
520 mkdir ~postgres/REL7_1
522 cvs ... checkout -r REL7_1_STABLE pgsql
524 and now I have a maintenance copy of 7.1.*.
526 When you've done a checkout in this way, the branch name is "sticky":
527 CVS automatically knows that this directory tree is for the branch,
528 and whenever you do "cvs update" or "cvs commit" in this tree, you'll
529 fetch or store the latest version in the branch, not the head version.
532 So, if you have a patch that needs to apply to both the head and a
533 recent stable branch, you have to make the edits and do the commit
534 twice, once in your development tree and once in your stable branch
535 tree. This is kind of a pain, which is why we don't normally fork the
536 tree right away after a major release --- we wait for a dot-release or
537 two, so that we won't have to double-patch the first wave of fixes.
539 1.16) Where can I get a copy of the SQL standards?
541 There are three versions of the SQL standard: SQL-92, SQL:1999, and
542 SQL:2003. They are endorsed by ANSI and ISO. Draft versions can be
544 * SQL-92 http://www.contrib.andrew.cmu.edu/~shadow/sql/sql1992.txt
546 http://www.cse.iitb.ac.in/dbms/Data/Papers-Other/SQL1999/ansi-iso-
548 * SQL:2003 http://www.wiscorp.com/sql/sql_2003_standard.zip
550 Some SQL standards web pages are:
551 * http://troels.arvin.dk/db/rdbms/links/#standards
552 * http://www.wiscorp.com/SQLStandards.html
553 * http://www.contrib.andrew.cmu.edu/~shadow/sql.html#syntax (SQL-92)
554 * http://dbs.uni-leipzig.de/en/lokal/standards.pdf (paper)
556 1.17) Where can I get technical assistance?
558 Many technical questions held by those new to the code have been
559 answered on the pgsql-hackers mailing list - the archives of which can
560 be found at http://archives.postgresql.org/pgsql-hackers/.
562 If you cannot find discussion or your particular question, feel free
563 to put it to the list.
565 Major contributors also answer technical questions, including
566 questions about development of new features, on IRC at
567 irc.freenode.net in the #postgresql channel.
569 1.18) How do I get involved in PostgreSQL web site development?
571 PostgreSQL website development is discussed on the
572 pgsql-www@postgresql.org mailing list. The is a project page where the
573 source code is available at
574 http://gborg.postgresql.org/project/pgweb/projdisplay.php , the code
575 for the next version of the website is under the "portal" module. You
576 will also find code for the "techdocs" website if you would like to
577 contribute to that. A temporary todo list for current website
578 development issues is available at http://xzilla.postgresql.org/todo
582 2.1) How do I efficiently access information in tables from the backend code?
584 You first need to find the tuples(rows) you are interested in. There
585 are two ways. First, SearchSysCache() and related functions allow you
586 to query the system catalogs. This is the preferred way to access
587 system tables, because the first call to the cache loads the needed
588 rows, and future requests can return the results without accessing the
589 base table. The caches use system table indexes to look up tuples. A
590 list of available caches is located in
591 src/backend/utils/cache/syscache.c.
592 src/backend/utils/cache/lsyscache.c contains many column-specific
593 cache lookup functions.
595 The rows returned are cache-owned versions of the heap rows.
596 Therefore, you must not modify or delete the tuple returned by
597 SearchSysCache(). What you should do is release it with
598 ReleaseSysCache() when you are done using it; this informs the cache
599 that it can discard that tuple if necessary. If you neglect to call
600 ReleaseSysCache(), then the cache entry will remain locked in the
601 cache until end of transaction, which is tolerable but not very
604 If you can't use the system cache, you will need to retrieve the data
605 directly from the heap table, using the buffer cache that is shared by
606 all backends. The backend automatically takes care of loading the rows
607 into the buffer cache.
609 Open the table with heap_open(). You can then start a table scan with
610 heap_beginscan(), then use heap_getnext() and continue as long as
611 HeapTupleIsValid() returns true. Then do a heap_endscan(). Keys can be
612 assigned to the scan. No indexes are used, so all rows are going to be
613 compared to the keys, and only the valid rows returned.
615 You can also use heap_fetch() to fetch rows by block number/offset.
616 While scans automatically lock/unlock rows from the buffer cache, with
617 heap_fetch(), you must pass a Buffer pointer, and ReleaseBuffer() it
620 Once you have the row, you can get data that is common to all tuples,
621 like t_self and t_oid, by merely accessing the HeapTuple structure
622 entries. If you need a table-specific column, you should take the
623 HeapTuple pointer, and use the GETSTRUCT() macro to access the
624 table-specific start of the tuple. You then cast the pointer as a
625 Form_pg_proc pointer if you are accessing the pg_proc table, or
626 Form_pg_type if you are accessing pg_type. You can then access the
627 columns by using a structure pointer:
628 ((Form_pg_class) GETSTRUCT(tuple))->relnatts
630 You must not directly change live tuples in this way. The best way is
631 to use heap_modifytuple() and pass it your original tuple, and the
632 values you want changed. It returns a palloc'ed tuple, which you pass
633 to heap_replace(). You can delete tuples by passing the tuple's t_self
634 to heap_destroy(). You use t_self for heap_update() too. Remember,
635 tuples can be either system cache copies, which might go away after
636 you call ReleaseSysCache(), or read directly from disk buffers, which
637 go away when you heap_getnext(), heap_endscan, or ReleaseBuffer(), in
638 the heap_fetch() case. Or it may be a palloc'ed tuple, that you must
639 pfree() when finished.
641 2.2) Why are table, column, type, function, view names sometimes referenced
642 as Name or NameData, and sometimes as char *?
644 Table, column, type, function, and view names are stored in system
645 tables in columns of type Name. Name is a fixed-length,
646 null-terminated type of NAMEDATALEN bytes. (The default value for
647 NAMEDATALEN is 64 bytes.)
648 typedef struct nameData
650 char data[NAMEDATALEN];
652 typedef NameData *Name;
654 Table, column, type, function, and view names that come into the
655 backend via user queries are stored as variable-length,
656 null-terminated character strings.
658 Many functions are called with both types of names, ie. heap_open().
659 Because the Name type is null-terminated, it is safe to pass it to a
660 function expecting a char *. Because there are many cases where
661 on-disk names(Name) are compared to user-supplied names(char *), there
662 are many cases where Name and char * are used interchangeably.
664 2.3) Why do we use Node and List to make data structures?
666 We do this because this allows a consistent way to pass data inside
667 the backend in a flexible way. Every node has a NodeTag which
668 specifies what type of data is inside the Node. Lists are groups of
669 Nodes chained together as a forward-linked list.
671 Here are some of the List manipulation commands:
673 lfirst(i), lfirst_int(i), lfirst_oid(i)
674 return the data (a point, integer and OID respectively) at list
678 return the next list element after i.
681 loop through list, assigning each list element to i. It is
682 important to note that i is a List *, not the data in the List
683 element. You need to use lfirst(i) to get at the data. Here is
684 a typical code snippet that loops through a List containing Var
685 *'s and processes each one:
692 Var *var = lfirst(i);
694 /* process var here */
698 add node to the front of list, or create a new list with node
702 add node to the end of list. This is more expensive that lcons.
705 Concat list2 on to the end of list1.
708 return the length of the list.
711 return the i'th element in list.
714 There are integer versions of these: lconsi, lappendi, etc.
715 Also versions for OID lists: lconso, lappendo, etc.
717 You can print nodes easily inside gdb. First, to disable output
718 truncation when you use the gdb print command:
719 (gdb) set print elements 0
721 Instead of printing values in gdb format, you can use the next two
722 commands to print out List, Node, and structure contents in a verbose
723 format that is easier to understand. List's are unrolled into nodes,
724 and nodes are printed in detail. The first prints in a short format,
725 and the second in a long format:
726 (gdb) call print(any_pointer)
727 (gdb) call pprint(any_pointer)
729 The output appears in the postmaster log file, or on your screen if
730 you are running a backend directly without a postmaster.
732 2.4) I just added a field to a structure. What else should I do?
734 The structures passing around from the parser, rewrite, optimizer, and
735 executor require quite a bit of support. Most structures have support
736 routines in src/backend/nodes used to create, copy, read, and output
737 those structures (in particular, the files copyfuncs.c and
738 equalfuncs.c. Make sure you add support for your new field to these
739 files. Find any other places the structure might need code for your
740 new field. mkid is helpful with this (see 1.9).
742 2.5) Why do we use palloc() and pfree() to allocate memory?
744 palloc() and pfree() are used in place of malloc() and free() because
745 we find it easier to automatically free all memory allocated when a
746 query completes. This assures us that all memory that was allocated
747 gets freed even if we have lost track of where we allocated it. There
748 are special non-query contexts that memory can be allocated in. These
749 affect when the allocated memory is freed by the backend.
751 2.6) What is ereport()?
753 ereport() is used to send messages to the front-end, and optionally
754 terminate the current query being processed. The first parameter is an
755 ereport level of DEBUG (levels 1-5), LOG, INFO, NOTICE, ERROR, FATAL,
756 or PANIC. NOTICE prints on the user's terminal and the postmaster
757 logs. INFO prints only to the user's terminal and LOG prints only to
758 the server logs. (These can be changed from postgresql.conf.) ERROR
759 prints in both places, and terminates the current query, never
760 returning from the call. FATAL terminates the backend process. The
761 remaining parameters of ereport are a printf-style set of parameters
764 ereport(ERROR) frees most memory and open file descriptors so you
765 don't need to clean these up before the call.
767 2.7) What is CommandCounterIncrement()?
769 Normally, transactions can not see the rows they modify. This allows
770 UPDATE foo SET x = x + 1 to work correctly.
772 However, there are cases where a transactions needs to see rows
773 affected in previous parts of the transaction. This is accomplished
774 using a Command Counter. Incrementing the counter allows transactions
775 to be broken into pieces so each piece can see rows modified by
776 previous pieces. CommandCounterIncrement() increments the Command
777 Counter, creating a new part of the transaction.
779 2.8) What debugging features are available?
781 First, try running configure with the --enable-cassert option, many
782 assert()s monitor the progress of the backend and halt the program
783 when something unexpected occurs.
785 The postmaster has a -d option that allows even more detailed
786 information to be reported. The -d option takes a number that
787 specifies the debug level. Be warned that high debug level values
788 generate large log files.
790 If the postmaster is not running, you can actually run the postgres
791 backend from the command line, and type your SQL statement directly.
792 This is recommended only for debugging purposes. If you have compiled
793 with debugging symbols, you can use a debugger to see what is
794 happening. Because the backend was not started from postmaster, it is
795 not running in an identical environment and locking/backend
796 interaction problems might not be duplicated.
798 If the postmaster is running, start psql in one window, then find the
799 PID of the postgres process used by psql using SELECT
800 pg_backend_pid(). Use a debugger to attach to the postgres PID. You
801 can set breakpoints in the debugger and issue queries from psql. If
802 you are debugging postgres startup, you can set PGOPTIONS="-W n", then
803 start psql. This will cause startup to delay for n seconds so you can
804 attach to the process with the debugger, set any breakpoints, and
805 continue through the startup sequence.
807 You can also compile with profiling to see what functions are taking
808 execution time. The backend profile files will be deposited in the
809 pgsql/data/base/dbname directory. The client profile file will be put
810 in the client's current directory. Linux requires a compile with
811 -DLINUX_PROFILE for proper profiling.