{"id":34114167,"url":"https://github.com/jason810496/pgmq-sqlalchemy","last_synced_at":"2026-04-02T02:08:37.421Z","repository":{"id":249507668,"uuid":"823736310","full_name":"jason810496/pgmq-sqlalchemy","owner":"jason810496","description":"More flexible PGMQ Postgres extension Python client that using SQLAlchemy ORM, supporting both async and sync engines, sessionmakers or built from dsn.","archived":false,"fork":false,"pushed_at":"2026-01-07T13:21:14.000Z","size":660,"stargazers_count":26,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-08T08:49:04.798Z","etag":null,"topics":["message-queue","pgmq","postgresql","python-package","python-postgresql","sqlalchemy"],"latest_commit_sha":null,"homepage":"https://pgmq-sqlalchemy.readthedocs.io/en/latest/","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/jason810496.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-07-03T15:52:39.000Z","updated_at":"2026-01-08T01:48:32.000Z","dependencies_parsed_at":"2024-08-03T16:59:28.835Z","dependency_job_id":"e06c8fb6-f25d-4e46-bb56-6a3030c8be5d","html_url":"https://github.com/jason810496/pgmq-sqlalchemy","commit_stats":null,"previous_names":["jason810496/pgmq-sqlalchemy"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/jason810496/pgmq-sqlalchemy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jason810496%2Fpgmq-sqlalchemy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jason810496%2Fpgmq-sqlalchemy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jason810496%2Fpgmq-sqlalchemy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jason810496%2Fpgmq-sqlalchemy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jason810496","download_url":"https://codeload.github.com/jason810496/pgmq-sqlalchemy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jason810496%2Fpgmq-sqlalchemy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31294399,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T01:43:37.129Z","status":"online","status_checked_at":"2026-04-02T02:00:08.535Z","response_time":89,"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":["message-queue","pgmq","postgresql","python-package","python-postgresql","sqlalchemy"],"created_at":"2025-12-14T19:27:22.113Z","updated_at":"2026-04-02T02:08:37.414Z","avatar_url":"https://github.com/jason810496.png","language":"Python","readme":"[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n[![PyPI - Version](https://img.shields.io/pypi/v/pgmq-sqlalchemy.svg)](https://pypi.org/project/pgmq-sqlalchemy/)\n[![PyPI - Downloads](https://img.shields.io/pypi/dm/pgmq-sqlalchemy.svg)](https://pypi.org/project/pgmq-sqlalchemy/)\n[![PyPI - License](https://img.shields.io/pypi/l/pgmq-sqlalchemy.svg)](https://github.com/jason810496/pgmq-sqlalchemy/blob/main/LICENSE)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pgmq-sqlalchemy.svg)](https://pypi.python.org/pypi/pgmq-sqlalchemy)\n[![codecov](https://codecov.io/gh/jason810496/pgmq-sqlalchemy/graph/badge.svg?token=C5ZVZCW7TE)](https://codecov.io/gh/jason810496/pgmq-sqlalchemy)\n[![Documentation Status](https://readthedocs.org/projects/pgmq-sqlalchemy/badge/?version=latest)](https://pgmq-sqlalchemy.readthedocs.io/en/latest/?badge=latest)\n\n\n# pgmq-sqlalchemy\n\nMore flexible [PGMQ Postgres extension](https://github.com/tembo-io/pgmq) Python client that using **sqlalchemy ORM**, supporting both **async** and **sync** `engines`, `sessionmakers` or built from `dsn`.\n\n## Table of Contents\n\n* [pgmq-sqlalchemy](#pgmq-sqlalchemy)\n   * [Features](#features)\n   * [Installation](#installation)\n   * [Getting Started](#getting-started)\n      * [Postgres Setup](#postgres-setup)\n      * [Usage](#usage)\n      * [Transaction Usage](#transaction-usage)\n      * [FastAPI Pub/Sub Example with tests](#fastapi-pubsub-example)\n   * [Issue/ Contributing / Development](#issue-contributing--development)\n   * [TODO](#todo)\n\n\n## Features\n\n- Supports **async** and **sync** `engines` and `sessionmakers`, or built from `dsn`.\n- Supports **all postgres DBAPIs supported by sqlalchemy**.\n    \u003e e.g. `psycopg`, `psycopg2`, `asyncpg` .. \u003cbr\u003e\n    \u003e See [SQLAlchemy Postgresql Dialects](https://docs.sqlalchemy.org/en/20/dialects/postgresql.html)\n- **Transaction-friendly operations** via the `op` module for combining PGMQ with your business logic in the same transaction.\n- [Fully tested across all **supported DBAPIs** in both **async** and **sync** modes](https://github.com/jason810496/pgmq-sqlalchemy/actions/workflows/codecov.yml).\n- Battle-tested with **[real-world FastAPI Pub/Sub examples](./examples/fastapi_pub_sub/README.md)** and **[corresponding tests](https://github.com/jason810496/pgmq-sqlalchemy/actions/workflows/examples.yml)**.\n\n## Installation\n\nInstall with pip:\n\n```bash\npip install pgmq-sqlalchemy\n```\n\nInstall with additional DBAPIs packages:\n\n```bash\npip install \"pgmq-sqlalchemy[asyncpg]\"\npip install \"pgmq-sqlalchemy[psycopg2-binary]\"\n# pip install \"pgmq-sqlalchemy[postgres-python-driver]\"\n```\n\n## Getting Started\n\n### Postgres Setup\n\nPrerequisites: **Postgres** with **PGMQ** extension installed. \u003cbr\u003e\nFor quick setup: \n```bash\ndocker run -d --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 quay.io/tembo/pg16-pgmq:latest\n```\n\u003e For more information, see [PGMQ](https://github.com/tembo-io/pgmq)\n\n### Usage\n\n\u003e [!NOTE]  \n\u003e Check [pgmq-sqlalchemy Document](https://pgmq-sqlalchemy.readthedocs.io/en/latest/) for more examples and detailed usage.\n\n\nFor `dispatcher.py`:\n```python\nfrom typing import List\nfrom pgmq_sqlalchemy import PGMQueue\n\npostgres_dsn = 'postgresql://postgres:postgres@localhost:5432/postgres'\n\npgmq = PGMQueue(dsn=postgres_dsn)\npgmq.create_queue('my_queue')\n\nmsg = {'key': 'value', 'key2': 'value2'}\nmsg_id:int = pgmq.send('my_queue', msg)\n\n# could also send a list of messages\nmsg_ids:List[int] = pgmq.send_batch('my_queue', [msg, msg])\n```\n\nFor `consumer.py`:\n```python\nfrom pgmq_sqlalchemy import PGMQueue\nfrom pgmq_sqlalchemy.schema import Message\n\npostgres_dsn = 'postgresql://postgres:postgres@localhost:5432/postgres'\n\npgmq = PGMQueue(dsn=postgres_dsn)\n\n# read a single message\nmsg:Message = pgmq.read('my_queue')\n\n# read a batch of messages\nmsgs:List[Message] = pgmq.read_batch('my_queue', 10)\n```\n\nFor `monitor.py`:\n```python\nfrom pgmq_sqlalchemy import PGMQueue\nfrom pgmq_sqlalchemy.schema import QueueMetrics\n\npostgres_dsn = 'postgresql://postgres:postgres@localhost:5432/postgres'\n\npgmq = PGMQueue(dsn=postgres_dsn)\n\n# get queue metrics\nmetrics:QueueMetrics = pgmq.metrics('my_queue')\nprint(metrics.queue_length)\nprint(metrics.total_messages)\n```\n\n### Transaction Usage\n\nUse the `op` module to combine PGMQ operations with your business logic in a single transaction:\n\n```python\nfrom sqlalchemy import create_engine, text\nfrom sqlalchemy.orm import sessionmaker\nfrom pgmq_sqlalchemy import op\n\nengine = create_engine('postgresql://postgres:postgres@localhost:5432/postgres')\nSessionLocal = sessionmaker(bind=engine)\n\nwith SessionLocal() as session:\n    try:\n        # Create queue\n        op.create_queue('orders_queue', session=session, commit=False)\n        \n        # Insert order into your database\n        session.execute(\n            text(\"INSERT INTO orders (user_id, total) VALUES (:user_id, :total)\"),\n            {\"user_id\": 123, \"total\": 99.99}\n        )\n        \n        # Send message to queue\n        op.send(\n            'orders_queue',\n            {'user_id': 123, 'action': 'process_order'},\n            session=session,\n            commit=False\n        )\n        \n        # Commit everything together\n        session.commit()\n    except Exception as e:\n        session.rollback()\n        print(f\"Transaction failed: {e}\")\n```\n\n\u003e See [Transaction Usage Documentation](https://pgmq-sqlalchemy.readthedocs.io/en/latest/getting-started.html#using-transaction-friendly-operations) for more examples.\n\n### FastAPI Pub/Sub Example with tests\n\nSee the [FastAPI Pub/Sub Example](./examples/fastapi_pub_sub/README.md) for a complete example of using `pgmq-sqlalchemy` in a FastAPI application with asynchronous message consumption and tests.\n\n## Issue/ Contributing / Development \n\nWelcome to open an issue or pull request ! \u003cbr\u003e\nSee [`Development` on Online Document](https://pgmq-sqlalchemy.readthedocs.io/en/latest/) or [CONTRIBUTING.md](.github/CONTRIBUTING.md) for more information.\n\n## TODO\n\n- [ ] [Alembic](https://alembic.sqlalchemy.org/en/latest/) compatible migration scripts for PGMQ extension and schema setup, upgrade, downgrade.\n- [ ] Compatibility tests with PGMQ across different PGMQ versions.\n- [ ] More examples\n- [ ] Smoothen contributing process with custom script for one step setup\n- [ ] Mypy strict type checking\n- [ ] Enable more ruff rules\n- [ ] Drop Python 3.9 support in next minor release","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjason810496%2Fpgmq-sqlalchemy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjason810496%2Fpgmq-sqlalchemy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjason810496%2Fpgmq-sqlalchemy/lists"}