Skip to content

Commit 3184254

Browse files
3nids3nids
committed
checker docs
1 parent 8a70d67 commit 3184254

File tree

2 files changed

+131
-1
lines changed

2 files changed

+131
-1
lines changed

‎docs/docs/checker.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Database Checker
2+
3+
The PUM Checker is a powerful tool for comparing two PostgreSQL databases and identifying structural differences. This is particularly useful for:
4+
5+
- **Quality Assurance**: Verify that development and production databases are in sync
6+
- **Migration Validation**: Confirm that database upgrades were applied correctly
7+
- **Environment Comparison**: Compare staging, testing, and production environments
8+
- **CI/CD Integration**: Automatically validate database schemas in continuous integration pipelines
9+
10+
## How It Works
11+
12+
The Checker compares two PostgreSQL databases by analyzing their metadata from `information_schema` tables. It performs systematic checks across multiple database elements and generates a detailed report of any differences found.
13+
14+
### Comparison Process
15+
16+
1. **Connection**: Establishes connections to both databases using PostgreSQL service names
17+
2. **Element Scanning**: Queries database metadata for each structural element
18+
3. **Comparison**: Compares the results between the two databases
19+
4. **Difference Detection**: Identifies added (+) or removed (-) elements
20+
5. **Report Generation**: Creates a comprehensive report in text, HTML, or JSON format
21+
22+
### Checked Elements
23+
24+
The Checker examines the following database elements:
25+
26+
- **Tables**: Table definitions and their schemas
27+
- **Columns**: Column names, types, and attributes
28+
- **Constraints**: Primary keys, foreign keys, unique constraints, and check constraints
29+
- **Views**: View definitions
30+
- **Sequences**: Sequence definitions and configurations
31+
- **Indexes**: Index definitions and types
32+
- **Triggers**: Trigger functions and configurations
33+
- **Functions**: Stored procedures and functions
34+
- **Rules**: Database rules
35+
36+
### Filtering and Exclusions
37+
38+
You can customize what gets compared:
39+
40+
- **Ignore specific elements**: Skip certain types of objects (e.g., `--ignore views triggers`)
41+
- **Exclude schemas**: Ignore specific schemas (e.g., `-N audit -N logging`)
42+
- **Exclude field patterns**: Filter out fields matching SQL LIKE patterns (e.g., `-P '%_backup'`)
43+
44+
System schemas (`information_schema` and `pg_%`) are automatically excluded from checks.
45+
46+
## Output Formats
47+
48+
The Checker supports three output formats:
49+
50+
### Text Format (Default)
51+
Simple, readable text output showing differences with `+` (added) and `-` (removed) markers.
52+
53+
```
54+
Tables: OK
55+
Columns: 2 differences found
56+
+ public.users.created_at
57+
- public.users.updated_by
58+
```
59+
60+
### HTML Format
61+
Interactive HTML report with styling and collapsible sections, ideal for sharing with teams or embedding in documentation.
62+
63+
### JSON Format
64+
Structured JSON output for programmatic processing and integration with other tools.
65+
66+
## Usage
67+
68+
For detailed command-line usage and examples, see the [check command documentation](cli/check.md).
69+
70+
### Basic Example
71+
72+
```bash
73+
pum -s my_database check production_database
74+
```
75+
76+
This compares the `my_database` service against `production_database` and shows any structural differences.
77+
78+
### Advanced Example
79+
80+
```bash
81+
pum -s dev_db check prod_db \
82+
--ignore triggers functions \
83+
--exclude-schema audit \
84+
--format html \
85+
--output_file comparison_report.html
86+
```
87+
88+
This creates an HTML report comparing databases while ignoring triggers and functions, and excluding the audit schema.
89+
90+
## Exit Codes
91+
92+
- **0**: Databases are identical (or only ignored differences were found)
93+
- **1**: Differences were detected
94+
95+
This makes the Checker ideal for CI/CD pipelines where you need to fail builds if databases are out of sync.
96+
97+
## Programmatic Usage
98+
99+
You can also use the Checker in Python code:
100+
101+
```python
102+
from pum.checker import Checker
103+
from pum.report_generator import ReportGenerator
104+
105+
checker = Checker(
106+
pg_service1="development",
107+
pg_service2="production",
108+
exclude_schema=["audit"],
109+
ignore_list=["triggers"]
110+
)
111+
112+
report = checker.run_checks()
113+
114+
if report.passed:
115+
print("✓ Databases are in sync")
116+
else:
117+
print(f"✗ Found {report.total_differences} differences")
118+
119+
# Generate HTML report
120+
html = ReportGenerator.generate_html(report)
121+
with open("report.html", "w") as f:
122+
f.write(html)
123+
```
124+
125+
## See Also
126+
127+
- [CLI Reference](cli/check.md) - Complete command-line options and examples
128+
- [Getting Started](getting_started.md) - Initial setup and configuration
129+
- [Application](application.md) - Understanding the PUM architecture

‎docs/mkdocs.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@ markdown_extensions:
6767
nav:
6868
- About: index.md
6969
- Getting Started: getting_started.md
70+
- Application: application.md
7071
- Configuration:
7172
- Overview: configuration/configuration.md
7273
- ConfigModel: configuration/config_model.md
@@ -78,8 +79,8 @@ nav:
7879
- PumModel: configuration/pum_model.md
7980
- RoleModel: configuration/role_model.md
8081

81-
- Application: application.md
8282
- Roles: roles.md
83+
- Checker: checker.md
8384
- CLI:
8485
- Overview: cli.md
8586
- info: cli/info.md

0 commit comments

Comments
 (0)