#postgresql #database-server #server #embedded-database #linux-macos

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.

23 releases (7 breaking)

0.8.2 Apr 5, 2024
0.7.3 Mar 25, 2024

#271 in Database interfaces

Download history 281/week @ 2024-02-09 177/week @ 2024-02-16 505/week @ 2024-02-23 639/week @ 2024-03-01 775/week @ 2024-03-08 911/week @ 2024-03-15 350/week @ 2024-03-22 478/week @ 2024-03-29 285/week @ 2024-04-05

2,089 downloads per month
Used in 2 crates (via rsql_drivers)

(Apache-2.0 OR MIT) AND PostgreSQL

455KB
11K SLoC

PostgreSQL Embedded

ci Documentation Code Coverage Benchmarks Latest version License Semantic Versioning

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

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

use postgresql_embedded::Result;
use postgresql_embedded::blocking::PostgreSQL;

fn main() -> Result<()> {
    let mut postgresql = PostgreSQL::default();
    postgresql.setup()?;
    postgresql.start()?;

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

    postgresql.stop()
}

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 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

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
tokio Enables using tokio for async No

Safety

This crate uses #![forbid(unsafe_code)] to ensure everything is implemented in 100% safe Rust.

License

Licensed under either of

at your option.

Notes

Uses PostgreSQL binaries from theseus-rs/postgresql-binaries.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Dependencies

~13–30MB
~482K SLoC