Skip to content

Commit 9bd3d61

Browse files
authored
Update FAQ.md
1 parent 3dec1d1 commit 9bd3d61

File tree

1 file changed

+56
-0
lines changed

1 file changed

+56
-0
lines changed

FAQ.md

+56
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,62 @@ as they can often be a whole year or more out-of-date.
3636

3737
[`rust-version`]: https://doc.rust-lang.org/stable/cargo/reference/manifest.html#the-rust-version-field
3838

39+
----------------------------------------------------------------
40+
41+
### Can SQLx Add Support for New Databases?
42+
43+
We are always open to discuss adding support for new databases, but as of writing, have no plans to in the short term.
44+
45+
Implementing support for a new database in SQLx is a _huge_ lift. Expecting this work to be done for free is highly unrealistic.
46+
In all likelihood, the implementation would need to be written from scratch.
47+
Even if Rust bindings exist, they may not support `async`.
48+
Even if they support `async`, they may only support either Tokio or `async-std`, and not both.
49+
Even if they support Tokio and `async-std`, the API may not be flexible enough or provide sufficient information (e.g. for implementing the macros).
50+
51+
If we have to write the implementation from scratch, is the protocol publicly documented, and stable?
52+
53+
Even if everything is supported on the client side, how will we run tests against the database? Is it open-source, or proprietary? Will it require a paid license?
54+
55+
For example, Oracle Database's protocol is proprietary and only supported through their own libraries, which do not support Rust, and only have blocking APIs (see: [Oracle Call Interface for C](https://docs.oracle.com/en/database/oracle/oracle-database/23/lnoci/index.html)).
56+
This makes it a poor candidate for an async-native crate like SQLx--though we support SQLite, which also only has a blocking API, that's the exception and not the rule. Wrapping blocking APIs is not very scalable.
57+
58+
We still have plans to bring back the MSSQL driver, but this is not feasible as of writing with the current maintenance workload. Should this change, an announcement will be made on Github as well as our [Discord server](https://discord.gg/uuruzJ7).
59+
60+
### What If I'm Willing to Contribute the Implementation?
61+
62+
Being willing to contribute an implementation for a new database is one thing, but there's also the ongoing maintenance burden to consider.
63+
64+
Are you willing to provide support long-term?
65+
Will there be enough users that we can rely on outside contributions?
66+
Or is support going to fall to the current maintainer(s)?
67+
68+
This is the kind of thing that will need to be supported in SQLx _long_ after the initial implementation, or else later need to be removed.
69+
If you don't have plans for how to support a new driver long-term, then it doesn't belong as part of SQLx itself.
70+
71+
However, drivers don't necessarily need to live _in_ SQLx anymore. Since 0.7.0, drivers don't need to be compiled-in to be functional.
72+
Support for third-party drivers in `sqlx-cli` and the `query!()` macros is pending, as well as documenting the process of writing a driver, but contributions are welcome in this regard.
73+
74+
For example, see [sqlx-exasol](https://crates.io/crates/sqlx-exasol).
75+
76+
----------------------------------------------------------------
77+
### Can SQLx Add Support for New Data-Type Crates (e.g. Jiff in addition to `chrono` and `time`)?
78+
79+
This has a lot of the same considerations as adding support for new databases (see above), but with one big additional problem: Semantic Versioning.
80+
81+
When we add trait implementations for types from an external crate, that crate then becomes part of our public API. We become beholden to its release cycle.
82+
83+
If the crate's API is still evolving, meaning they are making breaking changes frequently, and thus releasing new major versions frequently, that then becomes a burden on us to upgrade and release a new major version as well so everyone _else_ can upgrade.
84+
85+
We don't have the maintainer bandwidth to support multiple major versions simultaneously (we have no Long-Term Support policy), so this means that users who want to keep up-to-date are forced to make frequent manual upgrades as well.
86+
87+
Thus, it is best that we stick to only supporting crates which have a stable API, and which are not making new major releases frequently.
88+
89+
Conversely, adding support for SQLx _in_ these crates may not be desirable either, since SQLx is a large dependency and a higher-level crate. In this case, the SemVer problem gets pushed onto the other crate.
90+
91+
There isn't a satisfying answer to this problem, but one option is to have an intermediate wrapper crate.
92+
For example, [`jiff-sqlx`](https://crates.io/crates/jiff-sqlx), which is maintained by the author of Jiff.
93+
API changes to SQLx are pending to make this pattern easier to use.
94+
3995
----------------------------------------------------------------
4096
### I'm getting `HandshakeFailure` or `CorruptMessage` when trying to connect to a server over TLS using RusTLS. What gives?
4197

0 commit comments

Comments
 (0)