Extract dialects out of the core

[sdepold]

In order to support additional dialects more easily in the future, we want to pull the dialect specific files out of the core and move them into dedicated npm modules.

Relates to sequelize/meetings#2

Current Progress

Beta Give feedback

1. Decide on the API
2. Can we have the same set of tests for all built-in dialects?
3. feat(mariadb)!: move mariadb to the @sequelize/mariadb package #17198
   +0
4. feat(mssql)!: move mssql to the @sequelize/mssql package #17206
   +0
5. feat(mysql)!: move mysql to the @sequelize/mysql package #17202
   +0
6. feat: move postgres to the @sequelize/postgres package #17190
   +0
7. feat(sqlite)!: move sqlite to the @sequelize/sqlite package #17205
   +0
8. feat(snowflake)!: move snowflake to the @sequelize/snowflake package #17207
   +0
9. feat(ibmi)!: move ibmi to the @sequelize/ibmi package #17209
   +0
10. feat(db2): move db2 to the @sequelize/db2 package #17197
    +0
11. meta: rename ./dialects/abstract to ./abstract-dialect #17216
    +0
12. feat: re-add the ability to override the connector library #17219
    +0
13. feat: type options per dialect, add "url" option, remove alternative Sequelize constructor signatures #17222
    +0
14. fix: parse the url option based on the dialect #17252
    +0
15. document how to connect to each database + process for new dialects website#742
    +0
16. feat: rename @sequelize/sqlite to @sequelize/sqlite3, @sequelize/ibmi to @sequelize/db2-ibmi, ban conflicting options #17269
    +0
17. Require the dialect class to be provided instead of a dialect name
18. Add a README.md to all packages

[ephys]

We're finally working on this

The high level plan is to have individual packages for each dialect, such as @sequelize/postgres, @sequelize/mariadb, @sequelize/oracle, etc

Each package will provide all the dialect-specific code. This means that it will be much easier for the community to create third-party dialect packages, even though they would currently still need to use many unstable internal APIs. This second part is something we'll improve in the future by providing a clean public dialect API, such as @sequelize/core/dialect-toolbox

Each package will also include the relevant connector library (pg, mariadb, tedious, etc). Users won't have to figure out which version should be installed anymore.

Finally, the dialect-specific options will be better checked in both typing and runtime checks

When initializing Sequelize, users will now need to provide the dialect package instead of a dialect name. Here is what it would look like:

import { PostgresDialect } from '@sequelize/postgres';

new Sequelize({
  dialect: PostgresDialect,
  // dialect-specific options
  username: 'demo',
  password: 'demo',
  native: true,

  // sequelize options
  pool: { max: 5 },
});

In this version, all options are provided to Sequelize itself. Sequelize then picks the ones that are dialect specific and gives them to the dialect instance when initializing it.

The dialectOptions option would be removed. All dialect-specific options would be moved to the top-level option bag.

The dialect would expose a static method called getSupportedOptions that is used to:

• Make sure all user-provided options are supported by either Sequelize or the dialect
• Make sure no dialect-specific option conflicts with Sequelize

Because credentials are dialect-specific, we need to change the signature of the constructor to only accept an option bag. The old new Sequelize(database, username, password) one does not make sense for some dialects.

[jdgriffith]

I believe this is a great direction to take this. Will this apply to v6 or is this a v7 initiative?

[WikiRik]

This is a v7 initiative, and will also continue on in v8 most likely

[jdgriffith]

v7 I think* has been worked for the last two years if I'm not mistaken. Do we think v7 will reach a stable release in the foreseeable future?

[WikiRik]

We've discussed the release of v7 today with our core team. The v7 alphas are already quite stable. After the initial extraction of dialects we want to move into a beta phase for v7 while we work on updating CLI and help bigger third-party packages migrate to v7. During that beta phase we will be more careful about breaking changes that we add.
See more here; https://github.com/sequelize/meetings/wiki/Meeting-2024%E2%80%9003%E2%80%9022#latest-v7-release-plan

Doing this work on v6 is counterproductive and requires a lot more work for us.

[ephys]

@WikiRik for the task about updating the documentation, note that we now have this project to keep track of which PRs still need to be documented: https://github.com/orgs/sequelize/projects/5

[ephys]

If we're going to add support for better-sqlite3, maybe we should rename the @sequelize/sqlite to @sequelize/sqlite3 to reflect the name of the library that is used by it. We'd then be able to add @sequelize/better-sqlite3

[WikiRik]

If we're going to add support for better-sqlite3, maybe we should rename the @sequelize/sqlite to @sequelize/sqlite3 to reflect the name of the library that is used by it. We'd then be able to add @sequelize/better-sqlite3

Bit more verbose, but I was also thinking about @sequelize/sqlite/better-sqlite possibly. Users shouldn't need to care which adapter they use, but if they have a preference they can use another one we provide. Alternatively both @sequelize/sqlite and @sequelize/better-sqlite would also be fine with me. I like @sequelize/sqlite less because it forces us towards an implementation and not just the dialect name

[ephys]

The problem with @sequelize/sqlite/better-sqlite is that it requires installing both dialect libraries. If we want to deduplicate code between the two, we can just publish @sequelize/abstract-sqlite that is not connector-dependant

Users shouldn't need to care which adapter they use

If we start proposing multiple adapters, they should make an informed decision on which one they want to use. Otherwise, we'd just pick the one we consider to be the best. Naming one /sqlite indicates that it's the one users should use by default, when instead we should document the differences

[WikiRik]

If we start proposing multiple adapters, they should make an informed decision on which one they want to use. Otherwise, we'd just pick the one we consider to be the best. Naming one /sqlite indicates that it's the one users should use by default, when instead we should document the differences

You've got a point there. Do we want to do this for the other dialects as well or is this only for sqlite since there is a relatively big demand to support better-sqlite?

[ephys]

To be consistent, we probably should. Considering the demand has only ever been for sqlite, that may not be worth the trouble.

[ephys]

Following the changes done in #17222, it will be very important to have a clear page that explains how to configure the credentials per dialect. Right now it's in the "dialect specific things" page, which is a bit too buried for my liking. The "how to connect to your database" chapter should probably go at the very start of the documentation, right after "getting started" and before "defining models". I think it would make sense to have one page per dialect that first gives the basics of connecting to that database type, and has sub-chapters for other dialect-specific options

The other dialect-specific things on that page should probably be moved to where they can be used too, so that page could be deleted

[ephys]

Considering DB2 is really DB2 for Linux, Unix, Windows, and ibmi is really DB2 for IBM i, should we rename the packages to @sequelize/db2-luw and @sequelize/db2-ibmi respectively?

Following discussion with @WikiRik, based on IBM's branding, they should be @sequelize/db2 and @sequelize/db2-ibmi