Developer's Frequently Asked Questions (FAQ) for PostgreSQL
- Last updated: Fri May 6 13:47:54 EDT 2005
+ Last updated: Sat May 14 12:26:01 EDT 2005
Current maintainer: Bruce Momjian (pgman@candle.pha.pa.us)
1.2) What development environment is required to develop code?
1.3) What areas need work?
1.4) What do I do after choosing an item to work on?
- 1.5) Where can I learn more about the code?
- 1.6) I've developed a patch, what next?
+ 1.5) I've developed a patch, what next?
+ 1.6) Where can I learn more about the code?
1.7) How do I download/update the current source tree?
1.8) How do I test my changes?
1.9) What tools are available for developers?
Send an email to pgsql-hackers with a proposal for what you want to do
(assuming your contribution is not trivial). Working in isolation is
- not advisable: others may be working on the same TODO item; you may
- have misunderstood the TODO item; your approach may benefit from the
- review of others.
+ not advisable because others might be working on the same TODO item,
+ or you might have misunderstood the TODO item. In the email, discuss
+ both the internal implementation method you plan to use, and any
+ user-visible changes (new syntax, etc). For complex patches, it is
+ important to get community feeback on your proposal before starting
+ work. Failure to do so might mean your patch is rejected.
A web site is maintained for patches that are ready to be applied,
http://momjian.postgresql.org/cgi-bin/pgpatches, and those that are
being kept for the next release,
http://momjian.postgresql.org/cgi-bin/pgpatches2.
- 1.5) Where can I learn more about the code?
-
- Other than documentation in the source tree itself, you can find some
- papers/presentations discussing the code at
- http://www.postgresql.org/developer.
-
- 1.6) I've developed a patch, what next?
+ 1.5) I've developed a patch, what next?
Generate the patch in contextual diff format. If you are unfamiliar
- with this, you may find the script src/tools/makediff/difforig useful.
+ with this, you might find the script src/tools/makediff/difforig
+ useful.
Ensure that your patch is generated against the most recent version of
the code. If it is a patch adding new functionality, the most recent
- version is cvs HEAD; if it is a bug fix, this will be the most
+ version is CVS HEAD; if it is a bug fix, this will be the most
recently version of the branch which suffers from the bug (for more on
branches in PostgreSQL, see 1.15).
Finally, submit the patch to pgsql-patches@postgresql.org. It will be
- reviewed by other contributors to the project and may be either
- accepted or sent back for further work.
+ reviewed by other contributors to the project and will be either
+ accepted or sent back for further work. Also, please try to include
+ documentation changes as part of the patch. If you can't do that, let
+ us know and we will manually update the documentation when the patch
+ is applied.
+
+ 1.6) Where can I learn more about the code?
+
+ Other than documentation in the source tree itself, you can find some
+ papers/presentations discussing the code at
+ http://www.postgresql.org/developer.
1.7) How do I download/update the current source tree?
developers can just get the most recent source tree snapshot from
ftp://ftp.postgresql.org.
- Regular developers may want to take advantage of anonymous access to
+ Regular developers might want to take advantage of anonymous access to
our source code management system. The source tree is currently hosted
in CVS. For details of how to obtain the source from CVS see
http://developer.postgresql.org/docs/postgres/cvs.html.
test suite. To do this, issue "make check" in the root directory of
the source tree. If any tests failure, investigate.
- If you've deliberately changed existing behavior, this change may
+ If you've deliberately changed existing behavior, this change might
cause a regression test failure but not any actual regression. If so,
you should also patch the regression test suite.
values you want changed. It returns a palloc'ed tuple, which you pass
to heap_replace(). You can delete tuples by passing the tuple's t_self
to heap_destroy(). You use t_self for heap_update() too. Remember,
- tuples can be either system cache copies, which may go away after you
- call ReleaseSysCache(), or read directly from disk buffers, which go
- away when you heap_getnext(), heap_endscan, or ReleaseBuffer(), in the
- heap_fetch() case. Or it may be a palloc'ed tuple, that you must
+ tuples can be either system cache copies, which might go away after
+ you call ReleaseSysCache(), or read directly from disk buffers, which
+ go away when you heap_getnext(), heap_endscan, or ReleaseBuffer(), in
+ the heap_fetch() case. Or it may be a palloc'ed tuple, that you must
pfree() when finished.
2.2) Why are table, column, type, function, view names sometimes referenced
routines in src/backend/nodes used to create, copy, read, and output
those structures (in particular, the files copyfuncs.c and
equalfuncs.c. Make sure you add support for your new field to these
- files. Find any other places the structure may need code for your new
- field. mkid is helpful with this (see 1.9).
+ files. Find any other places the structure might need code for your
+ new field. mkid is helpful with this (see 1.9).
2.5) Why do we use palloc() and pfree() to allocate memory?
with debugging symbols, you can use a debugger to see what is
happening. Because the backend was not started from postmaster, it is
not running in an identical environment and locking/backend
- interaction problems may not be duplicated.
+ interaction problems might not be duplicated.
If the postmaster is running, start psql in one window, then find the
PID of the postgres process used by psql using SELECT
<H1>Developer's Frequently Asked Questions (FAQ) for
PostgreSQL</H1>
- <P>Last updated: Fri May 6 13:47:54 EDT 2005</P>
+ <P>Last updated: Sat May 14 12:26:01 EDT 2005</P>
<P>Current maintainer: Bruce Momjian (<A href=
"mailto:pgman@candle.pha.pa.us">pgman@candle.pha.pa.us</A>)<BR>
<A href="#1.3">1.3</A>) What areas need work?<BR>
<A href="#1.4">1.4</A>) What do I do after choosing an item to
work on?<BR>
- <A href="#1.5">1.5</A>) Where can I learn more about the code?<BR>
- <A href="#1.6">1.6</A>) I've developed a patch, what next?<BR>
+ <A href="#1.5">1.5</A>) I've developed a patch, what next?<BR>
+ <A href="#1.6">1.6</A>) Where can I learn more about the code?<BR>
<A href="#1.7">1.7</A>) How do I download/update the current
source tree?<BR>
<A href="#1.8">1.8</A>) How do I test my changes?<BR>
<P>Send an email to pgsql-hackers with a proposal for what you want
to do (assuming your contribution is not trivial). Working in
- isolation is not advisable: others may be working on the same TODO
- item; you may have misunderstood the TODO item; your approach may
- benefit from the review of others.</P>
+ isolation is not advisable because others might be working on the same
+ TODO item, or you might have misunderstood the TODO item. In the
+ email, discuss both the internal implementation method you plan to
+ use, and any user-visible changes (new syntax, etc). For complex
+ patches, it is important to get community feeback on your proposal
+ before starting work. Failure to do so might mean your patch is
+ rejected.</P>
<P>A web site is maintained for patches that are ready to be applied,
<a href="http://momjian.postgresql.org/cgi-bin/pgpatches">
<a href="http://momjian.postgresql.org/cgi-bin/pgpatches2">
http://momjian.postgresql.org/cgi-bin/pgpatches2</a>.</P>
- <H3><A name="1.5">1.5</A>) Where can I learn more about the
- code?</H3>
-
- <P>Other than documentation in the source tree itself, you can find
- some papers/presentations discussing the code at <A href=
- "http://www.postgresql.org/developer">
- http://www.postgresql.org/developer</A>.</P>
-
- <H3><A name="1.6">1.6</A>) I've developed a patch, what next?</H3>
+ <H3><A name="1.5">1.5</A>) I've developed a patch, what next?</H3>
<P>Generate the patch in contextual diff format. If you are
- unfamiliar with this, you may find the script
+ unfamiliar with this, you might find the script
<I>src/tools/makediff/difforig</I> useful.</P>
<P>Ensure that your patch is generated against the most recent
version of the code. If it is a patch adding new functionality, the
- most recent version is cvs HEAD; if it is a bug fix, this will be
+ most recent version is CVS HEAD; if it is a bug fix, this will be
the most recently version of the branch which suffers from the bug
(for more on branches in PostgreSQL, see <A href=
"#1.15">1.15</A>).</P>
<P>Finally, submit the patch to pgsql-patches@postgresql.org. It
- will be reviewed by other contributors to the project and may be
- either accepted or sent back for further work.</P>
+ will be reviewed by other contributors to the project and will be
+ either accepted or sent back for further work. Also, please try to
+ include documentation changes as part of the patch. If you can't do
+ that, let us know and we will manually update the documentation when
+ the patch is applied.</P>
+
+ <H3><A name="1.6">1.6</A>) Where can I learn more about the
+ code?</H3>
+
+ <P>Other than documentation in the source tree itself, you can find
+ some papers/presentations discussing the code at <A href=
+ "http://www.postgresql.org/developer">
+ http://www.postgresql.org/developer</A>.</P>
<H3><A name="1.7">1.7</A>) How do I download/update the current
source tree?</H3>
<A href=
"ftp://ftp.postgresql.org">ftp://ftp.postgresql.org</A>.</P>
- <P>Regular developers may want to take advantage of anonymous
+ <P>Regular developers might want to take advantage of anonymous
access to our source code management system. The source tree is
currently hosted in CVS. For details of how to obtain the source
from CVS see <A href=
investigate.</P>
<P>If you've deliberately changed existing behavior, this change
- may cause a regression test failure but not any actual regression.
+ might cause a regression test failure but not any actual regression.
If so, you should also patch the regression test suite.</P>
<P><B>Other run time testing</B></P>
delete tuples by passing the tuple's <I>t_self</I> to
<I>heap_destroy().</I> You use <I>t_self</I> for
<I>heap_update()</I> too. Remember, tuples can be either system
- cache copies, which may go away after you call
+ cache copies, which might go away after you call
<I>ReleaseSysCache()</I>, or read directly from disk buffers, which
go away when you <I>heap_getnext()</I>, <I>heap_endscan</I>, or
<I>ReleaseBuffer()</I>, in the <I>heap_fetch()</I> case. Or it may
to create, copy, read, and output those structures (in particular,
the files <I>copyfuncs.c</I> and <I>equalfuncs.c</I>. Make sure you
add support for your new field to these files. Find any other
- places the structure may need code for your new field. <I>mkid</I>
+ places the structure might need code for your new field. <I>mkid</I>
is helpful with this (see <A href="#1.9">1.9</A>).</P>
<H3><A name="2.5">2.5</A>) Why do we use <I>palloc</I>() and
symbols, you can use a debugger to see what is happening. Because
the backend was not started from <I>postmaster</I>, it is not
running in an identical environment and locking/backend interaction
- problems may not be duplicated.</P>
+ problems might not be duplicated.</P>
<P>If the <I>postmaster</I> is running, start <I>psql</I> in one
window, then find the <SMALL>PID</SMALL> of the <I>postgres</I>
projects / postgresql / commitdiff