The clld database models are declared using SQLAlchemy’s declarative extension. In particular we follow the approach of mixins and custom base class, to provide building blocks with enough shared commonality for custom data models.

Declarative base and mixins

While the above mixin only adds columns to a model, the following mixins do also add relations between models, thus have to be used in combination, tied together by naming conventions.

Typical usage looks like

class MyModel_data(Base, Versioned, DataMixin):

class MyModel_files(Base, Versioned, FilesMixin):

class MyModel(Base, HasDataMixin, HasFilesMixin):

Core models

The CLLD data model includes the following entities commonly found in linguistic databases and publications:


Versioned model objects are supported via the clld.db.versioned.Versioned mixin, implemented following the corresponding SQLAlchemy ORM Example.


Migrations provide a mechanism to update the database model (or the data) in a controlled and repeatable way. clld apps use Alembic to implement migrations.

Since a migration may change the database schema, it is generally not possible to fully use ORM mechanisms in migration scripts. Instead, migration scripts typically construct SQL to be sent to the database “by hand”, or using SQLAlchemy’s SQL expression language. Now dropping down to these lower levels of database access makes scripts verbose and error prone. Thus, clld provides a module with helpers for Alembic migration scripts.