|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +This is a GitOps demonstration repository for database CI/CD using Bytebase and GitHub Actions with GitHub Flow. The repository shows how to integrate database schema changes with application deployment pipelines. |
| 8 | + |
| 9 | +## Repository Structure |
| 10 | + |
| 11 | +- `migrations-semver/`: Contains SQL migration files following semantic versioning naming convention (e.g., `1.0.0_init.sql`, `1.1.1_comment.sql`) |
| 12 | +- `schema/`: Contains base database schema definitions |
| 13 | +- `.github/workflows/`: GitHub Actions workflows for CI/CD pipeline |
| 14 | + |
| 15 | +## Migration File Naming |
| 16 | + |
| 17 | +Migration files MUST follow semantic versioning pattern: `{major}.{minor}.{patch}_{description}.sql` |
| 18 | +- Examples: `1.0.0_init.sql`, `1.1.1_comment.sql`, `1.13.0_phone.sql` |
| 19 | +- Files are processed by Bytebase in semantic version order |
| 20 | + |
| 21 | +## GitHub Actions Workflows |
| 22 | + |
| 23 | +### SQL Review Workflow (`sql-review-action.yml`) |
| 24 | +- Triggers on pull requests to `main` branch when `migrations-semver/*.sql` files change |
| 25 | +- Uses `bytebase/bytebase-action:latest` Docker image |
| 26 | +- Runs SQL validation against production database |
| 27 | +- Requires `BYTEBASE_SERVICE_ACCOUNT_SECRET` repository secret |
| 28 | + |
| 29 | +### Release Workflow (`release-action.yml`) |
| 30 | +- Triggers on push to `main` branch when `migrations-semver/*.sql` files change |
| 31 | +- Three-stage process: |
| 32 | + 1. `build`: Mock application build step |
| 33 | + 2. `create-rollout`: Creates Bytebase rollout plan for both test and prod databases |
| 34 | + 3. `deploy-to-test`: Deploys to test environment automatically |
| 35 | + 4. `deploy-to-prod`: Deploys to production (requires manual approval via GitHub environment protection) |
| 36 | + |
| 37 | +## Environment Configuration |
| 38 | + |
| 39 | +Both workflows use these environment variables: |
| 40 | +- `BYTEBASE_URL`: Bytebase instance URL |
| 41 | +- `BYTEBASE_SERVICE_ACCOUNT`: Service account email |
| 42 | +- `BYTEBASE_SERVICE_ACCOUNT_SECRET`: Service account password (stored in GitHub secrets) |
| 43 | +- `BYTEBASE_PROJECT`: Target Bytebase project |
| 44 | +- `BYTEBASE_TARGETS`: Comma-separated list of database targets |
| 45 | +- `FILE_PATTERN`: Glob pattern for migration files (`migrations-semver/*.sql`) |
| 46 | + |
| 47 | +## Database Schema |
| 48 | + |
| 49 | +The schema includes: |
| 50 | +- Employee management system with tables: `employee`, `department`, `dept_manager`, `dept_emp`, `title`, `salary` |
| 51 | +- Audit logging system with trigger-based change tracking |
| 52 | +- Views for current department assignments |
| 53 | + |
| 54 | +## Development Workflow |
| 55 | + |
| 56 | +1. Create feature branch |
| 57 | +2. Add SQL migration files to `migrations-semver/` with proper semantic versioning |
| 58 | +3. Create pull request - triggers SQL review workflow |
| 59 | +4. Merge to main - triggers release workflow |
| 60 | +5. Test environment deployment happens automatically |
| 61 | +6. Production deployment requires manual approval through GitHub environment protection |
| 62 | + |
| 63 | +## Key Integration Points |
| 64 | + |
| 65 | +- All database changes go through Bytebase for review and deployment |
| 66 | +- GitHub environment protection rules control production deployments |
| 67 | +- Migration files are validated against actual database schemas during PR review |
0 commit comments