146 lines
6.9 KiB
Plaintext
146 lines
6.9 KiB
Plaintext
Developer's Frequently Asked Questions (FAQ) for PostgreSQL
|
|
|
|
Last updated: Wed Feb 11 20:23:01 EST 1998
|
|
|
|
Current maintainer: Bruce Momjian (maillist@candle.pha.pa.us)
|
|
|
|
The most recent version of this document can be viewed at the postgreSQL Web
|
|
site, http://postgreSQL.org.
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
Questions answered:
|
|
|
|
1) What tools are available for developers?
|
|
2) What books are good for developers?
|
|
3) Why do we use palloc() and pfree() to allocate memory?
|
|
4) Why do we use Node and List to make data structures?
|
|
5) How do I add a feature or fix a bug?
|
|
6) How do I download/update the current source tree?
|
|
7) How do I test my changes?
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
1) What tools are available for developers?
|
|
|
|
Aside from the User documentation mentioned in the regular FAQ, there
|
|
are several development tools available. First, all the files in the
|
|
pgsql/src/tools directory are designed for developers.
|
|
|
|
RELEASE_CHANGES changes we have to make for each release
|
|
SQL_keywords standard SQL'92 keywords
|
|
backend web flowchart of the backend directories
|
|
ccsym find standard defines made by your compiler
|
|
entab converts tabs to spaces, used by pgindent
|
|
find_static finds functions that could be made static
|
|
find_typedef get a list of typedefs in the source code
|
|
make_ctags make vi 'tags' file in each directory
|
|
make_diff make *.orig and diffs of source
|
|
make_etags make emacs 'etags' files
|
|
make_keywords.README make comparison of our keywords and SQL'92
|
|
make_mkid make mkid ID files
|
|
mkldexport create AIX exports file
|
|
pgindent indents C source files
|
|
|
|
Let me note some of these. If you point your browser at the
|
|
pgsql/src/tools/backend directory, you will see all the backend
|
|
components in a flow chart. You can click on any one to see a
|
|
description. If you then click on the directory name, you will be taken
|
|
to the source directory, to browse the actual source code behind it. We
|
|
also have several README files in some source directories to describe
|
|
the function of the module. The browser will display these when you
|
|
enter the directory also. The pgsql/src/tools/backend directory is also
|
|
contained on our web page under the title Backend Flowchart.
|
|
|
|
Second, you really should have an editor that can handle tags, so you can
|
|
tag a function call to see the function definition, and then tag inside that
|
|
function to see an even lower-level function, and then back out twice to
|
|
return to the original function. Most editors support this via tags or etags
|
|
files.
|
|
|
|
Third, you need to get mkid from ftp.postgresql.org. By running
|
|
tools/make_mkid, an archive of source symbols can be created that can be
|
|
rapidly queried like grep or edited.
|
|
|
|
make_diff has tools to create patch diff files that can be applied to the
|
|
distribution.
|
|
|
|
pgindent will format source files to match our standard format, which has
|
|
four-space tabs, and an indenting format specified by flags to the your
|
|
operating system's utility indent.
|
|
|
|
2) What books are good for developers?
|
|
|
|
I have three good books, An Introduction to Database Systems, by C.J. Date,
|
|
Addison, Wesley, A Guide to the SQL Standard, by C.J. Date, et. al,
|
|
Addison, Wesley, and Transaction Processing: Concepts and Techniques,
|
|
by Jim Gray and Andreas Reuter, Morgan, Kaufmann.
|
|
|
|
3) Why do we use palloc() and pfree() to allocate memory?
|
|
|
|
palloc() and pfree() are used in place of malloc() and free() because we
|
|
automatically free all memory allocated when a transaction completes. This
|
|
makes it easier to make sure we free memory that gets allocated in one
|
|
place, but only freed much later. There are several contexts that memory can
|
|
be allocated in, and this controls when the allocated memory is
|
|
automatically freed by the backend.
|
|
|
|
4) Why do we use Node and List to make data structures?
|
|
|
|
We do this because this allows a consistent way to pass data inside the
|
|
backend in a flexible way. Every node has a NodeTag which specifies what
|
|
type of data is inside the Node. Lists are lists of Nodes. lfirst(),
|
|
lnext(), and foreach() are used to get, skip, and traverse through Lists.
|
|
|
|
5) How do I add a feature or fix a bug?
|
|
|
|
The source code is over 250,000 lines. Many problems/features are isolated
|
|
to one specific area of the code. Others require knowledge of much of the
|
|
source. If you are confused about where to start, ask the hackers list, and
|
|
they will be glad to assess the complexity and give pointers on where to
|
|
start.
|
|
|
|
Another thing to keep in mind is that many fixes and features can be added
|
|
with surprisingly little code. I often start by adding code, then looking at
|
|
other areas in the code where similar things are done, and by the time I am
|
|
finished, the patch is quite small and compact.
|
|
|
|
When adding code, keep in mind that it should use the existing facilities in
|
|
the source, for performance reasons and for simplicity. Often a review of
|
|
existing code doing similar things is helpful.
|
|
|
|
6) How do I download/update the current source tree?
|
|
|
|
There are several ways to obtain the source tree. Occasional developers can
|
|
just get the most recent source tree snapshot from ftp.postgresql.org. For
|
|
regular developers, you can use CVSup, which is available from
|
|
ftp.postgresql.org too. CVSup allows you to download the source tree, then
|
|
occasionally update your copy of the source tree with any new changes. Using
|
|
CVSup, you don't have to download the entire source each time, only the
|
|
changed files. CVSup does not allow developers to update the source tree.
|
|
|
|
Anonymous CVS is available too. See the doc/FAQ_CVS file for more
|
|
information.
|
|
|
|
To update the source tree, there are two ways. You can generate a patch
|
|
against your current source tree, perhaps using the make_diff tools
|
|
mentioned above, and send them to the patches list. They will be reviewed,
|
|
and applied in a timely manner. If the patch is major, and we are in beta
|
|
testing, the developers may wait for the final release before applying your
|
|
patches.
|
|
|
|
For hard-core developers, Marc(scrappy@postgresql.org) will give you a Unix
|
|
shell account on postgresql.org, and you can ftp your files into your
|
|
account, patch, and cvs install the changes directly into the source tree.
|
|
|
|
6) How do I test my changes?
|
|
|
|
First, use psql to make sure it is working as you expect. Then run
|
|
src/test/regress and get the output of src/test/regress/checkresults with
|
|
and without your changes, to see that your patch does not change the
|
|
regression test in unexpected ways. This practice has saved me many times.
|
|
The regression tests test the code in ways I would never do, and has caught
|
|
many bugs in my patches. By finding the problems now, you save yourself a
|
|
lot of debugging later when things are broken, and you can't figure out when
|
|
it happened.
|