{"id":20636729,"url":"https://github.com/libcommon/sqlalchemy-dbutils-py","last_synced_at":"2026-05-29T08:04:53.349Z","repository":{"id":62575374,"uuid":"233140565","full_name":"libcommon/sqlalchemy-dbutils-py","owner":"libcommon","description":"Python library with utilities for working with databases through SQLAlchemy.","archived":false,"fork":false,"pushed_at":"2022-12-26T21:31:44.000Z","size":67,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-26T02:58:44.462Z","etag":null,"topics":["library","python","sqlalchemy"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/libcommon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-01-10T22:26:12.000Z","updated_at":"2020-06-13T21:03:20.000Z","dependencies_parsed_at":"2023-01-31T01:45:48.472Z","dependency_job_id":null,"html_url":"https://github.com/libcommon/sqlalchemy-dbutils-py","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":"libcommon/template-repo-py","purl":"pkg:github/libcommon/sqlalchemy-dbutils-py","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libcommon%2Fsqlalchemy-dbutils-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libcommon%2Fsqlalchemy-dbutils-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libcommon%2Fsqlalchemy-dbutils-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libcommon%2Fsqlalchemy-dbutils-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/libcommon","download_url":"https://codeload.github.com/libcommon/sqlalchemy-dbutils-py/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libcommon%2Fsqlalchemy-dbutils-py/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33642325,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["library","python","sqlalchemy"],"created_at":"2024-11-16T15:12:00.333Z","updated_at":"2026-05-29T08:04:53.330Z","avatar_url":"https://github.com/libcommon.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sqlalchemy-dbutils-py\n\n## Overview\n\n[SQLAlchemy](https://www.sqlalchemy.org/) has two high-level components: Core and ORM. Core provides (not surprisingly)\nthe core functionality of SQLAlchemy's SQL abstraction layer. The ORM (\"Object-Relational Mapper\") component offers\nthe ability to map between Python and database types. `sqlalchemy-dbutils-py` offers a number of utilities built upon\nthe ORM component, including:\n* Views and materialized views as regular database tables (`view` module)\n* Default types for common database engines (`schema` module)\n* Database connection/session management (`manager` module)\n\n## Installation\n\n### Install from PyPi (preferred method)\n\n```bash\npip install lc-sqlalchemy-dbutils\n```\n\n### Install from GitHub with Pip\n\n```bash\npip install git+https://github.com/libcommon/sqlalchemy-dbutils-py.git@vx.x.x#egg=lc_sqlalchemy_dbutils\n```\n\nwhere `x.x.x` is the version you want to download.\n\n## Install by Manual Download\n\nTo download the source distribution and/or wheel files, navigate to\n`https://github.com/libcommon/sqlalchemy-dbutils-py/tree/releases/vx.x.x/dist`, where `x.x.x` is the version you want to install,\nand download either via the UI or with a tool like wget. Then to install run:\n\n```bash\npip install \u003cdownloaded file\u003e\n```\n\nDo _not_ change the name of the file after downloading, as Pip requires a specific naming convention for installation files.\n\n## Dependencies\n\n`sqlalchemy-dbutils-py` depends on, and is designed to work with, [SQLAlchemy](https://www.sqlalchemy.org/). Only Python\nversions \u003e= 3.6 are officially supported.\n\n## Getting Started\n\n### Views\n\nThe `view` module exposes a function, `create_view`, for creating (materialized) views that act like ORM tables.\n\n```python\nfrom sqlalchemy import Column, Integer, Text\nfrom sqlalchemy.ext.declarative import declarative_base\nfrom sqlalchemy.sql import select\n\nfrom lc_sqlalchemy_dbutils.view import create_view\n\n\nBaseTable = declarative_base()\n\n\nclass User(BaseTable):\n    id = Column(Integer, primary_key=True)\n    name = Column(Text, nullable=False)\n    email_address = Column(Text, nullable=False)\n\n\n# Creates view named \"vuser_names\" as \"SELECT id, name FROM user\"\nUserNames = create_view(\"vuser_names\", select([User.id, User.name]), BaseTable.metadata)\n```\n\nThe `UserNames` type, which points to the `vuser_names` view in the database, can be used like any other ORM table class.\nFor Postgres databases, the `materialized` parameter to `create_view` can be set to `True` to make a `MATERIALIZED VIEW`. For\nmore information about the difference from a standard SQL view, see https://www.postgresql.org/docs/current/rules-materializedviews.html.\n\n### Database Types\n\nThe `schema` module defines a type to generate database expressions for default datetime/timestamp values.\nA common database design pattern is to use datetime/timestamp columns to track when records are created and/or modified.\nThe `TimestampDefaultExpression` type can be used with the `server_default` parameter to the\n[Column constructor](https://docs.sqlalchemy.org/en/13/core/metadata.html#sqlalchemy.schema.Column.params.server_default).\n\n```python\nfrom sqlalchemy import Column, Integer, Text, TIMESTAMP\nfrom sqlalchemy.ext.declarative import declarative_base\nfrom sqlalchemy.sql import select\n\nfrom lc_sqlalchemy_dbutils.schema import TimestampDefaultExpression\n\n\nBaseTable = declarative_base()\n\n\nclass User(BaseTable):\n    id = Column(Integer, primary_key=True)\n    name = Column(Text, nullable=False)\n    email_address = Column(Text, nullable=False)\n    created_at = Column(TIMESTAMP(True), nullable=False, server_default=TimestampDefaultExpression())\n```\n\nNote the use of `TIMESTAMP(True)`, as the `TimestampDefaultExpression` type will attempt to generate an expression to\nretrieve a UTC timestamp in all cases.\n\n### Database Connection Management\n\nThe `manager` module exposes a class, `DBManager`, for managing database connections and sessions with higher-level methods.\nSimply create an instance of `DBManager` with an RFC-1738 compliant connection URL, and with that instance you can\nconnect to the datbase server, generate ORM [Sessions](https://docs.sqlalchemy.org/en/13/orm/session_api.html#session-and-sessionmaker),\nbuild queries using ORM objects, add and remove records from the active session, and commit or rollback transactions.\n\n```python\nimport sys\n\nfrom sqlalchemy import Column, Integer, Text\nfrom sqlalchemy.ext.declarative import declarative_base\nfrom sqlalchemy.sql import select\n\nfrom lc_sqlalchemy_dbutils.manager import DBManager\n\n\nBaseTable = declarative_base()\n\n\nclass User(BaseTable):\n    id = Column(Integer, primary_key=True)\n    name = Column(Text, nullable=False)\n    email_address = Column(Text, nullable=False)\n\n\ndef main() -\u003e int:\n    # Get commandline arguments\n    config_path_str = sys.argv[1]\n    name_filter = sys.argv[2]\n\n    # Create DB manager from connection URL in config file\n    # and attach MetaData object from BaseTable\n    manager = (DBManager\n               .from_file(config_path_str)\n               .with_metadata(BaseTable.metadata))\n\n    # Connect to database (but don't generate a session yet)\n    manager.connect()\n    # NOTE: connect() is effectively equivalent to\n    # manager.create_engine().create_session_factory(), but it can also\n    # call the bootstrap_db() method to create all tables in the database.\n    # The caveat with using connect() is that you cannot pass specific kwargs\n    # to create_engine() or create_session_factory().\n\n    # Create an active database Session\n    manager.gen_session()\n    # Query the \"user\" table for the name specified on the commandline\n    matching_user = manager.query(User, name=name_filter).first()\n    if matching_user:\n        print(\"Found matching user with name {} (ID: {})\", name_filter, matching_user.id)\n    else:\n        print(\"Did not find matching user with name {}\", name_filter)\n\n    # Close active session and dispose of database engine (which closes all connections)\n    # NOTE: close_engine() automatically calls close_session()\n    manager.close_engine()\n    return 0\n\n\nif __name__ == \"__main__\":\n    main()\n```\n\nThe script above will read the database connection URL from the provided config filepath, connect to the database\nand generate a `Session`, run a query to find the first `User` record where `name` matches the provided name filter,\nand print the results. This is just an (heavily commented) example to show easy session management can be with the `DBManager`\nclass.\n\n## Contributing/Suggestions\n\nContributions and suggestions are welcome! To make a feature request, report a bug, or otherwise comment on existing\nfunctionality, please file an issue. For contributions please submit a PR, but make sure to lint, type-check, and test\nyour code before doing so. Thanks in advance!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flibcommon%2Fsqlalchemy-dbutils-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flibcommon%2Fsqlalchemy-dbutils-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flibcommon%2Fsqlalchemy-dbutils-py/lists"}