{"id":44257443,"url":"https://github.com/iamsr/tapa","last_synced_at":"2026-02-12T18:01:05.434Z","repository":{"id":337491337,"uuid":"1151337144","full_name":"iamsr/tapa","owner":"iamsr","description":"A tool that predicts the production impact of database migrations before execution.","archived":false,"fork":false,"pushed_at":"2026-02-09T20:25:19.000Z","size":631,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-10T19:22:04.213Z","etag":null,"topics":["database","migration","mysql","postgres"],"latest_commit_sha":null,"homepage":"https://tapa-rho.vercel.app/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iamsr.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-06T10:41:26.000Z","updated_at":"2026-02-09T20:21:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/iamsr/tapa","commit_stats":null,"previous_names":["iamsr/tapa"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/iamsr/tapa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamsr%2Ftapa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamsr%2Ftapa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamsr%2Ftapa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamsr%2Ftapa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iamsr","download_url":"https://codeload.github.com/iamsr/tapa/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamsr%2Ftapa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29338656,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-11T16:14:43.024Z","status":"ssl_error","status_checked_at":"2026-02-11T16:14:15.258Z","response_time":97,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["database","migration","mysql","postgres"],"created_at":"2026-02-10T16:35:24.354Z","updated_at":"2026-02-11T17:01:20.725Z","avatar_url":"https://github.com/iamsr.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Table Alteration Planning Assistant (TAPA)\n\n[![codecov](https://codecov.io/gh/iamsr/tapa/branch/main/graph/badge.svg)](https://codecov.io/gh/iamsr/tapa)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n\n**[https://tapa.com](https://tapa-rho.vercel.app/)**\n\nA static analysis tool that predicts the production impact of database migrations before execution. TAPA analyzes migration files and provides risk assessments, lock predictions, time estimates, and safer alternatives.\n\n**Supported Databases:** PostgreSQL 9.6+, MySQL 5.7+\n\n## Features\n\n### Migration Analysis\n\n- **Lock Detection**: Predicts lock types (ACCESS EXCLUSIVE, SHARE, etc.) and durations\n- **Risk Scoring**: Calculates risk scores (0-100) with categorization (LOW, MEDIUM, HIGH, CRITICAL)\n- **Time Estimation**: Estimates execution time including table rewrites and index builds\n- **Dependency Analysis**: Identifies breaking changes (indexes, views, foreign keys)\n- **Safe Alternatives**: Generates multi-step alternatives for high-risk operations\n- **Migration Batching**: Groups operations by risk for safer deployment\n\n### Database Support\n\n- **PostgreSQL**: Full DDL parsing with pg_query, supports CONCURRENTLY operations\n- **MySQL**: Native vitess parser with ALGORITHM/LOCK clause detection\n- **pt-online-schema-change**: Automatic command generation for high-risk MySQL operations\n- **Schema Introspection**: Queries live database metadata for accurate analysis\n\n### CI/CD Integration\n\n- **GitHub Actions**: Automatic PR analysis with risk-based blocking and comments\n- **GitLab CI**: Pipeline integration with JSON and Markdown reports\n- **JSON Output**: Machine-readable format for custom automation workflows\n\n## Installation\n\n```bash\ngo install github.com/iamsr/tapa/cmd/tapa@latest\n```\n\n## Quick Start\n\n### Analyze Migrations\n\n**PostgreSQL:**\n\n```bash\n# Single file\ntapa analyze migrations/001_add_column.sql --db postgres://localhost/mydb\n\n# Directory\ntapa analyze migrations/ --db postgres://user:pass@host/dbname\n\n# Comprehensive analysis with all features\ntapa analyze migrations/ --db $DATABASE_URL --comprehensive\n```\n\n**MySQL:**\n\n```bash\n# Basic analysis\ntapa analyze migrations/001_add_index.sql --db-type mysql --db mysql://root@localhost/mydb\n\n# With pt-osc recommendations\ntapa analyze migrations/ --db-type mysql --db mysql://localhost/mydb\n\n# Dry run (no database connection)\ntapa analyze migrations/ --db-type mysql --dry-run\n```\n\n### Output Formats\n\n**Human-readable (default):**\n\nTAPA provides beautiful, color-coded output with visual summary cards:\n\n```bash\ntapa analyze migrations/001_migration.sql --db $DATABASE_URL\n```\n\nExample output:\n\n```\n  ✓ Dry-run mode (no database connection)\n  Parsing migration file(s)...\n  ✓ Found 6 statements\n  Analyzing operations...\n  ✓ Analysis complete\n\n╭─ ANALYSIS RESULTS ────────────────────────────────────────────────────────╮\n│ Risk Score                                                               │\n│ ███████████████████░░░░░░░░░  70/100                                     │\n│ Status: HIGH RISK 🟠                                                     │\n│                                                                          │\n│ Est. Time: 4.3m                                                          │\n│                                                                          │\n│ Risk Breakdown:                                                          │\n│     ├── Low      ▪ 1                                                     │\n│     ├── Medium   ▪▪ 2                                                    │\n│     ├── High     ▪▪▪ 3                                                   │\n│     └── Critical  0                                                      │\n│                                                                          │\n│ Compatibility:                                                           │\n│   ✓ All operations backward compatible (6/6)                             │\n│   ✓ No breaking changes                                                  │\n│   ⚠ Requires maintenance window                                         │\n╰──────────────────────────────────────────────────────────────────────────╯\n```\n\nFeatures:\n\n- Visual progress bars with risk-based coloring\n- Tree-style risk breakdown with operation counts\n- Emoji status indicators for quick assessment\n- Compatibility checks at a glance\n\n**JSON (for CI/CD):**\n\n```bash\ntapa analyze migrations/ --db $DATABASE_URL --format json \u003e report.json\n```\n\n### Migration Batching\n\nGenerate safer deployment strategies by grouping operations by risk level:\n\n```bash\n# Analyze and generate batching strategy\ntapa batch migrations/ --db-type postgresql\n\n# Output in JSON format\ntapa batch migrations/ --format json \u003e batches.json\n```\n\nFeatures:\n\n- Risk-based operation grouping\n- Automatic prerequisite detection\n- Parallel execution recommendations\n- Per-batch time estimates\n\nSee [Batching Guide](docs/batching-guide.md) for details.\n\n### Progress Output\n\nTAPA displays step-by-step progress on stderr during analysis:\n\n```bash\ntapa analyze migrations/ --db $DATABASE_URL\n```\n\nProgress output (on stderr):\n\n```\n  Connecting to database...\n  ✓ Connected to Postgresql\n  Parsing migration file(s)...\n  ✓ Found 6 statements\n  Analyzing operations...\n  ✓ Analysis complete\n```\n\nThis keeps stdout clean for JSON output while showing progress:\n\n```bash\ntapa analyze migrations/ --format json \u003e report.json  # Progress on stderr, JSON on stdout\n```\n\nDisable emojis in progress output:\n\n```bash\nTAPA_NO_EMOJI=1 tapa analyze migrations/\n```\n\n### Color-Coded Output\n\nTAPA automatically displays risk levels and lock types in color for better visibility:\n\n- **Risk Levels:** Green (LOW), Yellow (MEDIUM), Orange (HIGH), Red (CRITICAL)\n- **Lock Types:** Color-coded based on severity\n\nDisable colors or emojis if needed:\n\n```bash\nNO_COLOR=1 tapa analyze migrations/       # Disable colors\nTAPA_NO_EMOJI=1 tapa analyze migrations/  # Replace emojis with text\n```\n\n### CI/CD Integration\n\n**GitHub Actions:**\n\n```yaml\n- uses: ./.github/actions/tapa-analyzer\n  with:\n    migration-path: \"migrations/\"\n    db-type: \"postgresql\"\n    fail-on-risk: \"high\"\n    github-token: ${{ secrets.GITHUB_TOKEN }}\n```\n\n**GitLab CI:**\n\n```yaml\nmigration-analysis:\n  script:\n    - ./.gitlab/tapa-analyzer.sh migrations/\n  variables:\n    DMA_DB_TYPE: postgresql\n    DMA_FAIL_ON_RISK: high\n```\n\n## Documentation\n\n- **[Architecture Guide](docs/architecture.md)** - Comprehensive system design, algorithms, and extension points\n- [Migration Batching Guide](docs/batching-guide.md) - Safer incremental deployment strategies\n- [MySQL Support Guide](docs/mysql-support.md) - MySQL-specific features and pt-osc integration\n- [GitHub Actions Setup](docs/github-action-usage.md) - Automated PR analysis\n- [GitLab CI Setup](docs/gitlab-ci-usage.md) - Pipeline integration\n\nFull documentation available in [docs/](docs/).\n\n## Architecture\n\nTAPA uses a multi-stage pipeline architecture for comprehensive migration analysis:\n\n```\ncmd/tapa/              # CLI entry point\ninternal/\n  parser/             # SQL parsing (PostgreSQL pg_query, MySQL Vitess)\n  analyzer/           # Lock detection, risk scoring, time estimation\n  introspector/       # Live database metadata queries\n  db/                 # Database connection management\n  batcher/            # Risk-based operation grouping\n  ui/                 # Progress bars, summary cards, visual output\n  output/             # Multi-format output (table, JSON, YAML)\npkg/models/           # Core data structures\n```\n\nFor detailed architecture documentation including data flows, algorithms, and extension points, see the **[Architecture Guide](docs/architecture.md)**.\n\n## Development\n\n**Requirements:**\n\n- Go 1.21+\n- PostgreSQL 9.6+ or MySQL 5.7+ (for integration tests)\n\n**Build:**\n\n```bash\ngo build ./cmd/tapa\n```\n\n**Test:**\n\nTAPA has comprehensive test coverage across multiple levels:\n\n### Unit Tests\n\nLocated in `tests/unit/` and alongside code in internal packages:\n\n```bash\n# Run all unit tests\ngo test ./... -short\n\n# Run specific package\ngo test ./internal/analyzer -v\n```\n\n### Integration Tests\n\nIntegration tests are co-located with code (see `tests/integration/README.md`):\n\n```bash\n# Requires Docker (PostgreSQL + MySQL)\ncd tests/e2e \u0026\u0026 docker-compose up -d\ngo test ./internal/analyzer/postgres -v -run Integration\ngo test ./internal/analyzer/mysql -v -run Integration\ncd tests/e2e \u0026\u0026 docker-compose down -v\n```\n\n### End-to-End Tests\n\nLocated in `tests/e2e/`:\n\n```bash\ncd tests/e2e\n./run_tests.sh\n```\n\nThis runs the full E2E suite including:\n\n- PostgreSQL integration tests\n- MySQL integration tests\n- Batch command tests\n\n### CI/CD Tests\n\nCI integration test scripts are in `tests/ci/`:\n\n```bash\n# GitHub Actions\nbash tests/ci/test-github-action.sh\n\n# GitLab CI\nbash tests/ci/test-gitlab-ci.sh\n```\n\n**Test with coverage:**\n\n```bash\ngo test ./... -coverprofile=coverage.out\ngo tool cover -html=coverage.out\n```\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nApache License 2.0 - see [LICENSE](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamsr%2Ftapa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiamsr%2Ftapa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamsr%2Ftapa/lists"}