From: Mike Bayer Date: Tue, 10 Feb 2026 15:45:29 +0000 (-0500) Subject: doc amendments for issue #1232 X-Git-Tag: rel_1_18_4~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b844a9cd9bbb8fb4a51ad1de73bb4af277dda538;p=thirdparty%2Fsqlalchemy%2Falembic.git doc amendments for issue #1232 Change-Id: I2508e632af75edec63df9c49bddfe07e9b8d71cc --- diff --git a/alembic/op.pyi b/alembic/op.pyi index 449798dc..7fadaf5f 100644 --- a/alembic/op.pyi +++ b/alembic/op.pyi @@ -80,17 +80,17 @@ def add_column( The :meth:`.Operations.add_column` method typically corresponds to the SQL command "ALTER TABLE... ADD COLUMN". Within the scope of this command, the column's name, datatype, nullability, - and optional server-generated defaults may be indicated. + and optional server-generated defaults may be indicated. Options + also exist for control of single-column primary key and foreign key + constraints to be generated. .. note:: Not all contraint types may be indicated with this directive. - PRIMARY KEY, NOT NULL, FOREIGN KEY, and CHECK are honored, UNIQUE + NOT NULL, FOREIGN KEY, and CHECK are honored, PRIMARY KEY + is conditionally honored, UNIQUE is currently not. - .. versionadded:: 1.18.2 Added support for PRIMARY KEY to be - emitted within :meth:`.Operations.add_column`. - As of 1.18.2, the following :class:`~sqlalchemy.schema.Column` parameters are **ignored**: @@ -99,6 +99,39 @@ def add_column( * :paramref:`~sqlalchemy.schema.Column.index` - use the :meth:`.Operations.create_index` method + **PRIMARY KEY support** + + The provided :class:`~sqlalchemy.schema.Column` object may include a + ``primary_key=True`` directive, indicating the column intends to be + part of a primary key constraint. However by default, the inline + "PRIMARY KEY" directive is not emitted, and it's assumed that a + separate :meth:`.Operations.create_primary_key` directive will be used + to create this constraint, which may potentially include other columns + as well as have an explicit name. To instead render an inline + "PRIMARY KEY" directive, the + :paramref:`.AddColumnOp.inline_primary_key` parameter may be indicated + at the same time as the ``primary_key`` parameter (both are needed):: + + from alembic import op + from sqlalchemy import Column, INTEGER + + op.add_column( + "organization", + Column("id", INTEGER, primary_key=True), + inline_primary_key=True + ) + + The ``primary_key=True`` parameter on + :class:`~sqlalchemy.schema.Column` also indicates behaviors such as + using the ``SERIAL`` datatype with the PostgreSQL database, which is + why two separate, independent parameters are provided to support all + combinations. + + .. versionadded:: 1.18.4 Added + :paramref:`.AddColumnOp.inline_primary_key` + to control use of the ``PRIMARY KEY`` inline directive. + + **FOREIGN KEY support** The provided :class:`~sqlalchemy.schema.Column` object may include a :class:`~sqlalchemy.schema.ForeignKey` constraint directive, @@ -128,6 +161,8 @@ def add_column( inline_references=True, ) + **Indicating server side defaults** + The column argument passed to :meth:`.Operations.add_column` is a :class:`~sqlalchemy.schema.Column` construct, used in the same way it's used in SQLAlchemy. In particular, values or functions to be indicated @@ -151,23 +186,25 @@ def add_column( quoting of the schema outside of the default behavior, use the SQLAlchemy construct :class:`~sqlalchemy.sql.elements.quoted_name`. - :param if_not_exists: If True, adds IF NOT EXISTS operator + :param if_not_exists: If True, adds ``IF NOT EXISTS`` operator when creating the new column for compatible dialects .. versionadded:: 1.16.0 - :param inline_references: If True, renders FOREIGN KEY constraints - inline within the ADD COLUMN directive using REFERENCES syntax, - rather than as a separate ALTER TABLE ADD CONSTRAINT statement. - This is supported by PostgreSQL, Oracle, MySQL 5.7+, and + :param inline_references: If True, renders ``FOREIGN KEY`` constraints + inline within the ``ADD COLUMN`` directive using ``REFERENCES`` + syntax, rather than as a separate ``ALTER TABLE ADD CONSTRAINT`` + statement. This is supported by PostgreSQL, Oracle, MySQL 5.7+, and MariaDB 10.5+. .. versionadded:: 1.18.2 - :param inline_primary_key: If True, renders the PRIMARY KEY constraint - inline within the ADD COLUMN directive, rather than rendering it - separately. This is a purely syntactic option and should only be - used for single-column primary keys. + :param inline_primary_key: If True, renders the ``PRIMARY KEY`` phrase + inline within the ``ADD COLUMN`` directive. When not present or + False, ``PRIMARY KEY`` is not emitted; it is assumed that the + migration script will include an additional + :meth:`.Operations.create_primary_key` directive to create a full + primary key constraint. .. versionadded:: 1.18.4 diff --git a/alembic/operations/base.py b/alembic/operations/base.py index 4eb25146..b9e6107f 100644 --- a/alembic/operations/base.py +++ b/alembic/operations/base.py @@ -646,17 +646,17 @@ class Operations(AbstractOperations): The :meth:`.Operations.add_column` method typically corresponds to the SQL command "ALTER TABLE... ADD COLUMN". Within the scope of this command, the column's name, datatype, nullability, - and optional server-generated defaults may be indicated. + and optional server-generated defaults may be indicated. Options + also exist for control of single-column primary key and foreign key + constraints to be generated. .. note:: Not all contraint types may be indicated with this directive. - PRIMARY KEY, NOT NULL, FOREIGN KEY, and CHECK are honored, UNIQUE + NOT NULL, FOREIGN KEY, and CHECK are honored, PRIMARY KEY + is conditionally honored, UNIQUE is currently not. - .. versionadded:: 1.18.2 Added support for PRIMARY KEY to be - emitted within :meth:`.Operations.add_column`. - As of 1.18.2, the following :class:`~sqlalchemy.schema.Column` parameters are **ignored**: @@ -665,6 +665,39 @@ class Operations(AbstractOperations): * :paramref:`~sqlalchemy.schema.Column.index` - use the :meth:`.Operations.create_index` method + **PRIMARY KEY support** + + The provided :class:`~sqlalchemy.schema.Column` object may include a + ``primary_key=True`` directive, indicating the column intends to be + part of a primary key constraint. However by default, the inline + "PRIMARY KEY" directive is not emitted, and it's assumed that a + separate :meth:`.Operations.create_primary_key` directive will be used + to create this constraint, which may potentially include other columns + as well as have an explicit name. To instead render an inline + "PRIMARY KEY" directive, the + :paramref:`.AddColumnOp.inline_primary_key` parameter may be indicated + at the same time as the ``primary_key`` parameter (both are needed):: + + from alembic import op + from sqlalchemy import Column, INTEGER + + op.add_column( + "organization", + Column("id", INTEGER, primary_key=True), + inline_primary_key=True + ) + + The ``primary_key=True`` parameter on + :class:`~sqlalchemy.schema.Column` also indicates behaviors such as + using the ``SERIAL`` datatype with the PostgreSQL database, which is + why two separate, independent parameters are provided to support all + combinations. + + .. versionadded:: 1.18.4 Added + :paramref:`.AddColumnOp.inline_primary_key` + to control use of the ``PRIMARY KEY`` inline directive. + + **FOREIGN KEY support** The provided :class:`~sqlalchemy.schema.Column` object may include a :class:`~sqlalchemy.schema.ForeignKey` constraint directive, @@ -694,6 +727,8 @@ class Operations(AbstractOperations): inline_references=True, ) + **Indicating server side defaults** + The column argument passed to :meth:`.Operations.add_column` is a :class:`~sqlalchemy.schema.Column` construct, used in the same way it's used in SQLAlchemy. In particular, values or functions to be indicated @@ -717,23 +752,25 @@ class Operations(AbstractOperations): quoting of the schema outside of the default behavior, use the SQLAlchemy construct :class:`~sqlalchemy.sql.elements.quoted_name`. - :param if_not_exists: If True, adds IF NOT EXISTS operator + :param if_not_exists: If True, adds ``IF NOT EXISTS`` operator when creating the new column for compatible dialects .. versionadded:: 1.16.0 - :param inline_references: If True, renders FOREIGN KEY constraints - inline within the ADD COLUMN directive using REFERENCES syntax, - rather than as a separate ALTER TABLE ADD CONSTRAINT statement. - This is supported by PostgreSQL, Oracle, MySQL 5.7+, and + :param inline_references: If True, renders ``FOREIGN KEY`` constraints + inline within the ``ADD COLUMN`` directive using ``REFERENCES`` + syntax, rather than as a separate ``ALTER TABLE ADD CONSTRAINT`` + statement. This is supported by PostgreSQL, Oracle, MySQL 5.7+, and MariaDB 10.5+. .. versionadded:: 1.18.2 - :param inline_primary_key: If True, renders the PRIMARY KEY constraint - inline within the ADD COLUMN directive, rather than rendering it - separately. This is a purely syntactic option and should only be - used for single-column primary keys. + :param inline_primary_key: If True, renders the ``PRIMARY KEY`` phrase + inline within the ``ADD COLUMN`` directive. When not present or + False, ``PRIMARY KEY`` is not emitted; it is assumed that the + migration script will include an additional + :meth:`.Operations.create_primary_key` directive to create a full + primary key constraint. .. versionadded:: 1.18.4 diff --git a/alembic/operations/ops.py b/alembic/operations/ops.py index a999311d..7eda50d6 100644 --- a/alembic/operations/ops.py +++ b/alembic/operations/ops.py @@ -2117,17 +2117,17 @@ class AddColumnOp(AlterTableOp): The :meth:`.Operations.add_column` method typically corresponds to the SQL command "ALTER TABLE... ADD COLUMN". Within the scope of this command, the column's name, datatype, nullability, - and optional server-generated defaults may be indicated. + and optional server-generated defaults may be indicated. Options + also exist for control of single-column primary key and foreign key + constraints to be generated. .. note:: Not all contraint types may be indicated with this directive. - PRIMARY KEY, NOT NULL, FOREIGN KEY, and CHECK are honored, UNIQUE + NOT NULL, FOREIGN KEY, and CHECK are honored, PRIMARY KEY + is conditionally honored, UNIQUE is currently not. - .. versionadded:: 1.18.2 Added support for PRIMARY KEY to be - emitted within :meth:`.Operations.add_column`. - As of 1.18.2, the following :class:`~sqlalchemy.schema.Column` parameters are **ignored**: @@ -2136,6 +2136,39 @@ class AddColumnOp(AlterTableOp): * :paramref:`~sqlalchemy.schema.Column.index` - use the :meth:`.Operations.create_index` method + **PRIMARY KEY support** + + The provided :class:`~sqlalchemy.schema.Column` object may include a + ``primary_key=True`` directive, indicating the column intends to be + part of a primary key constraint. However by default, the inline + "PRIMARY KEY" directive is not emitted, and it's assumed that a + separate :meth:`.Operations.create_primary_key` directive will be used + to create this constraint, which may potentially include other columns + as well as have an explicit name. To instead render an inline + "PRIMARY KEY" directive, the + :paramref:`.AddColumnOp.inline_primary_key` parameter may be indicated + at the same time as the ``primary_key`` parameter (both are needed):: + + from alembic import op + from sqlalchemy import Column, INTEGER + + op.add_column( + "organization", + Column("id", INTEGER, primary_key=True), + inline_primary_key=True + ) + + The ``primary_key=True`` parameter on + :class:`~sqlalchemy.schema.Column` also indicates behaviors such as + using the ``SERIAL`` datatype with the PostgreSQL database, which is + why two separate, independent parameters are provided to support all + combinations. + + .. versionadded:: 1.18.4 Added + :paramref:`.AddColumnOp.inline_primary_key` + to control use of the ``PRIMARY KEY`` inline directive. + + **FOREIGN KEY support** The provided :class:`~sqlalchemy.schema.Column` object may include a :class:`~sqlalchemy.schema.ForeignKey` constraint directive, @@ -2165,6 +2198,8 @@ class AddColumnOp(AlterTableOp): inline_references=True, ) + **Indicating server side defaults** + The column argument passed to :meth:`.Operations.add_column` is a :class:`~sqlalchemy.schema.Column` construct, used in the same way it's used in SQLAlchemy. In particular, values or functions to be indicated @@ -2188,23 +2223,25 @@ class AddColumnOp(AlterTableOp): quoting of the schema outside of the default behavior, use the SQLAlchemy construct :class:`~sqlalchemy.sql.elements.quoted_name`. - :param if_not_exists: If True, adds IF NOT EXISTS operator + :param if_not_exists: If True, adds ``IF NOT EXISTS`` operator when creating the new column for compatible dialects .. versionadded:: 1.16.0 - :param inline_references: If True, renders FOREIGN KEY constraints - inline within the ADD COLUMN directive using REFERENCES syntax, - rather than as a separate ALTER TABLE ADD CONSTRAINT statement. - This is supported by PostgreSQL, Oracle, MySQL 5.7+, and + :param inline_references: If True, renders ``FOREIGN KEY`` constraints + inline within the ``ADD COLUMN`` directive using ``REFERENCES`` + syntax, rather than as a separate ``ALTER TABLE ADD CONSTRAINT`` + statement. This is supported by PostgreSQL, Oracle, MySQL 5.7+, and MariaDB 10.5+. .. versionadded:: 1.18.2 - :param inline_primary_key: If True, renders the PRIMARY KEY constraint - inline within the ADD COLUMN directive, rather than rendering it - separately. This is a purely syntactic option and should only be - used for single-column primary keys. + :param inline_primary_key: If True, renders the ``PRIMARY KEY`` phrase + inline within the ``ADD COLUMN`` directive. When not present or + False, ``PRIMARY KEY`` is not emitted; it is assumed that the + migration script will include an additional + :meth:`.Operations.create_primary_key` directive to create a full + primary key constraint. .. versionadded:: 1.18.4 diff --git a/docs/build/changelog.rst b/docs/build/changelog.rst index 5cad83f6..d259ab5a 100644 --- a/docs/build/changelog.rst +++ b/docs/build/changelog.rst @@ -68,9 +68,10 @@ Changelog .. note:: As of version 1.18.4, this behavior has been amended to be opt-in - via the new ``inline_primary_key`` parameter to - :meth:`.Operations.add_column`, rather than occurring automatically - when ``primary_key=True`` is set on the :class:`.Column` object. + via the new :paramref:`.Operations.add_column.inline_primary_key` + parameter to :meth:`.Operations.add_column`, rather than occurring + automatically when ``primary_key=True`` is set on the + :class:`.Column` object. .. change:: :tags: bug, typing