{"id":13494967,"url":"https://github.com/jtv/libpqxx","last_synced_at":"2025-05-14T14:08:00.352Z","repository":{"id":11251623,"uuid":"68938580","full_name":"jtv/libpqxx","owner":"jtv","description":"The official C++ client API for PostgreSQL.","archived":false,"fork":false,"pushed_at":"2025-04-28T15:03:39.000Z","size":11132,"stargazers_count":1113,"open_issues_count":16,"forks_count":253,"subscribers_count":46,"default_branch":"master","last_synced_at":"2025-04-28T16:23:45.802Z","etag":null,"topics":["cplusplus","cplusplus-17","cplusplus-20","cplusplus-23","databases","postgres","postgresql"],"latest_commit_sha":null,"homepage":"http://pqxx.org/libpqxx/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jtv.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-09-22T16:06:50.000Z","updated_at":"2025-04-28T15:03:44.000Z","dependencies_parsed_at":"2023-02-10T10:00:28.890Z","dependency_job_id":"25c7128a-980e-4c87-918c-40051f638d43","html_url":"https://github.com/jtv/libpqxx","commit_stats":{"total_commits":4141,"total_committers":65,"mean_commits":"63.707692307692305","dds":0.04733156242453518,"last_synced_commit":"84fc4d762f4b2006e8a4b5d98dba37a192f02c27"},"previous_names":[],"tags_count":65,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtv%2Flibpqxx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtv%2Flibpqxx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtv%2Flibpqxx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtv%2Flibpqxx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jtv","download_url":"https://codeload.github.com/jtv/libpqxx/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254159470,"owners_count":22024562,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cplusplus","cplusplus-17","cplusplus-20","cplusplus-23","databases","postgres","postgresql"],"created_at":"2024-07-31T19:01:29.966Z","updated_at":"2025-05-14T14:08:00.289Z","avatar_url":"https://github.com/jtv.png","language":"C++","funding_links":[],"categories":["Database","C++","Libraries"],"sub_categories":["Database"],"readme":"libpqxx\n=======\n\nWelcome to libpqxx, the C++ API to the PostgreSQL database management system.\n\nHome page: [\n    http://pqxx.org/development/libpqxx\n](http://pqxx.org/development/libpqxx/)\n\nFind libpqxx on Github: [\n    https://github.com/jtv/libpqxx\n](https://github.com/jtv/libpqxx)\n\nDocumentation on Read The Docs: [\n    https://libpqxx.readthedocs.io\n](https://libpqxx.readthedocs.io)\n\nCompiling this package requires PostgreSQL to be installed -- or at least the C\nheaders and library for client development.  The library builds on top of\nPostgreSQL's standard C API, libpq, though your code won't notice.\n\nIf you're getting the code straight from the Git repo, the head of the `master`\nbranch represents the current _development version._  Releases are tags on\ncommits in `master`.  For example, to get version 7.1.1:\n\n```sh\n    git checkout 7.1.1\n```\n\n\nUpgrade notes\n-------------\n\n**The 7.x versions require at least C++17.**  Make sure your compiler is up to\ndate.  For libpqxx 8.x you will need at least C++20.\n\nAlso, **7.0 makes some breaking changes in rarely used APIs:**\n\n* There is just a single `connection` class.  It connects immediately.\n* Custom `connection` classes are no longer supported.\n* It's no longer possible to reactivate a connection once it's been closed.\n* The API for defining string conversions has changed.\n\nIf you're defining your own type conversions, **7.1 requires one additional\nfield in your `nullness` traits.**\n\n\nBuilding libpqxx\n----------------\n\nThere are two different ways of building libpqxx from the command line:\n\n1. Using CMake, on any system which supports it.\n2. On Unix-like systems, using a `configure` script.\n\n\"Unix-like\" systems include GNU/Linux, Apple macOS and the BSD family, AIX,\nHP-UX, Irix, Solaris, etc.  Even on Microsoft Windows, a Unix-like environment\nsuch as WSL, Cygwin, or MinGW should work.\n\nYou'll find detailed build and install instructions in [`BUILDING-configure.md`](./BUILDING-configure.md)\nand [`BUILDING-cmake.md`](./BUILDING-cmake.md), respectively.\n\nAnd if you're working with Microsoft Visual Studio, have a look at Gordon\nElliott's\n[\n  Easy-PQXX Build for Windows Visual Studio\n](https://github.com/GordonLElliott/Easy-PQXX-Build-for-Windows-Visual-Studio)\nproject.\n\n\nDocumentation\n-------------\n\nBuilding the library, if you have the right tools installed, generates HTML\ndocumentation in the `doc/` directory.  It is based on the headers in\n`include/pqxx/` and text in `include/pqxx/doc/`.  This documentation is also\navailable online at [readthedocs](https://libpqxx.readthedocs.io).\n\n\nProgramming with libpqxx\n------------------------\n\nYour first program will involve the libpqxx classes `connection` (see the\n`pqxx/connection.hxx` header), and `work` (a convenience alias for\n`transaction\u003c\u003e` which conforms to the interface defined in\n`pqxx/transaction_base.hxx`).\n\nThese `*.hxx` headers are not the ones you include in your program.  Instead,\ninclude the versions without filename suffix (e.g. `pqxx/connection`).  Those\nwill include the actual .hxx files for you.  This was done so that includes are\nin standard C++ style (as in `\u003ciostream\u003e` etc.), but an editor will still\nrecognize them as files containing C++ code.\n\nContinuing the list of classes, you may also need the result class\n(`pqxx/result.hxx`).  In a nutshell, you create a pqxx::connection based on a\nPostgres connection string (see below), create a pqxx::work (a transaction\nobject) in the context of that connection, and run one or more queries and/or\nSQL commands on that.\n\nDepending on how you execute a query, it can return a stream of `std::tuple`\n(each representing one row); or a pqxx::result object which holds both the\nresult data and additional metadata: how many rows your query returned and/or\nmodified, what the column names are, and so on.  A pqxx::result is a container\nof pqxx::row, and a pqxx::row is a container of pqxx::field.\n\nHere's an example with all the basics to get you going:\n\n```c++\n    #include \u003ciostream\u003e\n    #include \u003cpqxx/pqxx\u003e\n\n    int main()\n    {\n        try\n        {\n            // Connect to the database.  You can have multiple connections open\n            // at the same time, even to the same database.\n            pqxx::connection c;\n            std::cout \u003c\u003c \"Connected to \" \u003c\u003c c.dbname() \u003c\u003c '\\n';\n\n            // Start a transaction.  A connection can only have one transaction\n            // open at the same time, but after you finish a transaction, you\n            // can start a new one on the same connection.\n            pqxx::work tx{c};\n\n            // Query data of two columns, converting them to std::string and\n            // int respectively.  Iterate the rows.\n            for (auto [name, salary] : tx.query\u003cstd::string, int\u003e(\n                \"SELECT name, salary FROM employee ORDER BY name\"))\n            {\n                std::cout \u003c\u003c name \u003c\u003c \" earns \" \u003c\u003c salary \u003c\u003c \".\\n\";\n            }\n\n            // For large amounts of data, \"streaming\" the results is more\n            // efficient.  It does not work for all types of queries though.\n            //\n            // You can read fields as std::string_view here, which is not\n            // something you can do in most places.  A string_view becomes\n            // meaningless when the underlying string ceases to exist.  In this\n            // one situation, you can convert a field to string_view and it\n            // will be valid for just that one iteration of the loop.  The next\n            // iteration may overwrite or deallocate its buffer space.\n            for (auto [name, salary] : tx.stream\u003cstd::string_view, int\u003e(\n                \"SELECT name, salary FROM employee\"))\n            {\n                std::cout \u003c\u003c name \u003c\u003c \" earns \" \u003c\u003c salary \u003c\u003c \".\\n\";\n            }\n\n            // Execute a statement, and check that it returns 0 rows of data.\n            // This will throw pqxx::unexpected_rows if the query returns rows.\n            std::cout \u003c\u003c \"Doubling all employees' salaries...\\n\";\n            tx.exec0(\"UPDATE employee SET salary = salary*2\");\n\n            // Shorthand: conveniently query a single value from the database.\n            int my_salary = tx.query_value\u003cint\u003e(\n                \"SELECT salary FROM employee WHERE name = 'Me'\");\n            std::cout \u003c\u003c \"I now earn \" \u003c\u003c my_salary \u003c\u003c \".\\n\";\n\n            // Or, query one whole row.  This function will throw an exception\n            // unless the result contains exactly 1 row.\n            auto [top_name, top_salary] = tx.query1\u003cstd::string, int\u003e(\n                R\"(\n                    SELECT name, salary\n                    FROM employee\n                    WHERE salary = max(salary)\n                    LIMIT 1\n                )\");\n            std::cout \u003c\u003c \"Top earner is \" \u003c\u003c top_name \u003c\u003c \" with a salary of \"\n                      \u003c\u003c top_salary \u003c\u003c \".\\n\";\n\n            // If you need to access the result metadata, not just the actual\n            // field values, use the \"exec\" functions.  Most of them return\n            // pqxx::result objects.\n            pqxx::result res = tx.exec(\"SELECT * FROM employee\");\n            std::cout \u003c\u003c \"Columns:\\n\";\n            for (pqxx::row_size_type col = 0; col \u003c res.columns(); ++col)\n                std::cout \u003c\u003c res.column_name(col) \u003c\u003c '\\n';\n\n            // Commit the transaction.  If you don't do this, the database will\n            // undo any changes you made in the transaction.\n            std::cout \u003c\u003c \"Making changes definite: \";\n            tx.commit();\n            std::cout \u003c\u003c \"OK.\\n\";\n        }\n        catch (std::exception const \u0026e)\n        {\n            std::cerr \u003c\u003c \"ERROR: \" \u003c\u003c e.what() \u003c\u003c '\\n';\n            return 1;\n        }\n        return 0;\n    }\n```\n\n\nConnection strings\n------------------\n\nPostgres connection strings state which database server you wish to connect to,\nunder which username, using which password, and so on.  Their format is defined\nin the documentation for libpq, the C client interface for PostgreSQL.\nAlternatively, these values may be defined by setting certain environment\nvariables as documented in e.g. the manual for psql, the command line interface\nto PostgreSQL.  Again the definitions are the same for libpqxx-based programs.\n\nThe connection strings and variables are not fully and definitively documented\nhere; this document will tell you just enough to get going.  Check the\nPostgreSQL documentation for authoritative information.\n\nThe connection string consists of attribute=value pairs separated by spaces,\ne.g. \"user=john password=1x2y3z4\".  The valid attributes include:\n\n* `host` —\n  Name of server to connect to, or the full file path (beginning with a\n  slash) to a Unix-domain socket on the local machine.  Defaults to\n  \"/tmp\".  Equivalent to (but overrides) environment variable PGHOST.\n* `hostaddr` —\n  IP address of a server to connect to; mutually exclusive with \"host\".\n* `port` —\n  Port number at the server host to connect to, or socket file name\n  extension for Unix-domain connections.  Equivalent to (but overrides)\n  environment variable PGPORT.\n* `dbname` —\n  Name of the database to connect to.  A single server may host multiple\n  databases.  Defaults to the same name as the current user's name.\n  Equivalent to (but overrides) environment variable PGDATABASE.\n* `user` —\n  User name to connect under.  This defaults to the name of the current\n  user, although PostgreSQL users are not necessarily the same thing as\n  system users.\n* `requiressl` —\n  If set to 1, demands an encrypted SSL connection (and fails if no SSL\n  connection can be created).\n\nSettings in the connection strings override the environment variables, which in\nturn override the default, on a variable-by-variable basis.  You only need to\ndefine those variables that require non-default values.\n\n\nLinking with libpqxx\n--------------------\n\nTo link your final program, make sure you link to both the C-level libpq library\nand the actual C++ library, libpqxx.  With most Unix-style compilers, you'd do\nthis using these options: `-lpqxx -lpq`\n\nwhile linking.  Both libraries must be in your link path, so the linker knows\nwhere to find them.  Any dynamic libraries you use must also be in a place\nwhere the loader can find them when loading your program at runtime.\n\nSome users have reported problems using the above syntax, however, particularly\nwhen multiple versions of libpqxx are partially or incorrectly installed on the\nsystem.  If you get massive link errors, try removing the \"-lpqxx\" argument from\nthe command line and replacing it with the name of the libpqxx library binary\ninstead.  That's typically libpqxx.a, but you'll have to add the path to its\nlocation as well, e.g. /usr/local/pqxx/lib/libpqxx.a.  This will ensure that the\nlinker will use that exact version of the library rather than one found\nelsewhere on the system, and eliminate worries about the exact right version of\nthe library being installed with your program..\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjtv%2Flibpqxx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjtv%2Flibpqxx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjtv%2Flibpqxx/lists"}