matter-persistence 0.8.0

Matter persistance library.

matter-persistence

Table of Contents

• Installation
• License

Installation

pip install matter-persistence

With migration support

pip install matter-persistence[database-migration]

With postgres support

pip install matter-persistence[database-postgres]

With cache support

pip install matter-persistence[cache]

With memcached support

pip install matter-persistence[cache-memcached]

Usage

First you need to configure your database.

from matter_persistence.database import DatabaseConfig

db_config = DatabaseConfig(connection_uri="sqlite:///test.db")

Then you need start the DatabaseClient

from matter_persistence.database import DatabaseConfig, DatabaseClient

db_config = DatabaseConfig(connection_uri="sqlite:///test.db")
DatabaseClient.start(db_config)

One now have two options:

• Create ORM models
• Use the sqlalchemy connection directly

ORM models

from matter_persistence.database import DatabaseBaseModel
from sqlalchemy import Column, Integer, String

class ExampleModel(DatabaseBaseModel):
    __tablename__ = "example"
    id = Column(Integer, primary_key=True)
    name = Column(String)

async def an_async_function():
    example = ExampleModel(name="test")
    await example.save()

If you need to define a different schema or namespace for your class you can do:

from matter_persistence.database import DatabaseBaseModel
from sqlalchemy import Column, Integer, String

class ExampleModel(DatabaseBaseModel):
    __tablename__ = "example"
    __table_args__ = {"schema": "some_schema"}
    
    id = Column(Integer, primary_key=True)
    name = Column(String)

sqlalchemy connection directly

from matter_persistence.database import get_or_reuse_connection
import  sqlalchemy as sa

async def another_sync_function():
    async with get_or_reuse_connection() as conn:
        await conn.execute(sa.text("SELECT 1"))

Migrations

One may use the command migrations to create and apply migrations.

First you need to configure you database client:

from matter_persistence.database import DatabaseConfig

db_config = DatabaseConfig(connection_uri="sqlite:///test.db",
                           migration={"path": <a path to your migrations folder>,
                                      "models": [<a list of full qualified class path of your ORM models>]})

If models is an empty array, or you don't have changed the models, the command will create an empty migration and you can customize it.

Then you can use the command migrations to create and apply migrations. You must provide the full qualified python path to your configuration instance

migrations create --config python.path.to.your.db_config.instance --message <migration name>

Then apply it, You must provide the full qualified python path to your configuration instance:

migrations apply --config python.path.to.your.db_config.instance 

Schema support

If you need deal with schemas in your database, you can define one for you versions:

from matter_persistence.database import DatabaseConfig

db_config = DatabaseConfig(connection_uri="sqlite:///test.db",
                           migration={"path": <a path to your migrations folder>,
                                      "models": [<a list of full qualified class path of your ORM models>]},
                                      "version_schema": "another_schema")

However, the autogenerated migrations must be manually edited.

Contributing

for contributions, check the CONTRIBUTING.md file