Add config SQLALCHEMY_DATABASE_URL as an alias to SQLALCHEMY_DATABASE_URI

[greyli]

Although SQLALCHEMY_DATABASE_URI is technically correct here, I propose to add SQLALCHEMY_DATABASE_URL as an alias for it for the following reasons:

• "URL" is a more user-friendly word, it's widely known and used. Some people feel confused with the "URI" name (like #330), some people may even misuse the URL one.
• A common use case when setting this variable is to read the default value from an env var named DATABASE_URL (#66 even wants to make this config read from DATABASE_URL internally):

app.config['SQLALCHEMY_DATABASE_URI'] = os.getenv('DATABASE_URL', ...)

• In the SQLAlchemy docs, URL is used over URI:

The create_engine() function produces an Engine object based on a URL. These URLs follow RFC-1738, and ...The typical form of a database URL is:

• The arg name for this config in create_engine() is url instead of uri.

We may don't need to remove the old one or add any deprecated warning, just making the old one an alias, then updating the docs is fine.

If possible, changing it to SQLALCHEMY_DATABASE_URL will be a better option (add a warning for the old one).

I'll make a PR if you think it makes sense.

[ThiefMaster]

I think it'll cause more confusion than do good. Maybe warn if the other one is set instead?

[greyli]

Yeah, it will be better if we could change it to SQLALCHEMY_DATABASE_URL (start with a warning and then remove the old one in 4.0) instead of just adding an alias.

[ThiefMaster]

I meant keeping URI and warning if URL is used

[greyli]

Em... I think the URL one is better (with the reasons listed above).

[caffeinatedMike]

I have to agree with @ThiefMaster here. At this point URL would cause more confusion. I'm used to URI and moving all my projects to URL would be more of a nuisance.

[ThiefMaster]

Indeed - that's why I'd show a warning pointing towards the correct spelling if SQLALCHEMY_DATABASE_URL is set. Could even be an exception while in debug mode.

[caffeinatedMike]

Absolutely. And digging further into the differences in terminology (link) I found a simple difference that re-enforces the use of URI for SQLAlchemy connections.

In URL, the scheme must be a protocol like HTTP, FTP, HTTPS, etc. | In URI, the scheme may be anything like a protocol, specification, name, etc.

SQLAlchemy "URL"s provide db flavors, as well as drivers in place of simple protocols.

So, my stance remains: stick to URI because it more closely aligns with the purpose of the connections strings.

[davidism]

What's really unfortunate is that SQLAlchemy itself has URL objects, and the argument to create_engine is url. For 3.0 I'm working on how binds are specified, where SQLALCHEMY_DATABASE_URI is an alias for SQLALCHEMY_ENGINE_OPTIONS["url"], which is an alias for SQLALCHEMY_BINDS[None]["url"].

If we have two config keys URI and URL, you might set SQLALCHEMY_DATABASE_URI in your default config, and then override it with SQLALCHEMY_DATABASE_URL. Maybe it would be ok to error out if both are set, but I don't think I want to allow one to override the other.