# Flux Migrations
[](https://codecov.io/gh/k2bd/flux-migrations)
[](https://pypi.org/project/flux-migrations/)
`flux` is a database migration tool written in Python and built with Python projects in mind.
## N.B. this project is in a pre-release state. There may be breaking changes to all aspects of the tool while some decisions are being made and changed. It is not recommended for use in real projects until the v1.0.0 release. See (TODO milestone) for more info.
## Adding `flux` to your project
### CLI
``flux`` can be installed for now from Github. For example:
```
poetry add git+https://github.com/k2bd/flux-migrations.git[postgres]
```
The project will be properly maintained on PyPI when it's stable. The PyPI version may therefore not be up-to-date at this time.
``flux`` commands can then be listed with ``flux --help``
For example, migrations can be initialized and started with:
```
flux init postgres
flux new "Initial migration"
```
### Docker
(TODO)
## Writing migrations
## Use as a library
``flux`` can be used as a library in your Python project to manage migrations programmatically.
This can be particularly useful for testing.
## Database backends
``flux`` is a generic migration tool that can be adapted for use in many databases. It does this by having an abstract backend specification that can be implemented for any target database. Backends can also have their own configuration options.
### Inbuilt backends
#### Postgres
``flux`` comes packaged with a Postgres backend. It maintains information about migrations in a configurable schema and table. Additionally, it uses an advisory lock while migrations are being applied with a configurable index. The available ``[backend]`` configs are:
- ``migrations_schema``
- The schema in which to put the migration history table
- (default "public")
- ``migrations_table``
- The table used for applied migration history
- (default "_flux_migrations")
- ``migrations_lock_id``
- The ``pg_advisory_lock`` ID to use while applying migrations
- (default 3589 ('flux' on a phone keypad))
### Adding a new backend
Backends are loaded as plugins through Python's entry point system.
This means that you can add a new backend by simply installing a package that provides the backend as a plugin.
To create a new backend in your package, you need to subclass ``flux.MigrationBackend`` and implement its abstract methods.
Then register that class under the ``flux.backend`` entry point group in your package setup.
For example, in ``pyproject.toml``:
```toml
[project.entry-points."flux.backend"]
cooldb = "my_package.my_module:CoolDbBackend"
```
Once the package is installed, the backend will be available to use with a `flux`, as long as it's installed in the same environment.
An example configuration file for our new backend:
```toml
[flux]
backend = "cooldb"
migration_directory = "migrations"
[backend]
coolness_level = 11
another_option = "cool_value"
```
## Why `flux`?
I have used a number of migration frameworks for databases that sit behind Python projects.
I've liked some features of different projects but the complete feature-set I'd like to use in my work has never been in one project.
A non-exhaustive list of this feature-set includes
- very flexible support for repeatable migration scripts
- migration directory corruption detection
- the ability to easily leverage Python to reuse code in migrations
- a Python library to easily manage migrations programmatically for test writing (e.g. integration tests of the effects of individual migrations)
So, the motivation for this project was to
- present a more complete feature-set you'd want to find in a migration framework for use with Python projects
- use design patterns that make it easy to adapt for different kinds of projects, such as
- the plugin-based backend system
- the co-maintenance of official Docker images
Raw data
{
"_id": null,
"home_page": "https://github.com/k2bd/flux-migrations",
"name": "flux-migrations",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Kevin Duff",
"author_email": "kevinkelduff@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c0/9a/5892a87284a99fe5a968c3474f38f66a8574be2d6e710c6314e2d9f58d9f/flux_migrations-0.0.2.tar.gz",
"platform": null,
"description": "# Flux Migrations\n\n[](https://codecov.io/gh/k2bd/flux-migrations)\n\n[](https://pypi.org/project/flux-migrations/)\n\n\n`flux` is a database migration tool written in Python and built with Python projects in mind.\n\n## N.B. this project is in a pre-release state. There may be breaking changes to all aspects of the tool while some decisions are being made and changed. It is not recommended for use in real projects until the v1.0.0 release. See (TODO milestone) for more info.\n\n## Adding `flux` to your project\n\n### CLI\n\n``flux`` can be installed for now from Github. For example:\n\n```\npoetry add git+https://github.com/k2bd/flux-migrations.git[postgres]\n```\n\nThe project will be properly maintained on PyPI when it's stable. The PyPI version may therefore not be up-to-date at this time.\n\n``flux`` commands can then be listed with ``flux --help``\n\nFor example, migrations can be initialized and started with:\n\n```\nflux init postgres\n\nflux new \"Initial migration\"\n```\n\n### Docker\n\n(TODO)\n\n## Writing migrations\n\n## Use as a library\n\n``flux`` can be used as a library in your Python project to manage migrations programmatically.\nThis can be particularly useful for testing.\n\n## Database backends\n\n``flux`` is a generic migration tool that can be adapted for use in many databases. It does this by having an abstract backend specification that can be implemented for any target database. Backends can also have their own configuration options.\n\n### Inbuilt backends\n\n#### Postgres\n\n``flux`` comes packaged with a Postgres backend. It maintains information about migrations in a configurable schema and table. Additionally, it uses an advisory lock while migrations are being applied with a configurable index. The available ``[backend]`` configs are:\n\n- ``migrations_schema``\n - The schema in which to put the migration history table\n - (default \"public\")\n- ``migrations_table``\n - The table used for applied migration history\n - (default \"_flux_migrations\")\n- ``migrations_lock_id``\n - The ``pg_advisory_lock`` ID to use while applying migrations\n - (default 3589 ('flux' on a phone keypad))\n\n### Adding a new backend\n\nBackends are loaded as plugins through Python's entry point system.\nThis means that you can add a new backend by simply installing a package that provides the backend as a plugin.\n\nTo create a new backend in your package, you need to subclass ``flux.MigrationBackend`` and implement its abstract methods.\nThen register that class under the ``flux.backend`` entry point group in your package setup.\n\nFor example, in ``pyproject.toml``:\n \n```toml\n[project.entry-points.\"flux.backend\"]\ncooldb = \"my_package.my_module:CoolDbBackend\"\n```\n\nOnce the package is installed, the backend will be available to use with a `flux`, as long as it's installed in the same environment.\nAn example configuration file for our new backend:\n\n```toml\n[flux]\nbackend = \"cooldb\"\nmigration_directory = \"migrations\"\n\n[backend]\ncoolness_level = 11\nanother_option = \"cool_value\"\n```\n\n## Why `flux`?\n\nI have used a number of migration frameworks for databases that sit behind Python projects.\nI've liked some features of different projects but the complete feature-set I'd like to use in my work has never been in one project.\n\nA non-exhaustive list of this feature-set includes\n- very flexible support for repeatable migration scripts\n- migration directory corruption detection\n- the ability to easily leverage Python to reuse code in migrations\n- a Python library to easily manage migrations programmatically for test writing (e.g. integration tests of the effects of individual migrations)\n\nSo, the motivation for this project was to\n- present a more complete feature-set you'd want to find in a migration framework for use with Python projects\n- use design patterns that make it easy to adapt for different kinds of projects, such as \n - the plugin-based backend system\n - the co-maintenance of official Docker images\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A database migration tool that works well with Python projects",
"version": "0.0.2",
"project_urls": {
"Homepage": "https://github.com/k2bd/flux-migrations",
"Repository": "https://github.com/k2bd/flux-migrations"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "84649c5ebe3e48b47c3959c56cb39010224712f668277f08968ffb1f37822373",
"md5": "c10678b919c4077a5901acc972ee6b7f",
"sha256": "5195cdf10174d9e9d503c57d2fead3fcfeb53b5545822dc0a9df315c361bf5c6"
},
"downloads": -1,
"filename": "flux_migrations-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c10678b919c4077a5901acc972ee6b7f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 16436,
"upload_time": "2024-09-15T15:05:41",
"upload_time_iso_8601": "2024-09-15T15:05:41.548215Z",
"url": "https://files.pythonhosted.org/packages/84/64/9c5ebe3e48b47c3959c56cb39010224712f668277f08968ffb1f37822373/flux_migrations-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c09a5892a87284a99fe5a968c3474f38f66a8574be2d6e710c6314e2d9f58d9f",
"md5": "322e8d2597101fb8e71b4d588dc1e773",
"sha256": "2c71f2d173d17b72fc7e3617fba61a64559f117661de2bd2c63e444744925d31"
},
"downloads": -1,
"filename": "flux_migrations-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "322e8d2597101fb8e71b4d588dc1e773",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 13944,
"upload_time": "2024-09-15T15:05:42",
"upload_time_iso_8601": "2024-09-15T15:05:42.439468Z",
"url": "https://files.pythonhosted.org/packages/c0/9a/5892a87284a99fe5a968c3474f38f66a8574be2d6e710c6314e2d9f58d9f/flux_migrations-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-15 15:05:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "k2bd",
"github_project": "flux-migrations",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "flux-migrations"
}
JSON
