pg_embed/
pg_errors.rs

1//! Error types and [`Result`] alias for pg-embed.
2
3/// Convenience alias so every fallible function can write `Result<T>` instead
4/// of `Result<T, Error>`.
5pub type Result<T> = std::result::Result<T, Error>;
6
7/// All errors that pg-embed can produce.
8///
9/// Every variant maps to a distinct failure mode in the library.  Variants that
10/// carry a `String` field contain a human-readable message from the underlying
11/// OS or library call that caused the failure; this is always the `.to_string()`
12/// of the original error.
13#[derive(thiserror::Error, Debug, Clone, PartialEq)]
14pub enum Error {
15    /// The download URL for PostgreSQL binaries could not be constructed.
16    ///
17    /// Typically caused by the OS cache directory being unavailable or an
18    /// unsupported platform combination.
19    #[error("Invalid PostgreSQL binaries download URL.")]
20    InvalidPgUrl,
21
22    /// The downloaded file is not a valid PostgreSQL binaries package.
23    ///
24    /// Raised when the ZIP archive cannot be opened or does not contain the
25    /// expected `.xz`-compressed tarball.
26    #[error("Invalid PostgreSQL binaries package.")]
27    InvalidPgPackage,
28
29    /// A file write operation failed.
30    ///
31    /// The inner string is the OS error message (e.g. `Permission denied`).
32    #[error("Could not write to file: {0}")]
33    WriteFileError(String),
34
35    /// A file read or existence-check operation failed.
36    ///
37    /// The inner string is the OS error message.
38    #[error("Could not read file: {0}")]
39    ReadFileError(String),
40
41    /// A directory could not be created.
42    ///
43    /// The inner string is the OS error message.
44    #[error("Could not create directory: {0}")]
45    DirCreationError(String),
46
47    /// XZ decompression or tar extraction of the PostgreSQL binaries failed.
48    #[error("Failed to unpack PostgreSQL binaries.")]
49    UnpackFailure,
50
51    /// `pg_ctl start` exited with a non-zero status.
52    #[error("PostgreSQL could not be started.")]
53    PgStartFailure,
54
55    /// `pg_ctl stop` exited with a non-zero status.
56    #[error("PostgreSQL could not be stopped.")]
57    PgStopFailure,
58
59    /// `initdb` exited with a non-zero status.
60    #[error("PostgreSQL could not be initialized.")]
61    PgInitFailure,
62
63    /// Removal of the database directory or password file failed.
64    ///
65    /// The inner string is the OS error message.
66    #[error("Clean up error: {0}")]
67    PgCleanUpFailure(String),
68
69    /// Removal of the cached binaries directory failed.
70    ///
71    /// The inner string is the OS error message.
72    #[error("Purging error: {0}")]
73    PgPurgeFailure(String),
74
75    /// A buffered I/O read from a process stream failed unexpectedly.
76    #[error("Buffer read error.")]
77    PgBufferReadError,
78
79    /// A mutex or async lock could not be acquired.
80    #[error("Lock error.")]
81    PgLockError,
82
83    /// Spawning or waiting on a child process failed.
84    #[error("Child process error.")]
85    PgProcessError,
86
87    /// A `pg_ctl` or `initdb` call exceeded its configured timeout.
88    ///
89    /// See [`crate::postgres::PgSettings::timeout`].
90    #[error("Operation timed out.")]
91    PgTimedOutError,
92
93    /// A `tokio::task::spawn_blocking` join failed.
94    ///
95    /// The inner string is the [`tokio::task::JoinError`] message.
96    #[error("Task join error: {0}")]
97    PgTaskJoinError(String),
98
99    /// A generic error wrapper used internally to attach context.
100    ///
101    /// The first field is the original error message; the second is a
102    /// human-readable context string (e.g. `"spawn_blocking join error"`).
103    #[error("PgError: {0}, {1}")]
104    PgError(String, String),
105
106    /// The HTTP download of the PostgreSQL binaries JAR failed.
107    ///
108    /// The inner string is the `reqwest` error message.
109    #[error("PostgreSQL binaries download failure: {0}")]
110    DownloadFailure(String),
111
112    /// Converting the HTTP response body to bytes failed.
113    ///
114    /// The inner string is the `reqwest` error message.
115    #[error("Request response bytes conversion failure: {0}")]
116    ConversionFailure(String),
117
118    /// An internal MPSC channel send failed because the receiver was dropped.
119    #[error("Channel send error.")]
120    SendFailure,
121
122    /// A sqlx query or connection operation failed.
123    ///
124    /// The inner string is the sqlx error message.
125    /// Only produced when the `rt_tokio_migrate` feature is enabled.
126    #[error("SQLx query error: {0}")]
127    SqlQueryError(String),
128
129    /// Running sqlx migrations failed.
130    ///
131    /// The inner string is the sqlx migrator error message.
132    /// Only produced when the `rt_tokio_migrate` feature is enabled.
133    #[error("Migration error: {0}")]
134    MigrationError(String),
135}
pg_embed/pg_errors.rs

pg_embed/
pg_errors.rs
