{"id":40210542,"url":"https://github.com/awslabs/aurora-dsql-sqlalchemy","last_synced_at":"2026-01-19T21:06:00.978Z","repository":{"id":302711802,"uuid":"982335097","full_name":"awslabs/aurora-dsql-sqlalchemy","owner":"awslabs","description":"Aurora DSQL dialect for SQLAlchemy","archived":false,"fork":false,"pushed_at":"2026-01-16T01:20:17.000Z","size":171,"stargazers_count":10,"open_issues_count":4,"forks_count":1,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-01-16T01:52:59.037Z","etag":null,"topics":["aurora","aurora-dsql","dsql","postgresql","python","sqlalchemy"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/awslabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-12T18:16:07.000Z","updated_at":"2026-01-16T00:25:48.000Z","dependencies_parsed_at":"2025-07-03T20:54:07.150Z","dependency_job_id":"8fa1d2e2-a6ad-4ff4-ba3e-03f735b2e9b6","html_url":"https://github.com/awslabs/aurora-dsql-sqlalchemy","commit_stats":null,"previous_names":["awslabs/aurora-dsql-sqlalchemy"],"tags_count":3,"template":false,"template_full_name":"amazon-archives/__template_Apache-2.0","purl":"pkg:github/awslabs/aurora-dsql-sqlalchemy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awslabs%2Faurora-dsql-sqlalchemy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awslabs%2Faurora-dsql-sqlalchemy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awslabs%2Faurora-dsql-sqlalchemy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awslabs%2Faurora-dsql-sqlalchemy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/awslabs","download_url":"https://codeload.github.com/awslabs/aurora-dsql-sqlalchemy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awslabs%2Faurora-dsql-sqlalchemy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28585425,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-19T20:45:59.482Z","status":"ssl_error","status_checked_at":"2026-01-19T20:45:41.500Z","response_time":67,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["aurora","aurora-dsql","dsql","postgresql","python","sqlalchemy"],"created_at":"2026-01-19T21:05:58.084Z","updated_at":"2026-01-19T21:06:00.964Z","avatar_url":"https://github.com/awslabs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Amazon Aurora DSQL dialect for SQLAlchemy\n\n[![GitHub](https://img.shields.io/badge/github-awslabs/aurora--dsql--sqlalchemy-blue?logo=github)](https://github.com/awslabs/aurora-dsql-sqlalchemy)\n[![License](https://img.shields.io/badge/license-Apache--2.0-brightgreen)](https://github.com/awslabs/aurora-dsql-sqlalchemy/blob/main/LICENSE)\n[![PyPI - Version](https://img.shields.io/pypi/v/aurora-dsql-sqlalchemy)](https://pypi.org/project/aurora-dsql-sqlalchemy)\n[![Discord chat](https://img.shields.io/discord/1435027294837276802.svg?logo=discord)](https://discord.com/invite/nEF6ksFWru)\n\n## Introduction\n\nThe Aurora DSQL dialect for SQLAlchemy provides integration between SQLAlchemy ORM and Aurora DSQL. This dialect enables\nPython applications to leverage SQLAlchemy's powerful object-relational mapping capabilities while taking advantage of\nAurora DSQL's distributed architecture and high availability.\n\n## Sample Application\n\nThere is an included sample application in [examples/pet-clinic-app](https://github.com/awslabs/aurora-dsql-sqlalchemy/tree/main/examples/pet-clinic-app) that shows how to use Aurora DSQL\nwith SQLAlchemy. To run the included example please refer to the [sample README](https://github.com/awslabs/aurora-dsql-sqlalchemy/tree/main/examples/pet-clinic-app#readme).\n\n## Prerequisites\n\n- Python 3.10 or higher\n- SQLAlchemy 2.0.0 or higher\n- One of the following drivers:\n  - psycopg 3.2.0 or higher\n  - psycopg2 2.9.0 or higher\n\n## Installation\n\nInstall the packages using the commands below:\n\n```bash\npip install aurora-dsql-sqlalchemy\n\n# driver installation (in case you opt for psycopg)\n# DO NOT use pip install psycopg-binary\npip install \"psycopg[binary]\"\n\n# driver installation (in case you opt for psycopg2)\npip install psycopg2-binary\n```\n\n## Dialect Configuration\n\nAfter installation, you can connect to an Aurora DSQL cluster using the `create_dsql_engine` helper function:\n\n```python\nfrom aurora_dsql_sqlalchemy import create_dsql_engine\n\nengine = create_dsql_engine(\n    host=\"\u003cCLUSTER_ENDPOINT\u003e\",\n    user=\"\u003cCLUSTER_USER\u003e\",\n    driver=\"psycopg\",  # or \"psycopg2\"\n)\n```\n\nThe helper function handles:\n- IAM authentication via the Aurora DSQL Python Connector\n- SSL configuration with certificate verification\n- Direct SSL negotiation optimization (when supported by libpq \u003e= 17)\n- Connection pooling with sensible defaults\n\nFor more control, you can customize additional parameters:\n\n```python\nengine = create_dsql_engine(\n    host=\"\u003cCLUSTER_ENDPOINT\u003e\",\n    user=\"\u003cCLUSTER_USER\u003e\",\n    driver=\"psycopg\",\n    sslrootcert=\"./root.pem\",  # or \"system\" to use system CA store\n    pool_size=10,\n    max_overflow=20,\n)\n```\n\n**Note:** Each connection has a maximum duration limit. See the `Maximum connection duration` time limit in the [Cluster quotas and database limits in Amazon Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/CHAP_quotas.html) page.\n\n## Best Practices\n\n### Primary Key Generation\n\nSQLAlchemy applications connecting to Aurora DSQL should use UUID for the primary key column since auto-incrementing integer keys (sequences or serial) are not supported in DSQL. The following column definition can be used to define an UUID primary key column.\n\n```python\nColumn(\n    \"id\",\n    UUID(as_uuid=True),\n    primary_key=True,\n    default=text('gen_random_uuid()')\n)\n```\n\n`gen_random_uuid()` returns an UUID version 4 as the default value.\n\n## Dialect Features and Limitations\n\n- **Column Metadata**: The dialect fixes an issue related to `\"datatype json not supported\"` when calling SQLAlchemy's metadata() API.\n- **Foreign Keys**: Aurora DSQL does not support foreign key constraints. The dialect disables these constraints, but be aware that referential integrity must be maintained at the application level.\n- **Index Creation**: Aurora DSQL does not support `CREATE INDEX` or `CREATE UNIQUE INDEX` commands. The dialect instead uses `CREATE INDEX ASYNC` and `CREATE UNIQUE INDEX ASYNC` commands. See the [Asynchronous indexes in Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-create-index-async.html) page for more information.\n\n  The following parameters are used for customizing index creation\n\n  - `auroradsql_include` - specifies which columns to includes in an index by using the `INCLUDE` clause:\n\n    ```python\n    Index(\n        \"include_index\",\n        table.c.id,\n        auroradsql_include=['name', 'email']\n    )\n    ```\n\n    Generated SQL output:\n\n    ```sql\n    CREATE INDEX ASYNC include_index ON table (id) INCLUDE (name, email)\n    ```\n\n  - `auroradsql_nulls_not_distinct` - controls how `NULL` values are treated in unique indexes:\n\n    ```python\n    Index(\n        \"idx_name\",\n        table.c.column,\n        unique=True,\n        auroradsql_nulls_not_distinct=True\n    )\n    ```\n\n    Generated SQL output:\n\n    ```sql\n    CREATE UNIQUE INDEX idx_name ON table (column) NULLS NOT DISTINCT\n    ```\n\n- **Index Interface Limitation**: `NULLS FIRST | LAST` - SQLalchemy's Index() interface does not have a way to pass in the sort order of null and non-null columns. (Default: `NULLS LAST`). If `NULLS FIRST` is required, please refer to the syntax as specified in [Asynchronous indexes in Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-create-index-async.html) and execute the corresponding SQL query directly in SQLAlchemy.\n- **Psycopg (psycopg3) support**: When connecting to DSQL using the default postgresql dialect with psycopg, an unsupported `SAVEPOINT` error occurs. The DSQL dialect addresses this issue by disabling the `SAVEPOINT` during connection.\n\n## Developer instructions\n\nInstructions on how to build and test the dialect are available in the [Developer Instructions](https://github.com/awslabs/aurora-dsql-sqlalchemy/tree/main/aurora_dsql_sqlalchemy#readme).\n\n## Security\n\nSee [CONTRIBUTING](https://github.com/awslabs/aurora-dsql-sqlalchemy/blob/main/CONTRIBUTING.md#security-issue-notifications) for more information.\n\n## License\n\nThis project is licensed under the Apache-2.0 License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawslabs%2Faurora-dsql-sqlalchemy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fawslabs%2Faurora-dsql-sqlalchemy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawslabs%2Faurora-dsql-sqlalchemy/lists"}