| Name | pgrubic JSON |
| Version |
0.6.3
JSON |
| download |
| home_page | None |
| Summary | PostgreSQL linter and formatter for schema migrations and design best practices |
| upload_time | 2025-07-12 22:27:43 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.12 |
| license | None |
| keywords |
pgrubic
sql
postgres
postgresql
linter
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# pgrubic
[](https://github.com/bolajiwahab/pgrubic/)
[](https://pypi.org/project/pgrubic/)
[](https://pypi.org/project/pgrubic/)
[](https://github.com/bolajiwahab/pgrubic/blob/main/LICENSE)
[](https://pypi.org/project/pgrubic/)
[](https://github.com/bolajiwahab/pgrubic/actions/workflows/ci.yml)
[](https://github.com/bolajiwahab/pgrubic/tree/python-coverage-comment-action-data)
[](https://github.com/bolajiwahab/pgrubic/actions/workflows/doc.yml)
[](https://github.com/bolajiwahab/pgrubic/actions/workflows/release.yml)
[](https://pepy.tech/projects/pgrubic)
[](https://github.com/bolajiwahab/pgrubic/actions/workflows/github-code-scanning/codeql)
[](https://github.com/pre-commit/pre-commit)
[](https://github.com/charliermarsh/ruff)
[](https://github.com/python/mypy)
[](https://github.com/PyCQA/bandit)
[](https://socket.dev/pypi/package/pgrubic/overview/)
[](https://github.com/bolajiwahab/pgrubic/actions/workflows/dependency-review.yml)
pgrubic is a PostgreSQL linter and formatter for schema migrations and design best practices.
## Features
- Over 100+ rules
- Automatic violation correction (e.g., automatically add `concurrently` to index create statements)
- River style code formatting for DML statements
- Almost identical stying with **pg_dump** for DDL statements
- Python 3.12+ compatibility
- Automatic caching to avoid reformatting unchanged files
- Violations suppression, statement level, and file level
## Getting Started
For more, see the [documentation](https://bolajiwahab.github.io/pgrubic/).
## Installation
```bash
pip install pgrubic
```
**<span style="color:red">pgrubic is only supported on Python 3.12 or higher</span>**.
## Usage
For linting, try any of the following:
```bash
pgrubic lint # Lint SQL files in the current directory (and any subdirectories)
pgrubic lint . # Lint SQL files in the current directory (and any subdirectories)
pgrubic lint directory # Lint SQL files in *directory* (and any subdirectories)
pgrubic lint directory/*.sql # Lint SQL files in *directory*
pgrubic lint directory/file.sql # Lint `file.sql` in *directory*
pgrubic lint file.sql # Lint `file.sql`
pgrubic lint directory/*.sql --fix # Lint SQL files in *directory* and fix violations automatically
pgrubic lint file.sql --fix # Lint `file.sql` and fix fixable violations automatically
```
Sample output from linting:
```bash
pgrubic lint *.sql
file.sql:1:38: TP017: Boolean field should be not be nullable
1 | ALTER TABLE public.example ADD COLUMN foo boolean DEFAULT false;
```
```bash
pgrubic file.sql
test.sql:1:38: TP017: Boolean field should be not be nullable
1 | ALTER TABLE public.example ADD COLUMN foo boolean DEFAULT false;
```
For formatting, try any of the following:
```bash
pgrubic format # Format SQL files in the current directory (and any subdirectories)
pgrubic format . # Format SQL files in the current directory (and any subdirectories)
pgrubic format directory # Format SQL files in *directory* (and any subdirectories)
pgrubic format directory/*.sql # Format SQL files in *directory*
pgrubic format directory/file.sql # Format `file.sql` in *directory*
pgrubic format file.sql # Format `file.sql`
pgrubic format directory/*.sql --check # Check if SQL files would have been modified, returning a non-zero exit code
pgrubic format file.sql --diff # Report if `file.sql` would have been modified, returning a non-zero exit code as well the difference between `file.sql` and how the formatted file would look like
```
pgrubic can also be used as a pre-commit hook:
```
- repo: https://github.com/bolajiwahab/pgrubic
rev: 0.6.3
hooks:
- id: pgrubic-lint
- id: pgrubic-format
```
## Configuration
pgrubic can be configured via the [`pgrubic.toml`] file in either the current directory, up to the root directory or the path set by the `PGRUBIC_CONFIG_PATH` environment variable.
The following configuration options are available in the [`pgrubic.toml`] with the following defaults:
```toml
# Path to the cache directory
cache-dir = ".pgrubic_cache"
# Include all files by default
include = []
# Exclude no files by default
exclude = []
[lint]
# Target version 14 of PostgreSQL by default
postgres-target-version = 14
# Enable all rules by default
select = []
# Disable no rules by default
ignore = []
# Include all files by default
include = []
# Exclude no files by default
exclude = []
# Ignore suppressing violations that are marked as `noqa` by default
ignore-noqa = false
# Disallowed schemas
disallowed-schemas = []
# Allowed extensions
allowed-extensions = []
# Allowed languages
allowed-languages = []
# Do not fix violations automatically
fix = false
# Consider all rules as fixable
fixable = []
# Consider all rules as fixable
unfixable = []
# Disallowed data types
disallowed-data-types = []
# Required columns
required-columns = []
# Suffix Timestamp columns with `_at` by default
timestamp-column-suffix = "_at"
# Suffix Date columns with suffix `_date` by default
date-column-suffix = "_date"
# Allow nay naming convention for partitions by default
regex-partition = "^.+$"
# Allow all any naming convention for indexes by default
regex-index = "^.+$"
# Allow any naming convention for primary key constraints by default
regex-constraint-primary-key = "^.+$"
# ALlow any naming convention for unique keys by default
regex-constraint-unique-key = "^.+$"
# Allow any naming convention for foreign keys by default
regex-constraint-foreign-key = "^.+$"
# Allow any naming convention for check constraints by default
regex-constraint-check = "^.+$"
# Allow any naming convention for exclusion constraints by default
regex-constraint-exclusion = "^.+$"
# Allow any naming convention for sequences by default
regex-sequence = "^.+$"
[format]
# Include all files by default
include = []
# Exclude no files by default
exclude = []
# Comma at the beginning of an item by default
comma-at-beginning = true
# New line before semicolon false by default
new-line-before-semicolon = false
# Remove pg_catalog from functions by default
remove-pg-catalog-from-functions = true
# Separate statements by a certain number by of new line, 1 by default
lines-between-statements = 1
# Check if files would have been modified, returning a non-zero exit code
check = false
# Report if files would have been modified, returning a non-zero exit code as well the difference between the current file and how the formatted file would look like
diff = false
# Whether to read the cache.
no-cache = false
```
Some configuration options can be supplied via CLI arguments such as `--check`, `--diff`, `--fix`.
```bash
pgrubic format --check
```
```bash
pgrubic format --diff
```
```bash
pgrubic lint --fix
```
## Rules
There are 100+ rules. All rules are enabled by default. For a complete list, see [here](https://bolajiwahab.github.io/pgrubic/rules/).
## Formatting style
pgrubic uses **River** style code formatting.
## Contributing
We welcome and greatly appreciate contributions. If you would like to contribute, please see the [contributing guidelines](https://github.com/bolajiwahab/pgrubic/blob/main/docs/docs/contributing.md).
## Support
Encountering issues? Take a look at the existing GitHub [issues](https://github.com/bolajiwahab/pgrubic/issues), and don't hesitate to open a new one.
## Acknowledgments
pgrubic is inspired by a number of similar tools such as [Strong Migrations](https://github.com/ankane/strong_migrations), [squabble](https://github.com/erik/squabble),
[squawk](https://github.com/sbdchd/squawk), [pgextwlist](https://github.com/dimitri/pgextwlist), [Don't_Do_This](https://wiki.postgresql.org/wiki/Don't_Do_This)
and [schemalint](https://github.com/kristiandupont/schemalint).
pgrubic is built upon the shoulders of:
- [pglast](https://github.com/lelit/pglast) - Python bindings to libpg_query
- [libpg_query](https://github.com/pganalyze/libpg_query) - PostgreSQL parser outside of the server environment
## License
pgrubic is released under GPL-3.0 license.
Raw data
{
"_id": null,
"home_page": null,
"name": "pgrubic",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": "Bolaji Wahab <bolajiwahab23@gmail.com>",
"keywords": "pgrubic, sql, postgres, postgresql, linter",
"author": null,
"author_email": "Bolaji Wahab <bolajiwahab23@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/3e/7f/91379817c87440d98a920e61bf1bc3ac59ea99b8fa8ccd96dfca7441f9f7/pgrubic-0.6.3.tar.gz",
"platform": null,
"description": "# pgrubic\n\n[](https://github.com/bolajiwahab/pgrubic/)\n[](https://pypi.org/project/pgrubic/)\n[](https://pypi.org/project/pgrubic/)\n[](https://github.com/bolajiwahab/pgrubic/blob/main/LICENSE)\n[](https://pypi.org/project/pgrubic/)\n[](https://github.com/bolajiwahab/pgrubic/actions/workflows/ci.yml)\n[](https://github.com/bolajiwahab/pgrubic/tree/python-coverage-comment-action-data)\n[](https://github.com/bolajiwahab/pgrubic/actions/workflows/doc.yml)\n[](https://github.com/bolajiwahab/pgrubic/actions/workflows/release.yml)\n[](https://pepy.tech/projects/pgrubic)\n[](https://github.com/bolajiwahab/pgrubic/actions/workflows/github-code-scanning/codeql)\n[](https://github.com/pre-commit/pre-commit)\n[](https://github.com/charliermarsh/ruff)\n[](https://github.com/python/mypy)\n[](https://github.com/PyCQA/bandit)\n[](https://socket.dev/pypi/package/pgrubic/overview/)\n[](https://github.com/bolajiwahab/pgrubic/actions/workflows/dependency-review.yml)\n\npgrubic is a PostgreSQL linter and formatter for schema migrations and design best practices.\n\n## Features\n\n- Over 100+ rules\n- Automatic violation correction (e.g., automatically add `concurrently` to index create statements)\n- River style code formatting for DML statements\n- Almost identical stying with **pg_dump** for DDL statements\n- Python 3.12+ compatibility\n- Automatic caching to avoid reformatting unchanged files\n- Violations suppression, statement level, and file level\n\n## Getting Started\n\nFor more, see the [documentation](https://bolajiwahab.github.io/pgrubic/).\n\n## Installation\n\n```bash\npip install pgrubic\n```\n\n**<span style=\"color:red\">pgrubic is only supported on Python 3.12 or higher</span>**.\n\n## Usage\n\nFor linting, try any of the following:\n\n```bash\npgrubic lint # Lint SQL files in the current directory (and any subdirectories)\npgrubic lint . # Lint SQL files in the current directory (and any subdirectories)\npgrubic lint directory # Lint SQL files in *directory* (and any subdirectories)\npgrubic lint directory/*.sql # Lint SQL files in *directory*\npgrubic lint directory/file.sql # Lint `file.sql` in *directory*\npgrubic lint file.sql # Lint `file.sql`\npgrubic lint directory/*.sql --fix # Lint SQL files in *directory* and fix violations automatically\npgrubic lint file.sql --fix # Lint `file.sql` and fix fixable violations automatically\n```\n\nSample output from linting:\n\n```bash\npgrubic lint *.sql\n\nfile.sql:1:38: TP017: Boolean field should be not be nullable\n\n1 | ALTER TABLE public.example ADD COLUMN foo boolean DEFAULT false;\n```\n\n```bash\npgrubic file.sql\n\ntest.sql:1:38: TP017: Boolean field should be not be nullable\n\n1 | ALTER TABLE public.example ADD COLUMN foo boolean DEFAULT false;\n```\n\nFor formatting, try any of the following:\n\n```bash\npgrubic format # Format SQL files in the current directory (and any subdirectories)\npgrubic format . # Format SQL files in the current directory (and any subdirectories)\npgrubic format directory # Format SQL files in *directory* (and any subdirectories)\npgrubic format directory/*.sql # Format SQL files in *directory*\npgrubic format directory/file.sql # Format `file.sql` in *directory*\npgrubic format file.sql # Format `file.sql`\npgrubic format directory/*.sql --check # Check if SQL files would have been modified, returning a non-zero exit code\npgrubic format file.sql --diff # Report if `file.sql` would have been modified, returning a non-zero exit code as well the difference between `file.sql` and how the formatted file would look like\n```\n\npgrubic can also be used as a pre-commit hook:\n\n```\n- repo: https://github.com/bolajiwahab/pgrubic\n rev: 0.6.3\n hooks:\n - id: pgrubic-lint\n - id: pgrubic-format\n```\n\n## Configuration\n\npgrubic can be configured via the [`pgrubic.toml`] file in either the current directory, up to the root directory or the path set by the `PGRUBIC_CONFIG_PATH` environment variable.\n\nThe following configuration options are available in the [`pgrubic.toml`] with the following defaults:\n\n```toml\n# Path to the cache directory\ncache-dir = \".pgrubic_cache\"\n\n# Include all files by default\ninclude = []\n\n# Exclude no files by default\nexclude = []\n\n[lint]\n# Target version 14 of PostgreSQL by default\npostgres-target-version = 14\n\n# Enable all rules by default\nselect = []\n\n# Disable no rules by default\nignore = []\n\n# Include all files by default\ninclude = []\n\n# Exclude no files by default\nexclude = []\n\n# Ignore suppressing violations that are marked as `noqa` by default\nignore-noqa = false\n\n# Disallowed schemas\ndisallowed-schemas = []\n\n# Allowed extensions\nallowed-extensions = []\n\n# Allowed languages\nallowed-languages = []\n\n# Do not fix violations automatically\nfix = false\n\n# Consider all rules as fixable\nfixable = []\n\n# Consider all rules as fixable\nunfixable = []\n\n# Disallowed data types\ndisallowed-data-types = []\n\n# Required columns\nrequired-columns = []\n\n# Suffix Timestamp columns with `_at` by default\ntimestamp-column-suffix = \"_at\"\n\n# Suffix Date columns with suffix `_date` by default\ndate-column-suffix = \"_date\"\n\n# Allow nay naming convention for partitions by default\nregex-partition = \"^.+$\"\n\n# Allow all any naming convention for indexes by default\nregex-index = \"^.+$\"\n\n# Allow any naming convention for primary key constraints by default\nregex-constraint-primary-key = \"^.+$\"\n\n# ALlow any naming convention for unique keys by default\nregex-constraint-unique-key = \"^.+$\"\n\n# Allow any naming convention for foreign keys by default\nregex-constraint-foreign-key = \"^.+$\"\n\n# Allow any naming convention for check constraints by default\nregex-constraint-check = \"^.+$\"\n\n# Allow any naming convention for exclusion constraints by default\nregex-constraint-exclusion = \"^.+$\"\n\n# Allow any naming convention for sequences by default\nregex-sequence = \"^.+$\"\n\n[format]\n# Include all files by default\ninclude = []\n\n# Exclude no files by default\nexclude = []\n\n# Comma at the beginning of an item by default\ncomma-at-beginning = true\n\n# New line before semicolon false by default\nnew-line-before-semicolon = false\n\n# Remove pg_catalog from functions by default\nremove-pg-catalog-from-functions = true\n\n# Separate statements by a certain number by of new line, 1 by default\nlines-between-statements = 1\n\n# Check if files would have been modified, returning a non-zero exit code\ncheck = false\n\n# Report if files would have been modified, returning a non-zero exit code as well the difference between the current file and how the formatted file would look like\ndiff = false\n\n# Whether to read the cache.\nno-cache = false\n```\n\nSome configuration options can be supplied via CLI arguments such as `--check`, `--diff`, `--fix`.\n\n```bash\npgrubic format --check\n```\n\n```bash\npgrubic format --diff\n```\n\n```bash\npgrubic lint --fix\n```\n\n## Rules\n\nThere are 100+ rules. All rules are enabled by default. For a complete list, see [here](https://bolajiwahab.github.io/pgrubic/rules/).\n\n## Formatting style\n\npgrubic uses **River** style code formatting.\n\n## Contributing\n\nWe welcome and greatly appreciate contributions. If you would like to contribute, please see the [contributing guidelines](https://github.com/bolajiwahab/pgrubic/blob/main/docs/docs/contributing.md).\n\n## Support\n\nEncountering issues? Take a look at the existing GitHub [issues](https://github.com/bolajiwahab/pgrubic/issues), and don't hesitate to open a new one.\n\n## Acknowledgments\n\npgrubic is inspired by a number of similar tools such as [Strong Migrations](https://github.com/ankane/strong_migrations), [squabble](https://github.com/erik/squabble),\n[squawk](https://github.com/sbdchd/squawk), [pgextwlist](https://github.com/dimitri/pgextwlist), [Don't_Do_This](https://wiki.postgresql.org/wiki/Don't_Do_This)\nand [schemalint](https://github.com/kristiandupont/schemalint).\n\npgrubic is built upon the shoulders of:\n\n- [pglast](https://github.com/lelit/pglast) - Python bindings to libpg_query\n- [libpg_query](https://github.com/pganalyze/libpg_query) - PostgreSQL parser outside of the server environment\n\n## License\n\npgrubic is released under GPL-3.0 license.\n",
"bugtrack_url": null,
"license": null,
"summary": "PostgreSQL linter and formatter for schema migrations and design best practices",
"version": "0.6.3",
"project_urls": {
"Changelog": "https://github.com/bolajiwahab/pgrubic/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/bolajiwahab/pgrubic/blob/main/README.md",
"Homepage": "https://github.com/bolajiwahab/pgrubic",
"Issue Tracker": "https://github.com/bolajiwahab/pgrubic/issues",
"Repository": "https://github.com/bolajiwahab/pgrubic"
},
"split_keywords": [
"pgrubic",
" sql",
" postgres",
" postgresql",
" linter"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "72f5c9349e3d390f1f7507bbf0c5752a94b3cc50be565fd3b64409a9c5c8ed13",
"md5": "d9913f3e186c472c18fab70b0809207f",
"sha256": "cac4e4fbb8238789c27e1d97e4a45ffa6bbb301d0261bed66baca4dd2b462e01"
},
"downloads": -1,
"filename": "pgrubic-0.6.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d9913f3e186c472c18fab70b0809207f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 165697,
"upload_time": "2025-07-12T22:27:42",
"upload_time_iso_8601": "2025-07-12T22:27:42.290583Z",
"url": "https://files.pythonhosted.org/packages/72/f5/c9349e3d390f1f7507bbf0c5752a94b3cc50be565fd3b64409a9c5c8ed13/pgrubic-0.6.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3e7f91379817c87440d98a920e61bf1bc3ac59ea99b8fa8ccd96dfca7441f9f7",
"md5": "d77e76bb55d53a4bfc4229e2eb340221",
"sha256": "6e396c5a70b63f312d02981279b2d4bd3bfb11082d3b1daa7d4aaaf765505a51"
},
"downloads": -1,
"filename": "pgrubic-0.6.3.tar.gz",
"has_sig": false,
"md5_digest": "d77e76bb55d53a4bfc4229e2eb340221",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 92691,
"upload_time": "2025-07-12T22:27:43",
"upload_time_iso_8601": "2025-07-12T22:27:43.922195Z",
"url": "https://files.pythonhosted.org/packages/3e/7f/91379817c87440d98a920e61bf1bc3ac59ea99b8fa8ccd96dfca7441f9f7/pgrubic-0.6.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-12 22:27:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bolajiwahab",
"github_project": "pgrubic",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pgrubic"
}
