> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bytebase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Develop

Create SQL migration files following naming conventions that enable proper version tracking and execution order.

## File Naming Convention

Migration filenames must follow this structure:

```
<Version>_<Description>.sql
```

**Components:**

1. **Version** (required) - Optional `v` or `V` prefix, followed by one or more numbers separated by dots
   * Pattern: `^[vV]?(\d+(\.\d+)*)`
   * Examples: `v1.2.3`, `1.0`, `V2`
2. **Underscore** (`_`) separator
3. **Description** - Human-readable description using underscores or hyphens
4. **`.sql`** file extension

## Version Formats

Choose a versioning strategy that fits your team:

<Tabs>
  <Tab title="Timestamp">
    **Timestamp-Based** - Recommended for teams with parallel development

    ```
    20250120143000_add_user_email.sql
    20250121091500_create_orders_table.sql
    ```

    Format: `YYYYMMDDHHmmss`

    ✅ No merge conflicts
    ✅ Chronological ordering
    ✅ Supports distributed teams

    ⚠️  Less human-readable
  </Tab>

  <Tab title="Semantic">
    **Semantic Versioning** - Meaningful version numbers

    ```
    v1.0.0_initial_release.sql
    v1.1.0_add_user_profiles.sql
    v1.1.1_fix_profile_constraint.sql
    v2.0.0_redesign_authentication.sql
    ```

    ✅ Conveys change significance
    ✅ Aligns with application versioning

    ⚠️  Requires coordination
    ⚠️  Merge conflicts possible
  </Tab>

  <Tab title="Sequential">
    **Simple Sequential** - Easy to understand

    ```
    001_initial_schema.sql
    002_add_users.sql
    003_add_products.sql
    ```

    ✅ Simple and clear
    ✅ Milestones mark releases

    ⚠️  Merge conflicts in parallel work
  </Tab>
</Tabs>

## Migration Type (MySQL Only)

For zero-downtime MySQL schema changes, add this comment at the top of your file:

```sql theme={null}
-- gh-ost = {}

ALTER TABLE users ADD COLUMN email VARCHAR(255);
```

This uses [gh-ost](https://github.com/github/gh-ost) to apply changes without blocking your database. Use `{}` to run with default flags, or pass gh-ost flags as a JSON object:

```sql theme={null}
-- gh-ost = {"max-lag-millis":"1500","cut-over-lock-timeout-seconds":"10"}

ALTER TABLE users ADD COLUMN email VARCHAR(255);
```

<Card title="Online Schema Migration" icon="bolt" href="/change-database/online-schema-migration-for-mysql">
  Learn more about gh-ost
</Card>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="SQL Review CI" icon="shield-check" href="/gitops/migration-based-workflow/sql-review-ci">
    Set up automated validation in your CI/CD pipeline
  </Card>

  <Card title="Release" icon="rocket" href="/gitops/migration-based-workflow/release">
    Deploy your migrations to databases
  </Card>
</CardGroup>