Skip to main content

uqa_cli/
lib.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! `usql`: interactive REPL for UQA.
8//!
9//! Reads SQL statements terminated by `;` from stdin, runs each
10//! through [`uqa_engine::Engine`], and prints the result rows in a
11//! plain aligned table. A handful of meta commands round out the
12//! REPL: `\q` to quit, `\open <path>` to switch to persistent storage,
13//! `\new` to drop back to an in-memory engine, `\help` for the full
14//! list. Designed for piped input as well: when stdin is not a terminal,
15//! we read every statement until EOF and exit.
16
17use std::borrow::Cow;
18use std::collections::{BTreeMap, BTreeSet};
19use std::fs::OpenOptions;
20use std::io::{self, BufRead, IsTerminal, Write};
21use std::path::{Path, PathBuf};
22use std::process::ExitCode;
23
24use rustyline::completion::{Completer, Pair};
25use rustyline::error::ReadlineError;
26use rustyline::highlight::{CmdKind, Highlighter, MatchingBracketHighlighter};
27use rustyline::hint::{Hinter, HistoryHinter};
28use rustyline::validate::{MatchingBracketValidator, Validator};
29use rustyline::{
30    CompletionType, Config, Context, EditMode, Editor, Helper, Result as RustylineResult,
31};
32use uqa_core::Value;
33use uqa_engine::migration::{migrate_python_database, PythonMigrationReport};
34use uqa_engine::{Engine, SQLResult};
35use uqa_graph::GraphStore as _;
36use uqa_sql::ast::{ColumnDef, ColumnType, Expr};
37
38const PROMPT_PRIMARY: &str = "usql> ";
39const PROMPT_CONTINUATION: &str = "    > ";
40const HISTORY_FILE: &str = ".usql_history";
41
42struct TrackedWriter<W> {
43    inner: W,
44    first_error: Option<String>,
45}
46
47impl<W> TrackedWriter<W> {
48    fn new(inner: W) -> Self {
49        Self {
50            inner,
51            first_error: None,
52        }
53    }
54
55    fn error(&self) -> Option<&str> {
56        self.first_error.as_deref()
57    }
58
59    fn remember_error(&mut self, error: &io::Error) {
60        if self.first_error.is_none() {
61            self.first_error = Some(error.to_string());
62        }
63    }
64}
65
66impl<W: Write> Write for TrackedWriter<W> {
67    fn write(&mut self, buffer: &[u8]) -> io::Result<usize> {
68        match self.inner.write(buffer) {
69            Ok(written) => Ok(written),
70            Err(error) => {
71                self.remember_error(&error);
72                Err(error)
73            }
74        }
75    }
76
77    fn flush(&mut self) -> io::Result<()> {
78        match self.inner.flush() {
79            Ok(()) => Ok(()),
80            Err(error) => {
81                self.remember_error(&error);
82                Err(error)
83            }
84        }
85    }
86}
87mod completion;
88mod diagnostics;
89mod display;
90mod meta;
91mod migration_io;
92mod output;
93mod repl;
94mod statements;
95
96use completion::{UsqlEditor, UsqlHelper};
97use display::{
98    foreign_table_options_display, optional_value_to_display_value, options_display,
99    print_backslash_help, print_columns, result_row, sequence_row, sql_type_name, u64_count_value,
100    usize_count_value,
101};
102use migration_io::{
103    open_engine, open_engine_with_key, print_migration_report, print_migration_report_stdout,
104};
105use output::{
106    history_path, print_result, print_result_copy_text_with_engine,
107    print_result_expanded_with_engine, print_result_with_engine, value_to_display,
108};
109use repl::{PromptLineOutcome, Session};
110#[cfg(test)]
111use statements::contains_statement_terminator;
112use statements::{
113    contains_input_terminator, split_statements, statement_is_pure_comment,
114    unescape_psql_semicolons,
115};
116
117/// Run `usql` with the current process arguments and standard streams.
118pub fn run_from_env() -> ExitCode {
119    let args: Vec<String> = std::env::args().skip(1).collect();
120    run_from_args(&args)
121}
122
123/// Run `usql` with explicit arguments excluding the executable name, using the standard streams.
124pub fn run_from_args(args: &[String]) -> ExitCode {
125    let action = match CliAction::parse(args) {
126        Ok(action) => action,
127        Err(err) => {
128            eprintln!("{err}");
129            print_usage_stderr();
130            return ExitCode::FAILURE;
131        }
132    };
133    match action {
134        CliAction::Help => match print_usage_stdout() {
135            Ok(()) => ExitCode::SUCCESS,
136            Err(error) => {
137                eprintln!("write help output: {error}");
138                ExitCode::FAILURE
139            }
140        },
141        CliAction::Migrate {
142            source,
143            destination,
144        } => match migrate_python_database(&source, &destination) {
145            Ok(report) => match print_migration_report_stdout(&report) {
146                Ok(()) => ExitCode::SUCCESS,
147                Err(error) => {
148                    eprintln!("write migration report: {error}");
149                    ExitCode::FAILURE
150                }
151            },
152            Err(err) => {
153                eprintln!("migration failed: {err}");
154                ExitCode::FAILURE
155            }
156        },
157        CliAction::Run(args) => run_cli(args),
158    }
159}
160
161fn run_cli(args: CliArgs) -> ExitCode {
162    let key = match args.resolve_key() {
163        Ok(key) => key,
164        Err(err) => {
165            eprintln!("{err}");
166            return ExitCode::FAILURE;
167        }
168    };
169    let session = if args.command.is_some() {
170        Session::new_without_history(args.db_path.clone(), key.as_deref())
171    } else {
172        Session::new(args.db_path.clone(), key.as_deref())
173    };
174    let mut session = match session {
175        Ok(session) => session,
176        Err(err) => {
177            eprintln!("{err}");
178            return ExitCode::FAILURE;
179        }
180    };
181    session.copy_text = args.copy_text;
182    let stdin = io::stdin();
183    let stdout = io::stdout();
184    let mut out = TrackedWriter::new(stdout.lock());
185
186    let exit = if let Some(command) = args.command {
187        match session.execute_command_text_with_history(&command, &mut out, false) {
188            Ok(()) => ExitCode::SUCCESS,
189            Err(err) => {
190                let _ = writeln!(out, "ERROR: {err}");
191                ExitCode::FAILURE
192            }
193        }
194    } else {
195        let mut scripts_succeeded = true;
196        for script in &args.scripts {
197            if let Err(err) = session.run_file(script, &mut out) {
198                eprintln!("{err}");
199                scripts_succeeded = false;
200                break;
201            }
202        }
203
204        if !scripts_succeeded {
205            ExitCode::FAILURE
206        } else if !args.scripts.is_empty() && !stdin.is_terminal() {
207            ExitCode::SUCCESS
208        } else {
209            session.run_repl(&mut out)
210        }
211    };
212
213    if let Some(error) = out.error() {
214        eprintln!("write command output: {error}");
215        ExitCode::FAILURE
216    } else {
217        exit
218    }
219}
220
221#[derive(Debug)]
222enum CliAction {
223    Help,
224    Migrate {
225        source: PathBuf,
226        destination: PathBuf,
227    },
228    Run(CliArgs),
229}
230
231#[derive(Debug, Default)]
232struct CliArgs {
233    db_path: Option<PathBuf>,
234    command: Option<String>,
235    scripts: Vec<PathBuf>,
236    key: Option<String>,
237    key_file: Option<PathBuf>,
238    copy_text: bool,
239}
240
241impl CliArgs {
242    /// Resolve the encryption key with `--key` > `--key-file` >
243    /// `UQA_KEY` precedence. Only the final trailing newline of a key
244    /// file is stripped so keys may contain interior whitespace.
245    fn resolve_key(&self) -> Result<Option<String>, String> {
246        if let Some(key) = &self.key {
247            return Ok(Some(key.clone()));
248        }
249        if let Some(path) = &self.key_file {
250            let raw = std::fs::read_to_string(path)
251                .map_err(|err| format!("failed to read key file {}: {err}", path.display()))?;
252            let key = raw.strip_suffix('\n').unwrap_or(&raw);
253            let key = key.strip_suffix('\r').unwrap_or(key);
254            if key.is_empty() {
255                return Err(format!("key file {} is empty", path.display()));
256            }
257            return Ok(Some(key.to_string()));
258        }
259        match std::env::var("UQA_KEY") {
260            Ok(key) if !key.is_empty() => Ok(Some(key)),
261            _ => Ok(None),
262        }
263    }
264}
265
266impl CliAction {
267    fn parse(args: &[String]) -> Result<Self, String> {
268        match args {
269            [cmd] if cmd == "-h" || cmd == "--help" => return Ok(Self::Help),
270            [cmd, source, destination]
271                if cmd == "migrate-python-db" || cmd == "--migrate-python-db" =>
272            {
273                return Ok(Self::Migrate {
274                    source: PathBuf::from(source),
275                    destination: PathBuf::from(destination),
276                });
277            }
278            _ => {}
279        }
280
281        let mut parsed = CliArgs::default();
282        let mut i = 0;
283        while i < args.len() {
284            match args[i].as_str() {
285                "--db" => {
286                    let Some(path) = args.get(i + 1) else {
287                        return Err("--db requires a path".into());
288                    };
289                    parsed.db_path = Some(PathBuf::from(path));
290                    i += 2;
291                }
292                "-c" => {
293                    let Some(command) = args.get(i + 1) else {
294                        return Err("-c requires a SQL command string".into());
295                    };
296                    parsed.command = Some(command.clone());
297                    i += 2;
298                }
299                "--key" => {
300                    let Some(key) = args.get(i + 1) else {
301                        return Err("--key requires an encryption key".into());
302                    };
303                    if parsed.key_file.is_some() {
304                        return Err("--key and --key-file are mutually exclusive".into());
305                    }
306                    parsed.key = Some(key.clone());
307                    i += 2;
308                }
309                "--key-file" => {
310                    let Some(path) = args.get(i + 1) else {
311                        return Err("--key-file requires a path".into());
312                    };
313                    if parsed.key.is_some() {
314                        return Err("--key and --key-file are mutually exclusive".into());
315                    }
316                    parsed.key_file = Some(PathBuf::from(path));
317                    i += 2;
318                }
319                "--copy-text" => {
320                    parsed.copy_text = true;
321                    i += 1;
322                }
323                "-h" | "--help" => return Ok(Self::Help),
324                arg if arg.starts_with('-') => return Err(format!("unknown option: {arg}")),
325                script => {
326                    parsed.scripts.push(PathBuf::from(script));
327                    i += 1;
328                }
329            }
330        }
331        Ok(Self::Run(parsed))
332    }
333}
334
335fn print_usage_stdout() -> io::Result<()> {
336    writeln!(io::stdout().lock(), "{}", usage_text())
337}
338
339fn print_usage_stderr() {
340    eprintln!("{}", usage_text());
341}
342
343fn usage_text() -> &'static str {
344    "Usage:\n    usql                        Start with an in-memory database\n    usql --db mydata.db         Start with persistent storage\n    usql script.sql             Execute a SQL script then enter REPL when stdin is a terminal\n    usql --db mydata.db s.sql   Persistent + script\n    usql -c \"SELECT 1\"          Execute a command string and exit\n    usql --copy-text -c \"...\"  Emit rows in PostgreSQL COPY text format\n    usql migrate-python-db <source> <destination>\n\nEncrypted databases:\n    usql --db enc.db --key <key>        Open (or create) an encrypted database\n    usql --db enc.db --key-file <file>  Read the key from a file\n    UQA_KEY=<key> usql --db enc.db      Read the key from the environment\n    Interactive sessions prompt for the key when an encrypted database\n    is opened without one. Compressed containers are detected and\n    opened automatically, including encrypted ones."
345}
346
347#[cfg(test)]
348#[path = "main_tests.rs"]
349mod tests;