Metadata-Version: 2.1
Name: alembic-postgresql-enum
Version: 0.1.7a3
Summary: Alembic autogenerate support for creation, alteration and deletion of enums
License: MIT
Author: RustyGuard
Requires-Python: >=3.7,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: SQLAlchemy (>=1.4)
Requires-Dist: alembic (>=1.7)
Project-URL: Source code, https://github.com/RustyGuard/alembic-postgresql-enum
Description-Content-Type: text/markdown

# alembic-postgresql-enum
[<img src="https://img.shields.io/pypi/pyversions/alembic-postgresql-enum">](https://pypi.org/project/alembic-postgresql-enum/)
[<img src="https://img.shields.io/pypi/v/alembic-postgresql-enum">](https://pypi.org/project/alembic-postgresql-enum/)
[<img src="https://img.shields.io/pypi/l/alembic-postgresql-enum">](https://pypi.org/project/alembic-postgresql-enum/)

Alembic autogenerate support for creation, alteration and deletion of enums

Alembic will now automatically:
- Create enums that currently are not in postgres schema
- Remove/add/alter enum values
- Reorder enum values
- Delete unused enums from schema

If you are curious to know about analogs and reasons for this library to exist see [alternatives and motivation](https://github.com/Pogchamp-company/alembic-postgresql-enum/blob/master/docs/alternatives.md)

## Usage

Install library:
```
pip install alembic-postgresql-enum
```

Add the line:

```python 
# env.py
import alembic_postgresql_enum
...
```

To the top of your migrations/env.py file.

## Features

* [Creation of enums](#creation-of-enum)
* [Deletion of unreferenced enums](#deletion-of-unreferenced-enum)
* [Creation of new enum values](#creation-of-new-enum-values)
* [Deletion of enums values](#deletion-of-enums-values)
* [Renaming of enum values](#rename-enum-value)

### Creation of enum

#### When table is created

```python
class MyEnum(enum.Enum):
    one = 1
    two = 2
    three = 3


class ExampleTable(BaseModel):
    test_field = Column(Integer, primary_key=True, autoincrement=False)
    enum_field = Column(postgresql.ENUM(MyEnum)) 
```
This code will generate migration given below: 
```python
def upgrade():
    # ### commands auto generated by Alembic - please adjust! ###
    # this line is generated by our library
    sa.Enum('one', 'two', 'three', name='myenum').create(op.get_bind())
    op.create_table('example_table',
    sa.Column('test_field', sa.Integer(), nullable=False),
    # create_type=False argument is now present on postgresql.ENUM as library takes care of enum creation
    sa.Column('enum_field', postgresql.ENUM('one', 'two', 'three', name='myenum', create_type=False), nullable=True),
    sa.PrimaryKeyConstraint('test_field')
    )
    # ### end Alembic commands ###


def downgrade():
    # ### commands auto generated by Alembic - please adjust! ###
    # drop_table does not drop enum by alembic
    op.drop_table('example_table')
    # It is dropped by us
    sa.Enum('one', 'two', 'three', name='myenum').drop(op.get_bind())
    # ### end Alembic commands ###
```

#### When column is added
```python
class MyEnum(enum.Enum):
    one = 1
    two = 2
    three = 3


class ExampleTable(BaseModel):
    test_field = Column(Integer, primary_key=True, autoincrement=False)
    # this column has just been added
    enum_field = Column(postgresql.ENUM(MyEnum)) 
```
This code will generate migration given below: 
```python
def upgrade():
    # ### commands auto generated by Alembic - please adjust! ###
    # this line is generated by our library
    sa.Enum('one', 'two', 'three', name='myenum').create(op.get_bind())
    # create_type=False argument is now present on postgresql.ENUM as library takes care of enum creation
    op.add_column('example_table', sa.Column('enum_field', postgresql.ENUM('one', 'two', 'three', name='myenum', create_type=False), nullable=False))
    # ### end Alembic commands ###


def downgrade():
    # ### commands auto generated by Alembic - please adjust! ###
    op.drop_column('example_table', 'enum_field')
    # enum is explicitly dropped as it is no longer used
    sa.Enum('one', 'two', 'three', name='myenum').drop(op.get_bind())
    # ### end Alembic commands ###
```

### Deletion of unreferenced enum
If enum is defined in postgres schema, but its mentions removed from code - It will be automatically removed
```python
class ExampleTable(BaseModel):
    test_field = Column(Integer, primary_key=True, autoincrement=False)
    # enum_field is removed from table
```

```python
def upgrade():
    # ### commands auto generated by Alembic - please adjust! ###
    op.drop_column('example_table', 'enum_field')
    sa.Enum('one', 'two', 'four', name='myenum').drop(op.get_bind())
    # ### end Alembic commands ###


def downgrade():
    # ### commands auto generated by Alembic - please adjust! ###
    sa.Enum('one', 'two', 'four', name='myenum').create(op.get_bind())
    op.add_column('example_table', sa.Column('enum_field', postgresql.ENUM('one', 'two', 'four', name='myenum', create_type=False), autoincrement=False, nullable=True))
    # ### end Alembic commands ###
```

### Creation of new enum values

If new enum value is defined sync_enum_values function call will be added to migration to account for it

```python
class MyEnum(enum.Enum):
    one = 1
    two = 2
    three = 3
    four = 4 # New enum value
```

```python
def upgrade():
    # ### commands auto generated by Alembic - please adjust! ###
    op.sync_enum_values('public', 'myenum', ['one', 'two', 'three', 'four'], 
                        [('example_table', 'enum_field')],
                        enum_values_to_rename=[])
    # ### end Alembic commands ###


def downgrade():
    # ### commands auto generated by Alembic - please adjust! ###
    op.sync_enum_values('public', 'myenum', ['one', 'two', 'three'], 
                        [('example_table', 'enum_field')],
                        enum_values_to_rename=[])
    # ### end Alembic commands ###
```

### Deletion of enums values

If enum value is removed it also will be detected

```python
class MyEnum(enum.Enum):
    one = 1
    two = 2
    # three = 3 removed
```

```python
def upgrade():
    # ### commands auto generated by Alembic - please adjust! ###
    op.sync_enum_values('public', 'myenum', ['one', 'two'], 
                        [('example_table', 'enum_field')],
                        enum_values_to_rename=[])
    # ### end Alembic commands ###


def downgrade():
    # ### commands auto generated by Alembic - please adjust! ###
    op.sync_enum_values('public', 'myenum', ['one', 'two', 'three'], 
                        [('example_table', 'enum_field')],
                        enum_values_to_rename=[])
    # ### end Alembic commands ###
```

### Rename enum value
In this case you must manually edit migration

```python
class MyEnum(enum.Enum):
    one = 1
    two = 2
    three = 3 # renamed from `tree`
```

This code will generate this migration:
```python
def upgrade():
    # ### commands auto generated by Alembic - please adjust! ###
    op.sync_enum_values('public', 'myenum', ['one', 'two', 'three'], 
                        [('example_table', 'enum_field')],
                        enum_values_to_rename=[])
    # ### end Alembic commands ###


def downgrade():
    # ### commands auto generated by Alembic - please adjust! ###
    op.sync_enum_values('public', 'myenum', ['one', 'two', 'tree'], 
                        [('example_table', 'enum_field')],
                        enum_values_to_rename=[])
    # ### end Alembic commands ###
```

This migration will cause problems with existing rows that references MyEnum

So adjust migration like that

```python
def upgrade():
    op.sync_enum_values('public', 'myenum', ['one', 'two', 'three'], 
                        [('example_table', 'enum_field')],
                        enum_values_to_rename=[('tree', 'three')])


def downgrade():
    op.sync_enum_values('public', 'myenum', ['one', 'two', 'tree'], 
                        [('example_table', 'enum_field')],
                        enum_values_to_rename=[('three', 'tree')])
```

Do not forget to switch places old and new values for downgrade

All defaults in postgres will be renamed automatically as well

