rules_postgres

API reference, generated from the module’s .bzl docstrings (stardoc).

User-facing rules for rules_postgres.

• pg_parse_valid_test wraps the parse_check C binary as a sh_test that gates a .sql file against PostgreSQL’s own parser (via libpg_query). Passes iff parse_check exits 0, fails with the parser’s error + cursor position on stderr otherwise. Use this to keep emitted-SQL or hand-written-DDL in sync with what PostgreSQL accepts.

• pg_parse_tree runs the sql_to_protobuf C binary on a .sql file and captures the marshalled pg_query.ParseResult protobuf bytes as a .pgpb artifact. This is the single-file convenience macro; multi-file pipelines should use sql_library + sql_ast_library from @rules_lang//polyglot:sql.bzl instead.

pg_parse_tree

load("@rules_postgres//postgres:defs.bzl", "pg_parse_tree")

pg_parse_tree(name, sql, out, **kwargs)

Run libpg_query over a .sql file, capture the protobuf AST.

Single-file convenience around @rules_postgres//tools:sql_to_protobuf. For multi-file pipelines, prefer sql_library + sql_ast_library from @rules_lang//polyglot:sql.bzl, which use the same C tool via pg_sql_toolchain and propagate SqlAstInfo so downstream projections (json, lean, catalog) compose cleanly.

PARAMETERS

RETURNS

A .pgpb file whose bytes are exactly the marshalled pg_query.ParseResult (see @libpg_query//:pg_query.proto).

pg_parse_valid_test

load("@rules_postgres//postgres:defs.bzl", "pg_parse_valid_test")

pg_parse_valid_test(name, sql, **kwargs)

Assert that a SQL file parses cleanly under PostgreSQL’s parser.

PARAMETERS

Module extension for rules_postgres.

Exposes two tag classes:

pg.query(version = …) — fetches libpg_query and builds it as a cc_library. Creates @libpg_query.

pg.source(version = …) — fetches the full PostgreSQL source tarball and lays a minimal BUILD overlay on top (filegroups for source dirs + a probe pg_common_string cc_library). Creates @postgres_src.

The two paths are independent. Most consumers want only pg.query for SQL parse-validation gates; pg.source is for advanced tooling that needs the full PG codebase under Bazel.

Default usage:

pg = use_extension("@rules_postgres//postgres:extensions.bzl", "pg")
pg.query(version = "17-6.2.2")
use_repo(pg, "libpg_query")

With full PG source as well:

pg.source(version = "17.6")
use_repo(pg, "libpg_query", "postgres_src")

For generating compile_commands.json (consumable by rules_lang’s c_ast_dump_from_compdb), see pg_meson_configure in postgres/meson.bzl. That rule runs a hermetic meson setup as a Bazel build action using rules_foreign_cc’s meson + ninja toolchains.

pg

pg = use_extension("@rules_postgres//postgres:extensions.bzl", "pg")
pg.query(version)
pg.source(lay_overlay, version)

Module extension fetching libpg_query and/or the full PostgreSQL source tree.

TAG CLASSES

query

Pull libpg_query as @libpg_query.

Attributes

source

Pull the PostgreSQL source tarball as @postgres_src.

Attributes