README.md
1libpqxx
2=======
3
4Welcome to libpqxx, the C++ API to the PostgreSQL database management system.
5
6Home page: http://pqxx.org/development/libpqxx/
7
8Find libpqxx on Github: https://github.com/jtv/libpqxx
9
10Documentation on Read The Docs: https://readthedocs.org/projects/libpqxx/
11
12Compiling this package requires PostgreSQL to be installed -- or at least the C
13headers and library for client development. The library builds on top of
14PostgreSQL's standard C API, libpq, though your code won't notice.
15
16If you're getting the code straight from the Git repo, the `master` branch
17contains the current _development version._ To get a released version, check
18out the revision that's tagged for that version. For example, to get version
197.1.1:
20
21 git checkout 7.1.1
22
23
24### Upgrade notes
25
26**The 7.x versions require C++17.** However, it's probably not a problem if
27your compiler does not implement C++17 fully. Initially the 7.x series will
28only require some basic C++17 features such as `std::string_view`. More
29advanced use may follow later.
30
31Also, **7.0 makes some breaking changes in rarely used APIs:**
32 * There is just a single `connection` class. It connects immediately.
33 * Custom `connection` classes are no longer supported.
34 * Closed connections can no longer be reactivated.
35 * The API for defining string conversions has changed.
36
37And if you're defining your own type conversions, **7.1 requires one additional
38field in your `nullness` traits.*
39
40
41Building libpqxx
42----------------
43
44There are two different ways of building libpqxx from the command line:
45 1. Using CMake, on any system which supports it.
46 2. On Unix-like systems, using a `configure` script.
47
48"Unix-like" systems include GNU/Linux, Apple macOS and the BSD family, AIX,
49HP-UX, Irix, Solaris, etc. Even on Microsoft Windows, a Unix-like environment
50such as WSL, Cygwin, or MinGW should work.
51
52You'll find detailed build and install instructions in `BUILDING-configure.md`
53and `BUILDING-cmake.md`, respectively.
54
55And if you're working with Microsoft Visual Studio, have a look at Gordon
56Elliott's _Easy-PQXX Build for Windows Visual Studio_ project:
57
58 https://github.com/GordonLElliott/Easy-PQXX-Build-for-Windows-Visual-Studio
59
60At the time of writing, June 2020, this is still in development and in need of
61testers and feedback.
62
63
64Documentation
65-------------
66
67The `doc/` directory contains API reference documentation and a tutorial, both
68in HTML format. These are also available online.
69
70For more detailed information, look at the header files themselves. These are
71in the `include/pqxx/` directory. We extract the reference documentation from
72the headers using a program called Doxygen.
73
74When learning about programming with libpqxx, you'll want to start off by
75reading about the `connection` and `transaction_base` classes.
76
77For programming examples, take a look at the test programs in the `test/`
78directory. If you don't know how a certain function or class is used, try
79searching the tests for that name.
80
81
82Programming with libpqxx
83------------------------
84
85Your first program will involve the libpqxx classes "connection" (see the
86`pqxx/connection.hxx` header), and `work` (a convenience alias for
87`transaction<>` which conforms to the interface defined in
88`pqxx/transaction_base.hxx`).
89
90These `*.hxx` headers are not the ones you include in your program. Instead,
91include the versions without filename suffix (e.g. `pqxx/connection`). Those
92will include the actual .hxx files for you. This was done so that includes are
93in standard C++ style (as in `<iostream>` etc.), but an editor will still
94recognize them as files containing C++ code.
95
96Continuing the list of classes, you will most likely also need the result class
97(`pqxx/result.hxx`). In a nutshell, you create a `connection` based on a
98Postgres connection string (see below), create a `work` in the context of that
99connection, and run one or more queries on the work which return `result`
100objects. The results are containers of rows of data, each of which you can
101treat as an array of strings: one for each field in the row. It's that simple.
102
103Here is a simple example program to get you going, with full error handling:
104
105```c++
106#include <iostream>
107#include <pqxx/pqxx>
108
109int main()
110{
111 try
112 {
113 pqxx::connection C;
114 std::cout << "Connected to " << C.dbname() << std::endl;
115 pqxx::work W{C};
116
117 pqxx::result R{W.exec("SELECT name FROM employee")};
118
119 std::cout << "Found " << R.size() << "employees:\n";
120 for (auto row: R)
121 std::cout << row[0].c_str() << '\n';
122
123 std::cout << "Doubling all employees' salaries...\n";
124 W.exec0("UPDATE employee SET salary = salary*2");
125
126 std::cout << "Making changes definite: ";
127 W.commit();
128 std::cout << "OK.\n";
129 }
130 catch (std::exception const &e)
131 {
132 std::cerr << e.what() << '\n';
133 return 1;
134 }
135 return 0;
136}
137```
138
139
140Connection strings
141------------------
142
143Postgres connection strings state which database server you wish to connect to,
144under which username, using which password, and so on. Their format is defined
145in the documentation for libpq, the C client interface for PostgreSQL.
146Alternatively, these values may be defined by setting certain environment
147variables as documented in e.g. the manual for psql, the command line interface
148to PostgreSQL. Again the definitions are the same for libpqxx-based programs.
149
150The connection strings and variables are not fully and definitively documented
151here; this document will tell you just enough to get going. Check the
152PostgreSQL documentation for authoritative information.
153
154The connection string consists of attribute=value pairs separated by spaces,
155e.g. "user=john password=1x2y3z4". The valid attributes include:
156
157- `host`
158 Name of server to connect to, or the full file path (beginning with a
159 slash) to a Unix-domain socket on the local machine. Defaults to
160 "/tmp". Equivalent to (but overrides) environment variable PGHOST.
161
162- `hostaddr`
163 IP address of a server to connect to; mutually exclusive with "host".
164
165- `port`
166 Port number at the server host to connect to, or socket file name
167 extension for Unix-domain connections. Equivalent to (but overrides)
168 environment variable PGPORT.
169
170- `dbname`
171 Name of the database to connect to. A single server may host multiple
172 databases. Defaults to the same name as the current user's name.
173 Equivalent to (but overrides) environment variable PGDATABASE.
174
175- `user`
176 User name to connect under. This defaults to the name of the current
177 user, although PostgreSQL users are not necessarily the same thing as
178 system users.
179
180- `requiressl`
181 If set to 1, demands an encrypted SSL connection (and fails if no SSL
182 connection can be created).
183
184Settings in the connection strings override the environment variables, which in
185turn override the default, on a variable-by-variable basis. You only need to
186define those variables that require non-default values.
187
188
189Linking with libpqxx
190--------------------
191
192To link your final program, make sure you link to both the C-level libpq library
193and the actual C++ library, libpqxx. With most Unix-style compilers, you'd do
194this using the options
195
196```
197 -lpqxx -lpq
198```
199
200while linking. Both libraries must be in your link path, so the linker knows
201where to find them. Any dynamic libraries you use must also be in a place
202where the loader can find them when loading your program at runtime.
203
204Some users have reported problems using the above syntax, however, particularly
205when multiple versions of libpqxx are partially or incorrectly installed on the
206system. If you get massive link errors, try removing the "-lpqxx" argument from
207the command line and replacing it with the name of the libpqxx library binary
208instead. That's typically libpqxx.a, but you'll have to add the path to its
209location as well, e.g. /usr/local/pqxx/lib/libpqxx.a. This will ensure that the
210linker will use that exact version of the library rather than one found
211elsewhere on the system, and eliminate worries about the exact right version of
212the library being installed with your program..
213