{"id":13439727,"url":"https://github.com/pganalyze/libpg_query","last_synced_at":"2026-10-19T12:44:47.188Z","repository":{"id":36094090,"uuid":"40395126","full_name":"pganalyze/libpg_query","owner":"pganalyze","description":"C library for accessing the PostgreSQL parser outside of the server environment","archived":false,"fork":false,"pushed_at":"2026-10-02T20:30:57.000Z","size":24523,"stargazers_count":1486,"open_issues_count":59,"forks_count":230,"subscribers_count":31,"default_branch":"18-latest","last_synced_at":"2026-10-14T07:09:10.250Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/pganalyze.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"claude":null,"gemini":null,"cursor":null,"copilot":null,"dco":null,"cla":null,"disclosure":null}},"created_at":"2015-08-08T07:24:16.000Z","updated_at":"2026-10-13T03:58:59.000Z","dependencies_parsed_at":"2026-09-24T06:24:51.471Z","dependency_job_id":null,"html_url":"https://github.com/pganalyze/libpg_query","commit_stats":{"total_commits":451,"total_committers":38,"mean_commits":"11.868421052631579","dds":0.4101995565410199,"last_synced_commit":"c3ed78bd3c5ceef446e8a769991e89421af7b6b3"},"previous_names":["lfittl/libpg_query"],"tags_count":51,"template":false,"template_full_name":null,"purl":"pkg:github/pganalyze/libpg_query","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pganalyze%2Flibpg_query","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pganalyze%2Flibpg_query/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pganalyze%2Flibpg_query/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pganalyze%2Flibpg_query/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pganalyze","download_url":"https://codeload.github.com/pganalyze/libpg_query/tar.gz/refs/heads/18-latest","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pganalyze%2Flibpg_query/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":344872684,"owners_count":38356472,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-10-03T21:59:58.778Z","status":"online","status_checked_at":"2026-10-19T02:00:06.414Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-07-31T03:01:16.577Z","updated_at":"2026-10-19T12:44:47.183Z","avatar_url":"https://github.com/pganalyze.png","language":"C","funding_links":[],"categories":["📚 项目宗旨","Data and Storage","Database","HarmonyOS","C","others","SQL"],"sub_categories":["数据库","Database Clients and ORMs","Windows Manager","Parsers"],"readme":"# libpg_query\n\nC library for accessing the PostgreSQL parser outside of the server.\n\nThis library uses the actual PostgreSQL server source to parse SQL queries and return the internal PostgreSQL parse tree.\n\nNote that this is mostly intended as a base library for [pg_query](https://github.com/pganalyze/pg_query) (Ruby), [pg_query.go](https://github.com/pganalyze/pg_query_go) (Go), [pg_query.rs](https://github.com/pganalyze/pg_query.rs) (Rust), [pgsql-parser](https://github.com/launchql/pgsql-parser) (Node), [psqlparse](https://github.com/alculquicondor/psqlparse) (Python) and [pglast](https://pypi.org/project/pglast/) (Python 3).\n\nYou can find further background to why a query's parse tree is useful here: https://pganalyze.com/blog/parse-postgresql-queries-in-ruby.html\n\n\n## Installation\n\n```sh\ngit clone -b 18-latest git://github.com/pganalyze/libpg_query\ncd libpg_query\nmake\n```\n\nDue to compiling parts of PostgreSQL, running `make` will take a bit. Expect up to 3 minutes.\n\nFor a production build, its best to use a specific git tag (see CHANGELOG).\n\nWhen compiling on Windows with Visual Studio, instead use `nmake` with the `Makefile.msvc`:\n\n```sh\nnmake /F Makefile.msvc\n```\n\n\n## Usage: Parsing a query\n\nA [full example](https://github.com/pganalyze/libpg_query/blob/master/examples/simple.c) that parses a query looks like this:\n\n```c\n#include \u003cpg_query.h\u003e\n#include \u003cstdio.h\u003e\n\nint main() {\n  PgQueryParseResult result;\n\n  result = pg_query_parse(\"SELECT 1\");\n\n  printf(\"%s\\n\", result.parse_tree);\n\n  pg_query_free_parse_result(result);\n\n  return 0;\n}\n```\n\nCompile it like this:\n\n```\ncc -Ilibpg_query -Llibpg_query example.c -lpg_query\n```\n\nThis will output the parse tree (whitespace adjusted here for better readability):\n\n```json\n{\n    \"version\": 180006,\n    \"stmts\": [\n        {\n            \"stmt\": {\n                \"SelectStmt\": {\n                    \"targetList\": [\n                        {\n                            \"ResTarget\": {\n                                \"val\": {\n                                    \"A_Const\": {\n                                        \"ival\": {\n                                            \"ival\": 1\n                                        },\n                                        \"location\": 7\n                                    }\n                                },\n                                \"location\": 7\n                            }\n                        }\n                    ],\n                    \"limitOption\": \"LIMIT_OPTION_DEFAULT\",\n                    \"op\": \"SETOP_NONE\"\n                }\n            }\n        }\n    ]\n}\n```\n\n## Usage: Scanning a query into its tokens using the PostgreSQL scanner/lexer\n\npg_query also exposes the underlying scanner of Postgres, which is also used in\nthe very first part in the parsing process. It can be useful on its own for e.g.\nsyntax highlighting, where one is mostly concerned with differentiating keywords\nfrom identifiers and other parts of the query:\n\n```c\n#include \u003cstdio.h\u003e\n\n#include \u003cpg_query.h\u003e\n\nint main() {\n  PgQueryScanTokensResult result;\n  const char *input = \"SELECT update AS left /* comment */ FROM between\";\n\n  result = pg_query_scan_tokens(input);\n  if (result.error) {\n    printf(\"error: %s at %d\\n\", result.error-\u003emessage, result.error-\u003ecursorpos);\n    pg_query_free_scan_tokens_result(result);\n    return 1;\n  }\n\n  printf(\"  tokens: %d\\n\", result.n_tokens);\n  for (int j = 0; j \u003c result.n_tokens; j++) {\n    PgQueryScanToken token = result.tokens[j];\n    printf(\"  \\\"%.*s\\\" = [ %d, %d, %s, %s ]\\n\", token.end - token.start, \u0026(input[token.start]), token.start, token.end,\n           pg_query_token_name(token.token), pg_query_keyword_kind_name(token.keyword_kind));\n  }\n\n  pg_query_free_scan_tokens_result(result);\n\n  return 0;\n}\n```\n\nIf you need the tokens as a Protobuf message instead, e.g. to decode them in another language, use `pg_query_scan`, which returns the same tokens serialized as a `ScanResult`. It can be decoded with the vendored [upb](https://github.com/protocolbuffers/protobuf/tree/main/upb) runtime, which is included in `libpg_query.a` (the upb headers must then be on the include path as well, `-Ilibpg_query/vendor/upb`).\n\nThis will output the following:\n\n```\n  tokens: 7\n  \"SELECT\" = [ 0, 6, SELECT, RESERVED_KEYWORD ]\n  \"update\" = [ 7, 13, UPDATE, UNRESERVED_KEYWORD ]\n  \"AS\" = [ 14, 16, AS, RESERVED_KEYWORD ]\n  \"left\" = [ 17, 21, LEFT, TYPE_FUNC_NAME_KEYWORD ]\n  \"/* comment */\" = [ 22, 35, C_COMMENT, NO_KEYWORD ]\n  \"FROM\" = [ 36, 40, FROM, RESERVED_KEYWORD ]\n  \"between\" = [ 41, 48, BETWEEN, COL_NAME_KEYWORD ]\n```\n\nWhere the each element in the token list has the following fields:\n\n1. Start location in the source string\n2. End location in the source string\n3. Token value - `PgQueryToken` enum (e.g. `PG_QUERY_TOKEN_SELECT`), see `pg_query_scan_tokens.h`, or the Token type in `protobuf/pg_query.proto` for the Protobuf output\n4. Keyword type - `PgQueryKeywordKind` enum, see `pg_query_scan_tokens.h`, or the KeywordKind type in `protobuf/pg_query.proto` for the Protobuf output, possible values:\n  `PG_QUERY_NO_KEYWORD`: Not a keyword\n  `PG_QUERY_UNRESERVED_KEYWORD`: Unreserved keyword (available for use as any kind of unescaped name)\n  `PG_QUERY_COL_NAME_KEYWORD`: Unreserved keyword (can be unescaped column/table/etc names, cannot be unescaped function or type name)\n  `PG_QUERY_TYPE_FUNC_NAME_KEYWORD`: Reserved keyword (can be unescaped function or type name, cannot be unescaped column/table/etc names)\n  `PG_QUERY_RESERVED_KEYWORD`: Reserved keyword (cannot be unescaped column/table/variable/type/function names)\n\nThe token values are the token numbers of the Postgres grammar, which change between Postgres versions, so compare them by name rather than by value.\n\nNote that whitespace does not show as tokens.\n\n## Usage: Fingerprinting a query\n\nFingerprinting allows you to identify similar queries that are different only because\nof the specific object that is being queried for (i.e. different object ids in the WHERE clause),\nor because of formatting.\n\nExample:\n\n```c\n#include \u003cpg_query.h\u003e\n#include \u003cstdio.h\u003e\n\nint main() {\n  PgQueryFingerprintResult result;\n\n  result = pg_query_fingerprint(\"SELECT 1\");\n\n  printf(\"%s\\n\", result.fingerprint_str);\n\n  pg_query_free_fingerprint_result(result);\n\n  return 0;\n}\n```\n\nThis will output:\n\n```\n50fde20626009aba\n```\n\nIn general, fingerprinting intends to be a superset of the Postgres `queryid` mechanism. That means that for a given Postgres `queryid`, there should only be one valid fingerprint - even when varying the inputs that produce that same `queryid`. A simple example of this would be that the Postgres `queryid` ignores constant values (e.g. `... WHERE id = 123` is the same queryid as `... WHERE id = 456`), and thus the fingerprint also behaves that way.\n\nOne special case are the changes done in Postgres 18, which significantly changed how schema names and table aliases in `FROM` clauses are handled for `queryid` values. On Postgres 17 and older, the schema was significant, and the alias was always ignored. On Postgres 18, the schema is always ignored, and the table alias (if present) is used instead of the table name.\n\nTo support matching behaviour, you can optionally pass fingerprint options. By default fingerprinting behaves like Postgres 18, but you can pass `PG_QUERY_FINGERPRINT_RANGEVAR_PG17_COMPAT` to instead have it behave like Postgres 17 does for `queryid`:\n\n```c\n#include \u003cpg_query.h\u003e\n#include \u003cstdio.h\u003e\n\nint main() {\n  const char *queries[] = {\n    \"SELECT * FROM public.users u\",\n    \"SELECT * FROM myschema.users u\",\n  };\n  PgQueryFingerprintResult result;\n\n  for (int i = 0; i \u003c 2; i++) {\n    result = pg_query_fingerprint_opts(queries[i], PG_QUERY_PARSE_DEFAULT, PG_QUERY_FINGERPRINT_DEFAULT);\n    printf(\"Default:     %s\\n\", result.fingerprint_str);\n    pg_query_free_fingerprint_result(result);\n\n    result = pg_query_fingerprint_opts(queries[i], PG_QUERY_PARSE_DEFAULT, PG_QUERY_FINGERPRINT_RANGEVAR_PG17_COMPAT);\n    printf(\"PG17 compat: %s\\n\", result.fingerprint_str);\n    pg_query_free_fingerprint_result(result);\n  }\n\n  return 0;\n}\n```\n\nThis will output:\n\n```\nDefault:     6640d8be64880eed\nPG17 compat: d3198777453aef12\nDefault:     6640d8be64880eed\nPG17 compat: 91e880cf13f4f219\n```\n\nWith the default options both queries get the same fingerprint, because the schema is ignored and the alias `u` is used. With `PG_QUERY_FINGERPRINT_RANGEVAR_PG17_COMPAT`, the schema-qualified table name counts, so the two queries get different fingerprints.\n\nThe options also allow controlling whether relation names that have subsequent digits (often used for daily partitions) should be ignored for fingerprinting, which is the case by default.\n\nSee https://github.com/pganalyze/libpg_query/wiki/Fingerprinting for the full fingerprinting rules.\n\n## Usage: Parsing a PL/pgSQL function\n\nA [full example](https://github.com/pganalyze/libpg_query/blob/master/examples/simple_plpgsql.c) that parses a [PL/pgSQL](https://www.postgresql.org/docs/current/static/plpgsql.html) method looks like this:\n\n```c\n#include \u003cpg_query.h\u003e\n#include \u003cstdio.h\u003e\n#include \u003cstdlib.h\u003e\n\nint main() {\n  PgQueryPlpgsqlParseResult result;\n\n  result = pg_query_parse_plpgsql(\" \\\n  CREATE OR REPLACE FUNCTION cs_fmt_browser_version(v_name varchar, \\\n                                                  v_version varchar) \\\nRETURNS varchar AS $$ \\\nBEGIN \\\n    IF v_version IS NULL THEN \\\n        RETURN v_name; \\\n    END IF; \\\n    RETURN v_name || '/' || v_version; \\\nEND; \\\n$$ LANGUAGE plpgsql;\");\n\n  if (result.error) {\n    printf(\"error: %s at %d\\n\", result.error-\u003emessage, result.error-\u003ecursorpos);\n  } else {\n    printf(\"%s\\n\", result.plpgsql_funcs);\n  }\n\n  pg_query_free_plpgsql_parse_result(result);\n\n  return 0;\n}\n```\n\nThis will output (formatted for clarity):\n\n```json\n[\n    {\n        \"PLpgSQL_function\": {\n            \"datums\": [\n                {\n                    \"PLpgSQL_var\": {\n                        \"refname\": \"v_name\",\n                        \"datatype\": {\n                            \"PLpgSQL_type\": {\n                                \"typname\": \"varchar\"\n                            }\n                        }\n                    }\n                },\n                {\n                    \"PLpgSQL_var\": {\n                        \"refname\": \"v_version\",\n                        \"datatype\": {\n                            \"PLpgSQL_type\": {\n                                \"typname\": \"varchar\"\n                            }\n                        }\n                    }\n                },\n                {\n                    \"PLpgSQL_var\": {\n                        \"refname\": \"found\",\n                        \"datatype\": {\n                            \"PLpgSQL_type\": {\n                                \"typname\": \"bool\"\n                            }\n                        }\n                    }\n                }\n            ],\n            \"action\": {\n                \"PLpgSQL_stmt_block\": {\n                    \"lineno\": 1,\n                    \"body\": [\n                        {\n                            \"PLpgSQL_stmt_if\": {\n                                \"lineno\": 1,\n                                \"cond\": {\n                                    \"PLpgSQL_expr\": {\n                                        \"query\": \"v_version IS NULL\",\n                                        \"parseMode\": 2\n                                    }\n                                },\n                                \"then_body\": [\n                                    {\n                                        \"PLpgSQL_stmt_return\": {\n                                            \"lineno\": 1\n                                        }\n                                    }\n                                ]\n                            }\n                        },\n                        {\n                            \"PLpgSQL_stmt_return\": {\n                                \"lineno\": 1,\n                                \"expr\": {\n                                    \"PLpgSQL_expr\": {\n                                        \"query\": \"v_name || '/' || v_version\",\n                                        \"parseMode\": 2\n                                    }\n                                }\n                            }\n                        }\n                    ]\n                }\n            }\n        }\n    }\n]\n```\n\n## Versions\n\nFor stability, it is recommended you use individual tagged git versions, see CHANGELOG.\n\nEach major version is maintained in a dedicated git branch. Only the latest Postgres stable release receives active updates, with exceptions being made for the prior release branch for critical fixes.\n\n| PostgreSQL Major Version | Branch     | Status              |\n|--------------------------|------------|---------------------|\n| 18                       | 18-latest  | Active development  |\n| 17                       | 17-latest  | Critical fixes only |\n| 16                       | 16-latest  | No longer supported |\n| 15                       | 15-latest  | No longer supported |\n| 14                       | 14-latest  | No longer supported |\n| 13                       | 13-latest  | No longer supported |\n| 12                       | (n/a)      | Not supported       |\n| 11                       | (n/a)      | Not supported       |\n| 10                       | 10-latest  | No longer supported |\n| 9.6                      | (n/a)      | Not supported       |\n| 9.5                      | 9.5-latest | No longer supported |\n| 9.4                      | 9.4-latest | No longer supported |\n\n## Updating the vendored upb (Protobuf) runtime\n\nProtobuf serialization uses [upb](https://github.com/protocolbuffers/protobuf/tree/main/upb), vendored in `vendor/upb`. The generated code in `protobuf/pg_query.upb*.{c,h}` is tied to the exact upb version it was generated with, so both are updated together:\n\n```sh\nbrew upgrade protobuf       # protoc + protoc-gen-upb must match the target release\nmake -C vendor/upb update TAG=v$(protoc --version | awk '{print $2}')\nmake clean \u0026\u0026 make \u0026\u0026 make test\n```\n\nSee [vendor/upb/README](vendor/upb/README) for details, including the local patches that are re-applied on each update.\n\n## Resources\n\npg_query wrappers in other languages:\n\n* Ruby: [pg_query](https://github.com/pganalyze/pg_query)\n* Go: [pg_query_go](https://github.com/pganalyze/pg_query_go)\n* Javascript (Node): [pgsql-parser](https://github.com/launchql/pgsql-parser)\n* Javascript (Browser): [pg-query-emscripten](https://github.com/pganalyze/pg-query-emscripten)\n* Python: [psqlparse](https://github.com/alculquicondor/psqlparse), [pglast](https://github.com/lelit/pglast),\n[psqlparse2](https://github.com/dani-maarouf/psqlparse2)\n* OCaml: [pg_query-ocaml](https://github.com/roddyyaga/pg_query-ocaml)\n* Rust: [pg_query.rs](https://github.com/pganalyze/pg_query.rs)\n\nProducts, tools and libraries built on pg_query:\n\n* [pganalyze](https://pganalyze.com/)\n* [hsql](https://github.com/JackDanger/hsql)\n* [sqlint](https://github.com/purcell/sqlint)\n* [pghero](https://github.com/ankane/pghero)\n* [dexter](https://github.com/ankane/dexter)\n* [pgscope](https://github.com/gjalves/pgscope)\n* [pg_materialize](https://github.com/aanari/pg-materialize)\n* [DuckDB](https://github.com/cwida/duckdb) ([details](https://github.com/cwida/duckdb/tree/master/third_party/libpg_query))\n* [pgspot](https://github.com/timescale/pgspot)\n* [Postgres Language Server](https://github.com/supabase/postgres_lsp)\n* and more\n\nPlease feel free to [open a PR](https://github.com/pganalyze/libpg_query/pull/new/master) to add yours! :)\n\n## License\n\nPostgreSQL server source code, used under the [PostgreSQL license](https://www.postgresql.org/about/licence/).\u003cbr\u003e\nPortions Copyright (c) 1996-2026, The PostgreSQL Global Development Group\u003cbr\u003e\nPortions Copyright (c) 1994, The Regents of the University of California\n\nupb Protobuf runtime (`vendor/upb`), used under the [3-clause BSD license](vendor/upb/LICENSE).\u003cbr\u003e\nCopyright 2008 Google Inc.\u003cbr\u003e\nIncludes utf8_range (`vendor/upb/third_party/utf8_range`), used under the [MIT license](vendor/upb/third_party/utf8_range/LICENSE).\u003cbr\u003e\nCopyright (c) 2019 Yibo Cai\u003cbr\u003e\nCopyright 2022 Google LLC\n\nxxHash (`vendor/xxhash`), used under the [2-clause BSD license](vendor/xxhash/xxhash.h).\u003cbr\u003e\nCopyright (C) 2012-2020 Yann Collet\n\nAll other parts are licensed under the 3-clause BSD license, see LICENSE file for details.\u003cbr\u003e\nCopyright (c) 2015, Lukas Fittl \u003clukas@fittl.com\u003e\nCopyright (c) 2016-2026, Duboce Labs, Inc. (pganalyze) \u003cteam@pganalyze.com\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpganalyze%2Flibpg_query","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpganalyze%2Flibpg_query","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpganalyze%2Flibpg_query/lists"}