Skip to content

Improve the documentation of tokio-postgres connect #1099

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
JJaviMS wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Improve the documentation of tokio-postgres connect #1099

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions tokio-postgres/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -180,12 +180,32 @@ mod transaction_builder;
pub mod types;

/// A convenience function which parses a connection string and connects to the database.
///
/// This method returns the client which will allow you to interact with the database and a connection
/// object which is the one that performs the communication with the dabase. **It's important to use the
/// connection object as shown in the below example, if it is ignored then the client object will not work
/// and when a .wait is called it will await forever.**
Comment on lines +184 to +187
Copy link
Member

@paolobarbolini paolobarbolini Sep 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've cleaned it up a bit.

Suggested change
/// This method returns the client which will allow you to interact with the database and a connection
/// object which is the one that performs the communication with the dabase. **It's important to use the
/// connection object as shown in the below example, if it is ignored then the client object will not work
/// and when a .wait is called it will await forever.**
/// This method returns the client object, which will allow you to interact with the database,
/// and a connection object, which performs the communication with the database.
///
/// **The connection object must be actively polled, which is usually done by spawning it into
/// it's own tokio task, as shown below. If this is not done, calls to the client object will hang forever.**

///
/// See the documentation for [`Config`] for details on the connection string format.
///
/// Requires the `runtime` Cargo feature (enabled by default).
///
/// [`Config`]: config/struct.Config.html
Comment on lines 192 to 193
Copy link
Member

@paolobarbolini paolobarbolini Sep 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should go below the examples section.

///
/// # Examples
/// ```
/// // Connect to the database.
/// let (client, connection) =
/// tokio_postgres::connect("host=localhost user=postgres", NoTls).await?;
/// // The connection object performs the actual communication with the database,
/// // so spawn it off to run on its own.
/// tokio::spawn(async move {
/// if let Err(e) = connection.await {
/// eprintln!("connection error: {}", e);
/// }
/// });
/// // Use the client
/// ```
Comment on lines +195 to +208
Copy link
Member

@paolobarbolini paolobarbolini Sep 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// # Examples
/// ```
/// // Connect to the database.
/// let (client, connection) =
/// tokio_postgres::connect("host=localhost user=postgres", NoTls).await?;
/// // The connection object performs the actual communication with the database,
/// // so spawn it off to run on its own.
/// tokio::spawn(async move {
/// if let Err(e) = connection.await {
/// eprintln!("connection error: {}", e);
/// }
/// });
/// // Use the client
/// ```
/// # Examples
///
/// ```
/// // Connect to the database.
/// let (client, connection) =
/// tokio_postgres::connect("host=localhost user=postgres", NoTls).await?;
///
/// // The connection object performs the actual communication with the database,
/// // so spawn it off to run on its own.
/// tokio::spawn(async move {
/// if let Err(e) = connection.await {
/// eprintln!("connection error: {}", e);
/// }
/// });
///
/// // Now we can use the `client`
/// ```

#[cfg(feature = "runtime")]
pub async fn connect<T>(
config: &str,
Expand Down