This library was inspired by [Flask-SQLAlchemy](https://flask-sqlalchemy.palletsprojects.com/en/3.1.x/){target="_blank"}

EllarSQL also extends **Alembic** package

to add migration functionality and make database operations accessible through **EllarCLI** commandline interface.

**EllarSQL** with Alembic does not override Alembic action rather provide Alembic all the configs/information

it needs to for a proper migration/database operations.

We assume you have set up `EllarSQLModule` in your application, and you have specified `migration_options`.

**`EllarSQLModule`** is an Ellar Dynamic Module that offers two ways of configuration:

- `EllarSQLModule.register_setup()`: This method registers a `ModuleSetup` that depends on the application config.

- `EllarSQLModule.setup()`: This method immediately sets up the module with the provided options.

While we've explored many examples using `EllarSQLModule.setup()`, this section will focus on the usage of `EllarSQLModule.register_setup()`.

Before delving into that, let's first explore the setup options available for `EllarSQLModule`.

As mentioned earlier, **EllarSQLModule** can be configured from the application through `EllarSQLModule.register_setup`.

This process registers a [ModuleSetup](https://python-ellar.github.io/ellar/basics/dynamic-modules/#modulesetup){target="_blank"} factory

that depends on the Application Config object.

The factory retrieves the `ELLAR_SQL` attribute from the config and validates the data before passing it to `EllarSQLModule` for setup.

It's essential to note

that `ELLAR_SQL` will be a dictionary object with the [configuration parameters](#ellarsqlmodule-configuration-parameters)

mentioned above as keys.

The registered ModuleSetup factory reads the `ELLAR_SQL` value and configures the `EllarSQLModule` appropriately.

This approach is particularly useful when dealing with multiple environments.

It allows for seamless modification of the **ELLAR_SQL** values in various environments such as

Continuous Integration (CI), Development, Staging, or Production.

You can easily change the settings for each environment

and export the configurations as a string to be imported into `ELLAR_CONFIG_MODULE`.

In this segment, we will walk through the process of configuring **EllarSQL** within your Ellar application,

ensuring that all essential services are registered, configurations are set, and everything is prepared for immediate use.

Before we delve into the setup instructions, it is assumed that you possess a comprehensive

understanding of how [Ellar Modules](https://python-ellar.github.io/ellar/basics/dynamic-modules/#module-dynamic-setup){target="_blank"}

operate.

Let us install all the required packages, assuming that your Python environment has been properly configured:

In the `root_module.py` file, two main tasks need to be performed:

1. Register the `UsersController` to make the `/users` endpoint available when starting the application.

2. Configure the `EllarSQLModule`, which will set up and register essential services such as `EllarSQLService`, `Session`, and `Engine`.

In the provided code snippet:

- We registered `UserController` and `EllarSQLModule` with specific configurations for the database and migration options. For more details on [`EllarSQLModule` configurations](./configuration.md#ellarsqlmodule-config).

- In the `on_startup` method, we obtained the `EllarSQLService` from the Ellar Dependency Injection container using `EllarSQLModule`. Subsequently, we invoked the `create_all()` method to generate the necessary SQLAlchemy tables.

Additionally, please remember to uncomment the configurations for the `OpenAPIModule` in the `server.py`

file to enable visualization and interaction with the `/users` endpoint.

Once done,

you can access the OpenAPI documentation at [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs){target="_blank"}.

The `ellar_sql.model.Model` class acts as a factory for creating `SQLAlchemy` models, and

This class can be configured through the `__base_config__` attribute, allowing you to specify how your `SQLAlchemy` model should be created.

The `__base_config__` attribute can be of type `ModelBaseConfig`, which is a dataclass, or a dictionary with keys that

match the attributes of `ModelBaseConfig`.

Attributes of `ModelBaseConfig`:

- **as_base**: Indicates whether the class should be treated as a `Base` class for other model definitions, similar to creating a Base from a [DeclarativeBase](https://docs.sqlalchemy.org/en/20/orm/mapping_api.html#sqlalchemy.orm.DeclarativeBase){target="_blank"} or [DeclarativeBaseNoMeta](https://docs.sqlalchemy.org/en/20/orm/mapping_api.html#sqlalchemy.orm.DeclarativeBaseNoMeta){target="_blank"} class. *(Default: False)*

- **use_base**: Specifies the base classes that will be used to create the `SQLAlchemy` model. *(Default: [])*

`Model` treats each model as a standalone entity. Each instance of `model.Model` creates a distinct **declarative** base for itself, using the `__database__` key as a reference to determine its associated **Metadata**. Consequently, models sharing the same `__database__` key will utilize the same **Metadata** object.

Let's explore how we can create a `Base` model using `Model`, similar to the approach in traditional `SQLAlchemy`.

assert issubclass(Base, model.DeclarativeBase)

If you are interested in [SQLAlchemy’s native support for data classes](https://docs.sqlalchemy.org/en/20/changelog/whatsnew_20.html#native-support-for-dataclasses-mapped-as-orm-models){target="_blank"},

then you can add `MappedAsDataclass` to `use_bases` as shown below:

assert issubclass(Base, model.MappedAsDataclass)

In the examples above, `Base` classes are created, all subclassed from the `use_bases` provided, and with the `as_base`

option, the factory creates the `Base` class as a `Base`.

You can also configure the SQLAlchemy object with a custom [`MetaData`](https://docs.sqlalchemy.org/en/20/core/metadata.html#sqlalchemy.schema.MetaData){target="_blank"} object.

For instance, you can define a specific **naming convention** for constraints, ensuring consistency and predictability in constraint names.

This can be particularly beneficial during migrations, as detailed by [Alembic](https://alembic.sqlalchemy.org/en/latest/naming.html){target="_blank"}.

For example:

If the desired behavior is only applicable to specific models rather than all models,

you can use an abstract model base class to customize only those models.

For example, if certain models need to track their creation or update **timestamps**, t

his approach allows for targeted customization.

Unlike plain SQLAlchemy, **EllarSQL** models will automatically generate a table name if the `__tablename__` attribute is not set,

provided a primary key column is defined.

The table class is designed to receive a table name, followed by **columns** and other table **components** such as constraints.

EllarSQL enhances the functionality of the SQLAlchemy Table

by facilitating the selection of **Metadata** based on the `__database__` argument.

Directly creating a table proves particularly valuable when establishing **many-to-many** relationships.

In this section, we'll delve into straightforward **CRUD** operations using the ORM objects.

Having understood, `Model` usage. Let's create a `User` model