Package: dbdeclare
DbDeclareA declarative layer for your database, built onSQLAlchemy.The code ison GitHub.The docs arehosted on GitHub pages.The project is published onPyPI.OverviewWhat is it?DbDeclare is a Python package that helps you create and manage entities in your database cluster,
like databases, roles, access control, and (eventually) more. It aims to fill the gap between
SQLAlchemy (SQLA) and infrastructure as code (IaC).Why use it?DbDeclare does what SQLA does but for database entities beyond tables and columns. You can:Declare desired state in PythonAvoid maintaining raw SQLTightly integrate your databases, roles, access control, and more with your tablesFuture versions will have more features, and you will be able to:Have version control over database changes (likeAlembic)Define upgrades/downgrades without explicitly defining the changes (likeautogen)Additionally, DbDeclare is:Typed: Type-checking done viamypyThoroughly commented: There are docstrings for every method and classWell-tested: Though this is a new package under active development, solid test coverage is a high priorityRunning SQL scripts before SQLA and after IaC can be messy and hard to maintain.
If you prefer to have databases, roles, and the like declared alongside your infrastructure, then there are
great tools available for that, like Terraform and Pulumi's providers for Postgres and MySQL. So if you want
it tied to that, great! But if, like me, you want it closer to your application code and alongside SQLA, this
tool likely makes more sense for you.RequirementsThis requires a recent version of Python. Works with Python 3.11 or higher. We recommendpyenvto install any versions of Python you need and don't currently have installed.This also requires a compatible driver/package for your database of choice, likepsycopgfor Postgres. You'll also need a functioning cluster
to interact with (the example below shows a way to do so via Docker).SQLAlchemy is a dependency and will be installed when you install DbDeclare. DbDeclare
works with SQLAlchemy 2.0.0 or higher.InstallationDbDeclare is published onPyPI. You can install it withpipor any tool
that usespipunder the hood. This is typically installed in avirtual environment.> pip install db-declareExampleHere is a simple Postgres example. We will create a database and a user, and make sure the user
can connect to the database. You need a Postgres cluster/instance and a python environment.If needed, an easy way to spin up a Postgres instance is withDocker,
specifically theofficial Postgres image:> docker run --rm --name postgres -e POSTGRES_PASSWORD=postgres -p 127.0.0.1:5432:5432/tcp postgresThis spins up a Postgres instance with the default database name ofpostgres, an admin user ofpostgreswith the
passwordpostgres, on port5432.Assuming you have a Python environment set up, DbDeclare installed, and psycopg installed (pip install psycopg),
you can create a database and a user that can connect to it like this:fromsqlalchemyimportcreate_enginefromdbdeclare.controllerimportControllerfromdbdeclare.data_structuresimportGrantOn,Privilegefromdbdeclare.entitiesimportDatabase,Roledefmain()->None:# declare the databasefalafel_db=Database(name="falafel")# declare the userRole(name="hungry_user",login=True,# (1)!password="fakepassword",# (2)!grants=[GrantOn(privileges=[Privilege.CONNECT],on=[falafel_db])],# (3)!)# create engine with admin user and default databaseengine=create_engine(url="postgresql+psycopg://postgres:postgres@127.0.0.1:5432/postgres")# (4)!# create all entities and grant all privilegesController.run_all(engine=engine)if__name__=="__main__":main()Make sure this role can log in (make it a user)Provide a password for the user to log in withSpecify that this user can connect to thefalafeldatabaseThe engine to run DbDeclare must have admin privileges, so we use thepostgresuser hereAfter running this script, you should be able to access thefalafeldatabase ashungry_user. You can try it out withpsql(if you don't have it installed, find ithere).
In a separate shell from where the docker run command is running, you can run:> psql -h 127.0.0.1 -p 5432 -U hungry_user -d falafel

password for user hungry_user: ***

falafel=>Voila! Check out theuser guidefor more involved use cases.ContributingCheck out development, testing, and contributing guidancehere.LicenseThis project is licensed under the terms of theMIT license.