maxcountryman/forma

🐚 An opinionated SQL formatter.

forma 🐚

An opinionated SQL formatter.

📦 Install

The binary may be installed via cargo:

$ cargo install forma

Further the companion library formation may be required as a dependency:

[dependencies]
formation = "0.3.0"

🤸 Usage

⚠️ forma should be considered alpha quality, with several known, and many more unknown deficiencies. Use at your own risk!

Give forma some SQL via a file path or stdin and you'll get back formatted SQL.

$ echo "SELECT * FROM users" | forma
select * from users;

To format a SQL file, simply give forma the file path.

$ forma path/to/some/sql/example.sql

And if you'd prefer to not actually format the SQL but know if formatting would happen then use the --check flag.

The binary is a thin wrapper around the formation library, which can be used in your own applications to format SQL.

use formation::format;
let sql = "SELECT * FROM users;";
assert_eq!(
    format(sql, false, 100).unwrap(),
    vec!["select * from users;\n".to_owned()]
);

🚧 TODOs

• Comprehensive Statement variant support (currently only Query)
• Support for comments (these will be eaten by the formatter!)
• Parameterized dialects

forma's Issues

Support create, etc queries

Currently forma only works with select ... statements. However, the parser supports essentially any arbitrary query.

Modifying formation to cover the full enum should provide the missing coverage.

Experiment with lossless parser

In order to eventually support comments, we'll need to use a parsing method that is lossless. Such an effort is already underway, but will require reworking formation.

[proposal] Errors organized by phase

Which of these make more sense?

/// Forma error type.
#[derive(Debug)]
pub enum FormaError {
  InputErrorType1,
  InputErrorType2,
  TransformationErrorType1,
  TransformationErrorType2,
  OutputErrorType1,
  OutputErrorType2
}

or:

#[derive(Debug)]
pub enum InputError {
  Something1,
  Something2
}

#[derive(Debug)]
pub enum FormaError {
  Input(InputError),
  Transformation(TransformationError),
  Output(OutputError)
}

Parameterize dialect

Currently forma supplies a slightly modified generic dialect. It would be nice if the caller could specify their own dialects.