File Organization

Proper file organization is crucial for maintainable GitOps workflows. This guide covers repository structures and directory layouts that scale with your team.

Repository Structure

Monorepo Approach

Database migrations alongside application code:

my-app/
├── src/                         # Application code
├── migrations/                  # Database migrations
│   ├── versioned/
│   │   ├── 001__init.sql
│   │   └── 002__add_users.sql
│   └── schema/
│       └── public.sql           # SDL if using declarative
├── .github/workflows/
│   └── bytebase-gitops.yml      # CI/CD integration
└── README.md

Benefits:

Migrations versioned with application code
Atomic commits for schema + code changes
Single source of truth

Best for:

Small to medium teams
Tight schema-code coupling
Monolithic or modular monolith architectures

Separate Repository

Dedicated database repository:

database-schemas/
├── app-db/
│   ├── migrations/
│   └── schema/
├── analytics-db/
│   └── migrations/
└── .gitlab-ci.yml

Benefits:

Separation of concerns
Independent deployment cycles
Multiple teams/databases

Best for:

Larger organizations
Dedicated database teams
Microservices with shared databases

Choose based on your team structure. Co-located migrations work well for small teams with tight schema-code coupling. Separate repos fit larger organizations with dedicated database teams.

Directory Layout

For Migration-Based Workflow

Option 1: Organized by Category

migrations/
├── baseline/
│   └── 000__initial_schema.sql      # Initial baseline
├── features/
│   ├── 001__users.sql
│   ├── 002__products.sql
│   └── 003__orders.sql
└── hotfixes/
    └── 004__fix_index.sql

Benefits:

Clear organization by purpose
Easy to navigate
Separates routine changes from emergencies

Option 2: Flat Structure

migrations/
├── 001__initial_schema.sql
├── 002__add_users.sql
├── 003__add_products_dml.sql
└── 004__add_indexes.sql

Benefits:

Simple and straightforward
Chronological ordering
Easy to understand

For State-Based Workflow (SDL)

The recommended layout is a schema/ directory holding Bytebase’s multi-file schema export - one object per file, grouped by type. The SQL Review CI and Release examples match this layout with schema/**:

PostgreSQL
MySQL

schema/
└── schemas/
    ├── public/
    │   ├── tables/
    │   │   ├── users.sql
    │   │   └── orders.sql
    │   ├── views/
    │   │   └── active_users.sql
    │   ├── functions/
    │   │   └── get_user_count.sql
    │   └── sequences.sql
    └── analytics/
        └── tables/
            └── events.sql

Alternative layouts also work - one file per schema (schema/public.sql, schema/analytics.sql) or split by object type (01_tables.sql, 02_indexes.sql, …).

schema/
├── tables/
│   ├── users.sql
│   └── orders.sql
├── views/
│   └── active_users.sql
├── procedures/
│   └── update_user_status.sql
├── triggers/
│   └── users_audit_trigger.sql
└── events/
    └── purge_expired_sessions.sql

MySQL has no schema namespace, so the export layout is flat. A single file holding the whole database schema also works.

Benefits:

One object per file makes code reviews and Git diffs precise
Matches the Bytebase export, so adoption requires no manual reorganization
Predictable file structure

Hybrid Approach

Combine both workflows for different purposes:

database/
├── schema/               # SDL for structure (DDL)
│   ├── public.sql
│   └── analytics.sql
├── migrations/           # Migrations for data (DML)
│   ├── 001__seed_roles_dml.sql
│   └── 002__migrate_users_dml.sql
└── .github/workflows/
    ├── schema-cicd.yml   # SDL pipeline
    └── data-cicd.yml     # Migration pipeline

Best for:

Teams wanting declarative schema management
Projects requiring data migrations
Gradual migration from versioned to SDL

Documentation Structure

Maintain supporting documentation alongside migrations:

database/
├── migrations/
├── schema/
├── docs/
│   ├── CHANGELOG.md          # Schema changelog
│   ├── DEPENDENCIES.md       # Schema-app dependencies
│   └── ROLLBACK_PLAN.md      # Rollback procedures
└── test-data/
    └── seed.sql              # Test data for development

Database CI/CD

UI-Driven Workflow

GitOps Workflow

Appendix

Repository Structure

Monorepo Approach

Separate Repository

Directory Layout

For Migration-Based Workflow

For State-Based Workflow (SDL)

Hybrid Approach

Documentation Structure

Next Steps

Migration Guidelines

Git and CI/CD

​Repository Structure

​Monorepo Approach

​Separate Repository

​Directory Layout

​For Migration-Based Workflow

​For State-Based Workflow (SDL)

​Hybrid Approach

​Documentation Structure

​Next Steps

Migration Guidelines

Git and CI/CD

Repository Structure

Monorepo Approach

Separate Repository

Directory Layout

For Migration-Based Workflow

For State-Based Workflow (SDL)

Hybrid Approach

Documentation Structure

Next Steps