Metadata-Version: 2.4
Name: locksafe
Version: 0.3.1
Summary: Postgres migration safety analyzer — catch dangerous operations before they run
Project-URL: Homepage, https://locksafe.dev
Project-URL: Repository, https://github.com/yourusername/locksafe
Project-URL: Issues, https://github.com/yourusername/locksafe/issues
License: MIT
Keywords: ci-cd,database,migrations,postgres,safety
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: sqlglot[c]>=25.0.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Requires-Dist: typing-extensions>=4.12.0
Provides-Extra: api
Requires-Dist: asyncpg>=0.29.0; extra == 'api'
Requires-Dist: boto3>=1.35.0; extra == 'api'
Requires-Dist: fastapi>=0.115.0; extra == 'api'
Requires-Dist: pydantic>=2.0.0; extra == 'api'
Requires-Dist: python-multipart>=0.0.9; extra == 'api'
Requires-Dist: razorpay>=1.4.0; extra == 'api'
Requires-Dist: sentry-sdk[fastapi]>=2.0.0; extra == 'api'
Requires-Dist: uvicorn[standard]>=0.30.0; extra == 'api'
Provides-Extra: dev
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: mypy>=1.11.0; extra == 'dev'
Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.7.0; extra == 'dev'
Description-Content-Type: text/markdown

# LockSafe AI
 
**Catch unsafe Postgres migrations before they reach production.**
 
LockSafe AI is a CLI tool that analyzes PostgreSQL migration files and detects operations that can cause production downtime or data loss — before they are applied.
 
---
 
## Installation
 
```bash
pip install locksafe
```
 
Requires Python 3.10+
 
---
 
## Usage
 
### Analyze a single file
 
```bash
locksafe analyze migration.sql
```
 
With options:
 
```bash
locksafe analyze migration.sql --severity HIGH
locksafe analyze migration.sql --fail-on CRITICAL
locksafe analyze migration.sql --format json
cat migration.sql | locksafe analyze --stdin
```
 
### Check multiple files (CI/CD)
 
Analyze an entire directory:
 
```bash
locksafe check migrations/
```
 
Only check files changed since a git reference:
 
```bash
locksafe check . --since origin/main
```
 
Fail the build on unsafe migrations:
 
```bash
locksafe check migrations/ --fail-on HIGH
```
 
---
 
## Example
 
**Input**
 
```sql
CREATE INDEX idx_users_email ON users(email);
 
ALTER TABLE users ADD COLUMN status TEXT NOT NULL;
 
TRUNCATE payments;
```
 
**Output**
 
```
🔐 LockSafe Analysis
File: migration.sql
Statements: 3 │ Critical: 2 │ High: 0 │ Medium: 0 │ Low: 0
 
⚠ Migration risks detected
 
🔴 [CRITICAL] Statement 1
↳ CREATE INDEX without CONCURRENTLY on table 'users'
 
🔴 [CRITICAL] Statement 2
↳ ADD COLUMN NOT NULL without DEFAULT causes table rewrite
 
🔴 [CRITICAL] Statement 3
↳ TRUNCATE destroys all rows in payments
```
 
---
 
## CLI Reference
 
### `locksafe analyze`
 
| Option | Description |
|---|---|
| `--format json` | Output results in JSON format |
| `--severity LEVEL` | Show findings at or above severity |
| `--fail-on LEVEL` | Exit with code `1` if threshold is met |
| `--ignore RULE_ID` | Ignore specific rule(s) |
| `--quiet` | No output if no issues found |
| `--stdin` | Read SQL from stdin |
 
### `locksafe check`
 
| Option | Description |
|---|---|
| `--since REF` | Only check files changed since git ref |
| `--format json` | Output results in JSON |
| `--severity LEVEL` | Filter findings by severity |
| `--fail-on LEVEL` | Exit threshold |
| `--ignore RULE_ID` | Ignore specific rules |
 
---
 
## Severity Levels
 
| Level | Meaning |
|---|---|
| 🔴 `CRITICAL` | High risk of downtime or data loss |
| 🟠 `HIGH` | Likely to cause production issues |
| 🟡 `MEDIUM` | May cause performance or locking issues |
| 🔵 `LOW` | Informational or minor risk |
 
---
 
## Exit Codes
 
| Code | Meaning |
|---|---|
| `0` | No issues found |
| `1` | Issues detected (based on `--fail-on`) |
| `2` | SQL parsing error |
 
---
 
## Debug Mode
 
```bash
locksafe --debug analyze migration.sql
```
 
---
 
## CI/CD Integration
 
Block unsafe migrations in your pipeline:
 
```bash
locksafe check migrations/
```
 
Fail only on critical issues:
 
```bash
locksafe check migrations/ --fail-on CRITICAL
```
 
Check only changed files on pull requests:
 
```bash
locksafe check . --since origin/main
```
 
Exits with code `1` if risks are detected at or above the configured threshold.
 
---
 
## Tips
 
- Always review `CRITICAL` findings before applying migrations in production
- Use `CONCURRENTLY` for index operations on large tables
- Avoid schema changes that trigger a full table rewrite during peak traffic
- Run `locksafe explain <rule-id>` to understand any flagged rule in depth
 
---
 
## License
 
MIT License