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/    

Sunday, November 12, 2017

Rust: How to use the latest version of a Cargo Crate

Why Cargo is so brilliant
Cargo is a fantastic tool. From the get-go, it's gotten a lot of things right that package managers like npm and nuget still stumble over. The competitors to these tools, yarn and paket address the issues that, thankfully, Cargo has already solved.

You know what npm got right, though? It's dead simple to hook a package up. Do you want to use react? You can just type npm install --save react, and it will find the latest version of React, and add it to the packages.json file. Cargo, too, can be abused to have this functionality.

Warning: You really shouldn't do this...
By explicitly listing versions in your Cargo.toml file, you know for a fact that a future release of the package won't break your project. Furthermore, you know for a fact that the different dependencies that you're relying on play nicely together.

One of the goals of dev-ops is minimizing risk. Having an explicit definition of the packages that could break your project is one of the most important ways to do this.

With that said...
A quick spiel on Semver
Semver, the syntax for identifying the version of the package you want to use, is a widely upheld standard. You can read the full semver guidelines to grok exactly what's happening when you type a version in. Cargo use's a Rust semver library (which can be found here) to parse its dependencies version section.

By abusing the Greater-Than functionality, we can trick Cargo to installing the latest version of a package.

Example: Installing the latest Serde
This line in your Cargo.toml file:

serde = ">0.0.0"

is all you need for Cargo to install the latest version of Serde. This can be used for any package that you don't care about the version for. Be careful with this trick. There's a reason Cargo doesn't technically support this type of workflow outside of this hack.

How To: Remove part of i3's bar with i3status

The Problem
i3bar is perfectly simple. It's not this gaudy, in-your-face information supernova that Windows has been iterating on for the last ~20 years. It tells you just what you need to know: space left, internet speed, CPU load, and the time. But... what if you don't care about your internet speed? Or the time?

Thankfully, removing it is dead simple.

i3status.conf
If you're using the default i3status for your i3bar, the fix is simple. A configuration file in your home directory overrides the default in /etc/i3status.conf. (placing one in $HOME/.config/i3status/config will override the one in your home directory).

Setting the Overrides 
So, you have two options. You can make a NEW file in either of those locations, copying the existing data over. Or, you can edit /etc/i3status.conf directly as root (not recommended).

Using the documentation in man i3status and your existing file (/etc/i3status.conf), you should be able to find the commands you want. Then, make sure that only the commands you care about are in the order variable.

For instance, by default, my order looked like this:

order += "disk /"
order += "ethernet _first_"
order += "load"
order += "tztime local"
Since I don't care about my ethernet, I struck it. Resulting in this:

order += "disk /"
order += "load"
order += "tztime local"

Rust: Returning JSON with Rocket

Preamble
JSON is one of the technologies that, while very simple at its core, has had a profound impact on the technical landscape. Most modern public API's rely on JSON to transport information between application layers. It's become essential from everything ranging from Web API's, compiler technologies, and even data storage.

With that said, it's essential for an up-and-coming web tech stack like Rust and Rocket to support it. And support it they do.

Step 1: Install Dependencies
For some reason, the official Rocket documentation hides the fact that you need dependencies outside of rocket_codegen and rocket in order to return JSON.

You need to have all of the following lines in your Cargo.toml file:

rocket = "0.3.3"
rocket_codegen = "0.3.3"
rocket_contrib = "0.3.3"
Obviously, these versions will change over time. Without these dependencies, you may find yourself with errors such as:

"Cannot find macro json!", "Value cannot be found", etc. when following Rocket's documentation.

Step 2: Start returning JSON
Now, the easy part. I'm going to post the single most rudimentary example of a JSON return ever. In real web projects, you'll want to use serde and serde_derive to turn your data-transfer objects / models into a consistent JSON format. For now, we'll use the json! macro and Json struct to hard-return a value on the root route:

#[get("/")]fn index() -> Json<Value> {
    Json(json!({"value": 5}))
}

fn main() {
    rocket::ignite().mount("/", routes![index]).launch();}