Crate postgresql_embedded

postgresql_embedded

Install and run a PostgreSQL database locally on Linux, MacOS or Windows. PostgreSQL can be bundled with your application, or downloaded on demand.

Table of contents

• Examples
• Information
• Feature flags
• Safety
• License
• Notes

Examples

Asynchronous API

use postgresql_embedded::{PostgreSQL, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let mut postgresql = PostgreSQL::default();
    postgresql.setup().await?;
    postgresql.start().await?;

    let database_name = "test";
    postgresql.create_database(database_name).await?;
    postgresql.database_exists(database_name).await?;
    postgresql.drop_database(database_name).await?;

    postgresql.stop().await
}

Synchronous API

#[cfg(feature = "blocking")] {
use postgresql_embedded::blocking::PostgreSQL;

let mut postgresql = PostgreSQL::default();
postgresql.setup().unwrap();
postgresql.start().unwrap();

let database_name = "test";
postgresql.create_database(database_name).unwrap();
postgresql.database_exists(database_name).unwrap();
postgresql.drop_database(database_name).unwrap();

postgresql.stop().unwrap();
}

Information

During the build process, when the bundled feature is enabled, the PostgreSQL binaries are downloaded and included in the resulting binary. The version of the PostgreSQL binaries is determined by the POSTGRESQL_VERSION environment variable. If the POSTGRESQL_VERSION environment variable is not set, then postgresql_archive::LATEST will be used to determine the version of the PostgreSQL binaries to download.

When downloading the theseus PostgreSQL binaries, either during build, or at runtime, the GITHUB_TOKEN environment variable can be set to a GitHub personal access token to increase the rate limit for downloading the PostgreSQL binaries. The GITHUB_TOKEN environment variable is not required.

At runtime, the PostgreSQL binaries are cached by default in the following directories:

• Unix: $HOME/.theseus/postgresql
• Windows: %USERPROFILE%\.theseus\postgresql

Performance can be improved by Using a specific version of the PostgreSQL binaries (e.g. =16.4.0). After the first download, the PostgreSQL binaries will be cached and reused for subsequent runs. Further, the repository will no longer be queried to calculate the version match.

Feature flags

postgresql_embedded uses feature flags to address compile time and binary size uses.

The following features are available:

Name	Description	Default?
bundled	Bundles the PostgreSQL archive into the resulting binary	No
blocking	Enables the blocking API; requires tokio	No
native-tls	Enables native-tls support	Yes
rustls-tls	Enables rustls-tls support	No
theseus	Enables theseus PostgreSQL binaries	Yes
tokio	Enables using tokio for async	No
zonky	Enables zonky PostgreSQL binaries	No

Safety

These crates use #![forbid(unsafe_code)] to ensure everything is implemented in 100% safe Rust.

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

PostgreSQL is covered under The PostgreSQL License.

Modules

• blocking

Structs

• PostgreSQL
  PostgreSQL server
• Settings
  Database settings
• Version
  SemVer version as defined by https://semver.org.
• VersionReq
  SemVer version requirement describing the intersection of some version comparators, such as >=1.2.3, <1.8.

Enums

• Error
  Errors that can occur when using PostgreSQL embedded
• Status
  PostgreSQL status

Constants

• BOOTSTRAP_DATABASE
  PostgreSQL database
• BOOTSTRAP_SUPERUSER
  PostgreSQL superuser

Statics

• LATEST
  The latest PostgreSQL version requirement
• V12Deprecated
  The latest PostgreSQL version 12
• V13
  The latest PostgreSQL version 13
• V14
  The latest PostgreSQL version 14
• V15
  The latest PostgreSQL version 15
• V16
  The latest PostgreSQL version 16

Type Aliases

• Result
  PostgreSQL embedded result type