Wednesday, November 22, 2017

Rust: Setting up a Sqlite Database with diesel

How does the database stack in Rust work?
For a long while, the database ecosystem in Rust was severely lacking. Thankfully, once Rust Stable 1.0.0 was released, the ecosystem has seen nothing but improvement and growth. Now, most users wind up using diesel, a query-builder that helps immensely with designing your data access layer.

What you need before you start
 You should have sqlite3 installed on your system of choice, as well as the latest version of cargo and rustc.

Step 1: Set up your project
As with any Rust project, simply running cargo init {project} will initialize a rust project with the file structure that cargo can understand. This will generate your Cargo.toml file, where we'll tell it what it needs to start using diesel with sqlite3.
 
Step 2: Set up your project's dependencies
In order to use diesel, you'll need the diesel libraries. It's also highly recommended that you include something called dotenv. This will let you specify what your database is per-project, which you really want. Otherwise, your entire system will only find one database. Or, alternatively, you will need to manually specify a database with every session.

Add these lines to the [dependencies] section in your Cargo.toml file:

diesel = { version = "0.16.0", features = ["sqlite"] }
diesel_codegen = { version = "0.16.0", features = ["sqlite"] }
dotenv = "0.9.0"


Now, you can configure the URL of your database. Create a new file in the same directory as your Cargo.toml file simply called .env. This will be a hidden file, so you may need to enable those to see it.

Make the text of this .env file simply 

DATABASE_URL={database}

So, if you want a sqlite3 database called test.sqlite3, your .env would look like:

DATABASE_URL=test.sqlite3 
 
Step 3: Initialize your database
 Much of the work you'll be doing is done through a command line tool, called simply diesel. First, you need to install this utility globally, with
cargo install diesel --no-default-features --features sqlite

On Linux, this will place the executable in your $HOME/.cargo/bin/ folder. You may need to add this folder to your $PATH in order to use diesel.

To create your database, go to the directory where your Cargo.toml is located and run diesel setup. This will initialize a blank sqlite3 database.
  
Step 4: Start designing your schema 
In order to set up an initial schema, and begin using your database, you have to initalize a migration. To do this, run diesel migration generate {migration-name}.

For this first migration, I tend to just do

diesel migration generate initialize

This will generate a new directory, with today's date and time, that contains an up.sql and down.sql. As the official guide states, down.sql simply should undo any schema changes you make in up.sql

You're all set!
I wrote this guide because I ran into a few pitfalls following the official guide. However, the official guide is absolutely fantastic, and describes everything that I summarized here in a clearer, more complete way. I recommend that you go and check it out at

http://diesel.rs/guides/getting-started/    

5 comments:

  1. Hotmail is considered to be the most remarkable mailing client. But who will be responsible for the issues, one may face in it? You can take simple guidance from talented technical representative available at 0800-029-4639 toll free. Additionally, this service can be availed anytime you want.
    Hotmail Contact Number UK

    ReplyDelete
  2. This blog post really grabbed my attention. With that said I am going to subscribe. Therefore I will get more updates on what you have to say. Please keep writing as I want to learn more.
    You can find there lot's of free stuff like free Rust skins and many more!

    ReplyDelete
  3. Thanks for this post, mate! Just needed quick ref on the syntax for the .env file and this helped!
    JIC -- I'm not a bot like the other comments.

    ReplyDelete
  4. I love the way you write and share your niche! Very interesting and different! Keep it coming! rust trading site

    ReplyDelete