A Pure-Python PostgreSQL Driver

README.creole 3.1KB

=pg8000

pg8000 is a pure-[[http://www.python.org/|Python]]
[[http://www.postgresql.org/|PostgreSQL]] driver that complies with
[[http://www.python.org/dev/peps/pep-0249/|DB-API 2.0]]. The driver
communicates with the database using the
[[http://www.postgresql.org/docs/9.3/static/protocol.html|PostgreSQL Backend / Frontend Protocol]].

CircleCI [[https://circleci.com/gh/mfenniak/pg8000|Build Status]]: {{https://circleci.com/gh/mfenniak/pg8000.png?style=badge|CircleCI}}

Links:

* [[http://pythonhosted.org/pg8000/|User Docs]].
* [[https://groups.google.com/forum/#!forum/pg8000|Forum]]
* [[https://github.com/mfenniak/pg8000|Code, bugs, feature requests etc.]]

=Regression Tests

To run the regression tests, install [[http://testrun.org/tox/latest/|tox]]:

{{{
pip install tox
}}}

then install all the supported Python versions (using the
[[https://launchpad.net/~fkrull/+archive/ubuntu/deadsnakes|APT Repository]] if
you're using Ubuntu. Install all the currently supported versions of PostgreSQL
(using the [[http://wiki.postgresql.org/wiki/Apt|APT Repository]] if you're
using Ubuntu. Then for each of them, enable the hstore extension by running the
SQL command:

{{{
create extension hstore;
}}}

and add a line to pg_hba.conf for the various authentication options, eg.

{{{
host pg8000_md5 all 127.0.0.1/32 md5
host pg8000_gss all 127.0.0.1/32 gss
host pg8000_password all 127.0.0.1/32 password
host all all 127.0.0.1/32 trust
}}}

Set the following environment variables for the databases, for example:

{{{
export PG8000_TEST_NAME="PG8000_TEST_9_4"
export PG8000_TEST_9_0="{'user': 'postgres', 'password': 'pw', 'port': 5432}"
export PG8000_TEST_9_1="{'user': 'postgres', 'password': 'pw', 'port': 5433}"
export PG8000_TEST_9_2="{'user': 'postgres', 'password': 'pw', 'port': 5434}"
export PG8000_TEST_9_3="{'user': 'postgres', 'password': 'pw', 'port': 5435}"
export PG8000_TEST_9_4="{'user': 'postgres', 'password': 'pw', 'port': 5436}"
}}}

then run {{{tox}}} from the {{{pg8000}}} directory:

{{{
tox
}}}

Unfortunately, {{{tox}}} doesn't support Python 2.5, so to test CPython 2.5 and
Jython 2.5, run the {{{run_25}}} script.

==Performance Tests

To run the performance tests from the {{{pg8000}}} directory:

{{{
python -m pg8000.tests.performance
}}}

==Stress Test

There's a stress test that is run by doing:

{{{
python ./multi
}}}

The idea is to set {{{shared_buffers}}} in postgresql.conf to 128kB, and then
run the stress test, and you should get {{{no unpinned buffers}}} errors.

=Building The Documentation

The docs are written using [[http://sphinx-doc.org/|Sphinx]]. To build them,
install sphinx:

{{{
pip install sphinx
}}}

Then type:

{{{
python setup.py build_sphinx
}}}

and the docs will appear in {{{build/sphinx/html}}}.

=Doing A Release Of pg8000

Run {{{tox}}} and {{{run_25}}} to make sure all tests pass, then update
{{{doc/release_notes.rst}}} then do:

{{{
git tag -a x.y.z -m "Version x.y.z"
python setup.py register sdist bdist_wheel upload build_sphinx upload_docs
}}}

Then post a message to the forum.