sqlx_pg_test_template/
lib.rs

1//!
2//! Faster version of the `#[sqlx::test]` macro for PostgreSQL. Database for every test
3//! is created using `CREATE DATABASE ... WITH TEMPLATE ...` and dropped after test
4//! is finished.
5//!
6//! # Usage
7//!
8//! ```rust
9//! use sqlx_pg_test_template::test;
10//!
11//! #[sqlx_pg_test_template::test]
12//! async fn test(pool: Postgres<Pool>) {
13//!     // Do work
14//! }
15//!
16//! #[sqlx_pg_test_template::test(template = "my_db_with_seeds")]
17//! async fn test_with_seeds(pool: Postgres<Pool>) {
18//!     // Do work
19//! }
20//!
21//! #[sqlx_pg_test_template::test(max_connections=5)]
22//! async fn test_with_cursor(pool: Postgres<Pool>) {
23//!     // Do work
24//! }
25//! ```
26//!
27//! Run tests:
28//!
29//! ```sh
30//! DATABASE_URL="postgres://postgres:postgres@localhost:5432/test_template" cargo test
31//! ```
32//!
33//! `test_template` would be used as a template for test databases. Connection to the
34//! default `postgres` user database (`postgres`) will be used to manage test databases.
35//!
36//! You need to maintain the template database(s) manually. For example, you can use
37//! a `nextest` startup script:
38//!
39//! ```sh
40//! export DATABASE_URL="postgres://postgres:postgres@localhost:5432/test_template"
41//! sqlx database drop -y -D $DATABASE_URL
42//! sqlx database create -D $DATABASE_URL
43//! sqlx migrate run -D $DATABASE_URL --source ./migrations
44//! ```
45//!
46//! Macro uses the same runtime as the parent sqlx through `sqlx::test_block_on`.
47//!
48//! # Requirements
49//!
50//! * The user provided in `DATABASE_URL` should have permissions
51//!   to create and drop databases.
52//! * The user must have a default database created and accessible.
53//!   A connection to the default database is used to manipulate test databases.
54//! * If no `template` argument is provided for the macro, the database
55//!   from `DATABASE_URL` will be used as the template.
56//!
57//! # Differences from standard `#[sqlx::test]`
58//!
59//! * Standard macro uses master connection pool. The specific test pools share
60//!   semaphore with the parent pool ensuring that the total number of connections
61//!   won't exceed the connection limit.
62//!
63//!   Unfortunately, this API is private. Moreover, it does not help when tests
64//!   are run by `nextest` because tests are run in parallel processes.
65//!
66//!   So, the number of connections for individual test pool is limited by 2 or
67//!   `max_connections` parameter (in case a specific test needs more).
68//!
69//!   If you encounter any issues with the number of connections, you can use `pgBouncer`
70//!   or a similar tool or just decrease number of parallel runners.
71//!
72//! * No extra metadata is generated. We rely on the fact that module_path to a test function
73//!   is unique and calculate hash from it. This hash is used as a database name. Module path
74//!   to a test is set as a comment for a database.
75//!
76//! # Failed tests
77//!   
78//! To find failed database test, you can use the following SQL:
79//!
80//! ```sql
81//! SELECT
82//!     d.datname AS database_name,
83//!     sd.description AS comment
84//! FROM
85//!     pg_database d
86//! JOIN
87//!     pg_shdescription sd ON d.oid = sd.objoid
88//! WHERE
89//!     sd.description ILIKE '%test%';
90//! ```
91pub use sqlx_pg_test_template_macros::test;
92
93#[doc(hidden)]
94pub use sqlx_pg_test_template_runner::TestArgs;
95
96#[doc(hidden)]
97pub use sqlx_pg_test_template_runner::run_test;
sqlx_pg_test_template/lib.rs

sqlx_pg_test_template/
lib.rs
