use std::ffi::OsString;
use std::io::{self, IsTerminal, Read, Write};
use std::path::PathBuf;
use std::process::ExitCode;
use clap::parser::ValueSource;
use clap::{ArgMatches, CommandFactory, FromArgMatches, Parser};
use datafusion::error::DataFusionError;
use datafusion::prelude::SessionContext;
mod input;
mod notices;
mod print;
mod repl;
mod shell;
mod startup;
mod timer;
use print::{is_broken_pipe, OutputFormat, DEFAULT_MAX_ROWS};
use shell::{Flow, Shell};
const SKILL: &str = include_str!("ursa-sql-skill.md");
const AFTER_HELP: &str = concat!(
"Examples:\n",
" ursa -c \"SELECT * FROM 'edges.parquet' LIMIT 3\" # any file is a table\n",
" ursa --format json -c \"SELECT * FROM ursa_functions()\" # JSON, for programs\n",
" ursa club.ursa -f query.sql # SQL and dot-commands\n",
" ursa club.ursa # the shell (.help)\n",
"\n",
"An edge table is a graph:\n",
" CREATE PROPERTY GRAPH g EDGE TABLES (ties SOURCE KEY (src) DESTINATION KEY (dst));\n",
" SELECT * FROM pagerank(g) ORDER BY pagerank DESC LIMIT 5;\n",
"\n",
"SELECT * FROM ursa_functions() lists the graph functions and their parameters.\n",
"ursa --skill prints a guide to writing Ursa SQL, for coding agents.\n",
"Docs: https://cldixon.github.io/ursa/sql/",
);
#[derive(Debug, Parser)]
#[command(
name = "ursa",
version = env!("URSA_VERSION"),
about = "SQL for graph analytics over Parquet, CSV, JSON and Arrow files, local or in object storage.",
after_help = AFTER_HELP
)]
struct Args {
#[arg(value_name = "DATABASE")]
database: Option<String>,
#[arg(long = "readonly", requires = "database")]
readonly: bool,
#[arg(short = 'c', long = "command", value_name = "SQL")]
command: Vec<String>,
#[arg(short = 'f', long = "file", value_name = "PATH")]
file: Vec<PathBuf>,
#[arg(long = "format", value_enum, default_value_t = OutputFormat::Table)]
format: OutputFormat,
#[arg(long = "max-rows", value_name = "N", default_value_t = DEFAULT_MAX_ROWS)]
max_rows: usize,
#[arg(long = "init", value_name = "FILE", conflicts_with = "no_init")]
init: Option<PathBuf>,
#[arg(long = "no-init")]
no_init: bool,
#[arg(long = "no-history")]
no_history: bool,
#[arg(long = "skill")]
skill: bool,
#[arg(short = 'q', long = "quiet")]
quiet: bool,
}
enum Source {
Command(String),
File(PathBuf),
Stdin(String),
}
fn main() -> ExitCode {
let matches = Args::command().get_matches_from(single_dash_longs(std::env::args_os()));
let args = match Args::from_arg_matches(&matches) {
Ok(args) => args,
Err(e) => e.exit(),
};
if args.skill {
let _ = io::stdout().write_all(SKILL.as_bytes());
return ExitCode::SUCCESS;
}
if let Some(database) = &args.database {
if !database.ends_with(".ursa") {
return fail(&format!(
"'{database}' is not a database file (those end in .ursa); to run SQL, use \
-c \"<sql>\" or --file <path>"
));
}
}
let mut sources = sources_in_order(&args, &matches);
let interactive = sources.is_empty() && io::stdin().is_terminal();
if interactive && args.format == OutputFormat::Arrow {
return fail("the shell cannot show the arrow format; use --format arrow with -c or -f");
}
if sources.is_empty() && !interactive {
let mut sql = String::new();
if let Err(e) = io::stdin().read_to_string(&mut sql) {
return fail(&format!("cannot read SQL from stdin: {e}"));
}
if !sql.trim().is_empty() {
sources.push(Source::Stdin(sql));
}
}
let runtime = match tokio::runtime::Builder::new_multi_thread()
.enable_all()
.build()
{
Ok(runtime) => runtime,
Err(e) => return fail(&format!("cannot start: {e}")),
};
let given = Given {
format: matches.value_source("format") == Some(ValueSource::CommandLine),
max_rows: matches.value_source("max_rows") == Some(ValueSource::CommandLine),
};
if !interactive {
cancel_on_interrupt();
}
let result = runtime.block_on(run(sources, &args, interactive, given));
runtime.shutdown_background();
match result {
Ok(true) => ExitCode::SUCCESS,
Ok(false) => ExitCode::FAILURE,
Err(e) if is_broken_pipe(&e) => ExitCode::SUCCESS,
Err(e) => fail(&ursa_engine::user_message(&e)),
}
}
#[derive(Debug, Clone, Copy)]
struct Given {
format: bool,
max_rows: bool,
}
const INTERRUPTED_STATUS: i32 = 130;
fn cancel_on_interrupt() {
let waiting = std::thread::Builder::new()
.name("ursa-sigint".into())
.spawn(|| {
let Ok(runtime) = tokio::runtime::Builder::new_current_thread()
.enable_all()
.build()
else {
return;
};
if runtime.block_on(tokio::signal::ctrl_c()).is_ok() {
print::interrupt();
let mut err = io::stderr().lock();
let _ = writeln!(err, "Error: interrupted");
let _ = err.flush();
std::process::exit(INTERRUPTED_STATUS);
}
});
drop(waiting);
}
fn sources_in_order(args: &Args, matches: &ArgMatches) -> Vec<Source> {
let commands = matches
.indices_of("command")
.into_iter()
.flatten()
.zip(args.command.iter().cloned().map(Source::Command));
let files = matches
.indices_of("file")
.into_iter()
.flatten()
.zip(args.file.iter().cloned().map(Source::File));
let mut sources: Vec<(usize, Source)> = commands.chain(files).collect();
sources.sort_by_key(|(index, _)| *index);
sources.into_iter().map(|(_, source)| source).collect()
}
fn format_hint(path: &std::path::Path) -> String {
use clap::ValueEnum;
let name = path.to_string_lossy();
let is_format = OutputFormat::value_variants().iter().any(|f| {
f.to_possible_value()
.is_some_and(|v| v.matches(&name, true))
});
if is_format && !path.exists() {
format!("; to choose the output format, use --format {name}")
} else {
String::new()
}
}
fn single_dash_longs(args: impl IntoIterator<Item = OsString>) -> Vec<OsString> {
const TAKE_VALUES: [&str; 7] = [
"-c",
"--command",
"--file",
"-f",
"--format",
"--init",
"--max-rows",
];
let mut out: Vec<OsString> = Vec::new();
for arg in args {
let is_value = out.len() > 1
&& out
.last()
.is_some_and(|previous| TAKE_VALUES.iter().any(|option| previous == option));
let rewritten = match arg.to_str() {
_ if is_value || out.is_empty() => arg,
Some("-init") => "--init".into(),
Some("-no-init") => "--no-init".into(),
Some(a) if a.starts_with("-init=") => format!("-{a}").into(),
_ => arg,
};
out.push(rewritten);
}
out
}
fn fail(message: &str) -> ExitCode {
eprintln!("Error: {message}");
ExitCode::FAILURE
}
async fn run(
sources: Vec<Source>,
args: &Args,
interactive: bool,
given: Given,
) -> Result<bool, DataFusionError> {
let ctx = match &args.database {
Some(path) => {
let options = ursa_sql::OpenOptions {
read_only: args.readonly,
..Default::default()
};
ursa_sql::open_session(path, &options).await?
}
None => ursa_engine::new_session(),
};
if !args.quiet {
notices::to_stderr(&ctx);
}
let result = run_session(ctx.clone(), sources, args, interactive, given).await;
ursa_engine::database::flush(&ctx.state());
if std::env::var_os(INDEX_STATS_VAR).is_some() {
eprintln!(
"ursa: graph indexes built {}, loaded {}",
ursa_engine::graph::index_builds(&ctx),
ursa_engine::graph::index_loads(&ctx)
);
}
result
}
const INDEX_STATS_VAR: &str = "URSA_INDEX_STATS";
async fn run_session(
ctx: SessionContext,
sources: Vec<Source>,
args: &Args,
interactive: bool,
given: Given,
) -> Result<bool, DataFusionError> {
let home = startup::home_dir();
let init = startup::init_file(
args.init.as_deref(),
args.no_init,
interactive,
home.as_deref(),
);
if !interactive && init.is_none() && sources.is_empty() {
return Ok(true);
}
let out: Box<dyn Write> = if interactive {
Box::new(io::stdout())
} else {
Box::new(io::BufWriter::new(print::Interruptible(io::stdout())))
};
let mut shell = Shell::new(ctx, args.format, out, io::stderr());
shell.set_max_rows(args.max_rows);
if interactive {
println!("{}", banner(args));
}
if let Some(init) = init {
if shell.run_file(&init).await == Flow::Exit {
return Ok(true);
}
if given.format {
shell.set_mode(args.format);
}
if given.max_rows {
shell.set_max_rows(args.max_rows);
}
}
if interactive {
let history = startup::history_file(
args.no_history,
std::env::var_os(startup::HISTORY_VAR),
home.as_deref(),
);
repl::run(&mut shell, history)
.await
.map_err(|e| DataFusionError::External(Box::new(e)))?;
return Ok(true);
}
shell.stop_on_error();
for source in sources {
let text = match source {
Source::Command(sql) | Source::Stdin(sql) => sql,
Source::File(path) => std::fs::read_to_string(&path).map_err(|e| {
DataFusionError::Execution(format!(
"cannot read '{}': {e}{}",
path.display(),
format_hint(&path)
))
})?,
};
if shell.run_text(&text).await == Flow::Exit {
break;
}
}
Ok(!shell.failed())
}
fn banner(args: &Args) -> String {
let session = match &args.database {
Some(path) if args.readonly => format!("database {path} (read-only)"),
Some(path) => format!("database {path}"),
None => "in memory".to_string(),
};
format!(
"ursa {}, {session}. Enter .help for commands, .quit to exit.",
env!("URSA_VERSION")
)
}
#[cfg(test)]
mod tests {
use super::*;
fn rewrite(args: &[&str]) -> Vec<String> {
single_dash_longs(args.iter().map(OsString::from))
.into_iter()
.map(|a| a.into_string().unwrap())
.collect()
}
#[test]
fn single_dash_init_is_rewritten() {
assert_eq!(
rewrite(&["ursa", "-init", "a.sql", "club.ursa"]),
["ursa", "--init", "a.sql", "club.ursa"]
);
assert_eq!(rewrite(&["ursa", "-no-init"]), ["ursa", "--no-init"]);
assert_eq!(rewrite(&["ursa", "-init=a.sql"]), ["ursa", "--init=a.sql"]);
assert_eq!(
rewrite(&["ursa", "-c", "-init", "--init", "-no-init"]),
["ursa", "-c", "-init", "--init", "-no-init"]
);
assert_eq!(rewrite(&["-init"]), ["-init"]);
}
#[test]
fn flags_parse() {
let args =
Args::try_parse_from(rewrite(&["ursa", "-init", "a.sql", "--no-history"])).unwrap();
assert_eq!(args.init, Some(PathBuf::from("a.sql")));
assert!(args.no_history && !args.no_init);
assert!(Args::try_parse_from(["ursa", "--init", "a.sql", "--no-init"]).is_err());
}
#[test]
fn the_banner_names_the_session() {
let version = env!("URSA_VERSION");
let args = Args::try_parse_from(["ursa"]).unwrap();
assert_eq!(
banner(&args),
format!("ursa {version}, in memory. Enter .help for commands, .quit to exit.")
);
let args = Args::try_parse_from(["ursa", "club.ursa", "--readonly"]).unwrap();
assert!(
banner(&args).starts_with(&format!("ursa {version}, database club.ursa (read-only).")),
"{}",
banner(&args)
);
}
}