Connecting Heroku Postgres to Rust

2022-05-18T00:00:00+00:00
I was learning Postgres and Actix Web recently to create a comment system for this blog and it ended up being a huge pain to connect the Heroku Postgres database to my Actix Web application. Inspired by that pain, I have written this guide.</p>
Dependencies</h1>
This is going to require a few crates. Here is a list of dependencies in Cargo.toml</code>:</p>
[</span>dependencies</span>]</span></span>
url</span> =</span> "2.2.2"</span></span>
tokio-postgres</span> =</span> "0.7.6"</span></span>
deadpool-postgres</span> =</span> "0.10.2"</span></span>
postgres-openssl</span> =</span> "0.5.0"</span></span>
openssl</span> =</span> "0.10.40"</span></span></code></pre>
Here's what all these dependencies do:</p>

url</code>: Used to parse database info from the URL given by Heroku.</li>
tokio-postgres</code>: An async client for Postgres in Rust.</li>
deadpool-postgres</code>: Async pool for database connections.</li>
postgres-openssl</code>: SSL support for Postgres.</li>
openssl</code>: SSL support for Rust.</li>
</ul>
You'll also need some sort of async runtime. For my project I was using Actix
Web which runs on Tokio but for simplicity I'm just going to use Tokio for this
post.</p>
tokio</span> =</span> { version</span> =</span> "1.18.2"</span>,</span> features</span> =</span> [</span>"full"</span>] }</span></span></code></pre>
Now that we have our dependencies added, we're ready to go!</p>
Connecting to Postgres</h1>
Generating a deadpool_postgres</code> config</h2>
When you create a Postgres database in Heroku, it will set an environment
variable in your project called DATABASE_URL</code>. Unfortunately we can't use this
URL directly so we are going to parse it.</p>
Here's what the function to parse it looks like:</p>
fn</span> config_from_url</span>(url</span>: &</span>str</span>)</span> -></span> Result</span><deadpool_postgres</span>::</span>Config</span>,</span> &</span>'</span>static str</span>> {</span></span>
    // Config URL is in format:</span></span>
    // postgres://USER:PASSWORD@HOST:PORT/DBNAME</span></span>
    let</span> url</span> =</span> Url</span>::</span>parse</span>(url)</span>.</span>map_err</span>(</span>|</span>_</span>|</span> "could not parse db url"</span>)</span>?</span>;</span></span>
    let</span> user</span> =</span> url</span>.</span>username</span>()</span>.</span>to_string</span>();</span></span>
    let</span> password</span> =</span> url</span>.</span>password</span>()</span>.</span>ok_or</span>(</span>"bad password"</span>)</span>?.</span>to_string</span>();</span></span>
    let</span> host</span> =</span> url</span>.</span>host</span>()</span>.</span>ok_or</span>(</span>"bad host"</span>)</span>?.</span>to_string</span>();</span></span>
    let</span> port</span> =</span> url</span>.</span>port</span>()</span>.</span>ok_or</span>(</span>"no port in url"</span>)</span>?</span>;</span></span>
    let</span> dbname</span> =</span> url</span></span>
        .</span>path_segments</span>()</span></span>
        .</span>ok_or</span>(</span>"cannot be base"</span>)</span>?</span></span>
        .</span>next</span>()</span></span>
        .</span>unwrap</span>()</span></span>
        .</span>to_string</span>();</span></span>
</span>
    let mut</span> cfg</span> =</span> deadpool_postgres</span>::</span>Config</span>::</span>new</span>();</span></span>
    cfg</span>.</span>user </span>=</span> Some</span>(user);</span></span>
    cfg</span>.</span>password </span>=</span> Some</span>(password);</span></span>
    cfg</span>.</span>host </span>=</span> Some</span>(host);</span></span>
    cfg</span>.</span>port </span>=</span> Some</span>(port);</span></span>
    cfg</span>.</span>dbname </span>=</span> Some</span>(dbname);</span></span>
</span>
    Ok</span>(cfg)</span></span>
}</span></span></code></pre>
Let's give it a try!</p>
#[tokio</span>::</span>main]</span></span>
async fn</span> main</span>() {</span></span>
    let</span> database_url</span> =</span> std</span>::</span>env</span>::</span>var</span>(</span>"DATABASE_URL"</span>)</span>.</span>unwrap</span>();</span></span>
    let</span> cfg</span> =</span> config_from_url</span>(</span>&</span>database_url)</span>.</span>unwrap</span>();</span></span>
    dbg!</span>(</span>&</span>cfg);</span></span>
}</span></span></code></pre>
The output you get should look something like this:</p>
[src/main.rs:35] &cfg = Config {</span></span>
    user: Some(</span></span>
        "[user]",</span></span>
    ),</span></span>
    password: Some(</span></span>
        "[password]",</span></span>
    ),</span></span>
    dbname: Some(</span></span>
        "[database name]",</span></span>
    ),</span></span>
    options: None,</span></span>
    application_name: None,</span></span>
    ssl_mode: None,</span></span>
    host: Some(</span></span>
        "[link]",</span></span>
    ),</span></span>
    hosts: None,</span></span>
    port: Some(</span></span>
        [port],</span></span>
    ),</span></span>
    ports: None,</span></span>
    connect_timeout: None,</span></span>
    keepalives: None,</span></span>
    keepalives_idle: None,</span></span>
    target_session_attrs: None,</span></span>
    channel_binding: None,</span></span>
    manager: None,</span></span>
    pool: None,</span></span>
}</span></span></code></pre>
With all the values in the square brackets being replaced by the values from the
Heroku URL.</p>
Setting up SSL</h2>
This was the biggest headache for me but it's actually very simple. The thing
with Heroku Postgres is that it requires SSL, but doesn't give certificates. To
make this work we need to set the SSL verify mode to off in our SSL config in Rust.</p>
let mut</span> builder</span> =</span> SslConnector</span>::</span>builder</span>(</span>SslMethod</span>::</span>tls</span>())</span>.</span>unwrap</span>();</span></span>
builder</span>.</span>set_verify</span>(</span>SslVerifyMode</span>::</span>NONE</span>);</span></span>
let</span> connector</span> =</span> MakeTlsConnector</span>::</span>new</span>(builder</span>.</span>build</span>());</span></span></code></pre>
And that's all the SSL stuff we need to do.</p>
Creating a connection pool</h2>
Creating a connection pool with deadpool_postgres</code> is just one line of code:</p>
let</span> pool</span> =</span> cfg</span>.</span>create_pool</span>(</span>None</span>, connector)</span>.</span>unwrap</span>();</span></span></code></pre>
And that's it for the setup! Now we can query the database.</p>
Querying the database</h1>
Creating a table</h2>
Before we can query anything we need to create a table in our database. If you
have already done this just skip to the next step.</p>
I'm going to make a directory for all our SQL files in the root of the project.
The structure should now look like this:</p>
.</span></span>
├── .gitignore</span></span>
├── Cargo.lock</span></span>
├── Cargo.toml</span></span>
├── sql</span></span>
└── src</span></span>
    └── main.rs</span></span></code></pre>
For creating the table I'll make a file called schema.sql</code> in the sql
directory. For this example we'll make a simple blog system. We will store the
id, author, date, title, and content of each post.</p>
The SQL code to create such a table looks like this:</p>
CREATE TABLE</span> post</span> (</span></span>
    id </span>SERIAL PRIMARY KEY</span>,</span></span>
    posted </span>DATE NOT NULL DEFAULT</span> CURRENT_DATE,</span></span>
    author </span>VARCHAR</span>(</span>50</span>)</span> NOT NULL</span>,</span></span>
    title </span>VARCHAR</span>(</span>255</span>)</span> NOT NULL</span>,</span></span>
    content </span>TEXT NOT NULL</span></span>
);</span></span></code></pre>
We can write a function in our Rust code to call this SQL query.</p>
// Add this at the top of your file</span></span>
use</span> deadpool_postgres</span>::</span>Client</span>;</span></span>
</span>
async fn</span> create_table</span>(client</span>: &</span>Client</span>) {</span></span>
    let</span> stmt</span> =</span> include_str!</span>(</span>"../sql/schema.sql"</span>);</span></span>
    let</span> stmt</span> =</span> client</span>.</span>prepare</span>(stmt)</span>.</span>await</span>.</span>unwrap</span>();</span></span>
</span>
    client</span>.</span>query</span>(</span>&</span>stmt,</span> &</span>[])</span>.</span>await</span>.</span>unwrap</span>();</span></span>
}</span></span></code></pre>
I'm just going to put this at the bottom of my main function, run it once, then
remove it. You could also use the psql command line tool instead of all of this
if you prefer.</p>
Inserting some data</h2>
Now lets make another SQL file to add a post. I'll call it add_post.sql</code>.</p>
INSERT INTO</span> post (author, title, content)</span></span>
VALUES</span> ($</span>1</span>, $</span>2</span>, $</span>3</span>);</span></span></code></pre>
We omit the date field because Postgres will default it to the current date. The
numbers prefixed by $ will be replaced in our Rust code.</p>
Now lets make a struct to represent one post.</p>
struct</span> Post</span> {</span></span>
    author</span>:</span> String</span>,</span></span>
    title</span>:</span> String</span>,</span></span>
    content</span>:</span> String</span>,</span></span>
}</span></span></code></pre>
Now that we have the SQL to add a post and the Rust struct, we can write a
function that inserts a Post</code> into the database.</p>
async fn</span> add_post</span>(client</span>: &</span>Client</span>, post</span>:</span> Post</span>) {</span></span>
    let</span> stmt</span> =</span> include_str!</span>(</span>"../sql/add_post.sql"</span>);</span></span>
    let</span> stmt</span> =</span> client</span>.</span>prepare</span>(stmt)</span>.</span>await</span>.</span>unwrap</span>();</span></span>
</span>
    let</span> res</span> =</span> client</span></span>
        .</span>query</span>(</span>&</span>stmt,</span> &</span>[</span>&</span>post</span>.</span>author,</span> &</span>post</span>.</span>title,</span> &</span>post</span>.</span>content])</span></span>
        .</span>await</span></span>
        .</span>unwrap</span>();</span></span>
</span>
    dbg!</span>(res);</span></span>
}</span></span></code></pre>Getting data</h2>
Getting data is very similar to inserting data. Say we want to get all the posts
where the author is "John Doe". First we need to build an SQL query. I'll make a
file called get_posts.sql</code>.</p>
SELECT</span> *</span> FROM</span> post</span></span>
WHERE</span> author</span>=</span>$</span>1</span></span>
ORDER BY</span> posted </span>DESC</span>;</span></span></code></pre>
Now we make a Rust function very similar to the one used to add a new post:</p>
async fn</span> get_posts</span>(client</span>: &</span>Client</span>, author</span>: &</span>str</span>) {</span></span>
    let</span> stmt</span> =</span> include_str!</span>(</span>"../sql/get_posts.sql"</span>);</span></span>
    let</span> stmt</span> =</span> client</span>.</span>prepare</span>(stmt)</span>.</span>await</span>.</span>unwrap</span>();</span></span>
</span>
    let</span> res</span> =</span> client</span></span>
        .</span>query</span>(</span>&</span>stmt,</span> &</span>[</span>&</span>author])</span></span>
        .</span>await</span></span>
        .</span>unwrap</span>();</span></span>
</span>
    dbg!</span>(res);</span></span>
}</span></span></code></pre>Conclusion</h1>
These are the basic building blocks you need to use Heroku Postgres from Rust.
Hopefully this was helpful! Please leave a comment if something in this post
needs to be clarified.</p>
If you plan to use any of this code you should DEFINITELY</strong> add error handling
instead of just unwrapping everything!</p>
If you want to see the project that I used this in, check out
this old commit of my website</a>. I actually ended up getting rid of the backend in a later commit and switching to a different comment system but the code works fine.</p>
- rust

Connecting Heroku Postgres to Rust

Connecting to Postgres</h1>

Querying the database</h1>
