How to setup diesel ORM

If you're working with Rust and Diesel on Windows and have encountered the frustrating link libpq.lib error while installing diesel_cli, you're not alone. This guide provides a comprehensive walkthrough to resolve this issue step by step.

---

Step 1: Install PostgreSQL

The first step is to ensure that PostgreSQL is installed on your system, as diesel_cli requires PostgreSQL's libraries to compile successfully.

How to Install PostgreSQL

1. Download: Visit the official PostgreSQL website to download the latest version for your platform.

2. Install: Run the installer and follow the on-screen instructions.

Verify Installation: After installation, confirm PostgreSQL is installed by opening a command prompt or terminal and running:

psql --version

You should see the installed version of PostgreSQL printed in the terminal.

Step 2: Add PostgreSQL bin Directory to PATH

To make PostgreSQL tools like psql accessible from the command line, add the bin directory of PostgreSQL to your system's PATH.

Instructions:

1. Locate your PostgreSQL installation directory, typically found at:

    C:\Program Files\PostgreSQL\<version>\bin
   

   Replace <version> with the installed version number, e.g., 16.

2. Add the directory to the PATH environment variable:

   • Right-click on This PC or Computer, and select Properties.

   • Click Advanced system settings.

   • In the System Properties dialog, click Environment Variables.

   • Under System variables, find the PATH variable, select it, and click Edit.

   • Add the PostgreSQL bin directory path at the end of the variable value, separated by a semicolon ;.

Open a new command prompt and confirm the PATH is updated:

echo %PATH%

Look for the PostgreSQL bin directory in the output.

Step 3: Set the PQ_LIB_DIR Environment Variable

The next step involves setting the PQ_LIB_DIR environment variable to point to PostgreSQL's lib directory. This is essential because diesel_cli requires access to PostgreSQL's libpq library during the build process.

Instructions:

1. Locate the lib directory in your PostgreSQL installation, typically at:

    C:\Program Files\PostgreSQL\<version>\lib
   

2. Set the PQ_LIB_DIR environment variable:

   • Open the command prompt and run:

       setx PQ_LIB_DIR "C:\Program Files\PostgreSQL\<version>\lib"
     

     Replace <version> with the actual version number.

   • Alternatively, you can set this variable permanently via the Environment Variables settings in the same way you edited the PATH.

3. Verify the environment variable:

Open a new command prompt and run:

echo %PQ_LIB_DIR%

Ensure it prints the correct lib directory path.

---

Step 4: Install diesel_cli

Now, you can proceed to install diesel_cli using Cargo. Since PostgreSQL support is not enabled by default, you need to specify the appropriate feature during installation.

Instructions:

1. Open a command prompt or PowerShell.

2. Run the following command:

    cargo install diesel_cli --no-default-features --features postgres
   

3. Wait for the installation process to complete. If everything is configured correctly, the installation should succeed without errors.

---

Step 5: Configure Cargo for Linking

To ensure Rust correctly links against PostgreSQL's libpq library, you need to modify Cargo's configuration.

Instructions:

1. Open or create a Cargo configuration file:

    $HOME/.cargo/config.toml
   

   If the file does not exist, create it manually.

2. Add the following configuration to the file:

    [target.x86_64-pc-windows-msvc.pq]
    rustc-link-search = ["C:\\Program Files\\PostgreSQL\\<version>\\lib"]
    rustc-link-lib = ["libpq"]
   

   Replace <version> with your PostgreSQL version. Note the use of double backslashes (\\) to escape paths in TOML files.

3. Save the file and re-run the cargo install command if necessary.

---

Step 6: Verify the Installation

Finally, test whether diesel_cli is installed correctly by running:

diesel --version

If the version number is displayed, you're all set! You can now use Diesel with PostgreSQL in your Rust projects.

---

Troubleshooting Tips

If you still encounter errors, consider the following:

1. Double-check Paths: Ensure the PATH and PQ_LIB_DIR variables point to the correct directories.

2. PostgreSQL Version: Make sure the PostgreSQL version you installed is supported by Diesel.

3. Rebuild Diesel: Sometimes, cleaning up and reinstalling Diesel can resolve lingering issues. Use:

    cargo clean
    cargo install diesel_cli --no-default-features --features postgres
   

Windows Build Tools: Ensure you have the necessary build tools installed for compiling Rust projects, such as the Visual Studio C++ Build Tools.

---

Conclusion

Fixing the diesel_cli link libpq.lib error may seem daunting, but following these steps systematically will ensure success. By properly configuring your environment and linking PostgreSQL libraries, you’ll be ready to leverage Diesel’s powerful ORM capabilities in your Rust projects.