Add canonical PostgreSQL client parameter `sslmode` by amotl · Pull Request #202 · crate/sqlalchemy-cratedb

amotl · 2025-02-16T11:39:04Z

Introduction

We need the capability to connect to CrateDB using SSL without verifying the host name.
We also would like to standardize connection parameters to be more like PostgreSQL.

About

This implements sslmode=require to connect to SSL-enabled CrateDB instances without verifying the host name.

Respect sslmode option #197

Preview

uv pip install 'sqlalchemy-cratedb @ https://github.com/crate/sqlalchemy-cratedb/archive/refs/heads/sslmode.zip'

export SQLALCHEMY_CRATEDB_URL=crate://localhost:4200/?sslmode=require

NB: The environment where you are installing this into needs to have Git installed first, see jwodder/versioningit#106.

Backlog

No dedicated software tests yet, which would validate this change thoroughly. This miniature rig can be used to validate it manually.

Docker/Podman: Add basic runnable Docker Compose example for CrateDB+SSL cratedb-examples#825

NB: Please also make yourself heard on this patch and/or acknowledge even when not assigned as reviewers. I am just not doing it because it is not appropriate to slot in more than two of us. /cc @surister, @kneth

seut · 2025-02-17T08:49:04Z

src/sqlalchemy_cratedb/dialect.py

-            if use_ssl:
+            # TODO: Switch to the canonical default `sslmode=prefer` later.
+            sslmode = kwargs.pop("sslmode", "disable")
+            if use_ssl or sslmode in ["allow", "prefer", "require", "verify-ca", "verify-full"]:


If ssl is explicit disabled, sslmode shouldn't have any effect. At least for bwc imho.

Suggested change

if use_ssl or sslmode in ["allow", "prefer", "require", "verify-ca", "verify-full"]:

if use_ssl and sslmode in ["allow", "prefer", "require", "verify-ca", "verify-full"]:

The patch is intended to set the stage to transition to PostgreSQL conventions, so sslmode is intended to be handled in parallel / as an alternative to the ssl option parameter, so we can phase it out in the future.

If that is the intention, then we should deprecate ssl in the docs/changes, and clearly state that sslmode has higher precedence and overrides ssl.

Yes, documentation needs to be added. I will reflect that correspondingly, but did not intend to deprecate the ssl option just yet, maybe just give an outlook about it.

If you think it is the right choice to officially deprecate it, but still keep it just for bwc reasons, sure I can do it timely. I am trying to find out about your opinion on this. Thanks!

At least this should be documented as it may not behave as expected.

imho, it wouldn't make sense to keep 2 different mechanisms in the future, or do you see some value in that?

I agree. Let's just keep it for bwc purposes until we may remove the previous one, possibly paired with a 1.0.0 release?

seut · 2025-02-17T08:50:39Z

src/sqlalchemy_cratedb/dialect.py

+            if use_ssl or sslmode in ["allow", "prefer", "require", "verify-ca", "verify-full"]:
                servers = ["https://" + server for server in servers]
+            if sslmode == "require":
+                kwargs["verify_ssl_cert"] = False


This looks odd as it disables cert verification even that the user did not intend to do that.
If one need to do that, one can set the arg explicitly, or what do I miss?

Currently, verify_ssl_cert can not be defined by the user on behalf of the SQLAlchemy connection string. It's the intention of the patch to unlock that, and make connectivity options adhere to PostgreSQL conventions.

Ok, but this will disable cert verification for everyone who uses require. This sounds not like it is what we really want.

We think sslmode=require is the right option to strictly use an SSL connection, but turn off host name validation on it.

The PostgreSQL docs possibly uses uncommon jargon there, that's why it is sometimes difficult to understand, but of course we may also be wrong on this detail. ¹

Please validate and clarify.

Footnotes

We will try to use a better jargon on our docs, but still adhere to the option values PostgreSQL clients are using here. ↩

Ah ok, I understood it wrongly, thanks for the clarification.

Why would we want to disable hostname validation with sslmode=require ?

Hi. It's for the same reasons PostgreSQL and other network clients talking SSL offer the same option in one way or another.

The specific need is originating from cloud operations when connecting to CrateDB/SSL from internal spots within an K8s cluster. @WalBeh can possibly explain it better.

This implements `sslmode=prefer` to connect to SSL-enabled CrateDB instances without verifying the host name.

amotl · 2025-02-17T11:31:00Z

CHANGES.md


 ## Unreleased
+- Added canonical [PostgreSQL client parameter `sslmode`], implementing
+  `sslmode=prefer` to connect to SSL-enabled CrateDB instances without


Suggested change

`sslmode=prefer` to connect to SSL-enabled CrateDB instances without

`sslmode=require` to connect to SSL-enabled CrateDB instances without

amotl · 2025-04-15T19:20:26Z

src/sqlalchemy_cratedb/dialect.py

            return self.dbapi.connect(servers=servers, **kwargs)
        return self.dbapi.connect(**kwargs)


When evaluating the patch downstream using sqlalchemy-cratedb==0.42.0.dev2, we found that this connection string syntax, omitting the host name, is not supported yet: crate://?sslmode=require.

Currently, it bails out like this:

TypeError: Connection.__init__() got an unexpected keyword argument 'sslmode'

The reason is, as you can observe above, that two different code paths are used here.

This was referenced Feb 16, 2025

Feature request: Installing package from Zip archive jwodder/versioningit#106

Closed

Docker/Podman: Add basic runnable Docker Compose example for CrateDB+SSL crate/cratedb-examples#825

Merged

Respect sslmode option #197

Open

amotl changed the base branch from main to versioningit-git-archive February 16, 2025 19:48

amotl force-pushed the sslmode branch from 75585c8 to 9726b11 Compare February 16, 2025 19:48

amotl requested review from matriv and seut February 16, 2025 20:25

amotl marked this pull request as ready for review February 16, 2025 20:25

Base automatically changed from versioningit-git-archive to main February 17, 2025 08:09

seut reviewed Feb 17, 2025

View reviewed changes

Add canonical PostgreSQL client parameter sslmode

10f275b

This implements `sslmode=prefer` to connect to SSL-enabled CrateDB instances without verifying the host name.

amotl force-pushed the sslmode branch from 9726b11 to 10f275b Compare February 17, 2025 11:30

amotl commented Feb 17, 2025

View reviewed changes

kneth linked an issue Mar 27, 2025 that may be closed by this pull request

Respect sslmode option #197

Open

amotl mentioned this pull request Apr 2, 2025

Preview: Bundle a few improvements #215

Draft

amotl commented Apr 15, 2025

View reviewed changes

amotl mentioned this pull request Apr 16, 2025

CrateDB SSL: Add client programs using sslmode=require and enable testing on CI crate/cratedb-examples#898

Merged

amotl self-assigned this Jan 21, 2026

	if use_ssl or sslmode in ["allow", "prefer", "require", "verify-ca", "verify-full"]:
	if use_ssl and sslmode in ["allow", "prefer", "require", "verify-ca", "verify-full"]:

	`sslmode=prefer` to connect to SSL-enabled CrateDB instances without
	`sslmode=require` to connect to SSL-enabled CrateDB instances without

		return self.dbapi.connect(servers=servers, **kwargs)
		return self.dbapi.connect(**kwargs)

Conversation

amotl commented Feb 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Introduction

About

Preview

Backlog

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amotl Feb 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amotl Feb 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amotl Feb 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amotl Feb 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amotl Feb 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Footnotes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amotl Feb 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

amotl commented Feb 16, 2025 •

edited

Loading

amotl Feb 17, 2025 •

edited

Loading

amotl Feb 17, 2025 •

edited

Loading

amotl Feb 17, 2025 •

edited

Loading

amotl Feb 17, 2025 •

edited

Loading

amotl Feb 17, 2025 •

edited

Loading

amotl Feb 17, 2025 •

edited

Loading