{"id":13762,"library":"pg-proto-parser","title":"PostgreSQL Protocol Buffers Definition Parser","description":"The `pg-proto-parser` library is a TypeScript project designed to parse Protocol Buffers (`.proto`) definitions specifically for `pganalyze/libpg_query` PostgreSQL Abstract Syntax Tree (AST) structures. It does not parse raw SQL queries or the PostgreSQL wire protocol directly. Instead, its primary function is to generate TypeScript interfaces, utility functions, and JSON mappings for the enums and messages defined within these PostgreSQL-related protobuf schemas. This generated code facilitates the creation of type-safe AST nodes and simplifies enum value conversions, serving as a foundational tool for other PostgreSQL tooling like `launchql/pgsql-parser` for maintainable upgrades. The package is currently at version 1.30.5 and appears to be actively maintained, offering a crucial layer for developers working with PostgreSQL's internal query representation in a type-safe TypeScript environment.","status":"active","version":"1.30.5","language":"javascript","source_language":"en","source_url":"https://github.com/constructive-io/pgsql-parser","tags":["javascript","sql","postgres","postgresql","pg","query","ast","proto","parser","typescript"],"install":[{"cmd":"npm install pg-proto-parser","lang":"bash","label":"npm"},{"cmd":"yarn add pg-proto-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add pg-proto-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library is written in TypeScript and primarily designed for ESM environments. CommonJS `require` syntax is generally incorrect or requires bundler configuration.","wrong":"const PgProtoParser = require('pg-proto-parser');","symbol":"PgProtoParser","correct":"import { PgProtoParser } from 'pg-proto-parser';"},{"note":"This is a TypeScript type/interface, so use `import type` for clarity and to avoid bundling issues if using older TypeScript versions or specific bundler configurations.","wrong":"import { PgProtoParserOptions } from 'pg-proto-parser';","symbol":"PgProtoParserOptions","correct":"import type { PgProtoParserOptions } from 'pg-proto-parser';"},{"note":"Many of the useful exports are generated types, enums, or utilities from parsing the protobuf definitions. These are often located in subpaths like `pg-proto-parser/types` or `pg-proto-parser/enums` rather than the main entry point.","wrong":"import { A_Const } from 'pg-proto-parser';","symbol":"GeneratedTypes","correct":"import type { A_Const } from 'pg-proto-parser/types';"}],"quickstart":{"code":"import { PgProtoParser } from 'pg-proto-parser';\nimport { readFileSync, mkdirSync, writeFileSync } from 'fs';\nimport { resolve } from 'path';\n\nconst protoContent = `\nsyntax = \"proto3\";\n\npackage pg_query;\n\nmessage Node {\n  int32 location = 1;\n}\n\nmessage A_Const {\n  Node node = 1;\n  oneof val {\n    int64 ival = 2; // integer\n    bool bval = 3; // boolean\n    string sval = 4; // string\n  }\n  int32 location = 5;\n}\n`;\n\n// Create a dummy proto file for parsing demonstration\nconst tempDir = resolve(__dirname, './temp-proto-output');\nmkdirSync(tempDir, { recursive: true });\nconst tempProtoFile = resolve(tempDir, 'dummy.proto');\nwriteFileSync(tempProtoFile, protoContent);\n\nasync function generatePgProtoTypes() {\n  try {\n    // In a real application, 'inFile' would point to the libpg_query proto definitions.\n    // For this example, we use our dummy proto file.\n    const parser = new PgProtoParser(tempProtoFile, {\n      outDir: tempDir,\n      enums: {\n        enumMap: { enabled: true, format: 'ts', toIntOutFile: 'enum-to-int.ts', toStrOutFile: 'enum-to-str.ts' }\n      }\n    });\n\n    await parser.write();\n\n    console.log(`Successfully generated types and utilities in: ${tempDir}`);\n    console.log('Check files like types.ts, enums.ts, utils.ts in the output directory.');\n\n    // Example of importing a generated type (after generation)\n    // const { A_Const } = await import(resolve(tempDir, 'types.ts'));\n    // const myConst: A_Const = { node: { location: 0 }, ival: '123' }; // Example usage\n\n  } catch (error) {\n    console.error('Error generating types:', error);\n  }\n}\n\ngeneratePgProtoTypes();\n","lang":"typescript","description":"This quickstart demonstrates how to initialize `PgProtoParser` with a dummy protobuf schema, configure output options, and generate corresponding TypeScript interfaces, enums, and utility files into a specified directory."},"warnings":[{"fix":"Verify that your use case specifically involves working with the protobuf schemas that define PostgreSQL's AST or internal messages. If you need to parse SQL, consider `@pgsql/parser` or `pgsql-parser`. If you need to interact with the PostgreSQL wire protocol, `pg-protocol` is the appropriate library.","message":"This package (`pg-proto-parser`) is designed to parse PostgreSQL *Protocol Buffer definitions* (specifically for the AST generated by `libpg_query`), not raw SQL statements or the PostgreSQL wire protocol. Developers often confuse it with other `pg-` related parsing libraries like `pgsql-parser` (for SQL) or `pg-protocol` (for wire protocol), leading to incorrect usage. Ensure you need to process `.proto` files defining PostgreSQL internal structures.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Regularly regenerate your types and utilities with `pg-proto-parser` after updating the source PostgreSQL protobuf definitions. Implement robust versioning and compatibility checks for your generated code consumers, as per standard Protocol Buffers schema evolution best practices. Consider using tools like `proto-break` to detect breaking changes in `.proto` files before deployment.","message":"Changes in the underlying PostgreSQL protobuf schema (e.g., `libpg_query` protobuf definitions) can lead to breaking changes in the generated TypeScript types, interfaces, and utilities. Field renumbering, type changes, or removal of fields within the `.proto` files directly impact the output of `pg-proto-parser`, requiring updates to any code consuming these generated artifacts.","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.30.5':109 'abstract':27 'activ':114 'appear':111 'ast':30,82,142 'buffer':3,20 'code':74 'convers':88 'creation':77 'crucial':118 'current':106 'defin':64 'definit':4,22 'design':16 'develop':121 'direct':44 'enum':61,86 'environ':135 'facilit':75 'foundat':92 'function':48,55 'generat':51,73 'instead':45 'interfac':53 'intern':126 'javascript':136 'json':57 'launchql/pgsql-parser':99 'layer':119 'librari':11 'like':98 'maintain':101,115 'map':58 'messag':63 'node':83 'offer':116 'packag':104 'pars':18,35 'parser':5,10,144 'pg':8,140 'pg-proto-pars':7 'pganalyze/libpg_query':25 'postgr':138 'postgresql':1,26,41,68,96,124,139 'postgresql-rel':67 'primari':47 'project':15 'proto':9,21,143 'protobuf':70 'protocol':2,19,43 'queri':38,127,141 'raw':36 'relat':69 'represent':128 'safe':81,133 'schema':71 'serv':89 'simplifi':85 'specif':23 'sql':37,137 'structur':31 'syntax':28 'tool':93,97 'tree':29 'type':80,132 'type-saf':79,131 'typescript':14,52,134,145 'upgrad':102 'util':54 'valu':87 'version':108 'wire':42 'within':65 'work':122","created_at":"2026-04-20T01:56:10.598541+00:00","updated_at":"2026-04-20T01:56:10.598541+00:00","problems":[{"fix":"Ensure the package is installed (`npm install pg-proto-parser` or `yarn add pg-proto-parser`). If using ESM `import` syntax in a CommonJS project, ensure your `package.json` has `\"type\": \"module\"` or use a bundler. For TypeScript, check `tsconfig.json` for `moduleResolution` and `target` settings, and confirm the package's type declarations are correctly linked.","cause":"This error typically indicates an issue with module resolution, either due to incorrect package installation, wrong import paths, or a CommonJS/ESM conflict.","error":"Error: Cannot find module 'pg-proto-parser' or its corresponding type declarations."},{"fix":"When initializing `PgProtoParser`, pass a valid path to your primary `.proto` file as the first argument, and an options object containing at least `outDir` where the generated files should be placed. For example: `new PgProtoParser('path/to/your.proto', { outDir: './generated' });`","cause":"The `PgProtoParser` constructor requires a source for the protobuf definitions, either a protobuf `Root` object or a path to a `.proto` file, along with an `outDir` for generated files.","error":"Error: The 'root' or 'inFile' option must be provided to the PgProtoParser constructor."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/constructive-io/pgsql-parser","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/pg-proto-parser","openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}