rustyroad 1.0.23

Rusty Road is a framework written in Rust that is based on Ruby on Rails. It is designed to provide the familiar conventions and ease of use of Ruby on Rails, while also taking advantage of the performance and efficiency of Rust.
Documentation

Hackathon Status GitHub Issues GitHub Pull Requests License

In loving memory of Rusty, Rusty was my dog who passed away in September 2023. He was a wonderful loving pup. I am forever grateful for the time I had with him. He was my best friend and I will miss him dearly. I love you Rusty. 2014 - 2023

Note: Rusty Road is still in development. Please use the release candidate or the cargo crate. Do not use master for production purposes. It is still under heavy development and is not ready for production use.

🆕 What's New in Rusty Road 0.1.8

  • Rusty Road now includes GrapeJS, a drag and drop website builder. You can add it to your project by running rustyroad feature add grapesjs.
    1. You can read more about GrapeJS here.
    2. Find the example project here.
  • Stable release of PostgreSQL support.
  • Beta release of MySQL support.
  • Beta release of SQLite support.

📝 Table of Contents

🧐 Problem Statement

Rust Needs a Rails

I outlined this in a blog post here: https://rileyseaburg.com/posts/rust-needs-a-rails

  • IDEAL: In a perfect world, Rust would have a framework that is as easy to use as Ruby on Rails. It would be easy to learn, easy to use, and easy to maintain. It would be fast, secure, and reliable. It would be extensible and customizable. It would be a joy to use.
  • REALITY: Rust is a powerful language, but it is not easy to use. It is not easy to learn, and it is not easy to maintain. It is not fast to build with, even though it is secure, there is no framework that is as easy to use as Ruby on Rails. Rust is still the most loved programming language.

💡 Idea / Solution

Rusty Road is a framework written in Rust that is based on Ruby on Rails. It is designed to provide the familiar conventions and ease of use of Ruby on Rails, while also taking advantage of the performance and efficiency of Rust.

:dog: What is Rusty Road

Rusty Road is a framework written in Rust that is based on Ruby on Rails. It is designed to provide the familiar conventions and ease of use of Ruby on Rails, while also taking advantage of the performance and efficiency of Rust.

Rusty Road is intended to offer developers a powerful and reliable platform for building web applications using Rust, and its name incorporates a rust-themed crab pun in a playful and memorable way.

Understanding Rusty Road

Rusty Road currently works with the actix web framework, Sqlx, the Tera template engine, MySQL, PostgreSQL, and SQLite. It also has an additional optional feature that allows yout to add the GrapesJs editor with tailwind css support to your project.

🎈 Current Features

  • Database migrations
  • Support for PostgreSQL
  • Support for MySQL
  • Support for SQLite
  • Routing (actix)
  • Templating (Tera)
  • CSS Framework (Tailwind CSS)
  • Optional support for GrapesJs editor with tailwind css support

🚀 Future Scope

  • Add support for GraphQL.
  • Add support for API based microservices.
  • Add support for more asset pipelines.
  • Add kubernetes support.
  • Add support for more authentication frameworks.

🏁 Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Understanding the Build Process

Before diving into the setup and resolving the known issues, it’s crucial to understand how the build process works in this project and why certain steps are essential.

Why Use build.rs?

The build.rs file in Rust is a build script, executed before the Rust compiler to perform various tasks, such as compiling linked C libraries, generating code, and more.

In this project, build.rs performs crucial tasks:

  1. PostgreSQL Linkage: It handles the linkage to the PostgreSQL library. If the build script cannot find the required PostgreSQL library, it will cause a build failure, hence the need to set up environment variables correctly, as mentioned in the Solving PostgreSQL linkage issue section.

  2. Node.js Integration: It ensures the correct Node.js version is used and runs the build for the Node.js part of the project, housed in the grapesjs-tailwind directory. This is vital for integrating GrapesJS, a JavaScript framework, into the Rust project.

  3. JavaScript File Inclusion: To include the JavaScript file (grapesjs-tailwind.min.js) required for GrapesJS, the build script copies this file to a known location during compile time. The Rust code then includes the file content using include_bytes! from this known location. This approach is robust, portable, and does not rely on the absolute path of the file.

🛠️ Setup and Installation

1. Install Prerequisites

Before you start, make sure you have Rust installed on your machine. If not, you can install it using rustup. Also, follow the instructions in the Installing Node Version Manager (nvm) for Windows section to set up Node.js.

2. Resolve Known Issues

3. Clone and Build the Project

  • Clone the project to your local machine.
  • Navigate to the project directory and run cargo build to build the project.

4. Verify the Build

  • Ensure that there are no errors during the build process.
  • If any issues arise, refer to the Known Issues section and make sure all prerequisites are correctly installed and configured.

🚀 Running the Project

Once you have resolved the known issues and understood the build process, you can run the project locally for development and testing purposes. Use cargo run to start the project, and follow the on-screen instructions or refer to the project documentation for using and testing the implemented features.

⚠️ Note

Understanding the build process and resolving known issues are crucial steps in setting up the project. While they might seem cumbersome, they ensure that the project runs seamlessly across different environments and configurations, laying a solid foundation for development, testing, and deployment.

Known Issues

There are a couple known issues, but they are easy to fix.

Solving PostgreSQL linkage issue

If you encounter an error like this: LINK : fatal error LNK1181: cannot open input file 'libpq.lib', it means the project is not able to find the libpq library. Follow these steps to resolve the issue:

  1. If you haven't already, download and install PostgreSQL binaries for Windows from the official website.

  2. Make sure to install it in an easily accessible location, like C:\\Program Files\\PostgreSQL\\13\\.

  3. Set the POSTGRES_LIB_PATH environment variable pointing to your PostgreSQL lib directory where libpq.lib resides:

    • Press Windows key -> Type 'Environment Variables' -> Click on 'Edit the system environment variables' -> Click the 'Environment Variables...' button -> Under the 'System Variables' section, click the 'New...' button -> For 'Variable name', enter 'POSTGRES_LIB_PATH'. For 'Variable value', enter the path to the directory containing libpq.lib` -> Confirm and apply the changes. Remember, you might need to open a new command prompt or PowerShell window for the changes to take effect.

  4. After you generate a website using rustyRoad, if you are on windows.

    • Create or edit the config.toml file inside the .cargo directory in your rustyroad project's root directory (create the .cargo directory if it doesn't exist). Add the following lines, replacing C:\\Program Files\\PostgreSQL\\13\\lib with your actual path where your libpq.lib is located. Remember to use double backslashes \\ for cross-platform compatibility.
    [target.'cfg(windows)']

rustflags = ["-C", "link-arg=/LIBPATH:C:\\Program Files\\PostgreSQL\\13\\lib"]

Rust CI Crates.io Docs.rs Issues PRs License

RustyRoad is under active development. For day-to-day use, prefer the latest released version on crates.io.

What is RustyRoad?

How rustyroad.toml is used

RustyRoad reads your database settings from a TOML file in your project root.

  • Default (dev): RustyRoad reads ./rustyroad.toml
  • If ENVIRONMENT is set and not dev: RustyRoad reads ./rustyroad.<ENVIRONMENT>.toml

Examples:

  • ENVIRONMENT=prod → reads rustyroad.prod.toml
  • ENVIRONMENT=test → reads rustyroad.test.toml

There is no special rustyroad.dev.toml—dev is the plain rustyroad.toml file.

If you’re unsure what RustyRoad is going to read on your machine, run:

rustyroad config

(It prints ENVIRONMENT=..., the config filename, and a sanitized view of the parsed database settings.)

RustyRoad is a Rust CLI + generator toolkit inspired by Ruby on Rails.

It focuses on:

  • generating a consistent project structure
  • generating controllers/routes/models
  • generating and running database migrations
  • providing a few productivity-focused database commands

Under the hood, generated projects use Actix for HTTP, Tera for templates, and SQLx for database support.

If you’re curious about the motivation, there’s a short write-up here: https://rileyseaburg.com/posts/rust-needs-a-rails

Features

  • Project generator (rustyroad new)
  • Generators (rustyroad generate ...)
  • Database migrations (rustyroad migration ...)
  • Database inspection / queries (rustyroad db ..., rustyroad query ...)
  • Optional GrapesJS feature (drag-and-drop editor) via rustyroad feature add grapesjs

Install

From crates.io

cargo install rustyroad

From source

git clone --recurse-submodules https://github.com/RustyRoad/RustyRoad

cd RustyRoad

cargo build

Quick start

Create a new project:

rustyroad new my_project

Generate a route/controller:

rustyroad generate route users

Migrations

RustyRoad expects migrations in this exact location (do not create a plain ./migrations/ folder):

  • ./config/database/migrations/<timestamp>-<name>/up.sql
  • ./config/database/migrations/<timestamp>-<name>/down.sql

List migrations:

rustyroad migration list

Run all migrations (up) in order:

rustyroad migration all

Run a single migration by name (the name is the part after the timestamp in the folder name):

rustyroad migration run create_users_table

Generate a migration (folder + files):

rustyroad migration generate create_users_table id:serial:primary_key email:string:not_null,unique

Database commands

Inspect schema:

rustyroad db schema

Run ad-hoc queries:

rustyroad query "SELECT * FROM users LIMIT 10;"

rustyroad query "SELECT COUNT(*) AS total_users FROM users;"

Optional: GrapesJS

RustyRoad can scaffold an optional GrapesJS editor experience:

rustyroad feature add grapesjs

You can learn more about GrapesJS at https://grapesjs.com/ and see the example project at example-grapesjs/.

Examples

  • example/ – a basic generated app
  • example-grapesjs/ – a generated app with GrapesJS enabled

Troubleshooting

Building from source on Windows (PostgreSQL linkage)

If you build this repository from source on Windows and see errors about POSTGRES_LIB_PATH or libpq.lib, install PostgreSQL and set POSTGRES_LIB_PATH to the directory containing libpq.lib.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md.

License

MIT — see LICENSE.

Dedication

Dedicated to Rusty (2014–2023). ❤️