# `sqlalchemy-rdsiam`
SQLAlchemy dialect to connect to Amazon RDS instances with IAM authentication.
The following are supported:
- Amazon RDS PostgreSQL, with `psycopg2`.
- Amazon RDS PostgreSQL, with `asyncpg`.
SQLAlchemy 1.3, 1.4 and 2.0 are supported.
## Background
Amazon RDS is managed database service on AWS, which provides the ability
to connect to database instances with
[IAM authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.Connecting.html)
instead of passwords. AWS SDKs or the AWS CLI can be used to generate a
connection token, valid for 15 minutes, and based on an Amazon IAM identity.
With SQLAlchemy, it is possible to use IAM authentication using one of the
following options:
- Using an event handler and the
[`do_connect` event](https://docs.sqlalchemy.org/en/14/core/engines.html#generating-dynamic-authentication-tokens).
- Using a
[custom connection factory](https://docs.sqlalchemy.org/en/14/core/engines.html#use-the-connect-args-dictionary-parameter).
Both options require modifying the codebase to either inject the event handler or
the custom connection factory. With many open-source tools, this requires
maintaining a fork. This repository provides a set of _dialects_ which can be
installed and used directly in any SQLAlchemy codebase instead.
## Getting Started
- Install the Python package:
```sh
pip install sqlalchemy-rdsiam
```
- Use a connection string with scheme corresponding to the target PostgreSQL library, and
leave out the password. For instance:
```sh
postgresql+psycopg2rdsiam://username@host/dbname
postgresql+asyncpgrdsiam://username@host/dbname
```
> **Note**: if a password is provided, it will be ignored.
- Run with an IAM identity that has IAM permissions to connect to the database.
See
[IAM authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.Connecting.html).
## Additional Configuration
### AWS Region
The default region in the environment is used. To access a database in a
different region without changing your environment, pass the query parameter
`aws_region_name` in the connection string:
```sh
postgresql+psycopg2rdsiam://username@host/dbname?aws_region_name=us-east-2
```
### Creating the Database If It Doesn't Exists
The dialect supports optionally creating the database upon connection if it
doesn't exist. This is disabled by default. To create the database if it doesn't
exist, set the query parameter `create_db_if_not_exists` to `true`:
```sh
postgresql+psycopg2rdsiam://username@host/dbname?create_db_if_not_exists=true
```
> **Note**: the role used must have permissions to create databases.
### Set `sslrootcert` to the Amazon RDS Certificate Bundle
[Amazon RDS TLS certificates](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.SSL.html)
are signed by Amazon certificate authorities, and the `sslrootcert` PostgreSQL
argument must be used in order to verify the certificate chain when connecting
to the instance. In some cases, it can be useful to directly get the CA bundle
along with the package for testing, or to streaming provisioning. To this end,
the CA bundle is automatically downloaded when installing the Python package,
and you can opt-in to use it directly.
> **Note**: make sure this is in line with your **security posture requirements**
> first.
The package can directly set `sslrootcert` to the certificate bundle for all
Amazon RDS regions. This is disabled by default. To do so, set the query
parameter `rds_sslrootcert` to `true`:
```sh
postgresql+psycopg2rdsiam://username@host/dbname?rds_sslrootcert=true
```
You still need to set `sslmode` - for instance, with `sslmode=verify-full`:
```sh
postgresql+psycopg2rdsiam://username@host/dbname?rds_sslrootcert=true&sslmode=verify-full
```
See [SSL Support](https://www.postgresql.org/docs/current/libpq-ssl.html)
for additional details.
## Contributing
See [Contributing](CONTRIBUTING.md).
## License
See [License](LICENSE).
Raw data
{
"_id": null,
"home_page": "https://github.com/cisco-open/sqlalchemy-rdsiam",
"name": "sqlalchemy-rdsiam",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/99/eb/5d5335f28b0acbe4cf9cbd2e62da9ab98945449507306534a0652fb5b9cd/sqlalchemy-rdsiam-1.0.2.tar.gz",
"platform": null,
"description": "# `sqlalchemy-rdsiam`\n\nSQLAlchemy dialect to connect to Amazon RDS instances with IAM authentication.\n\nThe following are supported:\n\n- Amazon RDS PostgreSQL, with `psycopg2`.\n- Amazon RDS PostgreSQL, with `asyncpg`.\n\nSQLAlchemy 1.3, 1.4 and 2.0 are supported.\n\n## Background\n\nAmazon RDS is managed database service on AWS, which provides the ability\nto connect to database instances with\n[IAM authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.Connecting.html)\ninstead of passwords. AWS SDKs or the AWS CLI can be used to generate a\nconnection token, valid for 15 minutes, and based on an Amazon IAM identity.\n\nWith SQLAlchemy, it is possible to use IAM authentication using one of the\nfollowing options:\n\n- Using an event handler and the\n [`do_connect` event](https://docs.sqlalchemy.org/en/14/core/engines.html#generating-dynamic-authentication-tokens).\n- Using a\n [custom connection factory](https://docs.sqlalchemy.org/en/14/core/engines.html#use-the-connect-args-dictionary-parameter).\n\nBoth options require modifying the codebase to either inject the event handler or\nthe custom connection factory. With many open-source tools, this requires\nmaintaining a fork. This repository provides a set of _dialects_ which can be\ninstalled and used directly in any SQLAlchemy codebase instead.\n\n## Getting Started\n\n- Install the Python package:\n\n ```sh\n pip install sqlalchemy-rdsiam\n ```\n\n- Use a connection string with scheme corresponding to the target PostgreSQL library, and\n leave out the password. For instance:\n\n ```sh\n postgresql+psycopg2rdsiam://username@host/dbname\n postgresql+asyncpgrdsiam://username@host/dbname\n ```\n\n > **Note**: if a password is provided, it will be ignored.\n\n- Run with an IAM identity that has IAM permissions to connect to the database.\n See\n [IAM authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.Connecting.html).\n\n## Additional Configuration\n\n### AWS Region\n\nThe default region in the environment is used. To access a database in a\ndifferent region without changing your environment, pass the query parameter\n`aws_region_name` in the connection string:\n\n```sh\npostgresql+psycopg2rdsiam://username@host/dbname?aws_region_name=us-east-2\n```\n\n### Creating the Database If It Doesn't Exists\n\nThe dialect supports optionally creating the database upon connection if it\ndoesn't exist. This is disabled by default. To create the database if it doesn't\nexist, set the query parameter `create_db_if_not_exists` to `true`:\n\n```sh\npostgresql+psycopg2rdsiam://username@host/dbname?create_db_if_not_exists=true\n```\n\n> **Note**: the role used must have permissions to create databases.\n\n### Set `sslrootcert` to the Amazon RDS Certificate Bundle\n\n[Amazon RDS TLS certificates](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.SSL.html)\nare signed by Amazon certificate authorities, and the `sslrootcert` PostgreSQL\nargument must be used in order to verify the certificate chain when connecting\nto the instance. In some cases, it can be useful to directly get the CA bundle\nalong with the package for testing, or to streaming provisioning. To this end,\nthe CA bundle is automatically downloaded when installing the Python package,\nand you can opt-in to use it directly.\n\n> **Note**: make sure this is in line with your **security posture requirements**\n> first.\n\nThe package can directly set `sslrootcert` to the certificate bundle for all\nAmazon RDS regions. This is disabled by default. To do so, set the query\nparameter `rds_sslrootcert` to `true`:\n\n```sh\npostgresql+psycopg2rdsiam://username@host/dbname?rds_sslrootcert=true\n```\n\nYou still need to set `sslmode` - for instance, with `sslmode=verify-full`:\n\n```sh\npostgresql+psycopg2rdsiam://username@host/dbname?rds_sslrootcert=true&sslmode=verify-full\n```\n\nSee [SSL Support](https://www.postgresql.org/docs/current/libpq-ssl.html)\nfor additional details.\n\n## Contributing\n\nSee [Contributing](CONTRIBUTING.md).\n\n## License\n\nSee [License](LICENSE).\n",
"bugtrack_url": null,
"license": "",
"summary": "SQLAlchemy dialects to connect to Amazon RDS instances with IAM authentication",
"version": "1.0.2",
"project_urls": {
"Homepage": "https://github.com/cisco-open/sqlalchemy-rdsiam"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "52dce146383fd7b7ad30de3a96a73f03591a680513278755be3115ec8147e152",
"md5": "c016c09449eaf924511eb6a036893214",
"sha256": "9fc7540261132b11209e4d0dd8b136b78ae7a72d6c37157b5e7cc8916c32dbf8"
},
"downloads": -1,
"filename": "sqlalchemy_rdsiam-1.0.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "c016c09449eaf924511eb6a036893214",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.6",
"size": 97876,
"upload_time": "2023-09-12T15:43:09",
"upload_time_iso_8601": "2023-09-12T15:43:09.323613Z",
"url": "https://files.pythonhosted.org/packages/52/dc/e146383fd7b7ad30de3a96a73f03591a680513278755be3115ec8147e152/sqlalchemy_rdsiam-1.0.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "99eb5d5335f28b0acbe4cf9cbd2e62da9ab98945449507306534a0652fb5b9cd",
"md5": "03218188da0dfbf70c3bc368f549e360",
"sha256": "e9e4b2e14469e94c057b3690369d510543fb0a2b03fd9f655ed6b4c12fac7c54"
},
"downloads": -1,
"filename": "sqlalchemy-rdsiam-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "03218188da0dfbf70c3bc368f549e360",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 18183,
"upload_time": "2023-09-12T15:43:10",
"upload_time_iso_8601": "2023-09-12T15:43:10.577681Z",
"url": "https://files.pythonhosted.org/packages/99/eb/5d5335f28b0acbe4cf9cbd2e62da9ab98945449507306534a0652fb5b9cd/sqlalchemy-rdsiam-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-12 15:43:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cisco-open",
"github_project": "sqlalchemy-rdsiam",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "sqlalchemy-rdsiam"
}
JSON
