rpsql 0.2.0

A preprocessor for SQL files: variables, includes and comments
Documentation
  • Coverage
  • 100%
    143 out of 143 items documented1 out of 84 items with examples
  • Size
  • Source code size: 111.7 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 1.8 MB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 2s Average build duration of successful builds.
  • all releases: 2s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • Comet11x/rpsql
    0 0 0
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • Comet11x

rpsql

rpsql is a preprocessor for SQL files. It expands variables, inlines included files and strips comments, so that the result can be handed over to a database client. It is a rewrite of the Python project ppsql, with no dependencies outside the standard library.


Table of Contents

Installation

cargo install rpsql

Or from a checkout:

cargo build --release
./target/release/rpsql -i main.sql -o out.sql

Usage

rpsql -i path/to/main.sql -o path/to/out.sql
rpsql -i path/to/queries    -o path/to/out.sql   # reads queries/index.sql

The repository ships an example that runs as it is:

cargo run -- -i main.sql -o out.sql   # the file example
cargo run -- -i queries -o out.sql    # the directory example
Option Description Default
-i, --input <PATH> entry point, a file or a directory -
-s, --source <DIR> source directory current dir
-o, --out <FILE> file that receives the result ./out.sql
-e, --env <PATH> file or directory holding a .env file current dir
-c, --credential <DIR> directory holding a .password file home dir
-d, --debug verbose logging on standard error off
-h, --help print the usage -
-V, --version print the version -

The entry point and an @include accept a directory as well as a file: a directory is read as the index.sql it holds, and a directory without one is reported as an error. Values can be written as --input main.sql or --input=main.sql. A failed run prints one line on standard error and exits with 1, a wrong command line exits with 2.

Directives

Every directive is written on its own line and is removed from the output.

Directive Description
@set name = value sets a variable of the file
@set global name = value sets a variable of the global scope
@unset name removes a variable
@include path inlines a file, or the index.sql of a directory

A file is built in two passes. The first one applies the directives of the file and of everything it includes, so every variable of a file is known before it is used. The second one replaces the variable references that are left. Lines that come from an included file are already preprocessed and are not touched again, which keeps the scopes of the files apart.

A line that starts with -- is a comment and is dropped. A variable is looked up in the scope of the file first, then in the global scope, which starts as a copy of the environment and grows with --env and --credential files.

Variables

A reference is written $name or ${name}, where name starts with a letter and continues with letters, digits and underscores. The second form is the one to use when the name touches other characters. \$ is a literal dollar sign, and a dollar sign that is not followed by a name is left alone. An unknown variable is an error that names the file and the line.

-- main.sql, the entry point of the example
@set table = users
@set columns = id, name, email
@set order_by = created_at desc

@include queries/rows.sql

select count(*) as total from ${table};

The included file sees the variables of the file that includes it:

-- queries/rows.sql
select
    ${columns}
from
    ${table}
order by
    ${order_by};

Every directive of a file is applied before any of its variables is replaced, so @set and @unset apply to the whole file and not only to the lines that follow them. An include is built with the variables as they are where it is written, and its own variables stay in the file that declares them.

Library

use rpsql::{Builder, Error, Result};

fn main() -> Result<()> {
    let sql = Builder::new("main.sql").build()?;
    println!("{sql}");
    Ok(())
}
Item Responsibility
Builder builds an entry point and the files it includes
Context the lines of a file, its variables and its include chain
VariableScope local and global variables
Loader reads a file into a Context
Writer writes the result into a file
actions the directive handlers and the variable expander
cli the arguments, load_env, load_password, run
Error every failure, with the position when it is known

Development

cargo build            # build the library and the binary
cargo test             # run the unit, integration and documentation tests
cargo fmt --check      # check the formatting
cargo clippy --all-targets -- -D warnings
cargo doc --open       # read the documentation
cargo publish --dry-run

License

rpsql is distributed under the terms of the MIT license.