{"id":3864,"library":"alembic-utils","title":"Alembic Utils","description":"Alembic Utils is an extension for SQLAlchemy and Alembic, enabling the migration and management of PostgreSQL-specific database entities such as functions, views, materialized views, triggers, and policies. It helps integrate DDL (Data Definition Language) for these objects into the standard Alembic migration workflow. The current version is 0.8.8, with an active but moderate release cadence.","status":"active","version":"0.8.8","language":"en","source_language":"en","source_url":"https://github.com/olirice/alembic_utils","tags":["alembic","sqlalchemy","postgresql","migrations","ddl","views","functions","triggers"],"install":[{"cmd":"pip install alembic-utils","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Alembic Utils extends Alembic for database migrations.","package":"alembic"},{"reason":"Underlying ORM framework that Alembic and Alembic Utils integrate with.","package":"SQLAlchemy","optional":true}],"imports":[{"symbol":"PGView","correct":"from alembic_utils.pg_view import PGView"},{"symbol":"PGFunction","correct":"from alembic_utils.pg_function import PGFunction"},{"symbol":"PGMaterializedView","correct":"from alembic_utils.pg_materialized_view import PGMaterializedView"},{"symbol":"PGTrigger","correct":"from alembic_utils.pg_trigger import PGTrigger"},{"symbol":"PGPolicy","correct":"from alembic_utils.pg_policy import PGPolicy"},{"note":"Primarily for older Alembic/Alembic-Utils versions; op.sync_alembic_utils() is preferred for newer setups.","symbol":"add_alembic_utils_meta","correct":"from alembic_utils.utils import add_alembic_utils_meta"}],"quickstart":{"code":"import sys\nfrom alembic_utils.pg_view import PGView\nfrom alembic_utils.pg_function import PGFunction\n\n# Mock op object for demonstration purposes to show API usage.\n# In a real Alembic migration, `op` is provided by Alembic.\nclass MockOp:\n    def execute(self, statement):\n        print(f\"Executing DDL: {statement}\")\n\n    def create_entity(self, entity):\n        print(f\"Creating entity: {entity.entity_name}\")\n        print(f\"  Definition: {entity.to_sql_statement()}\")\n\n    def drop_entity(self, entity):\n        print(f\"Dropping entity: {entity.entity_name}\")\n        print(f\"  Definition: {entity.to_sql_drop_statement()}\")\n\n    def sync_alembic_utils(self):\n        print(\"Synchronizing Alembic-Utils entities (mocked).\")\n\nop = MockOp()\n\n# Define a PostgreSQL view\nmy_view = PGView(\n    schema=\"public\",\n    signature=\"my_first_view\",\n    definition=\"SELECT id, name FROM users WHERE active = TRUE;\"\n)\n\n# Define a PostgreSQL function\nmy_function = PGFunction(\n    schema=\"public\",\n    signature=\"my_first_function(a integer, b integer)\",\n    definition=\"RETURNS integer LANGUAGE plpgsql IMMUTABLE AS $$ BEGIN RETURN a + b; END; $$\",\n    returns=\"integer\" # Required since 0.6.0\n)\n\n# Simulate usage in an Alembic migration's upgrade() function\nprint(\"--- Simulating 'upgrade' phase ---\")\nop.create_entity(my_view)\nop.create_entity(my_function)\n\n# For Alembic >= 1.10.0 and Alembic-Utils >= 0.8.0, use this in env.py\n# to automatically discover and manage entities defined in your model.\n# If you define entities directly in migration scripts, this might not be needed.\nop.sync_alembic_utils()\n\nprint(\"\\n--- Simulating 'downgrade' phase ---\")\n# Entities should be dropped in reverse order of creation if dependencies exist\nop.drop_entity(my_function)\nop.drop_entity(my_view)\n","lang":"python","description":"This quickstart demonstrates how to define a PostgreSQL view and function using Alembic Utils, and how to use the `op.create_entity()`, `op.drop_entity()`, and `op.sync_alembic_utils()` methods within an Alembic migration script. The `MockOp` class allows the code to run and display the intended DDL operations without requiring an actual database connection or full Alembic project setup."},"warnings":[{"fix":"Replace `PGText` definitions with `PGFunction` for functions or `PGView` for views, updating arguments as necessary (e.g., adding `returns` to `PGFunction`).","message":"`PGText` was removed in version `0.8.0`. Users who previously used `PGText` for defining functions or views must migrate their definitions to `PGFunction` or `PGView` respectively. This change provides more specific and structured interfaces for each entity type.","severity":"breaking","affected_versions":">=0.8.0"},{"fix":"Ensure all `PGFunction` definitions include the `returns` argument specifying the return type (e.g., `returns='integer'` or `returns='void'`).","message":"The `PGFunction` constructor signature changed in version `0.6.0`, making the `returns` argument mandatory. Migrations using `PGFunction` from older versions will fail if `returns` is not provided.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"Consult the documentation for your specific Alembic and Alembic-Utils versions. Use `op.sync_alembic_utils()` if on modern versions, otherwise use `add_alembic_utils_meta(op)`.","message":"Alembic integration for change detection and synchronization varies by version. For Alembic >= 1.10.0 and Alembic-Utils >= 0.8.0, the preferred method to automatically manage entities defined in your application models is `op.sync_alembic_utils()`, typically called in `env.py`. For older versions, `add_alembic_utils_meta(op)` was used in `env.py`.","severity":"gotcha","affected_versions":"<0.8.0 (for `add_alembic_utils_meta`), >=0.8.0 (for `op.sync_alembic_utils`)"},{"fix":"Ensure you are using Alembic Utils with a PostgreSQL database. For other databases, seek alternative migration tools for custom DDL.","message":"Alembic Utils is primarily designed for PostgreSQL. While some concepts might apply to other SQL dialects, the specific entity classes (e.g., `PGView`, `PGFunction`) and their underlying DDL generation are tailored to PostgreSQL syntax and features. Attempting to use these with other databases may lead to syntax errors or unexpected behavior.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}