1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Introduction — Psycopg 2.5.4 documentation</title>
<link rel="stylesheet" href="_static/psycopg.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '2.5.4',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="Psycopg 2.5.4 documentation" href="index.html" />
<link rel="next" title="Basic module usage" href="usage.html" />
<link rel="prev" title="Psycopg – PostgreSQL database adapter for Python" href="index.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="usage.html" title="Basic module usage"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="index.html" title="Psycopg – PostgreSQL database adapter for Python"
accesskey="P">previous</a> |</li>
<li><a href="index.html">Psycopg 2.5.4 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="introduction">
<h1>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h1>
<p>Psycopg is a <a class="reference external" href="http://www.postgresql.org/">PostgreSQL</a> adapter for the <a class="reference external" href="http://www.python.org/">Python</a> programming language. It is a
wrapper for the <a class="reference external" href="http://www.postgresql.org/docs/current/static/libpq.html">libpq</a>, the official PostgreSQL client library.</p>
<p>The <a class="reference internal" href="module.html#module-psycopg2" title="psycopg2"><tt class="xref py py-obj docutils literal"><span class="pre">psycopg2</span></tt></a> package is the current mature implementation of the adapter: it
is a C extension and as such it is only compatible with <a class="reference external" href="http://en.wikipedia.org/wiki/CPython">CPython</a>. If you want
to use Psycopg on a different Python implementation (PyPy, Jython, IronPython)
there is an experimental <a class="reference external" href="https://github.com/mvantellingen/psycopg2-ctypes">porting of Psycopg for Ctypes</a>, but it is not as
mature as the C implementation yet.</p>
<p>The current <tt class="xref py py-obj docutils literal"><span class="pre">psycopg2</span></tt> implementation supports:</p>
<ul class="simple">
<li>Python 2 versions from 2.5 to 2.7</li>
<li>Python 3 versions from 3.1 to 3.4</li>
<li>PostgreSQL versions from 7.4 to 9.4</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><tt class="xref py py-obj docutils literal"><span class="pre">psycopg2</span></tt> usually depends at runtime on the libpq dynamic library.
However it can connect to PostgreSQL servers of any supported version,
independently of the version of the libpq used: just install the most
recent libpq version or the most practical, without trying to match it to
the version of the PostgreSQL server you will have to connect to.</p>
</div>
</div>
<div class="section" id="installation">
<h1>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h1>
<p>If possible, and usually it is, please <a class="reference internal" href="#install-from-package"><em>install Psycopg from a package</em></a> available for your distribution or operating system.</p>
<p>Compiling from source is a very easy task, however <tt class="xref py py-obj docutils literal"><span class="pre">psycopg2</span></tt> is a C
extension module and as such it requires a few more things in place respect to
a pure Python module. So, if you don’t have experience compiling Python
extension packages, <em>above all if you are a Windows or a Mac OS user</em>, please
use a pre-compiled package and go straight to the <a class="reference internal" href="usage.html#usage"><em>module usage</em></a>
avoid bothering with the gory details.</p>
<div class="section" id="install-from-a-package">
<span id="install-from-package"></span><h2>Install from a package<a class="headerlink" href="#install-from-a-package" title="Permalink to this headline">¶</a></h2>
<dl class="docutils" id="index-0">
<dt><strong>Linux</strong></dt>
<dd><p class="first">Psycopg is available already packaged in many Linux distributions: look
for a package such as <tt class="docutils literal"><span class="pre">python-psycopg2</span></tt> using the package manager of
your choice.</p>
<p>On Debian, Ubuntu and other deb-based distributions you should just need:</p>
<div class="highlight-python"><div class="highlight"><pre>sudo apt-get install python-psycopg2
</pre></div>
</div>
<p class="last">to install the package with all its dependencies.</p>
</dd>
</dl>
<dl class="docutils" id="index-1">
<dt><strong>Mac OS X</strong></dt>
<dd><p class="first">Psycopg is available as a <a class="reference external" href="http://pdb.finkproject.org/pdb/package.php/psycopg2-py27">fink package</a> in the <em>unstable</em> tree: you may
install it with:</p>
<div class="highlight-python"><div class="highlight"><pre>fink install psycopg2-py27
</pre></div>
</div>
<p>The library is also available on <a class="reference external" href="http://www.macports.org/">MacPorts</a> try:</p>
<div class="last highlight-python"><div class="highlight"><pre>sudo port install py27-psycopg2
</pre></div>
</div>
</dd>
</dl>
<dl class="docutils" id="index-2">
<dt><strong>Microsoft Windows</strong></dt>
<dd>Jason Erickson maintains a packaged <a class="reference external" href="http://www.stickpeople.com/projects/python/win-psycopg/">Windows port of Psycopg</a> with
installation executable. Download. Double click. Done.</dd>
</dl>
</div>
<div class="section" id="install-from-source">
<span id="index-3"></span><span id="id5"></span><h2>Install from source<a class="headerlink" href="#install-from-source" title="Permalink to this headline">¶</a></h2>
<p>These notes illustrate how to compile Psycopg on Linux. If you want to compile
Psycopg on other platforms you may have to adjust some details accordingly.</p>
<p id="requirements">Psycopg is a C wrapper to the libpq PostgreSQL client library. To install it
from sources you will need:</p>
<ul>
<li><p class="first">A C compiler.</p>
</li>
<li><p class="first">The Python header files. They are usually installed in a package such as
<strong>python-dev</strong>. A message such as <em>error: Python.h: No such file or
directory</em> is an indication that the Python headers are missing.</p>
</li>
<li><p class="first">The libpq header files. They are usually installed in a package such as
<strong>libpq-dev</strong>. If you get an <em>error: libpq-fe.h: No such file or directory</em>
you are missing them.</p>
</li>
<li><p class="first">The <strong class="program">pg_config</strong> program: it is usually installed by the
<strong>libpq-dev</strong> package but sometimes it is not in a <span class="target" id="index-4"></span><tt class="xref std std-envvar docutils literal"><span class="pre">PATH</span></tt> directory.
Having it in the <span class="target" id="index-5"></span><tt class="xref std std-envvar docutils literal"><span class="pre">PATH</span></tt> greatly streamlines the installation, so try
running <tt class="docutils literal"><span class="pre">pg_config</span> <span class="pre">--version</span></tt>: if it returns an error or an unexpected
version number then locate the directory containing the <strong class="program">pg_config</strong>
shipped with the right libpq version (usually
<tt class="docutils literal"><span class="pre">/usr/lib/postgresql/X.Y/bin/</span></tt>) and add it to the <span class="target" id="index-6"></span><tt class="xref std std-envvar docutils literal"><span class="pre">PATH</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre>$ export PATH=/usr/lib/postgresql/X.Y/bin/:$PATH
</pre></div>
</div>
<p>You only need it to compile and install <tt class="xref py py-obj docutils literal"><span class="pre">psycopg2</span></tt>, not for its regular
usage.</p>
</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The libpq header files used to compile <tt class="xref py py-obj docutils literal"><span class="pre">psycopg2</span></tt> should match the
version of the library linked at runtime. If you get errors about missing
or mismatching libraries when importing <tt class="xref py py-obj docutils literal"><span class="pre">psycopg2</span></tt> check (e.g. using
<strong class="program">ldd</strong>) if the module <tt class="docutils literal"><span class="pre">psycopg2/_psycopg.so</span></tt> is linked to the
right <tt class="docutils literal"><span class="pre">libpq.so</span></tt>.</p>
</div>
<div class="section" id="use-a-python-package-manager">
<span id="package-manager"></span><span id="index-7"></span><h3>Use a Python package manager<a class="headerlink" href="#use-a-python-package-manager" title="Permalink to this headline">¶</a></h3>
<p>If the above requirements are satisfied, you can use <strong class="program">easy_install</strong>,
<strong class="program">pip</strong> or whatever the Python package manager of the week:</p>
<div class="highlight-python"><div class="highlight"><pre>$ pip install psycopg2
</pre></div>
</div>
<p>Please refer to your package manager documentation about performing a local or
global installation, <strong class="program">virtualenv</strong> (fully supported by recent Psycopg
versions), using different Python versions and other nuances.</p>
</div>
<div class="section" id="use-the-source-package">
<span id="source-package"></span><span id="index-8"></span><h3>Use the source package<a class="headerlink" href="#use-the-source-package" title="Permalink to this headline">¶</a></h3>
<p>You can download a copy of Psycopg source files from the <a class="reference external" href="http://initd.org/psycopg/download/">Psycopg download
page</a>. Once unpackaged, to compile and install the package you can run:</p>
<div class="highlight-python"><div class="highlight"><pre>$ python setup.py build
$ sudo python setup.py install
</pre></div>
</div>
<p>If you have less standard requirements such as:</p>
<ul class="simple">
<li>creating a <a class="reference internal" href="#debug-build"><em>debug build</em></a>,</li>
<li>using <strong class="program">pg_config</strong> not in the <span class="target" id="index-9"></span><tt class="xref std std-envvar docutils literal"><span class="pre">PATH</span></tt>,</li>
<li>supporting <tt class="docutils literal"><span class="pre">mx.DateTime</span></tt>,</li>
</ul>
<p>then take a look at the <tt class="docutils literal"><span class="pre">setup.cfg</span></tt> file.</p>
<p>Some of the options available in <tt class="docutils literal"><span class="pre">setup.cfg</span></tt> are also available as command
line arguments of the <tt class="docutils literal"><span class="pre">build_ext</span></tt> sub-command. For instance you can specify
an alternate <strong class="program">pg_config</strong> version using:</p>
<div class="highlight-python"><div class="highlight"><pre>$ python setup.py build_ext --pg-config /path/to/pg_config build
</pre></div>
</div>
<p>Use <tt class="docutils literal"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">build_ext</span> <span class="pre">--help</span></tt> to get a list of the options
supported.</p>
</div>
<div class="section" id="running-the-test-suite">
<span id="test-suite"></span><span id="index-10"></span><h3>Running the test suite<a class="headerlink" href="#running-the-test-suite" title="Permalink to this headline">¶</a></h3>
<p>The included <tt class="docutils literal"><span class="pre">Makefile</span></tt> allows to run all the tests included in the
distribution. Just run:</p>
<div class="highlight-python"><div class="highlight"><pre>make
make check
</pre></div>
</div>
<p>The tests run against a database called <tt class="docutils literal"><span class="pre">psycopg2_test</span></tt> on UNIX socket and
the standard port. You can configure a different database to run the test by
setting the environment variables:</p>
<ul class="simple">
<li><span class="target" id="index-11"></span><tt class="xref std std-envvar docutils literal"><span class="pre">PSYCOPG2_TESTDB</span></tt></li>
<li><span class="target" id="index-12"></span><tt class="xref std std-envvar docutils literal"><span class="pre">PSYCOPG2_TESTDB_HOST</span></tt></li>
<li><span class="target" id="index-13"></span><tt class="xref std std-envvar docutils literal"><span class="pre">PSYCOPG2_TESTDB_PORT</span></tt></li>
<li><span class="target" id="index-14"></span><tt class="xref std std-envvar docutils literal"><span class="pre">PSYCOPG2_TESTDB_USER</span></tt></li>
</ul>
<p>The database should already exist before running the tests.</p>
</div>
</div>
<div class="section" id="creating-a-debug-build">
<span id="debug-build"></span><span id="index-15"></span><h2>Creating a debug build<a class="headerlink" href="#creating-a-debug-build" title="Permalink to this headline">¶</a></h2>
<p>In case of problems, Psycopg can be configured to emit detailed debug
messages, which can be very useful for diagnostics and to report a bug. In
order to create a debug package:</p>
<ul>
<li><p class="first"><a class="reference external" href="http://initd.org/psycopg/download/">Download</a> and unpack the Psycopg source package.</p>
</li>
<li><p class="first">Edit the <tt class="docutils literal"><span class="pre">setup.cfg</span></tt> file adding the <tt class="docutils literal"><span class="pre">PSYCOPG_DEBUG</span></tt> flag to the
<tt class="docutils literal"><span class="pre">define</span></tt> option.</p>
</li>
<li><p class="first"><a class="reference internal" href="#source-package"><em>Compile and install</em></a> the package.</p>
</li>
<li><p class="first">Set the <span class="target" id="index-16"></span><tt class="xref std std-envvar docutils literal"><span class="pre">PSYCOPG_DEBUG</span></tt> environment variable:</p>
<div class="highlight-python"><div class="highlight"><pre>$ export PSYCOPG_DEBUG=1
</pre></div>
</div>
</li>
<li><p class="first">Run your program (making sure that the <tt class="xref py py-obj docutils literal"><span class="pre">psycopg2</span></tt> package imported is the
one you just compiled and not e.g. the system one): you will have a copious
stream of informations printed on stderr.</p>
</li>
</ul>
</div>
<div class="section" id="if-you-still-have-problems">
<span id="other-problems"></span><h2>If you still have problems<a class="headerlink" href="#if-you-still-have-problems" title="Permalink to this headline">¶</a></h2>
<p>Try the following. <em>In order:</em></p>
<ul class="simple">
<li>Read again the <a class="reference internal" href="#requirements"><em>requirements</em></a>.</li>
<li>Read the <a class="reference internal" href="faq.html#faq-compile"><em>FAQ</em></a>.</li>
<li>Google for <tt class="xref py py-obj docutils literal"><span class="pre">psycopg2</span></tt> <em>your error message</em>. Especially useful the week
after the release of a new OS X version.</li>
<li>Write to the <a class="reference external" href="http://mail.postgresql.org/mj/mj_wwwusr/domain=postgresql.org?func=lists-long-full&extra=psycopg">Mailing List</a>.</li>
<li>Complain on your blog or on Twitter that <tt class="xref py py-obj docutils literal"><span class="pre">psycopg2</span></tt> is the worst package
ever and about the quality time you have wasted figuring out the correct
<span class="target" id="index-17"></span><tt class="xref std std-envvar docutils literal"><span class="pre">ARCHFLAGS</span></tt>. Especially useful from the Starbucks near you.</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Introduction</a></li>
<li><a class="reference internal" href="#installation">Installation</a><ul>
<li><a class="reference internal" href="#install-from-a-package">Install from a package</a></li>
<li><a class="reference internal" href="#install-from-source">Install from source</a><ul>
<li><a class="reference internal" href="#use-a-python-package-manager">Use a Python package manager</a></li>
<li><a class="reference internal" href="#use-the-source-package">Use the source package</a></li>
<li><a class="reference internal" href="#running-the-test-suite">Running the test suite</a></li>
</ul>
</li>
<li><a class="reference internal" href="#creating-a-debug-build">Creating a debug build</a></li>
<li><a class="reference internal" href="#if-you-still-have-problems">If you still have problems</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="index.html"
title="previous chapter">Psycopg – PostgreSQL database adapter for Python</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="usage.html"
title="next chapter">Basic module usage</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/install.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="usage.html" title="Basic module usage"
>next</a> |</li>
<li class="right" >
<a href="index.html" title="Psycopg – PostgreSQL database adapter for Python"
>previous</a> |</li>
<li><a href="index.html">Psycopg 2.5.4 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2001-2014, Federico Di Gregorio, Daniele Varrazzo.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
</div>
</body>
</html>
|
