{"id":46463909,"url":"https://github.com/hardbyte/pgroles","last_synced_at":"2026-04-15T00:00:42.300Z","repository":{"id":342426346,"uuid":"1173894781","full_name":"hardbyte/pgroles","owner":"hardbyte","description":"Declarative PostgreSQL role graph manager. Define roles, memberships, object privileges, and default privileges in YAML.","archived":false,"fork":false,"pushed_at":"2026-04-14T03:20:00.000Z","size":1794,"stargazers_count":9,"open_issues_count":10,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-14T03:20:46.755Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hardbyte.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":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-05T21:31:14.000Z","updated_at":"2026-04-14T03:18:56.000Z","dependencies_parsed_at":"2026-03-12T01:00:32.171Z","dependency_job_id":null,"html_url":"https://github.com/hardbyte/pgroles","commit_stats":null,"previous_names":["hardbyte/pgpolicy"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/hardbyte/pgroles","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hardbyte%2Fpgroles","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hardbyte%2Fpgroles/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hardbyte%2Fpgroles/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hardbyte%2Fpgroles/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hardbyte","download_url":"https://codeload.github.com/hardbyte/pgroles/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hardbyte%2Fpgroles/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31820369,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"ssl_error","status_checked_at":"2026-04-14T18:05:01.765Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":"2026-03-06T04:05:18.121Z","updated_at":"2026-04-15T00:00:42.288Z","avatar_url":"https://github.com/hardbyte.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"pgroles logo\" src=\"https://raw.githubusercontent.com/hardbyte/pgroles/main/docs/public/logo.svg\" width=\"140\" /\u003e\n\u003c/p\u003e\n\n# pgroles\n\n\u003cdiv align=\"center\"\u003e\n\n[![CI](https://github.com/hardbyte/pgroles/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/hardbyte/pgroles/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/hardbyte/pgroles?sort=semver)](https://github.com/hardbyte/pgroles/releases)\n[![Docs](https://img.shields.io/badge/docs-github_pages-blue)](https://hardbyte.github.io/pgroles/)\n[![Helm Chart OCI](https://img.shields.io/badge/helm-ghcr.io%2Fhardbyte%2Fcharts-informational)](https://github.com/hardbyte/pgroles/pkgs/container/charts%2Fpgroles-operator)\n\n\u003c/div\u003e\n\nDeclarative PostgreSQL access control. Define roles, grants, and memberships in YAML — pgroles diffs against your live database and generates the exact SQL to converge it.\n\nBy default, anything not in the manifest gets revoked or dropped. Same model as Terraform, applied to PostgreSQL. For incremental adoption, use `--mode additive` to only grant and never revoke, or `--mode adopt` to manage declared roles fully without dropping undeclared ones.\n\n## How it works\n\nDefine a policy. Profiles are reusable privilege templates that expand across schemas:\n\n```yaml\nprofiles:\n  editor:\n    grants:\n      - privileges: [USAGE]\n        object: { type: schema }\n      - privileges: [SELECT, INSERT, UPDATE, DELETE, REFERENCES, TRIGGER]\n        object: { type: table, name: \"*\" }\n      - privileges: [USAGE, SELECT, UPDATE]\n        object: { type: sequence, name: \"*\" }\n      - privileges: [EXECUTE]\n        object: { type: function, name: \"*\" }\n    default_privileges:\n      - privileges: [SELECT, INSERT, UPDATE, DELETE, REFERENCES, TRIGGER]\n        on_type: table\n      - privileges: [USAGE, SELECT, UPDATE]\n        on_type: sequence\n      - privileges: [EXECUTE]\n        on_type: function\n\n  viewer:\n    grants:\n      - privileges: [USAGE]\n        object: { type: schema }\n      - privileges: [SELECT]\n        object: { type: table, name: \"*\" }\n\nschemas:\n  - name: inventory\n    profiles: [editor, viewer]\n  - name: catalog\n    profiles: [viewer]\n\nroles:\n  - name: app-service\n    login: true\n\nmemberships:\n  - role: inventory-editor\n    members:\n      - name: app-service\n```\n\nThis generates roles `inventory-editor`, `inventory-viewer`, and `catalog-viewer`, each scoped to their schema. `app-service` gets `inventory-editor` membership.\n\nRun `pgroles diff` to see exactly what SQL will be executed:\n\n```sql\nCREATE ROLE \"inventory-editor\"\n  NOLOGIN NOSUPERUSER INHERIT;\n\nGRANT USAGE ON SCHEMA \"inventory\"\n  TO \"inventory-editor\";\nGRANT SELECT, INSERT, UPDATE, DELETE, REFERENCES, TRIGGER\n  ON TABLE \"inventory\".\"orders\"\n  TO \"inventory-editor\";\nGRANT SELECT, INSERT, UPDATE, DELETE, REFERENCES, TRIGGER\n  ON TABLE \"inventory\".\"customers\"\n  TO \"inventory-editor\";\nGRANT USAGE, SELECT, UPDATE\n  ON SEQUENCE \"inventory\".\"orders_id_seq\"\n  TO \"inventory-editor\";\nGRANT EXECUTE\n  ON FUNCTION \"inventory\".\"refresh_inventory_cache\"()\n  TO \"inventory-editor\";\n\n-- Roles removed from the manifest get cleaned up:\nREVOKE ALL ON SCHEMA \"legacy\"\n  FROM \"old-reader\";\nDROP ROLE \"old-reader\";\n```\n\nFor wildcard relation grants, pgroles expands the current objects of the requested\ntype safely, so table grants do not accidentally touch views or materialized\nviews.\n\nThen `pgroles apply` to execute it.\n\n## Quick start\n\n```bash\n# Already have a database with roles? Generate a manifest from it:\npgroles generate --database-url postgres://... \u003e pgroles.yaml\n\n# See what SQL pgroles would run:\npgroles diff -f pgroles.yaml --database-url postgres://...\n\n# Apply the changes:\npgroles apply -f pgroles.yaml --database-url postgres://...\n\n# Write the generated manifest directly to a file:\npgroles generate --database-url postgres://... --output pgroles.yaml\n```\n\n`--database-url` can also be set via the `DATABASE_URL` environment variable.\n\n## Install\n\n**Pre-built binaries** from [GitHub Releases](https://github.com/hardbyte/pgroles/releases) (Linux x86_64/aarch64, macOS x86_64/aarch64).\n\n**Cargo CLI:**\n```bash\ncargo install pgroles-cli\n```\n\n**Rust crates:**\n- [`pgroles-cli`](https://crates.io/crates/pgroles-cli) — end-user CLI\n- [`pgroles-core`](https://crates.io/crates/pgroles-core) — manifest model, diff engine, SQL rendering\n- [`pgroles-inspect`](https://crates.io/crates/pgroles-inspect) — database inspection and managed-provider detection\n- [`pgroles-operator`](https://crates.io/crates/pgroles-operator) — Kubernetes operator crate, controller runtime, and CRD types\n\n**Docker:**\n```bash\ndocker run --rm ghcr.io/hardbyte/pgroles --help\n```\n\n## Features\n\n- **Convergent** — the manifest is the desired state. Missing roles get created, extra roles get dropped, drifted grants get fixed.\n- **Reconciliation modes** — `--mode authoritative` (default) for full convergence, `--mode additive` to only grant and never revoke, `--mode adopt` to manage declared roles without dropping undeclared ones. Additive mode is the safest way to start using pgroles on an existing database.\n- **Profiles** — define privilege templates once, apply them across schemas. Each `schema x profile` pair becomes a role.\n- **Safer privilege bundles** — common application profiles can pair table, sequence, and function privileges so identity columns and trigger-driven routines are covered together.\n- **Brownfield adoption** — `pgroles generate` introspects an existing database and produces a manifest you can refine.\n- **Reproducible export** — `pgroles generate --output` writes the current database state directly to a manifest file.\n- **Drift detection** — `pgroles diff --exit-code` returns exit code 2 on drift, designed for CI gates.\n- **Password management** — login roles can set passwords from environment variables (CLI) or Kubernetes Secrets (operator), with `VALID UNTIL` expiration and redacted output.\n- **Safe role removal** — preflight checks for owned objects, active sessions, and dependencies before dropping roles. Explicit `retirements` declare cleanup steps.\n- **Managed PostgreSQL** — works with RDS, Aurora, Cloud SQL, AlloyDB, and Azure Database for PostgreSQL. Detects provider-specific reserved roles and warns about privilege limitations.\n- **Kubernetes operator** — reconcile `PostgresPolicy` custom resources continuously. Install via Helm:\n  ```bash\n  helm install pgroles-operator oci://ghcr.io/hardbyte/charts/pgroles-operator\n  ```\n  Use `spec.mode: plan` to inspect drift without executing SQL.\n\n## Documentation\n\nFull documentation is published at [hardbyte.github.io/pgroles](https://hardbyte.github.io/pgroles/).\n\n- [Quick start](https://hardbyte.github.io/pgroles/docs/quick-start/)\n- [Installation](https://hardbyte.github.io/pgroles/docs/installation/)\n- [Manifest format](https://hardbyte.github.io/pgroles/docs/manifest-format/)\n- [CLI reference](https://hardbyte.github.io/pgroles/docs/cli/)\n- [Kubernetes operator](https://hardbyte.github.io/pgroles/docs/operator/)\n- [Operator architecture](https://hardbyte.github.io/pgroles/docs/operator-architecture/)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhardbyte%2Fpgroles","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhardbyte%2Fpgroles","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhardbyte%2Fpgroles/lists"}