sqlx_build_trust_core/
database.rs

1//! Traits to represent a database driver.
2//!
3//! # Support
4//!
5//! ## Tier 1
6//!
7//! Tier 1 support can be thought of as "guaranteed to work". Automated testing is setup to
8//! ensure a high level of stability and functionality.
9//!
10//! | Database | Version | Driver |
11//! | - | - | - |
12//! | [MariaDB] | 10.1+ | [`mysql`] |
13//! | [Microsoft SQL Server] | 2019 | [`mssql`] |
14//! | [MySQL] | 5.6, 5.7, 8.0 | [`mysql`] |
15//! | [PostgreSQL] | 9.5+ | [`postgres`] |
16//! | [SQLite] | 3.20.1+ | [`sqlite`] |
17//!
18//! [MariaDB]: https://mariadb.com/
19//! [MySQL]: https://www.mysql.com/
20//! [Microsoft SQL Server]: https://www.microsoft.com/en-us/sql-server
21//! [PostgreSQL]: https://www.postgresql.org/
22//! [SQLite]: https://www.sqlite.org/
23//!
24//! [`mysql`]: crate::mysql
25//! [`postgres`]: crate::postgres
26//! [`mssql`]: crate::mssql
27//! [`sqlite`]: crate::sqlite
28//!
29//! ## Tier 2
30//!
31//! Tier 2 support can be thought as "should work". No specific automated testing is done,
32//! at this time, but there are efforts to ensure compatibility. Tier 2 support also includes
33//! database distributions that provide protocols that closely match a database from Tier 1.
34//!
35//! _No databases are in tier 2 at this time._
36//!
37//! # `Any`
38//!
39//! Selecting a database driver is, by default, a compile-time decision. SQLx is designed this way
40//! to take full advantage of the performance and type safety made available by Rust.
41//!
42//! We recognize that you may wish to make a runtime decision to decide the database driver. The
43//! [`Any`](crate::any) driver is provided for that purpose.
44//!
45//! ## Example
46//!
47//! ```rust,ignore
48//! // connect to SQLite
49//! let conn = AnyConnection::connect("sqlite://file.db").await?;
50//!
51//! // connect to Postgres, no code change
52//! // required, decided by the scheme of the URL
53//! let conn = AnyConnection::connect("postgres://localhost/sqlx").await?;
54//! ```
55
56use std::fmt::Debug;
57
58use crate::arguments::Arguments;
59use crate::column::Column;
60use crate::connection::Connection;
61use crate::row::Row;
62
63use crate::statement::Statement;
64use crate::transaction::TransactionManager;
65use crate::type_info::TypeInfo;
66use crate::value::{Value, ValueRef};
67
68/// A database driver.
69///
70/// This trait encapsulates a complete set of traits that implement a driver for a
71/// specific database (e.g., MySQL, PostgreSQL).
72pub trait Database:
73    'static
74    + Sized
75    + Send
76    + Debug
77    + for<'r> HasValueRef<'r, Database = Self>
78    + for<'q> HasArguments<'q, Database = Self>
79    + for<'q> HasStatement<'q, Database = Self>
80{
81    /// The concrete `Connection` implementation for this database.
82    type Connection: Connection<Database = Self>;
83
84    /// The concrete `TransactionManager` implementation for this database.
85    type TransactionManager: TransactionManager<Database = Self>;
86
87    /// The concrete `Row` implementation for this database.
88    type Row: Row<Database = Self>;
89
90    /// The concrete `QueryResult` implementation for this database.
91    type QueryResult: 'static + Sized + Send + Sync + Default + Extend<Self::QueryResult>;
92
93    /// The concrete `Column` implementation for this database.
94    type Column: Column<Database = Self>;
95
96    /// The concrete `TypeInfo` implementation for this database.
97    type TypeInfo: TypeInfo;
98
99    /// The concrete type used to hold an owned copy of the not-yet-decoded value that was
100    /// received from the database.
101    type Value: Value<Database = Self> + 'static;
102
103    /// The display name for this database driver.
104    const NAME: &'static str;
105
106    /// The schemes for database URLs that should match this driver.
107    const URL_SCHEMES: &'static [&'static str];
108}
109
110/// Associate [`Database`] with a [`ValueRef`](crate::value::ValueRef) of a generic lifetime.
111///
112/// ---
113///
114/// The upcoming Rust feature, [Generic Associated Types], should obviate
115/// the need for this trait.
116///
117/// [Generic Associated Types]: https://github.com/rust-lang/rust/issues/44265
118pub trait HasValueRef<'r> {
119    type Database: Database;
120
121    /// The concrete type used to hold a reference to the not-yet-decoded value that has just been
122    /// received from the database.
123    type ValueRef: ValueRef<'r, Database = Self::Database>;
124}
125
126/// Associate [`Database`] with an [`Arguments`](crate::arguments::Arguments) of a generic lifetime.
127///
128/// ---
129///
130/// The upcoming Rust feature, [Generic Associated Types], should obviate
131/// the need for this trait.
132///
133/// [Generic Associated Types]: https://github.com/rust-lang/rust/issues/44265
134pub trait HasArguments<'q> {
135    type Database: Database;
136
137    /// The concrete `Arguments` implementation for this database.
138    type Arguments: Arguments<'q, Database = Self::Database>;
139
140    /// The concrete type used as a buffer for arguments while encoding.
141    type ArgumentBuffer;
142}
143
144/// Associate [`Database`] with a [`Statement`](crate::statement::Statement) of a generic lifetime.
145///
146/// ---
147///
148/// The upcoming Rust feature, [Generic Associated Types], should obviate
149/// the need for this trait.
150///
151/// [Generic Associated Types]: https://github.com/rust-lang/rust/issues/44265
152pub trait HasStatement<'q> {
153    type Database: Database;
154
155    /// The concrete `Statement` implementation for this database.
156    type Statement: Statement<'q, Database = Self::Database>;
157}
158
159/// A [`Database`] that maintains a client-side cache of prepared statements.
160pub trait HasStatementCache {}
sqlx_build_trust_core/database.rs

sqlx_build_trust_core/
database.rs
