SQLAlchemy Declarative Extensions

https://sqlalchemy-declarative-extensions.readthedocs.io/
Admin
SQLAlchemy Declarative Extensions extends SQLAlchemy and Alembic to declaratively define, create,...
Tokens:44,153
Snippets:416
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Initialize Empty Schemas

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/schemas.html

Example of initializing an empty Schemas collection.

```python
>>> schemas = Schemas()
```

--------------------------------

### Alembic integration test example

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/_sources/contributing/testing.md.txt

A standard test file structure for Alembic integration, requiring the test name to match the corresponding examples folder name.

```python
import pytest

from tests.utilities import successful_test_run

@pytest.mark.alembic
def test_view_create_pg(pytester):
    successful_test_run(pytester, count=1)
```

--------------------------------

### Kitchen Sink Example: Using all available features

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest

A comprehensive example showing how to use all features of sqlalchemy-declarative-extensions. It defines a declarative base with schemas, roles, grants, rows, views, functions, and triggers, and applies auditing to a model. Note that collection-level options like ignore_unspecified can be used, and objects can also be declared directly through MetaData.

```python
from sqlalchemy import Column, types, select
from sqlalchemy.orm import as_declarative
from sqlalchemy_declarative_extensions import (
    declarative_database, Schemas, Roles, Row, View, view,
)
from sqlalchemy_declarative_extensions.dialects.postgresql import (
    DefaultGrant, Function, Trigger, Role
)
from sqlalchemy_declarative_extensions.audit import audit


@declarative_database
@as_declarative
class Base:
    # Note: each object type also has a plural version (i.e. Schemas/Roles/etc) where you can specify
    # collection-level options like `ignore_unspecified`).
    #
    # If you dont set any collection-level options, you can instead use raw list/iterable as the collection.
    schemas = Schemas().are("example")
    roles = Roles(ignore_unspecified=True).are(
        Role("read", login=False),
        Role(
            "app",
            in_roles=['read']
        ),
    )
    grants = [
        DefaultGrant.on_tables_in_schema("public", 'example').grant("select", to="read"),
        DefaultGrant.on_sequences_in_schema("public").grant("usage", to="read"),
        Grant.new("usage", to="read").on_schemas("example")
    ]
    rows = [
        Row('foo', id=1),
    ]
    views = [
        View("low_foo", "select * from foo where i < 10"),
    ]
    functions = [
        Function(
            "fancy_function",
            """
            BEGIN
            INSERT INTO foo (id) select NEW.id + 1;
            RETURN NULL;
            END
            """,
            language="plpgsql",
            returns="trigger",
        ),
    ]
    triggers = [
        Trigger.after("insert", on="foo", execute="fancy_function")
        .named("on_insert_foo")
        .when("pg_trigger_depth() < 1")
        .for_each_row(),
    ]


@audit()
class Foo(Base):
    __tablename__ = 'foo'

    id = Column(types.Integer(), primary_key=True)


audit_table = Foo.__audit_table__


@view(Base)
class HighFoo:
    __tablename__ = "high_foo"
    __view__ = select(Foo.__table__).where(Foo.__table__.c.id >= 10)
```

--------------------------------

### Initialize Schemas with Options

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/schemas.html

Example of initializing a Schemas collection with the ignore_unspecified option set to True.

```python
>>> schemas = Schemas(ignore_unspecified=True)
```

--------------------------------

### Define a Generic Protocol class

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/dialects/postgresql.html

Example of defining a generic Protocol class.

```python
class GenProto(Protocol[T]):
    def meth(self) -> T:
        ...
```

--------------------------------

### Define Roles

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/_sources/roles.md.txt

Example of defining roles using the Roles and Role classes, including an ignore_roles configuration.

```python
from sqlalchemy_declarative_extensions import Roles, Role

roles = Roles(ignore_roles=["user"]).are(
    "read",
    Role("admin", in_roles=["read"]),
)
```

--------------------------------

### Functions and Procedures

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/dialects/mysql.html

Example of defining MySQL functions and procedures using the generic Functions and Procedures containers.

```APIDOC
## Functions and Procedures

### Description
Define MySQL functions and procedures using the generic Functions and Procedures containers.

### Usage Example
```python
from sqlalchemy_declarative_extensions import Functions, Procedures, Function, Procedure

functions = Functions().are(
    Function("some_function", "INSERT INTO foo"),
    ...
)
procedures = Procedures().are(
    Procedure("some_proc", "INSERT INTO foo"),
    ...
)
```

### Notes
- Neither functions nor procedures currently support arguments.
- Dialect-specific variants exist at `sqlalchemy_declarative_extensions.dialects.mysql`.
```

--------------------------------

### Generic query.py dispatch example

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/_sources/contributing/dialect-support.md.txt

Shows how generic functions like check_schema_exists are defined using dialect_dispatch, mapping dialect names to their specific implementations. This is the central pattern for adding support for a new dialect.

```python
from sqlalchemy_declarative_extensions.dialects.mysql.query import (
    check_schema_exists_mysql,
)
from sqlalchemy_declarative_extensions.dialects.postgresql.query import (
    check_schema_exists_postgresql,
)
from sqlalchemy_declarative_extensions.dialects.sqlite.query import (
    check_schema_exists_sqlite,
)
from sqlalchemy_declarative_extensions.sqlalchemy import dialect_dispatch

check_schema_exists = dialect_dispatch(
    postgresql=check_schema_exists_postgresql,
    sqlite=check_schema_exists_sqlite,
    mysql=check_schema_exists_mysql,
)
```

--------------------------------

### Define PostgreSQL roles with Roles().are()

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/_sources/dialects/postgresql.md.txt

Creates a Roles collection with PostgreSQL-specific Role objects. The example defines roles 'foo' and 'bar' (with login enabled).

```python
from sqlalchemy_declarative_extensions import Roles
from sqlalchemy_declarative_extensions.dialects.postgresql import Role

roles = Roles().are(Role('foo'), Role('bar', login=True), ...)
```

--------------------------------

### Define a Protocol class

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/dialects/postgresql.html

Example of defining a Protocol class for structural subtyping.

```python
class Proto(Protocol):
    def meth(self) -> int:
        ...
```

--------------------------------

### Use a Protocol class for static type checking

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/dialects/postgresql.html

Example demonstrating how to use a Protocol class with a concrete class for static duck-typing.

```python
class C:
    def meth(self) -> int:
        return 0

def func(x: Proto) -> int:
    return x.meth()

func(C())  # Passes static type check
```

--------------------------------

### SQLAlchemy schema creation test

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/_sources/contributing/testing.md.txt

An example of testing SQLAlchemy model-base/MetaData scenarios across different dialects using pytest-mock-resources.

```python
import sqlalchemy
from pytest_mock_resources import create_postgres_fixture, create_sqlite_fixture

from sqlalchemy_declarative_extensions import (
    Schemas,
    declarative_database,
    register_sqlalchemy_events,
)
from sqlalchemy_declarative_extensions.sqlalchemy import declarative_base


_Base = declarative_base()

@declarative_database
class Base(_Base):  # type: ignore
    __abstract__ = True

    schemas = Schemas().are("fooschema")


class Foo(Base):
    __tablename__ = "foo"
    __table_args__ = {"schema": "fooschema"}

    id = sqlalchemy.Column(sqlalchemy.types.Integer(), primary_key=True)


register_sqlalchemy_events(Base.metadata, schemas=True)

pg = create_postgres_fixture(scope="function", engine_kwargs={"echo": True})
sqlite = create_sqlite_fixture()


def test_createall_schema_pg(pg):
    Base.metadata.create_all(bind=pg)
    with pg.connect() as conn:
        result = conn.execute(Foo.__table__.select()).fetchall()
    assert result == []


def test_createall_schema_sqlite(sqlite):
    Base.metadata.create_all(bind=sqlite, checkfirst=False)
    with sqlite.connect() as conn:
        result = conn.execute(Foo.__table__.select()).fetchall()
    assert result == []
```

--------------------------------

### Postgres schema.py with schemas_query

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/_sources/contributing/dialect-support.md.txt

Example of a Postgres dialect-specific schema.py that defines a lightweight table and a schemas_query using SQLAlchemy's table/column syntax. This decouples business logic from introspection queries and supports reuse of pg_ tables.

```python
from sqlalchemy import column, table
from sqlalchemy_declarative_extensions.sqlalchemy import select


pg_namespace = table(
    "pg_namespace",
    column("oid"),
    column("nspname"),
    column("nspowner"),
    column("nspacl"),
)

schemas_query = (
    select(pg_namespace.c.nspname)
    .where(column != "information_schema")
    .where(column.notlike("pg_%"))
    .where(pg_namespace.c.nspname != "public")
)
```

--------------------------------

### Configure Pytest-Mock-Resources for Role Isolation

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/_sources/roles.md.txt

Example of configuring pytest-mock-resources fixtures to ensure test isolation for global database roles.

```python
# test_migrations.py
from pytest_mock_resources import PostgresConfig, create_postgres_config
from pytest_mock_resources.container.base import get_container

@pytest.fixture(scope="function")
def postgres_config():
    return PostgresConfig(port=None)

@pytest.fixture(scope="function")
def pmr_postgres_container(pytestconfig, pmr_postgres_config: PostgresConfig):
    yield from get_container(pytestconfig, pmr_postgres_config)

alembic_engine = create_postgres_config()

from pytest_alembic.tests import test_model_definitions_match_ddl, test_up_down_consistency, test_upgrade, test_downgrade
```

--------------------------------

### Declare Schemas with are Method

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/schemas.html

Example of declaring multiple schemas using the are method on a Schemas instance.

```python
>>> from sqlalchemy_declarative_extensions import Schema, Schemas
>>> schema = Schemas().are("foo", Schema("bar"), ...)
```

--------------------------------

### Triggers

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/dialects/mysql.html

Example of defining a MySQL trigger using the dialect-specific Trigger class.

```APIDOC
## Triggers

### Description
Define MySQL triggers using the dialect-specific Trigger class.

### Usage Example
```python
from sqlalchemy_declarative_extensions import Triggers
from sqlalchemy_declarative_extensions.dialects.mysql import Trigger

triggers = Triggers().are(
    Trigger.before("insert", on="some_table", execute="SET NEW.value = NEW.value * 2")
    .named("before_insert_some_table")
    .follows("some_other_trigger")
)
```

### Notes
- Trigger options and semantics differ across dialects.
```

--------------------------------

### Register SQLAlchemy events with register_sqlalchemy_events

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest

Registers events so that `metadata.create_all(...)` creates declared database objects. All object types are opt-in; by default, none are registered unless explicitly included. The example shows the equivalent call with all options set to False.

```python
from sqlalchemy_declarative_extensions import register_sqlalchemy_events

metadata = Base.metadata  # Given the example above.
register_sqlalchemy_events(metadata)
# Which is equivalent to...
register_sqlalchemy_events(metadata, schemas=False, roles=False, grants=False, rows=False)

```

--------------------------------

### Postgres Immune Role Creation

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/_sources/roles.md.txt

Example of a Postgres DO block to make role creation statements immune to failure if the role already exists.

```postgresql
DO $$
  BEGIN
    CREATE ROLE rolename;
    EXCEPTION WHEN OTHERS THEN
    RAISE NOTICE 'not creating role';
  END
$$;
```

--------------------------------

### Using a Generic Mapping Class

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/dialects/postgresql.html

Example of using the previously defined generic mapping type in a function.

```python
def lookup_name(mapping: Mapping[KT, VT], key: KT, default: VT) -> VT:
    try:
        return mapping[key]
    except KeyError:
        return default
```

--------------------------------

### Define triggers and functions with declarative_database

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/_sources/triggers.md.txt

Use the declarative_database decorator to define functions and triggers on a base class. This example demonstrates creating a PostgreSQL trigger that executes after an insert on the 'foo' table.

```python
from sqlalchemy.orm import declarative_base
from sqlalchemy_declarative_extensions import declarative_database, Function, Functions, Triggers
from sqlalchemy_declarative_extensions.dialects.postgresql import Trigger

_Base = declarative_base()


@declarative_database
class Base(_Base):
    __abstract__ = True

    functions = Functions().are(
        Function(
            "fancy_trigger",
            """
            BEGIN
            INSERT INTO foo (id) select NEW.id + 1;
            RETURN NULL;
            END
            """,
            language="plpgsql",
            returns="trigger",
        )
    )

    triggers = Triggers().are(
        Trigger.after("insert", on="foo", execute="fancy_trigger")
        .named("on_insert_foo")
        .when("pg_trigger_depth() < 1")
        .for_each_row(),
    )
```

--------------------------------

### Define MySQL trigger with dialect-specific options

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/_sources/dialects/mysql.md.txt

Shows how to create a MySQL-specific trigger using the dialect-scoped Trigger class. The example defines a BEFORE INSERT trigger that doubles the new value and follows another trigger.

```python
from sqlalchemy_declarative_extensions import Triggers
from sqlalchemy_declarative_extensions.dialects.mysql import Trigger

triggers = Triggers().are(
     Trigger.before("insert", on="some_table", execute="SET NEW.value = NEW.value * 2")
     .named("before_insert_some_table")
     .follows("some_other_trigger")
)
```

--------------------------------

### Postgres get_schemas_postgresql dispatch function

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/_sources/contributing/dialect-support.md.txt

Example of a dialect-specific dispatch function for Postgres that returns a set of Schema objects by executing the schemas_query. This is the pattern for implementing dialect-specific query.py functions.

```python
from sqlalchemy.engine import Connection

from sqlalchemy_declarative_extensions.dialects.postgresql.schema import schemas_query
from sqlalchemy_declarative_extensions.schema.base import Schema


def get_schemas_postgresql(connection: Connection):
    return {Schema(schema) for schema, *_ in connection.execute(schemas_query).fetchall()}
```

--------------------------------

### DefaultGrantTypes.to_variants

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/dialects/postgresql.html

Method to get all variants of the DefaultGrantTypes.

```APIDOC
## DefaultGrantTypes.to_variants

### Description
Returns all variants of the DefaultGrantTypes enumeration.

### Method
instance method

### Returns
list
```

--------------------------------

### TypeGrants.acl_symbols()

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/dialects/postgresql.html

Class method to get the ACL symbols for type grants.

```APIDOC
## TypeGrants.acl_symbols()

### Description
Class method to get the ACL symbols for type grants.
```

--------------------------------

### Define schemas with Schemas and Schema

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/_sources/schemas.md.txt

Demonstrates how to initialize a collection of schemas using the Schemas class and individual Schema objects.

```python
from sqlalchemy_declarative_extensions import Schema, Schemas

schemas = Schemas().are("foo", "bar", Schema("baz"))
```

--------------------------------

### TablespaceGrants.acl_symbols()

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/dialects/postgresql.html

Class method to get the ACL symbols for tablespace grants.

```APIDOC
## TablespaceGrants.acl_symbols()

### Description
Class method to get the ACL symbols for tablespace grants.
```

--------------------------------

### Define materialized views with constraints

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/_sources/views.md.txt

Shows how to create a materialized view and apply a unique index using __table_args__.

```python
@view(Base, materialized=True)
class Bar:
    __tablename__ = 'bar'
    __view__ = select(Foo.__table__).where(Foo.__table__.id > 10)
    __table_args__ = (Index('uq_bar', 'id', unique=True))
```

--------------------------------

### TableGrants.acl_symbols()

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/dialects/postgresql.html

Class method to get the ACL symbols for table grants.

```APIDOC
## TableGrants.acl_symbols()

### Description
Class method to get the ACL symbols for table grants.
```

--------------------------------

### SequenceGrants.acl_symbols()

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/dialects/postgresql.html

Class method to get the ACL symbols for sequence grants.

```APIDOC
## SequenceGrants.acl_symbols()

### Description
Class method to get the ACL symbols for sequence grants.
```

--------------------------------

### Define MySQL functions and procedures

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/_sources/dialects/mysql.md.txt

Shows how to create generic Function and Procedure instances for MySQL. Note that neither functions nor procedures currently support arguments.

```python
from sqlalchemy_declarative_extensions import Functions, Procedures, Function, Procedure

functions = Functions().are(
     Function("some_function", "INSERT INTO foo"),
     ...
)
procedures = Procedures().are(
     Procedure("some_proc", "INSERT INTO foo"),
     ...
)
```

--------------------------------

### SchemaGrants.acl_symbols()

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/dialects/postgresql.html

Class method to get the ACL symbols for schema grants.

```APIDOC
## SchemaGrants.acl_symbols()

### Description
Class method to get the ACL symbols for schema grants.
```

--------------------------------

### LanguageGrants.acl_symbols()

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/dialects/postgresql.html

Class method to get the ACL symbols for language grants.

```APIDOC
## LanguageGrants.acl_symbols()

### Description
Class method to get the ACL symbols for language grants.
```

--------------------------------

### Dialect folder structure

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/_sources/contributing/dialect-support.md.txt

Shows the expected file layout for a new dialect implementation, including __init__.py, query.py, schema.py, and a feature-specific module.

```text
exampledialect/
    __init__.py
    query.py
    schema.py
    <feature>.py
```

--------------------------------

### GrantOptions.default

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/dialects/postgresql.html

Method to get the default grants for the current grant kind.

```APIDOC
## GrantOptions.default

### Description
Returns the default grants given by PostgreSQL for the current grant kind.

### Method
instance method

### Returns
List[FromStringsSelf]
```

--------------------------------

### Register a view with @view decorator

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/api.html

Shows how to use the view decorator to register a class as a view, with a raw SQL query as __view__.

```python
>>> try:
...     from sqlalchemy.orm import declarative_base
... except ImportError:
...     from sqlalchemy_declarative_extensions.sqlalchemy import declarative_base
>>> from sqlalchemy import Column, types
>>> from sqlalchemy_declarative_extensions import view
>>>
>>> Base = declarative_base()
>>>
>>> @view(Base)
... class Foo:
...     __tablename__ = "foo"
...     __view__ = "SELECT * from bar"
...
...     id = Column(types.Integer, primary_key=True)
```

--------------------------------

### Initialize Empty Grants Collection

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/grants.html

Initializes a new Grants collection with no grants defined.

```python
>>> grants = Grants()
```

--------------------------------

### LargeObjectGrants.acl_symbols()

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/dialects/postgresql.html

Class method to get the ACL symbols for large object grants.

```APIDOC
## LargeObjectGrants.acl_symbols()

### Description
Class method to get the ACL symbols for large object grants.
```

--------------------------------

### Schema.to_sql_create()

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/schemas.html

Generates SQL to create the schema. Returns an Executable or string.

```APIDOC
## Schema.to_sql_create()

### Description
Generates SQL to create the schema.

### Method
N/A (Python method)

### Endpoint
N/A

### Parameters
None

### Request Example
N/A

### Response
#### Success Response
- **Return type**: sqlalchemy.sql.base.Executable | str

#### Response Example
N/A
```

--------------------------------

### DatabaseGrants

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/dialects/postgresql.html

Grants for database-level privileges, with methods to get ACL symbols and create default grants.

```APIDOC
## DatabaseGrants

### Description
Grants for database-level privileges.

### Attributes
- connect
- create
- temporary

### Methods
- acl_symbols()
- default()

```

--------------------------------

### Create external and dependent roles

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/api.html

Shows how to define a role as external and another role that includes it.

```python
>>> base = Role("base", external=True)  # i.e. assumed to already exist, will not be created/updated
>>> foo = Role("base", in_roles=[base])
```

--------------------------------

### Registering SQLAlchemy creation-level events

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/_sources/sqlalchemy.md.txt

Opt into registration of creation-level events during metadata.create_all. All options are disabled by default.

```python
from sqlalchemy_declarative_extensions import register_sqlalchemy_events

register_sqlalchemy_events(schemas=True, roles=True, grants=True, rows=False)
```

--------------------------------

### Defining a Generic Mapping Class

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/dialects/postgresql.html

Example of defining a generic mapping type using the Generic class.

```python
class Mapping(Generic[KT, VT]):
    def __getitem__(self, key: KT) -> VT:
        ...
    # Etc.
```

--------------------------------

### View Module

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/_sources/api.md.txt

Provides Views, View, view, and register_view for declarative view management.

```APIDOC
## Module: sqlalchemy_declarative_extensions.view

### Members
- **Views**
- **View**
- **view**
- **register_view**

### Description
Classes and functions for declarative view management.
```

--------------------------------

### Define views on MetaData or declarative base

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/_sources/views.md.txt

Shows how to register views by defining them on the declarative base using the Views class.

```python
from sqlalchemy.orm import declarative_base
from sqlalchemy_declarative_extensions import declarative_database, View, Views

_Base = declarative_base()


@declarative_database
class Base(_Base):
    __abstract__ = True

    views = Views().are(
        View("foo", "select * from bar where id > 10", schema="baz"),
    )
```

--------------------------------

### Perform data alterations on audited tables

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/_sources/audit_tables.md.txt

Example operations on an audited model that trigger automatic recording in the audit table.

```python
foo1 = Foo(id=1, name=None, json=None)
foo2 = Foo(id=2, name='wat?', json={})
pg.add(foo1)
pg.add(foo2)
pg.commit()

foo1.name = 'wow!'
pg.delete(foo2)
pg.commit()
```

--------------------------------

### Initialize Grants with DefaultGrant

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/grants.html

Initializes a Grants collection and adds DefaultGrant objects using the are method.

```python
>>> from sqlalchemy_declarative_extensions.dialects.postgresql import DefaultGrant
>>> grants = Grants().are(DefaultGrant(..., ...), ...)
```

--------------------------------

### Create rows directly with Row

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/rows.html

Shows creating a list of Row objects directly for the 'users' table, with the resulting list output.

```python
>>> [
...     Row("users", id=1, name="John", active=True),
...     Row("users", id=2, name="Bob", active=True),
... ]
[Row(schema=None, tablename='users', column_values={'id': 1, 'name': 'John', 'active': True}), Row(schema=None, tablename='users', column_values={'id': 2, 'name': 'Bob', 'active': True})]
```

--------------------------------

### Grant.new

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/dialects/postgresql.html

Class method to create a new Grant instance.

```APIDOC
## Grant.new

### Description
Creates a new Grant instance with the specified grants and target role.

### Method
classmethod

### Parameters
- **grant** (str | G) - Required - The first grant.
- **grants** (str | G) - Required - Additional grants.
- **to** (str | HasName) - Required - The target role.
- **grant_option** (bool) - Optional - Whether to include grant option. Default is False.

### Returns
Grant
```

--------------------------------

### FromStrings

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/dialects/postgresql.html

Enumeration with class methods to create instances from strings.

```APIDOC
## FromStrings

### Description
Enumeration with class methods to create instances from strings.

### Class Methods
#### from_string(string)
- Parameters: string (Union[str, FromStringsSelf])
- Return type: FromStringsSelf
- Description: Creates an instance from a string.

#### from_strings(strings)
- Parameters: strings (Iterable[Union[str, FromStringsSelf]])
- Return type: List[FromStringsSelf]
- Description: Creates a list of instances from an iterable of strings.

```

--------------------------------

### Registering declared objects on a declarative base

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/_sources/sqlalchemy.md.txt

Demonstrates registering schemas and roles using the declarative base mechanism or the as_declarative decorator.

```python
# Using sqlalchemy's normal declarative base mechanism
from sqlalchemy.orm import declarative_base
from sqlalchemy_declarative_extensions import declarative_database

_Base = declarative_base()

@declarative_database
class Base(_Base):
    __abstract__ = True

    schemas = ...
    roles = ...

# Or using sqlalchemy's new decorator as of 1.4.
from sqlalchemy.orm import declarative_base
from sqlalchemy_declarative_extensions import as_declarative

@declarative_database
@as_declarative()
class Base(_Base):
    schemas = ...
    roles = ...
```

--------------------------------

### Initialize Grants with ignore_unspecified Option

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/grants.html

Initializes a Grants collection with the ignore_unspecified option set to True.

```python
>>> grants = Grants(ignore_unspecified=True)
```

--------------------------------

### Trigger

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/triggers.html

The Trigger class describes a generic trigger. It is not directly instantiable but provides properties and methods for configuring trigger behavior. The class is typically used via dialect-specific subclasses like postgresql.Trigger, as seen in the example above.

```APIDOC
## Class: Trigger

### Description
Describes a generic trigger. Use dialect-specific subclasses.

### Attributes
- **execute** (str) - The SQL function to execute when the trigger fires.
- **identity** (Hashable) - The dialect-specific identity used to compare triggers.
- **name** (str) - The name of the trigger.
- **on** (str) - The table on which the trigger operates.

### Methods

#### named(name)
Sets the name of the trigger.

##### Parameters
- **name** (str) - Required - The name to set for the trigger.

#### to_sql_create()
Abstract method. Generates SQL to create the trigger.

#### to_sql_drop()
Generates SQL to drop the trigger.

#### to_sql_update(connection=None)
Generates SQL to update the trigger definition.

##### Parameters
- **connection** (sqlalchemy.engine.Connection | None) - Optional - A database connection to use for the operation.
```

--------------------------------

### Registering declared objects on metadata

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/_sources/sqlalchemy.md.txt

Shows how to register schemas and roles directly on the MetaData object when not using the declarative style API.

```python
from sqlalchemy import MetaData
from sqlalchemy_declarative_extensions import declare_database

metadata = MetaData()

declare_database(
    metadata,
    schemas=...,
    roles=...,
)
```

--------------------------------

### Table

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/api.html

Represents a database table with methods for row creation.

```APIDOC
## Table

### Description
Represents a database table.

### Methods
- **row()** - Create a row for the table.

### Attributes
- **column_values** - The column values of the table.
- **name** - The name of the table.
```

--------------------------------

### Register Alembic events with register_alembic_events

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest

Registers comparators in Alembic's registration system so that `alembic revision --autogenerate` diffs the database against declared objects. All object types are opt-out but can be excluded. The example shows the equivalent call with all options set to True.

```python
# alembic's `env.py`
from sqlalchemy_declarative_extensions import register_alembic_events

register_alembic_events()
# Which is equivalent to...
register_sqlalchemy_events(schemas=True, roles=True, grants=True, rows=True)

```

--------------------------------

### Test folder structure

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/_sources/contributing/testing.md.txt

The directory layout for organizing tests by feature and type.

```text
tests/
    examples/
        test_view_create_pg/
        test_view_create_mysql/
        ...
    view/
        test_alembic.py
        test_materialized.py
        ...
```

--------------------------------

### GrantOptions

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/dialects/postgresql.html

Enumeration of grant options.

```APIDOC
## GrantOptions

### Description
Enumeration of grant options.

```

--------------------------------

### Grant.with_grant_option

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/dialects/postgresql.html

Method to enable the grant option.

```APIDOC
## Grant.with_grant_option

### Description
Enables the grant option for the grant.

### Method
instance method

### Returns
Grant
```

--------------------------------

### Define PostgreSQL default grants with DefaultGrant

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/_sources/dialects/postgresql.md.txt

Creates a Grants collection with a DefaultGrant for the 'public' schema, granting 'select' to role 'foo'. Note that generic grants may have provenance issues; DefaultGrant is recommended.

```python
from sqlalchemy_declarative_extensions import Grants
from sqlalchemy_declarative_extensions.dialects.postgresql import DefaultGrant

grants = Grants().are(DefaultGrant.on_table_in_schema('public').grant('select', to='foo'), ...)
```

--------------------------------

### Schema.to_sql_drop()

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/schemas.html

Generates SQL to drop the schema. Returns an Executable or string.

```APIDOC
## Schema.to_sql_drop()

### Description
Generates SQL to drop the schema.

### Method
N/A (Python method)

### Endpoint
N/A

### Parameters
None

### Request Example
N/A

### Response
#### Success Response
- **Return type**: sqlalchemy.sql.base.Executable | str

#### Response Example
N/A
```

--------------------------------

### default()

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/dialects/postgresql.html

Returns the default grants given by PostgreSQL for the current grant kind. PostgreSQL grants default privileges on some types of objects to PUBLIC, but no privileges are granted to PUBLIC by default on tables, columns, schemas, or tablespaces.

```APIDOC
## default()

### Description
Returns the default grants given by PostgreSQL for the current grant kind. PostgreSQL grants default privileges on some types of objects to PUBLIC, but no privileges are granted to PUBLIC by default on tables, columns, schemas, or tablespaces.

### Return Type
List[sqlalchemy_declarative_extensions.dialects.from_string.FromStringsSelf]
```

--------------------------------

### HasName

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/dialects/postgresql.html

Protocol class for objects that have a name attribute.

```APIDOC
## HasName

### Description
Protocol class for objects that have a name attribute.

### Attributes
- name (str): The name of the object.

```

--------------------------------

### Use Table to elide repetition

Source: https://sqlalchemy-declarative-extensions.readthedocs.io/en/latest/rows.html

Shows using the Table convenience class to define multiple rows for the same table, reducing repetition. The output list is shown.

```python
>>> users = Table("users", active=True)
>>> [
...     users.row(id=1, name="John"),
...     users.row(id=2, name="Bob"),
... ]
[Row(schema=None, tablename='users', column_values={'active': True, 'id': 1, 'name': 'John'}), Row(schema=None, tablename='users', column_values={'active': True, 'id': 2, 'name': 'Bob'})]
```
Tokens:
Raw