{"id":46320410,"url":"https://github.com/openframebox/gomigration","last_synced_at":"2026-03-04T15:03:10.312Z","repository":{"id":301336730,"uuid":"979899958","full_name":"openframebox/gomigration","owner":"openframebox","description":"Lightweight and extensible database migration library for Go, designed with simplicity and flexibility in mind","archived":false,"fork":false,"pushed_at":"2025-11-15T17:10:58.000Z","size":28,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-15T19:11:46.504Z","etag":null,"topics":["database","golang","migration"],"latest_commit_sha":null,"homepage":"https://github.com/openframebox/gomigration","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openframebox.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2025-05-08T08:44:57.000Z","updated_at":"2025-11-15T17:11:02.000Z","dependencies_parsed_at":"2025-06-26T10:59:02.707Z","dependency_job_id":"c54515e9-d51f-4202-9e57-57459d3a6142","html_url":"https://github.com/openframebox/gomigration","commit_stats":null,"previous_names":["openframebox/gomigration"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/openframebox/gomigration","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openframebox%2Fgomigration","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openframebox%2Fgomigration/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openframebox%2Fgomigration/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openframebox%2Fgomigration/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openframebox","download_url":"https://codeload.github.com/openframebox/gomigration/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openframebox%2Fgomigration/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30084685,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T13:22:36.021Z","status":"ssl_error","status_checked_at":"2026-03-04T13:20:45.750Z","response_time":59,"last_error":"SSL_read: 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","golang","migration"],"created_at":"2026-03-04T15:03:00.527Z","updated_at":"2026-03-04T15:03:07.377Z","avatar_url":"https://github.com/openframebox.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🧠 GoMigration\n\n**GoMigration** is a lightweight and extensible database migration library for Go, designed with simplicity and flexibility in mind. It allows you to register migrations in Go code, manage them efficiently, and execute or roll them back in a safe and structured manner.\n\n\u003e 📝 **Note**: This project is a fork of [ruangdeveloper/qafoia](https://github.com/ruangdeveloper/qafoia), moved under a new organization for long-term maintenance and development.\n\n## ✨ Features\n\n- Register migrations using Go structs.\n- Run, rollback, reset, or re-run migrations with ease.\n- Debug SQL output during migration execution.\n- Automatically generates migration file templates.\n- Tracks applied migrations using a dedicated database table.\n- Ready-to-use MySQL and Postgres drivers.\n\n## 📦 Installation\n\nTo install GoMigration, use the following command:\n\n```bash\ngo get github.com/openframebox/gomigration\n```\n\n## 🛠️ Usage\n\n### 1. Initialize GoMigration\n\nFirst, configure the library by providing a `Config`:\n\n```go\ncfg := \u0026gomigration.Config{\n    Driver:             yourDriver,  // Must implement gomigration.Driver\n    MigrationFilesDir:  \"migrations\",  // Optional: default is \"migrations\"\n    MigrationTableName: \"migrations\",  // Optional: default is \"migrations\"\n    DebugSql:           true,  // Optional: enables SQL debugging\n}\n\nq, err := gomigration.New(cfg)\nif err != nil {\n    log.Fatal(err)\n}\n```\n\n### 2. Register Migrations\n\n```go\nq.Register(\n    migration1, // Must implement gomigration.Migration\n    // Example\n    \u0026migrations.M20250418220011CreateUsersTable{},\n)\n```\n\nMigration struct is created automatically when creating migration file.\n\n### 3. Apply Migrations\n\nTo apply the migrations:\n\n```go\nerr := q.Migrate(context.Background())\nif err != nil {\n    log.Fatal(err)\n}\n```\n\n### 4. Other Operations\n\n- **Create a new migration file:**\n\n  ```go\n  q.Create(\"add_users_table\")\n  ```\n\n- **Run fresh migrations (clean + migrate):**\n\n  ```go\n  q.Fresh(context.Background())\n  ```\n\n- **Reset migrations (rollback all and reapply):**\n\n  ```go\n  q.Reset(context.Background())\n  ```\n\n- **Rollback last `n` migrations:**\n\n  ```go\n  q.Rollback(context.Background(), 2)\n  ```\n\n- **Clean the database:**\n\n  ```go\n  q.Clean(context.Background())\n  ```\n\n- **List all registered migrations and their status:**\n\n  ```go\n  list, err := q.List(context.Background())\n  ```\n\n### 5. Set migration files directory before creating migration file\n\nIf you want to set migration files directory before creating migration file, you can use `SetMigrationFilesDir` method. This is useful when you want to dynamically set the migration files directory, e.g. passing it as a command-line argument.\n\n```go\nq.SetMigrationFilesDir(\"migrations\")\nq.Create(\"add_users_table\")\n\n// or using chain\nq.SetMigrationFilesDir(\"migrations\").Create(\"add_users_table\")\n```\n\n## 📁 Migration Interface\n\nEach migration must implement the following interface:\n\n```go\ntype Migration interface {\n    Name() string\n    UpScript() string\n    DownScript() string\n}\n```\n\n## 🔌 Driver Interface\n\nYou can use any database driver that implements the `Driver` interface. We currently provide ready-to-use MySQL and Postgres drivers.\n\n### MySQL Driver\n\nTo use the MySQL driver:\n\n```go\nd, err := gomigration.NewMySqlDriver(\n    \"localhost\", // Host\n    \"3306\",      // Port\n    \"root\",      // Username\n    \"\",          // Password\n    \"gomigration\",    // Database Name\n    \"utf8mb4\",   // Charset\n)\n```\n\n### Postgres Driver\n\nTo use the Postgres driver:\n\n```go\nd, err := gomigration.NewPostgresDriver(\n    \"localhost\", // Host\n    \"5432\",      // Port\n    \"root\",      // Username\n    \"\",          // Password\n    \"gomigration\",    // Database Name\n    \"public\",    // Schema\n)\n```\n\n## 📦 Generated Migration File Example\n\nWhen you run `q.Create(\"create_users_table\")`, a file like this will be created:\n\n```go\npackage migrations\n\ntype M20250418220011CreateUsersTable struct{}\n\nfunc (m *M20250418220011CreateUsersTable) Name() string {\n  // Don't change this name\n\treturn \"20250418220011_create_users_table\"\n}\n\nfunc (m *M20250418220011CreateUsersTable) UpScript() string {\n  // Write your migration SQL here\n\treturn \"\"\n}\n\nfunc (m *M20250418220011CreateUsersTable) DownScript() string {\n  // Write your rollback SQL here\n\treturn \"\"\n}\n\n```\n\n## 🧑‍💻 CLI Helper\n\nGoMigration provides an optional CLI helper that simplifies running migrations and other tasks. You can use the CLI as follows:\n\n### 1. Initialize the CLI\n\nYou can initialize the CLI with the `CliConfig`:\n\n```go\ncli, err := gomigration.NewCli(gomigration.CliConfig{\n    GoMigration: q,  // The GoMigration instance you've initialized earlier\n})\n\nif err != nil {\n    log.Fatal(err)\n}\n\nerr = cli.Execute(context.TODO())\n\nif err != nil {\n    log.Fatal(err)\n}\n```\n\n### 2. Run CLI Commands\n\nAfter setting up the CLI, you can run the following commands directly from the terminal:\n\n- **Clean database (delete all tables):**\n\n  ```bash\n  go run main.go clean\n  ```\n\n- **Create a new migration:**\n\n  ```bash\n  go run main.go create\n  ```\n\n- **List all migrations:**\n\n  ```bash\n  go run main.go list\n  ```\n\n- **Run all pending migrations:**\n\n  ```bash\n  go run main.go migrate\n  ```\n\n- **Rollback all migrations and re-run all migrations:**\n\n  ```bash\n  go run main.go reset\n  ```\n\n- **Rollback the last migration:**\n\n  ```bash\n  go run main.go rollback\n  ```\n\nThese commands are built into the CLI, making it easy to perform common migration tasks without having to write custom code each time.\n\n### 3. Add Commands to Existing cobra.Command\n\n```go\nvar rootCmd = \u0026cobra.Command{\n    Use:   \"migration\",\n    Short: \"This is your existing cobra.Command\",\n    Run: func(cmd *cobra.Command, args []string) {\n        cmd.Help()\n    },\n}\n\nrootCmd.AddCommand(\n    cli.ListCommand(ctx),\n    cli.MigrateCommand(ctx),\n    cli.RollbackCommand(ctx),\n    cli.ResetCommand(ctx),\n    cli.CleanCommand(ctx),\n    cli.CreateCommand(ctx),\n)\n```\n\n### Full Example\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"log\"\n\n\t\"github.com/openframebox/gomigration\"\n\t\"your_app/migrations\"\n)\n\nfunc main() {\n\td, err := gomigration.NewMySqlDriver(\n\t\t\"localhost\",\n\t\t\"3306\",\n\t\t\"root\",\n\t\t\"\",\n\t\t\"gomigration\",\n\t\t\"utf8mb4\",\n\t)\n\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tq, err := gomigration.New(\u0026gomigration.Config{\n\t\tDriver:             d,\n\t\tMigrationFilesDir:  \"migrations\",\n\t\tMigrationTableName: \"migrations\",\n\t\tDebugSql:           false,\n\t})\n\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\terr = q.Register(\n\t\t\u0026migrations.M20250418220011CreateUsersTable{},\n\t\t\u0026migrations.M20250418233018CreateRolesTable{},\n\t)\n\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\tcli, err := gomigration.NewCli(gomigration.CliConfg{\n\t\tGoMigration: q,\n\t})\n\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\terr = cli.Execute(context.TODO())\n\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n}\n```\n\n## 📄 License\n\nMIT License\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenframebox%2Fgomigration","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenframebox%2Fgomigration","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenframebox%2Fgomigration/lists"}