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};
27use rustyline::hint::{Hinter, HistoryHinter};
28use rustyline::validate::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 arguments;
88mod completion;
89mod diagnostics;
90mod display;
91mod highlight;
92mod interrupt;
93mod lexer;
94mod meta;
95mod migration_io;
96mod output;
97mod printing;
98mod repl;
99mod shell;
100mod shell_catalog;
101mod shell_commands;
102mod shell_copy;
103mod shell_history;
104mod shell_notifications;
105mod sql_help;
106mod statements;
107mod variables;
108
109use completion::{UsqlEditor, UsqlHelper};
110use display::{
111    foreign_table_options_display, optional_value_to_display_value, options_display,
112    print_backslash_help, print_columns, result_row, sequence_row, sql_type_name, u64_count_value,
113    usize_count_value,
114};
115use migration_io::{open_engine, print_migration_report, print_migration_report_stdout};
116use output::{history_path, print_result, print_result_copy_text_with_engine, value_to_display};
117use repl::{PromptLineOutcome, Session};
118#[cfg(test)]
119use statements::contains_statement_terminator;
120use statements::{
121    contains_input_terminator, split_statements, statement_is_pure_comment,
122    unescape_psql_semicolons,
123};
124
125/// Run `usql` with the current process arguments and standard streams.
126pub fn run_from_env() -> ExitCode {
127    if let Err(error) = interrupt::install() {
128        eprintln!("{error}");
129        return ExitCode::FAILURE;
130    }
131    let args: Vec<String> = std::env::args().skip(1).collect();
132    run_from_args(&args)
133}
134
135/// Run `usql` with explicit arguments excluding the executable name, using the standard streams.
136pub fn run_from_args(args: &[String]) -> ExitCode {
137    let action = match CliAction::parse(args) {
138        Ok(action) => action,
139        Err(err) => {
140            eprintln!("{err}");
141            print_usage_stderr();
142            return ExitCode::FAILURE;
143        }
144    };
145    match action {
146        CliAction::Help => match print_usage_stdout() {
147            Ok(()) => ExitCode::SUCCESS,
148            Err(error) => {
149                eprintln!("write help output: {error}");
150                ExitCode::FAILURE
151            }
152        },
153        CliAction::Migrate {
154            source,
155            destination,
156        } => match migrate_python_database(&source, &destination) {
157            Ok(report) => match print_migration_report_stdout(&report) {
158                Ok(()) => ExitCode::SUCCESS,
159                Err(error) => {
160                    eprintln!("write migration report: {error}");
161                    ExitCode::FAILURE
162                }
163            },
164            Err(err) => {
165                eprintln!("migration failed: {err}");
166                ExitCode::FAILURE
167            }
168        },
169        CliAction::Run(args) => run_cli(args),
170    }
171}
172
173fn run_cli(args: CliArgs) -> ExitCode {
174    let key = match args.resolve_key() {
175        Ok(key) => key,
176        Err(err) => {
177            eprintln!("{err}");
178            return ExitCode::FAILURE;
179        }
180    };
181    let session = if args.command.is_some() {
182        Session::new_without_history(args.db_path.clone(), key.as_deref())
183    } else {
184        Session::new(args.db_path.clone(), key.as_deref())
185    };
186    let mut session = match session {
187        Ok(session) => session,
188        Err(err) => {
189            eprintln!("{err}");
190            return ExitCode::FAILURE;
191        }
192    };
193    session.copy_text = args.copy_text;
194    let stdin = io::stdin();
195    let stdout = io::stdout();
196    // Do not hold stdout's lock while waiting for input: signal-driven process exit
197    // flushes stdout from the interrupt thread.
198    let mut out = TrackedWriter::new(stdout);
199
200    let exit = if let Some(command) = args.command {
201        let result = if command.trim_start().starts_with('\\') {
202            match session.process_line(&command, &mut String::new(), &mut out, false) {
203                PromptLineOutcome::Failed => Err("shell command failed".into()),
204                _ => Ok(()),
205            }
206        } else {
207            session.execute_command_text_with_history(&command, &mut out, false)
208        };
209        match result {
210            Ok(()) => ExitCode::SUCCESS,
211            Err(err) => {
212                let _ = writeln!(out, "ERROR: {err}");
213                ExitCode::FAILURE
214            }
215        }
216    } else {
217        let generation = interrupt::generation();
218        let mut scripts_succeeded = true;
219        for script in &args.scripts {
220            if let Err(err) = session.run_file(script, &mut out) {
221                eprintln!("{err}");
222                scripts_succeeded = false;
223                break;
224            }
225            if session.shell.quit {
226                break;
227            }
228        }
229
230        if interrupt::generation() != generation {
231            ExitCode::from(3)
232        } else if !scripts_succeeded {
233            ExitCode::FAILURE
234        } else if session.shell.quit || (!args.scripts.is_empty() && !stdin.is_terminal()) {
235            ExitCode::SUCCESS
236        } else {
237            session.run_repl(&mut out)
238        }
239    };
240
241    if let Some(error) = out.error() {
242        eprintln!("write command output: {error}");
243        ExitCode::FAILURE
244    } else {
245        exit
246    }
247}
248
249#[derive(Debug)]
250enum CliAction {
251    Help,
252    Migrate {
253        source: PathBuf,
254        destination: PathBuf,
255    },
256    Run(CliArgs),
257}
258
259#[derive(Debug, Default)]
260struct CliArgs {
261    db_path: Option<PathBuf>,
262    command: Option<String>,
263    scripts: Vec<PathBuf>,
264    key: Option<String>,
265    key_file: Option<PathBuf>,
266    copy_text: bool,
267}
268
269impl CliArgs {
270    /// Resolve the encryption key with `--key` > `--key-file` >
271    /// `UQA_KEY` precedence. Only the final trailing newline of a key
272    /// file is stripped so keys may contain interior whitespace.
273    fn resolve_key(&self) -> Result<Option<String>, String> {
274        if let Some(key) = &self.key {
275            return Ok(Some(key.clone()));
276        }
277        if let Some(path) = &self.key_file {
278            let raw = std::fs::read_to_string(path)
279                .map_err(|err| format!("failed to read key file {}: {err}", path.display()))?;
280            let key = raw.strip_suffix('\n').unwrap_or(&raw);
281            let key = key.strip_suffix('\r').unwrap_or(key);
282            if key.is_empty() {
283                return Err(format!("key file {} is empty", path.display()));
284            }
285            return Ok(Some(key.to_string()));
286        }
287        match std::env::var("UQA_KEY") {
288            Ok(key) if !key.is_empty() => Ok(Some(key)),
289            _ => Ok(None),
290        }
291    }
292}
293
294impl CliAction {
295    fn parse(args: &[String]) -> Result<Self, String> {
296        match args {
297            [cmd] if cmd == "-h" || cmd == "--help" => return Ok(Self::Help),
298            [cmd, source, destination]
299                if cmd == "migrate-python-db" || cmd == "--migrate-python-db" =>
300            {
301                return Ok(Self::Migrate {
302                    source: PathBuf::from(source),
303                    destination: PathBuf::from(destination),
304                });
305            }
306            _ => {}
307        }
308
309        let mut parsed = CliArgs::default();
310        let mut i = 0;
311        while i < args.len() {
312            match args[i].as_str() {
313                "--db" => {
314                    let Some(path) = args.get(i + 1) else {
315                        return Err("--db requires a path".into());
316                    };
317                    parsed.db_path = Some(PathBuf::from(path));
318                    i += 2;
319                }
320                "-c" => {
321                    let Some(command) = args.get(i + 1) else {
322                        return Err("-c requires a SQL command string".into());
323                    };
324                    parsed.command = Some(command.clone());
325                    i += 2;
326                }
327                "--key" => {
328                    let Some(key) = args.get(i + 1) else {
329                        return Err("--key requires an encryption key".into());
330                    };
331                    if parsed.key_file.is_some() {
332                        return Err("--key and --key-file are mutually exclusive".into());
333                    }
334                    parsed.key = Some(key.clone());
335                    i += 2;
336                }
337                "--key-file" => {
338                    let Some(path) = args.get(i + 1) else {
339                        return Err("--key-file requires a path".into());
340                    };
341                    if parsed.key.is_some() {
342                        return Err("--key and --key-file are mutually exclusive".into());
343                    }
344                    parsed.key_file = Some(PathBuf::from(path));
345                    i += 2;
346                }
347                "--copy-text" => {
348                    parsed.copy_text = true;
349                    i += 1;
350                }
351                "-h" | "--help" => return Ok(Self::Help),
352                arg if arg.starts_with('-') => return Err(format!("unknown option: {arg}")),
353                script => {
354                    parsed.scripts.push(PathBuf::from(script));
355                    i += 1;
356                }
357            }
358        }
359        Ok(Self::Run(parsed))
360    }
361}
362
363fn print_usage_stdout() -> io::Result<()> {
364    writeln!(io::stdout().lock(), "{}", usage_text())
365}
366
367fn print_usage_stderr() {
368    eprintln!("{}", usage_text());
369}
370
371fn usage_text() -> &'static str {
372    "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."
373}
374
375#[cfg(test)]
376#[path = "main_tests.rs"]
377mod tests;
378
379#[cfg(test)]
380mod shell_tests;