Build a Rust App with CockroachDB and the Rust-Postgres Driver

On this page Carat arrow pointing down
Warning:
As of May 16, 2023, CockroachDB v21.2 is no longer supported. For more details, refer to the Release Support Policy.

This tutorial shows you how build a simple Rust application with CockroachDB and the Rust-Postgres driver.

We have tested the Rust-Postgres driver enough to claim beta-level support. If you encounter problems, please open an issue with details to help us make progress toward full support.

Before you begin

  1. Install CockroachDB.
  2. Start up a secure or insecure local cluster.
  3. Choose the instructions that correspond to whether your cluster is secure or insecure:
Warning:

The --insecure flag used in this tutorial is intended for non-production testing only. To run CockroachDB in production, use a secure cluster instead.

Step 1. Specify the Rust-Postgres driver as a dependency

Update your Cargo.toml file to specify a dependency on the Rust-Postgres driver, as described in the official documentation.

Additionally, include the OpenSSL bindings and Rust-Postgres OpenSSL crates as dependencies.

Step 2. Create the maxroach users and bank database

Start the built-in SQL shell:

icon/buttons/copy
$ cockroach sql --certs-dir=certs

In the SQL shell, issue the following statements to create the maxroach user and bank database:

icon/buttons/copy
> CREATE USER IF NOT EXISTS maxroach;
icon/buttons/copy
> CREATE DATABASE bank;

Give the maxroach user the necessary permissions:

icon/buttons/copy
> GRANT ALL ON DATABASE bank TO maxroach;

Exit the SQL shell:

icon/buttons/copy
> \q

Step 3. Generate a certificate for the maxroach user

Create a certificate and key for the maxroach user by running the following command. The code samples will run as this user.

icon/buttons/copy
$ cockroach cert create-client maxroach --certs-dir=certs --ca-key=my-safe-directory/ca.key

Step 4. Run the Rust code

Now that you have a database and a user, you'll run code to create a table and insert some rows, and then you'll run code to read and update values as an atomic transaction.

Get the code

Clone the example-app-rust-postgres GitHub repo:

icon/buttons/copy
$ git clone https://github.com/cockroachdb/example-app-rust-postgres

Basic statements

First, run basic-sample.rs to connect as the maxroach user and execute some basic SQL statements, inserting rows and reading and printing the rows:

icon/buttons/copy
404: Not Found

Transaction (with retry logic)

Next, run txn-sample.rs to again connect as the maxroach user but this time execute a batch of statements as an atomic transaction to transfer funds from one account to another, where all included statements are either committed or aborted.

Note:

CockroachDB may require the client to retry a transaction in case of read/write contention. CockroachDB provides a generic retry function that runs inside a transaction and retries it as needed. You can copy and paste the retry function from here into your code.

icon/buttons/copy
404: Not Found

After running the code, use the built-in SQL client to verify that funds were transferred from one account to another:

icon/buttons/copy
$ cockroach sql --certs-dir=certs -e 'SELECT id, balance FROM accounts' --database=bank
+----+---------+
| id | balance |
+----+---------+
|  1 |     900 |
|  2 |     350 |
+----+---------+
(2 rows)

What's next?

Read more about using the Rust-Postgres driver.

You might also be interested in the following pages:


Yes No
On this page

Yes No