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//! ## Information
61//!
62//! During the build process, when the `bundled` feature is enabled, the PostgreSQL binaries are
63//! downloaded and included in the resulting binary. The version of the PostgreSQL binaries is
64//! determined by the `POSTGRESQL_VERSION` environment variable. If the `POSTGRESQL_VERSION`
65//! environment variable is not set, then `postgresql_archive::LATEST` will be used to determine the
66//! version of the PostgreSQL binaries to download.
67//!
68//! When downloading the theseus PostgreSQL binaries, either during build, or at runtime, the
69//! `GITHUB_TOKEN` environment variable can be set to a GitHub personal access token to increase
70//! the rate limit for downloading the PostgreSQL binaries. The `GITHUB_TOKEN` environment
71//! variable is not required.
72//!
73//! At runtime, the PostgreSQL binaries are cached by default in the following directories:
74//!
75//! - Unix: `$HOME/.theseus/postgresql`
76//! - Windows: `%USERPROFILE%\.theseus\postgresql`
77//!
78//! Performance can be improved by using a specific version of the PostgreSQL binaries (e.g. `=16.4.0`).
79//! After the first download, the PostgreSQL binaries will be cached and reused for subsequent runs.
80//! Further, the repository will no longer be queried to calculate the version match.
81//!
82//! ## Feature flags
83//!
84//! postgresql_embedded uses feature flags to address compile time and binary size
85//! uses.
86//!
87//! The following features are available:
88//!
89//!
90//! | Name | Description | Default? |
91//! |--------------|----------------------------------------------------------|----------|
92//! | `bundled` | Bundles the PostgreSQL archive into the resulting binary | No |
93//! | `blocking` | Enables the blocking API; requires `tokio` | No |
94//! | `native-tls` | Enables native-tls support | Yes |
95//! | `rustls` | Enables rustls support | No |
96//! | `theseus` | Enables theseus PostgreSQL binaries | Yes |
97//! | `tokio` | Enables using tokio for async | No |
98//! | `zonky` | Enables zonky PostgreSQL binaries | No |
99//!
100//! ## Safety
101//!
102//! These crates use `#![forbid(unsafe_code)]` to ensure everything is implemented in 100% safe Rust.
103//!
104//! ## License
105//!
106//! Licensed under either of
107//!
108//! * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or <https://www.apache.org/licenses/LICENSE-2.0>)
109//! * MIT license ([LICENSE-MIT](LICENSE-MIT) or <https://opensource.org/licenses/MIT>)
110//!
111//! at your option.
112//!
113//! PostgreSQL is covered under [The PostgreSQL License](https://opensource.org/licenses/postgresql).
114
115#![forbid(unsafe_code)]
116#![forbid(clippy::allow_attributes)]
117#![deny(clippy::pedantic)]
118#![allow(dead_code)]
119#![allow(clippy::doc_markdown)]
120#![allow(deprecated)]
121
122#[cfg(feature = "blocking")]
123pub mod blocking;
124mod error;
125mod postgresql;
126mod settings;
127
128pub use error::{Error, Result};
129pub use postgresql::{PostgreSQL, Status};
130pub use postgresql_archive::{Version, VersionReq};
131pub use settings::Settings;
132use std::sync::LazyLock;
133
134/// The latest PostgreSQL version requirement
135pub static LATEST: VersionReq = VersionReq::STAR;
136
137/// The latest PostgreSQL version 17
138pub static V17: LazyLock<VersionReq> = LazyLock::new(|| VersionReq::parse("=17").unwrap());
139
140/// The latest PostgreSQL version 16
141pub static V16: LazyLock<VersionReq> = LazyLock::new(|| VersionReq::parse("=16").unwrap());
142
143/// The latest PostgreSQL version 15
144pub static V15: LazyLock<VersionReq> = LazyLock::new(|| VersionReq::parse("=15").unwrap());
145
146/// The latest PostgreSQL version 14
147pub static V14: LazyLock<VersionReq> = LazyLock::new(|| VersionReq::parse("=14").unwrap());
148
149/// The latest PostgreSQL version 13
150#[deprecated(
151 since = "0.17.0",
152 note = "See https://www.postgresql.org/developer/roadmap/"
153)]
154pub static V13: LazyLock<VersionReq> = LazyLock::new(|| VersionReq::parse("=13").unwrap());
155
156pub use settings::BOOTSTRAP_DATABASE;
157pub use settings::BOOTSTRAP_SUPERUSER;
158
159#[cfg(test)]
160mod tests {
161 use super::*;
162
163 #[test]
164 fn test_version() -> Result<()> {
165 let version = VersionReq::parse("=16.4.0")?;
166 assert_eq!(version.to_string(), "=16.4.0");
167 Ok(())
168 }
169
170 #[test]
171 fn test_version_latest() {
172 assert_eq!(LATEST.to_string(), "*");
173 }
174
175 #[test]
176 fn test_version_17() {
177 assert_eq!(V17.to_string(), "=17");
178 }
179
180 #[test]
181 fn test_version_16() {
182 assert_eq!(V16.to_string(), "=16");
183 }
184
185 #[test]
186 fn test_version_15() {
187 assert_eq!(V15.to_string(), "=15");
188 }
189
190 #[test]
191 fn test_version_14() {
192 assert_eq!(V14.to_string(), "=14");
193 }
194
195 #[test]
196 fn test_version_13() {
197 assert_eq!(V13.to_string(), "=13");
198 }
199}