Configuration

AMSDAL applications are configured through a config.yml file.

AMSDAL Cloud

The config.yml file is used only for local development. When deploying to AMSDAL Cloud via amsdal cloud deploys new, all configuration — database connections, lakehouse, worker — is generated automatically based on your deployment parameters. No manual config needed.

Configuration File

application_name

The name of your application.

async_mode

Whether the application runs in async mode. Default: false.

connections

A list of database connections. Each connection has:

Field	Description
name	Unique identifier for this connection
backend	Backend alias or full Python path to the connection class
credentials	Connection-specific parameters (passed to the connect method)

resources_config

Maps your connections to their roles:

Field	Description
lakehouse	Connection name for historical data storage
lock	Connection name for distributed locking
worker	Connection name for background task processing (Celery)
repository	Default and per-model connection mapping

Example

SyncAsync

application_name: MyApp

connections:
  - name: lakehouse
    backend: postgres-historical
    credentials:
      - dsn: postgresql://user:password@localhost:5432/lakehouse

  - name: main-db
    backend: sqlite
    credentials:
      - db_path: ./default.db

  - name: users-db
    backend: sqlite
    credentials:
      - db_path: ./users.db

  - name: lock
    backend: amsdal_data.lock.implementations.redis_lock.RedisLock
    credentials:
      - host: localhost
      - port: 6379

resources_config:
  lakehouse: lakehouse
  lock: lock
  repository:
    default: main-db
    models:
      user: users-db

application_name: MyApp
async_mode: true

connections:
  - name: lakehouse
    backend: postgres-historical-async
    credentials:
      - dsn: postgresql://user:password@localhost:5432/lakehouse

  - name: main-db
    backend: sqlite-async
    credentials:
      - db_path: ./default.db

  - name: users-db
    backend: sqlite-async
    credentials:
      - db_path: ./users.db

  - name: lock
    backend: amsdal_data.lock.implementations.redis_lock.RedisLock
    credentials:
      - host: localhost
      - port: 6379

resources_config:
  lakehouse: lakehouse
  lock: lock
  repository:
    default: main-db
    models:
      user: users-db

Backend Aliases

Instead of writing full Python paths, use built-in aliases:

State Connections

Alias	Backend
sqlite	SQLite (sync)
sqlite-async	SQLite (async)
postgres-state	PostgreSQL (sync)
postgres-state-async	PostgreSQL (async)

Historical Connections

Alias	Backend
sqlite-historical	SQLite historical (sync)
sqlite-historical-async	SQLite historical (async)
postgres-historical	PostgreSQL historical (sync)
postgres-historical-async	PostgreSQL historical (async)

You can also use a full Python path to a custom connection class:

backend: mypackage.connections.MyCustomConnection

Bootstrap behaviour

AmsdalManager.setup() eagerly imports every registered model module (user models + contribs) and bulk-resolves all deferred primary keys, foreign keys, and many-to-many references before returning. As a result, model import errors or circular imports surface at setup() rather than at first attribute access.

If you previously relied on a model being loaded lazily after setup() returned, either move its module into the bootstrap import set (user models path or a contrib) or wrap dynamic creations explicitly:

from amsdal_models.classes.loading import allow_late_registration
from amsdal_models.classes.model import Model

with allow_late_registration():
    class DynamicModel(Model):
        name: str

Your application can run its own code as the framework starts up and shuts down. Implement on_setup, on_ready, or on_teardown on your AppConfig — see App Config & Lifecycle for when each hook runs and what to put in it.

Cloud Deployment

When deploying to AMSDAL Cloud, configuration is handled automatically:

amsdal cloud deploys new --deploy-type include_state_db --lakehouse-type postgres

Flag	Options	Description
--deploy-type	include_state_db, lakehouse_only	Whether to provision a state database
--lakehouse-type	postgres, postgres-immutable, spark	Lakehouse backend
--env	environment name	Target environment

The cloud provisions all database connections, lakehouse, lock, and worker infrastructure based on these parameters. Your application code works identically in local and cloud environments.

See the CLI documentation for more cloud commands.