locksafe 0.3.0

Postgres migration safety analyzer — catch dangerous operations before they run

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

pip install locksafe

Requires Python 3.12+

---

Usage

Analyze a single file

locksafe analyze migration.sql

With options:

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:

locksafe check migrations/

Only check files changed since a git reference:

locksafe check . --since origin/main

Fail the build on unsafe migrations:

locksafe check migrations/ --fail-on HIGH

---

Example

Input

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

locksafe --debug analyze migration.sql

---

CI/CD Integration

Block unsafe migrations in your pipeline:

locksafe check migrations/

Fail only on critical issues:

locksafe check migrations/ --fail-on CRITICAL

Check only changed files on pull requests:

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