{"id":13412057,"url":"https://github.com/adlio/schema","last_synced_at":"2026-04-19T05:11:18.741Z","repository":{"id":36979551,"uuid":"210681401","full_name":"adlio/schema","owner":"adlio","description":"Embedded schema migration package for Go","archived":false,"fork":false,"pushed_at":"2024-04-08T03:05:46.000Z","size":245,"stargazers_count":30,"open_issues_count":3,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-04-09T03:43:27.606Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/adlio.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}},"created_at":"2019-09-24T19:27:13.000Z","updated_at":"2024-04-14T23:44:37.679Z","dependencies_parsed_at":"2024-04-08T03:49:55.605Z","dependency_job_id":null,"html_url":"https://github.com/adlio/schema","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adlio%2Fschema","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adlio%2Fschema/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adlio%2Fschema/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adlio%2Fschema/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adlio","download_url":"https://codeload.github.com/adlio/schema/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243618735,"owners_count":20320284,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-07-30T20:01:20.584Z","updated_at":"2026-04-19T05:11:18.718Z","avatar_url":"https://github.com/adlio.png","language":"Go","readme":"# Schema - Database Migrations for Go\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/adlio/schema.svg)](https://pkg.go.dev/github.com/adlio/schema)\n[![CI](https://github.com/adlio/schema/actions/workflows/ci.yml/badge.svg)](https://github.com/adlio/schema/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/adlio/schema/graph/badge.svg)](https://codecov.io/gh/adlio/schema)\n[![Go Report Card](https://goreportcard.com/badge/github.com/adlio/schema)](https://goreportcard.com/report/github.com/adlio/schema)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\nAn embeddable library for applying changes to your Go application's\n`database/sql` schema.\n\n## Features\n\n- Cloud-friendly design tolerates embedded use in clusters\n- Supports migrations in embed.FS via `go:embed`\n- [Depends only on Go standard library](https://pkg.go.dev/github.com/adlio/schema?tab=imports) (Note that all go.mod dependencies are used only in tests)\n- Unidirectional migrations (no \"down\" migration complexity)\n\n# Usage Instructions\n\nCreate a `schema.Migrator` in your bootstrap/config/database connection code,\nthen call its `Apply()` method with your database connection and a slice of\n`*schema.Migration` structs.\n\nThe `.Apply()` function figures out which of the supplied Migrations have not\nyet been executed in the database (based on the ID), and executes the `Script`\nfor each in **alphabetical order by IDe**.\n\nThe `[]*schema.Migration` can be created manually, but the package\nhas some utility functions to make it easier to parse .sql files into structs\nwith the filename as the `ID` and the file contents as the `Script`.\n\n## Using go:embed\n\nGo's `embed` package lets you embed a directory of files into the binary as an\nembedded filesystem (`embed.FS`).\n\nAssuming you have a directory of SQL files called `my-migrations/` next to your\nmain.go file, you'll run something like this:\n\n```go\n//go:embed my-migrations\nvar MyMigrations embed.FS\n\nfunc main() {\n   db, err := sql.Open(...) // Or however you get a *sql.DB\n\n   migrations, err := schema.FSMigrations(MyMigrations, \"my-migrations/*.sql\")\n   migrator := schema.NewMigrator(schema.WithDialect(schema.MySQL))\n   err = migrator.Apply(db, migrations)\n}\n```\n\nThe `WithDialect()` option accepts: `schema.MySQL`, `schema.Postgres`,\n`schema.SQLite` or `schema.MSSQL`. These dialects all use only `database/sql`\ncalls, so you may have success with other databases which are SQL-compatible\nwith the above dialects.\n\nYou can also provide your own custom `Dialect`. See `dialect.go` for the\ndefinition of the `Dialect` interface, and the optional `Locker` interface. Note\nthat `Locker` is critical for clustered operation to ensure that only one of\nmany processes is attempting to run migrations simultaneously.\n\n## Using Inline Migration Structs\n\nIf you prefer not to use embedded migration files, `Migration{}` structs can be\ncreated manually:\n\n```go\ndb, err := sql.Open(...)\n\nmigrator := schema.NewMigrator() // Postgres is the default Dialect\nmigrator.Apply(db, []*schema.Migration{\n   \u0026schema.Migration{\n      ID: \"2019-09-24 Create Albums\",\n      Script: `\n      CREATE TABLE albums (\n         id SERIAL PRIMARY KEY,\n         title CHARACTER VARYING (255) NOT NULL\n      )\n      `\n   },\n})\n```\n\n## Constructor Options\n\nThe `NewMigrator()` function accepts option arguments to customize the dialect\nand the name of the migration tracking table. By default, the tracking table\nwill be named `schema_migrations`. To change it\nto `my_migrations` instead:\n\n```go\nmigrator := schema.NewMigrator(schema.WithTableName(\"my_migrations\"))\n```\n\nIt is theoretically possible to create multiple Migrators and to use mutliple\nmigration tracking tables within the same application and database.\n\nIt is also OK for multiple processes to run `Apply` on identically configured\nmigrators simultaneously. The `Migrator` only creates the tracking table if it\ndoes not exist, and then locks it to modifications while building and running\nthe migration plan. This means that the first-arriving process will **win** and\nwill perform its migrations on the database.\n\n## Supported Databases\n\nThis package was extracted from a PostgreSQL project. Other databases have solid\nautomated test coverage, but should be considered somewhat experimental in\nproduction use cases. [Contributions](#contributions) are welcome for\nadditional databases or feature enhancements / bug fixes.\n\n- [x] PostgreSQL (database/sql driver only, see [adlio/pgxschema](https://github.com/adlio/pgxschema) if you use `jack/pgx`)\n- [x] SQLite (thanks [kalafut](https://github.com/kalafut)!)\n- [x] MySQL / MariaDB\n- [x] SQL Server\n- [ ] CockroachDB, Redshift, Snowflake, etc (open a Pull Request)\n\n## Package Opinions\n\nThere are many other schema migration tools. This one exists because of a\nparticular set of opinions:\n\n1. Database credentials are runtime configuration details, but database\n   schema is a **build-time applicaton dependency**, which means it should be\n   \"compiled in\" to the build, and should not rely on external tools.\n2. Using an external command-line tool for schema migrations needlessly\n   complicates testing and deployment.\n3. SQL is the best language to use to specify changes to SQL schemas.\n4. \"Down\" migrations add needless complication, aren't often used, and are\n   tedious to properly test when they are used. In the unlikely event you need\n   to migrate backwards, it's possible to write the \"rollback\" migration as\n   a separate \"up\" migration.\n5. Deep dependency chains should be avoided, especially in a compiled\n   binary. We don't want to import an ORM into our binaries just to get SQL\n   the features of this package. The `schema` package imports only\n   [standard library packages](https://godoc.org/github.com/adlio/schema?imports)\n   (**NOTE** \\*We do import `ory/dockertest` in our tests).\n6. Sequentially-numbered integer migration IDs will create too many unnecessary\n   schema collisions on a distributed, asynchronously-communicating team\n   (this is not yet strictly enforced, but may be later).\n\n## Rules of Applying Migrations\n\n1.  **Never, ever change** the `ID` (filename) or `Script` (file contents)\n    of a Migration which has already been executed on your database. If you've\n    made a mistake, you'll need to correct it in a subsequent migration.\n2.  Use a consistent, but descriptive format for migration `ID`s/filenames.\n    Consider prefixing them with today's timestamp. Examples:\n\n         ID: \"2019-01-01T13:45:00 Creates Users\"\n         ID: \"2001-12-18 001 Changes the Default Value of User Affiliate ID\"\n\n    Do not use simple sequentialnumbers like `ID: \"1\"`.\n\n## Migration Ordering\n\nMigrations **are not** executed in the order they are specified in the slice.\nThey will be re-sorted alphabetically by their IDs before executing them.\n\n## Contributions\n\n... are welcome. Please include tests with your contribution. We've integrated\n[dockertest](https://github.com/ory/dockertest) to automate the process of\ncreating clean test databases.\n\nBefore contributing, please read the [package opinions](#package-opinions)\nsection. If your contribution is in disagreement with those opinions, then\nthere's a good chance a different schema migration tool is more appropriate.\n\n## Roadmap\n\n- [x] Enhancements and documentation to facilitate asset embedding via go:embed\n- [ ] Add a `Validate()` method to allow checking migration names for\n      consistency and to detect problematic changes in the migrations list.\n- [x] SQL Server support\n- [x] SQL Server support for the Locker interface to protect against simultaneous\n      migrations from clusters of servers.\n\n## Version History\n\n### 1.5.0 - Apr 18, 2026\n\n- **Breaking:** Go 1.25.5+ is now required because the Docker-based test stack now depends on `ory/dockertest/v4`\n- Update Docker-based test dependencies to address security vulnerabilities by migrating to `ory/dockertest/v4`\n- Finalize GitHub Actions CI/release automation and improve automated release notes extraction from README version history\n\n### 1.4.0 - Feb 21, 2026\n\n- **Breaking:** Go 1.24+ now required (was 1.22)\n- **Breaking:** MSSQL driver changed from `denisenkom/go-mssqldb` to `microsoft/go-mssqldb`\n- Update all dependencies to latest versions\n- Fix data race in MSSQL Unlock function\n- Migrate CI from CircleCI to GitHub Actions\n- Add automated release workflow\n\n### 1.3.9 - Jul 21, 2025\n\n- Update Go version requirement to 1.21 to resolve CircleCI build issues with slices package dependency\n- Update CircleCI configuration to use Go 1.21\n\n### 1.3.8 - Jul 19, 2025\n\n- Update golang.org/x/crypto to v0.40.0 to address security vulnerabilities\n- Update golang.org/x/net to v0.42.0 to address security vulnerabilities\n\n### 1.3.7 - Jul 19, 2025\n\n- Add SQL Server support for the Locker interface using sp_getapplock/sp_releaseapplock\n- Fix SQL Server transaction handling for concurrent migrations\n\n### 1.3.4 - Apr 9, 2023\n\n- Update downstream dependencies to address vulnerabilities in test dependencies.\n\n### 1.3.3 - Jun 19, 2022\n\n- Update downstream dependencies of ory/dockertest due to security issues.\n\n### 1.3.0 - Mar 25, 2022\n\n- Basic SQL Server support (no locking, not recommended for use in clusters)\n- Improved support for running tests on ARM64 machines (M1 Macs)\n\n### 1.2.3 - Dec 10, 2021\n\n- BUGFIX: Restore the ability to chain NewMigrator().Apply\n\n### 1.2.2 - Dec 9, 2021\n\n- Add support for migrations in an embed.FS (`FSMigrations(filesystem fs.FS, glob string)`)\n- Add MySQL/MariaDB support (experimental)\n- Add SQLite support (experimental)\n- Update go.mod to `go 1.17`.\n\n### 1.1.14 - Nov 18, 2021\n\nSecurity patches in upstream dependencies.\n\n### 1.1.13 - May 22, 2020\n\nBugfix for error with advisory lock being held open. Improved test coverage for\nsimultaneous execution.\n\n### 1.1.11 - May 19, 2020\n\nUse a database-held lock for all migrations not just the initial table creation.\n\n### 1.1.9 - May 17, 2020\n\nAdd the ability to attach a logger.\n\n### 1.1.8 - Nov 24, 2019\n\nSwitch to `filepath` package for improved cross-platform filesystem support.\n\n### 1.1.7 - Oct 1, 2019\n\nBegan using pg_advisory_lock() to prevent race conditions when multiple\nprocesses/machines try to simultaneously create the migrations table.\n\n### 1.1.1 - Sep 28, 2019\n\nFirst published version.\n","funding_links":[],"categories":["数据库","Database","Data Integration Frameworks","Uncategorized","Generators","数据库  `go语言实现的数据库`"],"sub_categories":["标准 CLI","Advanced Console UIs","Database Schema Migration","数据库模式迁移"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadlio%2Fschema","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadlio%2Fschema","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadlio%2Fschema/lists"}