{"id":6407,"library":"peewee-migrate","title":"Peewee Migrate","description":"Peewee-migrate, currently at version 1.15.0, provides robust database migration support for the Peewee ORM. It enables developers to manage schema changes through versioned migrations, offering features like creation, application, and rollback of migrations. The library is actively maintained on GitHub with a regular release cadence, ensuring compatibility and ongoing improvements for Peewee projects.","status":"active","version":"1.15.0","language":"python","source_language":"en","source_url":"https://github.com/klen/peewee_migrate","tags":["peewee","orm","database","migrations"],"install":[{"cmd":"pip install peewee-migrate","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core ORM that peewee-migrate extends for database migrations.","package":"peewee","optional":false}],"imports":[{"symbol":"Router","correct":"from peewee_migrate import Router"}],"quickstart":{"code":"import os\nfrom peewee import *\nfrom peewee_migrate import Router\n\n# 1. Initialize a Peewee database instance\ndb = SqliteDatabase('example.db')\n\n# 2. Define the directory where your migration files are stored\nmigrations_dir = 'my_migrations'\n\n# Create a dummy migration directory and file for the example to be runnable\nos.makedirs(migrations_dir, exist_ok=True)\nwith open(os.path.join(migrations_dir, '001_initial.py'), 'w') as f:\n    f.write('from peewee import *\\ndef migrate(migrator, database, **kwargs):\\n    pass\\ndef rollback(migrator, database, **kwargs):\\n    pass')\n\n# 3. Initialize the Peewee-Migrate Router\nrouter = Router(db, migrate_dir=migrations_dir)\n\n# 4. Run all pending migrations\n# In a real scenario, you would have migration files in 'my_migrations'\n# defining schema changes.\nprint(\"Running migrations...\")\nrouter.run()\nprint(\"Migrations completed successfully.\")\n\n# Clean up created files/dirs for a repeatable example\nif os.path.exists('example.db'):\n    os.remove('example.db')\nif os.path.exists(migrations_dir):\n    import shutil\n    shutil.rmtree(migrations_dir)","lang":"python","description":"This quickstart demonstrates how to initialize the `Router` with a Peewee database and run migrations. It sets up a dummy migration directory and file for the example to be runnable. In a real application, you would create migration files using `router.create()` and then manually define your schema changes within them."},"warnings":[{"fix":"Update `Router(db, '/path/to/migrations')` to `Router(db, migrate_dir='/path/to/migrations')`.","message":"The `Router` constructor signature changed significantly in version 1.0.0. The second positional argument (path to migrations) was removed in favor of a keyword argument `migrate_dir`.","severity":"breaking","affected_versions":">=1.0.0 (breaking change from <1.0.0)"},{"fix":"Ensure migration files are named `NNN_descriptive_name.py` and located in the directory passed via `migrate_dir`.","message":"Migration files must adhere to the `NNN_name.py` naming convention (e.g., `001_create_user_table.py`) and be placed in the `migrate_dir` specified to the `Router` instance. Files not following this format or placed elsewhere will be ignored.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always implement a corresponding `rollback` function that effectively reverses the changes made by its `migrate` counterpart. For example, `migrator.add_model()` in `migrate` should be paired with `migrator.remove_model()` in `rollback`.","message":"Rollback functions (`rollback(migrator, database, **kwargs)`) are optional but highly recommended. If a `rollback` function is not provided for a `migrate` operation, that specific migration cannot be reversed using `peewee-migrate`'s rollback command.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'1.15.0':9 'activ':41 'applic':33 'cadenc':49 'chang':25 'compat':51 'creation':32 'current':6 'databas':12,60 'develop':21 'enabl':20 'ensur':50 'featur':30 'github':44 'improv':54 'librari':39 'like':31 'maintain':42 'manag':23 'migrat':2,5,13,28,37,61 'offer':29 'ongo':53 'orm':18,59 'peewe':1,4,17,56,58 'peewee-migr':3 'project':57 'provid':10 'regular':47 'releas':48 'robust':11 'rollback':35 'schema':24 'support':14 'version':8,27","created_at":"2026-04-15T05:35:57.374016+00:00","updated_at":"2026-04-16T17:57:57.710180+00:00","problems":[{"fix":"Install the 'peewee' library using pip: `pip install peewee`","cause":"The 'peewee' ORM library, a core dependency for 'peewee-migrate', is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'peewee'"},{"fix":"Activate your Python virtual environment if you are using one. Alternatively, run the command using Python's module execution: `python -m peewee_migrate <command>`","cause":"The 'pw_migrate' command-line entry point, installed by 'peewee-migrate', is not accessible in the system's PATH, or the Python virtual environment where it was installed is not activated.","error":"pw_migrate: command not found"},{"fix":"Ensure your Peewee database instance (e.g., `SqliteDatabase`, `PostgresqlDatabase`) is explicitly initialized and connected before passing it to `peewee_migrate.Router` or using it in migration scripts. If using a `Proxy` object, call `database_proxy.initialize(actual_database_instance)`.","cause":"The Peewee database object used by peewee-migrate was not properly initialized or connected before a migration operation was attempted.","error":"peewee.InterfaceError: Error, database must be initialized before opening a connection."},{"fix":"Ensure the `--auto-source` argument provides a valid, importable Python module path (e.g., `my_app.models`) and that the directory containing this module is correctly in your `PYTHONPATH` or that you are running `pw_migrate` from the project's root directory.","cause":"When using `pw_migrate create --auto-source <module_path>`, the specified Python module path where your Peewee models reside cannot be imported by 'peewee-migrate', often due to an incorrect path or the module not being discoverable in `PYTHONPATH`.","error":"Can't import models module"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.15.0","cli_name":"pw_migrate","cli_version":"Usage: pw_migrate [OPTIONS] COMMAND [ARGS]...","type":"library","homepage":null,"github":"https://github.com/klen/peewee_migrate","docs":null,"changelog":null,"pypi":"https://pypi.org/project/peewee-migrate/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","workflow"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}