Support credentials and SSL with SQLAlchemy via HTTP/DB URIs

[amotl]

Hi there,

in order to resolve crate/sqlalchemy-cratedb#116, this patch improves some bits when connecting to CrateDB, specifically in scenarios when preferring to connect using a SQLAlchemy DB URI instead of separate connect_args. This is convenient for programs which can be configured using a single DB URI as database connection option, like Apache Superset.

• 064e341: Accept credentials within the HTTP URI. Example: http://foo:[email protected]:4200/
• 52e715d: Enable SSL using SQLAlchemy DB URI. Example: crate://cratedb.example.org/?ssl=true

With kind regards,
Andreas.

P.S.: 30fc28e, 93f33b9 and 160aa1e are only maintenance commits without feature significance.

[mfussenegger]

P.S.: 30fc28e, 93f33b9 and 160aa1e are only maintenance commits without feature significance

Would be cool to split maintenance stuff and features into separate PRs in the future. It is much easier to review that way. Github doesn't support adding suggestions when looking at an individual commit.

[mfussenegger]

The changes should probably also get documented somewhere in

crate-python/docs/sqlalchemy.rst

Lines 47 to 129 in 1b1136a

	An SQLAlchemy database is represented by special type of *Uniform Resource
	Locator* (URL) called a `database URL`_.
	The simplest database URL for CrateDB looks like this::
	crate://<HOST>
	Here, ``<HOST>`` is the node *host string*.
	A host string looks like this::
	<HOST_ADDR>:<PORT>
	Here, ``<HOST_ADDR>`` is the hostname or IP address of the CrateDB node and
	``<PORT>`` is a valid `psql.port`_ number.
	Example host strings:
	- ``localhost:4200``
	- ``crate-1.vm.example.com:4200``
	- ``198.51.100.1:4200``
	.. TIP::
	If ``<HOST>`` is blank (i.e. just ``crate://``) then ``localhost:4200`` will
	be assumed.
	Getting a connection
	--------------------
	Create an engine
	................
	You can connect to CrateDB using the ``create_engine`` method. This method
	takes a `database URL`_.
	Import the ``sa`` module, like so:
	>>> import sqlalchemy as sa
	To connect to ``localhost:4200``, you can do this::
	>>> engine = sa.create_engine('crate://')
	To connect to ``crate-1.vm.example.com:4200``, you would do this:
	>>> engine = sa.create_engine('crate://crate-1.vm.example.com:4200')
	If your CrateDB cluster has multiple nodes, however, we recommend that you
	configure all of them. You can do that by specifying the ``crate://`` database
	URL and passing in a list of :ref:`host strings <database-urls>` passed using
	the ``connect_args`` argument, like so::
	>>> engine = sa.create_engine('crate://', connect_args={
	... 'servers': ['198.51.100.1:4200', '198.51.100.2:4200']
	... })
	When you do this, the Database API layer will use its :ref:`round-robin
	<multiple-nodes>` implementation.
	The client validates `SSL server certificates`_ by default. For further
	adjusting this behaviour, SSL verification options can be passed in by using
	the ``connect_args`` dictionary. For example, use ``ca_cert`` for providing
	a path to the CA certificate used for signing the server certificate::
	>>> engine = sa.create_engine(
	... 'crate://',
	... connect_args={
	... 'servers': ['198.51.100.1:4200', '198.51.100.2:4200'],
	... 'ca_cert': '<PATH_TO_CA_CERT>',
	... }
	... )
	In order to disable SSL verification, use ``verify_ssl_cert = False``, like::
	>>> engine = sa.create_engine(
	... 'crate://',
	... connect_args={
	... 'servers': ['198.51.100.1:4200', '198.51.100.2:4200'],
	... 'verify_ssl_cert': False,
	... }
	... )

Otherwise I think this looks good

[amotl]

The changes should probably also get documented somewhere.

Thank you for your attention. I've just added 8fa85a5 and c08ecd1, intending to improve the corresponding documentation about the new capabilities to connect by URI.