postgresql_embedded/lib.rs
1//! # postgresql_embedded
2//!
3//! [](https://codecov.io/gh/theseus-rs/postgresql-embedded)
4//! [](https://bencher.dev/perf/theseus-rs-postgresql-embedded)
5//! [](https://github.com/theseus-rs/postgresql-embedded/tree/main/postgresql_embedded#license)
6//! [](https://semver.org/spec/v2.0.0.html)
7//!
8//! Install and run a PostgreSQL database locally on Linux, MacOS or Windows. PostgreSQL can be
9//! bundled with your application, or downloaded on demand.
10//!
11//! ## Table of contents
12//!
13//! - [Examples](#examples)
14//! - [Information](#information)
15//! - [Feature flags](#feature-flags)
16//! - [Safety](#safety)
17//! - [License](#license)
18//! - [Notes](#notes)
19//!
20//! ## Examples
21//!
22//! ### Asynchronous API
23//!
24//! ```no_run
25//! use postgresql_embedded::{PostgreSQL, Result};
26//!
27//! #[tokio::main]
28//! async fn main() -> Result<()> {
29//! let mut postgresql = PostgreSQL::default();
30//! postgresql.setup().await?;
31//! postgresql.start().await?;
32//!
33//! let database_name = "test";
34//! postgresql.create_database(database_name).await?;
35//! postgresql.database_exists(database_name).await?;
36//! postgresql.drop_database(database_name).await?;
37//!
38//! postgresql.stop().await
39//! }
40//! ```
41//!
42//! ### Synchronous API
43//! ```no_run
44//! #[cfg(feature = "blocking")] {
45//! use postgresql_embedded::blocking::PostgreSQL;
46//!
47//! let mut postgresql = PostgreSQL::default();
48//! postgresql.setup().unwrap();
49//! postgresql.start().unwrap();
50//!
51//! let database_name = "test";
52//! postgresql.create_database(database_name).unwrap();
53//! postgresql.database_exists(database_name).unwrap();
54//! postgresql.drop_database(database_name).unwrap();
55//!
56//! postgresql.stop().unwrap();
57//! }
58//! ```
59//!
60//! ### Settings Builder
61//!
62//! ```no_run
63//! use postgresql_embedded::{PostgreSQL, Result, SettingsBuilder};
64//!
65//! #[tokio::main]
66//! async fn main() -> Result<()> {
67//! let settings = SettingsBuilder::new()
68//! .host("127.0.0.1")
69//! .port(5433)
70//! .username("admin")
71//! .password("secret")
72//! .temporary(false)
73//! .config("max_connections", "100")
74//! .build();
75//!
76//! let mut postgresql = PostgreSQL::new(settings);
77//! postgresql.setup().await?;
78//! postgresql.start().await?;
79//!
80//! postgresql.stop().await
81//! }
82//! ```
83//!
84//! ### Unix Socket
85//!
86//! ```no_run
87//! use postgresql_embedded::{PostgreSQL, Result, SettingsBuilder};
88//! use std::path::PathBuf;
89//!
90//! #[tokio::main]
91//! async fn main() -> Result<()> {
92//! let settings = SettingsBuilder::new()
93//! .socket_dir(PathBuf::from("/tmp/pg_socket"))
94//! .build();
95//!
96//! let mut postgresql = PostgreSQL::new(settings);
97//! postgresql.setup().await?;
98//! postgresql.start().await?;
99//!
100//! let database_name = "test";
101//! postgresql.create_database(database_name).await?;
102//! postgresql.database_exists(database_name).await?;
103//! postgresql.drop_database(database_name).await?;
104//!
105//! postgresql.stop().await
106//! }
107//! ```
108//!
109//! ## Information
110//!
111//! During the build process, when the `bundled` feature is enabled, the PostgreSQL binaries are
112//! downloaded and included in the resulting binary. The version of the PostgreSQL binaries is
113//! determined by the `POSTGRESQL_VERSION` environment variable. If the `POSTGRESQL_VERSION`
114//! environment variable is not set, then `postgresql_archive::LATEST` will be used to determine the
115//! version of the PostgreSQL binaries to download.
116//!
117//! When downloading the theseus PostgreSQL binaries, either during build, or at runtime, the
118//! `GITHUB_TOKEN` environment variable can be set to a GitHub personal access token to increase
119//! the rate limit for downloading the PostgreSQL binaries. The `GITHUB_TOKEN` environment
120//! variable is not required.
121//!
122//! At runtime, the PostgreSQL binaries are cached by default in the following directories:
123//!
124//! - Unix: `$HOME/.theseus/postgresql`
125//! - Windows: `%USERPROFILE%\.theseus\postgresql`
126//!
127//! Performance can be improved by using a specific version of the PostgreSQL binaries (e.g. `=16.10.0`).
128//! After the first download, the PostgreSQL binaries will be cached and reused for subsequent runs.
129//! Further, the repository will no longer be queried to calculate the version match.
130//!
131//! ## Feature flags
132//!
133//! postgresql_embedded uses feature flags to address compile time and binary size
134//! uses.
135//!
136//! The following features are available:
137//!
138//!
139//! | Name | Description | Default? |
140//! |--------------|----------------------------------------------------------|----------|
141//! | `bundled` | Bundles the PostgreSQL archive into the resulting binary | No |
142//! | `blocking` | Enables the blocking API; requires `tokio` | No |
143//! | `native-tls` | Enables native-tls support | Yes |
144//! | `rustls` | Enables rustls support | No |
145//! | `theseus` | Enables theseus PostgreSQL binaries | Yes |
146//! | `tokio` | Enables using tokio for async | No |
147//! | `zonky` | Enables zonky PostgreSQL binaries | No |
148//!
149//! ## Safety
150//!
151//! These crates use `#![forbid(unsafe_code)]` to ensure everything is implemented in 100% safe Rust.
152//!
153//! ## License
154//!
155//! Licensed under either of
156//!
157//! * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or <https://www.apache.org/licenses/LICENSE-2.0>)
158//! * MIT license ([LICENSE-MIT](LICENSE-MIT) or <https://opensource.org/licenses/MIT>)
159//!
160//! at your option.
161//!
162//! PostgreSQL is covered under [The PostgreSQL License](https://opensource.org/licenses/postgresql).
163
164#[cfg(feature = "blocking")]
165pub mod blocking;
166mod error;
167mod postgresql;
168mod settings;
169
170pub use error::{Error, Result};
171pub use postgresql::{PostgreSQL, Status};
172pub use postgresql_archive::{Version, VersionReq};
173pub use settings::{Settings, SettingsBuilder};
174use std::sync::LazyLock;
175
176/// The latest PostgreSQL version requirement
177pub static LATEST: VersionReq = VersionReq::STAR;
178
179/// The latest PostgreSQL version 18
180pub static V18: LazyLock<VersionReq> = LazyLock::new(|| VersionReq::parse("=18").unwrap());
181
182/// The latest PostgreSQL version 17
183pub static V17: LazyLock<VersionReq> = LazyLock::new(|| VersionReq::parse("=17").unwrap());
184
185/// The latest PostgreSQL version 16
186pub static V16: LazyLock<VersionReq> = LazyLock::new(|| VersionReq::parse("=16").unwrap());
187
188/// The latest PostgreSQL version 15
189pub static V15: LazyLock<VersionReq> = LazyLock::new(|| VersionReq::parse("=15").unwrap());
190
191/// The latest PostgreSQL version 14
192#[deprecated(
193 since = "0.18.0",
194 note = "See https://www.postgresql.org/developer/roadmap/"
195)]
196pub static V14: LazyLock<VersionReq> = LazyLock::new(|| VersionReq::parse("=14").unwrap());
197
198pub use settings::BOOTSTRAP_DATABASE;
199pub use settings::BOOTSTRAP_SUPERUSER;
200
201#[cfg(test)]
202mod tests {
203 use super::*;
204
205 #[test]
206 fn test_version() -> Result<()> {
207 let version = VersionReq::parse("=18.2.0")?;
208 assert_eq!(version.to_string(), "=18.2.0");
209 Ok(())
210 }
211
212 #[test]
213 fn test_version_latest() {
214 assert_eq!(LATEST.to_string(), "*");
215 }
216
217 #[test]
218 fn test_version_18() {
219 assert_eq!(V18.to_string(), "=18");
220 }
221
222 #[test]
223 fn test_version_17() {
224 assert_eq!(V17.to_string(), "=17");
225 }
226
227 #[test]
228 fn test_version_16() {
229 assert_eq!(V16.to_string(), "=16");
230 }
231
232 #[test]
233 fn test_version_15() {
234 assert_eq!(V15.to_string(), "=15");
235 }
236
237 #[test]
238 #[allow(deprecated)]
239 fn test_version_14() {
240 assert_eq!(V14.to_string(), "=14");
241 }
242}