# asyncpg-trek: simple migrations for asyncpg
A simple library for managing migrations.
## Target audience
Me.
But maybe if you use [asyncpg] and prefer to write migrations as raw SQL (i.e. you're not using SQLAlchemy/Alembic) then you as well.
## Features
- **async**: migrations usually don't benefit from being async, but you benefit from using the same database driver in as your application uses (only [asyncpg] is supported).
- **simple**: you just create `.sql` or Python files in a folder of your choosing and point this tool at that folder. No need to fight a new API to write migrations in.
- **API centric**: there is no CLI to figure out, _you_ decide how migrations get called, _you_ control how the database connection gets created. This makes it trivial to run migrations in tests, wrap them in a CLI or run them via an exposed HTTP endpoint.
- **declarative**: just specify the version you want and the library figures out if it needs an upgrade, downgrade or no action.
## Example usage
```python
from pathlib import Path
import asyncpg
from asyncpg_trek import plan, execute, Direction
from asyncpg_trek.asyncpg import AsyncpgBackend
MIGRATIONS_DIR = Path(__file__).parent / "migrations"
async def migrate(
conn: asyncpg.Connection,
target_revision: str,
) -> None:
backend = AsyncpgBackend(conn)
async with backend.connect() as conn:
planned = await plan(conn, backend, MIGRATIONS_DIR, target_revision=target_revision, direction=Direction.up)
await execute(conn, backend, planned)
```
You could make this an entrypoint in a docker image, an admin endpoint in your API or a helper function in your tests (or all of the above).
How you run your migrations depends on the complexity of your system.
For example, for simple systems it may be easy to run migrations on app startup based on a hardcoded revision.
For more complex systems you may want to run migrations manually or via an admin API.
See this release on GitHub: [v0.4.0](https://github.com/adriangb/asyncpg-trek/releases/tag/0.4.0)
Raw data
{
"_id": null,
"home_page": "https://github.com/adriangb/asyncpg-trek",
"name": "asyncpg-trek",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.8",
"maintainer_email": null,
"keywords": "asyncpg, postgres, postgresql, migrations",
"author": "Adrian Garcia Badaracco",
"author_email": "adrian@adriangb.com",
"download_url": "https://files.pythonhosted.org/packages/15/df/3dbad74b63ca14a47083849842a5ad6964a2b78d91ae09ae28e0f35f4971/asyncpg_trek-0.4.0.tar.gz",
"platform": null,
"description": "# asyncpg-trek: simple migrations for asyncpg\n\nA simple library for managing migrations.\n\n## Target audience\n\nMe.\nBut maybe if you use [asyncpg] and prefer to write migrations as raw SQL (i.e. you're not using SQLAlchemy/Alembic) then you as well.\n\n## Features\n\n- **async**: migrations usually don't benefit from being async, but you benefit from using the same database driver in as your application uses (only [asyncpg] is supported).\n- **simple**: you just create `.sql` or Python files in a folder of your choosing and point this tool at that folder. No need to fight a new API to write migrations in.\n- **API centric**: there is no CLI to figure out, _you_ decide how migrations get called, _you_ control how the database connection gets created. This makes it trivial to run migrations in tests, wrap them in a CLI or run them via an exposed HTTP endpoint.\n- **declarative**: just specify the version you want and the library figures out if it needs an upgrade, downgrade or no action.\n\n## Example usage\n\n```python\nfrom pathlib import Path\n\nimport asyncpg\nfrom asyncpg_trek import plan, execute, Direction\nfrom asyncpg_trek.asyncpg import AsyncpgBackend\n\nMIGRATIONS_DIR = Path(__file__).parent / \"migrations\"\n\nasync def migrate(\n conn: asyncpg.Connection,\n target_revision: str,\n) -> None:\n backend = AsyncpgBackend(conn)\n async with backend.connect() as conn:\n planned = await plan(conn, backend, MIGRATIONS_DIR, target_revision=target_revision, direction=Direction.up)\n await execute(conn, backend, planned)\n```\n\nYou could make this an entrypoint in a docker image, an admin endpoint in your API or a helper function in your tests (or all of the above).\nHow you run your migrations depends on the complexity of your system.\nFor example, for simple systems it may be easy to run migrations on app startup based on a hardcoded revision.\nFor more complex systems you may want to run migrations manually or via an admin API.\n\nSee this release on GitHub: [v0.4.0](https://github.com/adriangb/asyncpg-trek/releases/tag/0.4.0)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple migrations system for asyncpg",
"version": "0.4.0",
"project_urls": {
"Documentation": "https://github.com/adriangb/asyncpg-trek",
"Homepage": "https://github.com/adriangb/asyncpg-trek",
"Repository": "https://github.com/adriangb/asyncpg-trek"
},
"split_keywords": [
"asyncpg",
" postgres",
" postgresql",
" migrations"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b081d79224c679505e5224f921aaec09a6d667959b04fb35cd94d942e032c638",
"md5": "a4cba0eff928f3ee453d581ce99f9891",
"sha256": "31348799d67704ffd0e4c0a0ab419b0687449271796214ca7a08c5e1ef68925e"
},
"downloads": -1,
"filename": "asyncpg_trek-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a4cba0eff928f3ee453d581ce99f9891",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.8",
"size": 9545,
"upload_time": "2024-07-19T20:30:43",
"upload_time_iso_8601": "2024-07-19T20:30:43.391435Z",
"url": "https://files.pythonhosted.org/packages/b0/81/d79224c679505e5224f921aaec09a6d667959b04fb35cd94d942e032c638/asyncpg_trek-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "15df3dbad74b63ca14a47083849842a5ad6964a2b78d91ae09ae28e0f35f4971",
"md5": "108859157e705cca403506cc280fc1b6",
"sha256": "3a04c096ae896913d369329a96253b309bf095b1d4cd029ecad43c19dc5cf4da"
},
"downloads": -1,
"filename": "asyncpg_trek-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "108859157e705cca403506cc280fc1b6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.8",
"size": 7775,
"upload_time": "2024-07-19T20:30:44",
"upload_time_iso_8601": "2024-07-19T20:30:44.323796Z",
"url": "https://files.pythonhosted.org/packages/15/df/3dbad74b63ca14a47083849842a5ad6964a2b78d91ae09ae28e0f35f4971/asyncpg_trek-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-19 20:30:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "adriangb",
"github_project": "asyncpg-trek",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "asyncpg-trek"
}
JSON
