Frequently Asked Questions

How do I install SQL Agent CLI?

Installing SQL Agent CLI is quick and straightforward on Windows, macOS, and Linux. First, download the appropriate installer for your operating system from our downloads page. For Windows users, run the .exe installer and follow the setup wizard. macOS users can install via the .pkg installer. Linux users have multiple options including DEB packages for Debian/Ubuntu, RPM packages for Fedora/CentOS, or a universal TAR archive. After installation completes, open your terminal or command prompt and run sql-agent --help to verify the installation was successful and see available commands. The CLI is a standalone executable with no additional dependencies required. For detailed installation instructions and troubleshooting, visit our documentation page.

How do I activate my license?

Activating your SQL Agent CLI license is a simple one-time process. After purchasing a subscription plan from our pricing page, you'll receive a unique API license key via email and in your account cabinet. Open your terminal or command prompt and run sql-agent login YOUR-LICENSE-KEY, replacing YOUR-LICENSE-KEY with your actual key. The CLI will securely store your credentials locally using encryption and validate the license with our servers. Each license allows activation on a specific number of devices depending on your plan (Free: 1 device, Personal: 2 devices, Professional: 5 devices, Enterprise: unlimited). You can view all your active device installations and deactivate old devices from your cabinet dashboard. If you encounter activation issues, ensure you have an internet connection for license validation, or contact our support team.

Which databases are supported?

SQL Agent CLI provides comprehensive support for the three most popular relational database management systems: PostgreSQL, MySQL, and SQLite. PostgreSQL support includes all modern versions (10+) with full compatibility for PostGIS spatial extensions and advanced data types like JSONB and arrays. MySQL/MariaDB support covers versions 5.7+ including all standard SQL features. SQLite support works with both file-based and in-memory databases, making it perfect for development, testing, and lightweight applications. To connect to a database, use standard database URL connection strings in the format postgresql://user:pass@host:port/dbname for PostgreSQL, mysql://user:pass@host:port/dbname for MySQL, or sqlite:///path/to/database.db for SQLite. The natural language to SQL conversion automatically adapts to your specific database dialect, ensuring generated queries use the correct syntax and functions for each database platform.

Which AI providers can I use?

SQL Agent CLI offers flexible AI provider support, allowing you to choose the LLM that best fits your needs and budget. Supported providers include OpenAI with GPT-5.5 and GPT-5.4-mini models for industry-leading accuracy, Anthropic Claude 4 models (Opus 4.7, Sonnet 4.6, Haiku 4.5) known for their strong reasoning capabilities, xAI Grok 4.3 for fast frontier reasoning, Google Gemini 3.5 Flash and 3.1 Pro for multimodal workloads, Alibaba Qwen 3.7 Max for open-weights flexibility, and local Ollama models for completely offline, private operation with no external API calls. To configure your preferred provider, run sql-agent configuration llm.provider --value provider_name, then set your API key with the appropriate environment variable or configuration command. Using Ollama with models like Llama 3.3, Mistral, or CodeLlama enables fully offline natural language to SQL conversion without internet connectivity or recurring API costs. Each provider offers different trade-offs between speed, cost, accuracy, and privacy, giving you complete control over your AI SQL assistant infrastructure.

Can I use my license on multiple devices?

Yes! SQL Agent CLI licenses support multiple device activations, allowing you to use the same license key across your work computer, laptop, home desktop, and other machines. The number of simultaneous device activations depends on your subscription plan (see our pricing page for specific limits). The Free plan allows 1 active device, Personal plans support 2 devices, Professional plans include 5 device activations, and Enterprise plans offer unlimited device activations for your entire team. You can view all your currently activated devices, see their last connection time, and remotely deactivate devices you no longer use from your account cabinet. Device deactivation is instant and frees up a slot for activating SQL Agent on a new machine. This flexible device management makes it easy to upgrade hardware, switch between work and personal computers, or share a Professional license across a small development team without purchasing multiple subscriptions.

Does SQL Agent work offline?

SQL Agent can work in limited offline mode with proper configuration. By default, the CLI requires internet connectivity for two purposes: license validation with our servers and sending natural language queries to cloud-based AI providers like OpenAI or Anthropic. However, you can enable offline functionality using two approaches. First, configure "safe mode" by running sql-agent configuration license_fail_mode --value safe, which allows the CLI to continue operating with a warning message when license validation fails due to network issues. Second, for completely offline operation without any internet dependency, configure SQL Agent to use a local Ollama LLM provider running on your machine with sql-agent configuration llm.provider --value ollama. This combination enables fully offline natural language to SQL conversion and database querying, perfect for air-gapped environments, secure corporate networks, or working from locations without reliable internet access. The offline mode maintains all core functionality including schema discovery, query generation, and read-only database operations.

How does natural language querying work?

SQL Agent's natural language to SQL conversion uses advanced AI to understand your database questions and generate accurate SQL queries automatically. When you connect to a database, the AI agent first analyzes your complete database schema including table names, column names, data types, primary and foreign key relationships, indexes, and constraints. This schema understanding allows the AI to interpret your plain English questions contextually. Simply type questions like "Show me all users created this week", "What's the average order value by product category?", or "List the top 10 customers by revenue" and press enter. The AI processes your natural language input, identifies the relevant tables and columns, determines necessary JOIN operations, applies appropriate filters and aggregations, and generates optimized SQL SELECT statements. The generated SQL query is displayed for your review before execution, allowing you to learn SQL syntax patterns and verify the logic. You can also write SQL code directly when you prefer manual control. This text-to-SQL approach dramatically reduces query development time and makes database exploration accessible to anyone who can ask questions in their native language.

Is my data secure?

SQL Agent is read-only by default and encrypts saved credentials. In the Web Workspace, connection details are encrypted at rest and decrypted only inside the query worker when needed. In the CLI, credentials and history stay on your machine, and Ollama supports fully local AI workflows. Choose the interface that matches your security requirements and review generated SQL before execution.

Can I prevent accidental data modifications?

Yes. SQL Agent defaults to read-only mode and blocks modifying statements such as INSERT, UPDATE, DELETE, DROP, TRUNCATE, and ALTER before execution. In the Web Workspace, write access is enabled explicitly per connection profile. In the CLI, reconnect with the --write flag when writes are required. Keep production connections read-only whenever possible.

Do I need to install anything to use SQL Agent?

No. Alongside the CLI, every SQL Agent license includes the browser-based Web Workspace — the same AI agent with nothing to install. Sign in from any machine, save connection profiles for your PostgreSQL, MySQL, or SQLite databases, and run natural language queries directly in the browser, complete with a visual schema browser, query history, saved queries, and CSV/JSON/XLSX exports. The CLI remains available for people who prefer the terminal or need offline operation with local Ollama models, and both surfaces are unlocked by the same license key — including the 14-day free trial created at signup. Learn more on the Web Workspace page or try the no-signup live demo.

Is my database password stored securely in the Web Workspace?

Yes. When you save a connection profile in the Web Workspace, the database password (or connection URL) is encrypted with industry-standard Fernet encryption before it is stored — plaintext credentials never reach the database or backups. The password is decrypted only inside an isolated background worker at the moment a query job actually runs, is never written to logs, and is never displayed again in the interface after saving; you only ever see a masked placeholder. If you prefer credentials to never leave your machine at all, the CLI stores them locally with the same encryption approach instead.

Can the web agent write to my database?

Not unless you explicitly allow it. Every connection profile in the Web Workspace is read-only by default: INSERT, UPDATE, DELETE, DROP, TRUNCATE, and other modifying statements are blocked by the query validator before execution — exactly the same safety rules the CLI enforces. If you need write access for a specific database, you can enable the per-profile write option when creating or editing that profile; all your other profiles stay read-only. Additional protections apply regardless of mode: result previews are row-capped, queries run under statement timeouts, and each run records exactly what SQL was executed in your query history. This makes the Web Workspace safe for pointing at production replicas and letting non-engineers explore data.

How do I get support?

Support is available for Web Workspace and CLI users on every plan. For technical help, bug reports, feature requests, connection issues, or AI provider configuration, visit our contact page. Tell us which interface you use, your database type, and the error details. For CLI issues, also include the output of sql-agent --version. We typically respond within 24 hours on business days.

What is natural language to SQL?

Natural language to SQL converts plain-language questions into SQL database queries. Ask something like 'Show me all customers from New York' or 'What were last month's sales?' and SQL Agent generates the corresponding SQL. The same AI assistant is available in the Web Workspace and CLI.

How accurate is AI-generated SQL?

SQL Agent's AI-generated SQL queries achieve high accuracy by analyzing your actual database schema before generating queries. The AI agent inspects table structures, column names, data types, relationships, and constraints to ensure queries are syntactically correct and semantically meaningful. For straightforward queries like SELECT statements with simple WHERE clauses, accuracy typically exceeds 95%. Complex queries involving multiple JOINs, subqueries, or aggregations may require minor adjustments, but the AI provides a strong starting point that saves significant development time. The query executor includes built-in validation to catch potential errors before execution, and read-only mode protects against accidental data modifications. Users can review generated SQL before execution and provide feedback to refine results. Accuracy improves further when you use descriptive table and column names that clearly indicate their purpose.

Can SQL Agent handle complex SQL joins and queries?

Yes. SQL Agent can generate joins, subqueries, CTEs, window functions, aggregations, UNION operations, and nested SELECT statements. The AI analyzes table structures and relationships in both the Web Workspace and CLI. Review and test especially complex generated queries before production use.

Does SQL Agent support stored procedures?

Currently, SQL Agent CLI focuses on SELECT queries for data retrieval and basic INSERT, UPDATE, and DELETE operations when write mode is enabled. Stored procedures, functions, and triggers are not directly supported for creation or modification through natural language commands. However, you can execute existing stored procedures in your PostgreSQL or MySQL database by writing the CALL or EXEC statement directly in the CLI. The AI agent can help you understand what parameters a stored procedure expects and format the execution command correctly. If your use case requires frequent stored procedure development, we recommend using SQL Agent for exploratory querying and data analysis, then switching to a dedicated database IDE like DBeaver or DataGrip for procedural SQL development. We're exploring stored procedure generation capabilities for future releases based on user feedback and demand.

How does SQL Agent compare to manual SQL writing?

SQL Agent dramatically reduces the time required to write SQL queries, especially for users who aren't SQL experts. While experienced database developers can write optimized queries manually, SQL Agent offers several advantages: instant query generation without memorizing syntax, automatic schema discovery eliminating the need to reference documentation, reduced syntax errors and typos, and faster exploration of unfamiliar databases. For data analysts and business users with limited SQL knowledge, SQL Agent makes database querying accessible without extensive training. Even experienced developers find value in using SQL Agent to quickly prototype queries, explore new database schemas, and handle repetitive query patterns. The AI-generated SQL code is readable, follows best practices, and can be saved for future use or modified as needed. That said, for mission-critical queries requiring extreme performance optimization or complex business logic, manual SQL writing by an expert developer may still be preferable. SQL Agent works best as a productivity tool that augments human expertise rather than replacing it entirely.

Can I learn SQL using SQL Agent?

Absolutely! SQL Agent is an excellent educational tool for learning SQL programming. When you ask a question in plain English, SQL Agent not only executes the query but also displays the generated SQL code, allowing you to see exactly how your natural language request translates into SQL syntax. This immediate feedback helps beginners understand SQL fundamentals including SELECT statements, WHERE clauses, JOIN operations, ORDER BY sorting, and aggregate functions like COUNT, SUM, and AVG. You can experiment with different phrasings and observe how the SQL changes, building intuition for database query patterns. SQL Agent works with real databases (PostgreSQL, MySQL, SQLite), providing hands-on practice rather than abstract exercises. For structured learning, we recommend using SQL Agent alongside traditional SQL tutorials or courses—use the AI to quickly test concepts, explore syntax variations, and verify your understanding. The read-only mode ensures safe experimentation without risk of accidentally modifying data, making it ideal for SQL practice and learning how databases work.

What types of SQL queries can SQL Agent generate?

SQL Agent can generate a wide variety of SQL query types for PostgreSQL, MySQL, and SQLite databases. The most common queries include SELECT statements for data retrieval with filtering, sorting, and pagination; JOIN queries combining data from multiple related tables; aggregate queries using COUNT, SUM, AVG, MIN, MAX with GROUP BY; date and time filtering for temporal data analysis; pattern matching with LIKE and regular expressions; subqueries and nested SELECT statements; UNION and INTERSECT for combining result sets; DISTINCT for removing duplicates; and LIMIT/OFFSET for result pagination. When write mode is enabled with the --write flag, SQL Agent can also generate INSERT statements for adding new records, UPDATE statements for modifying existing data, and DELETE statements for removing records (with built-in safety confirmations). The AI query generator automatically selects appropriate SQL functions, operators, and clauses based on your natural language request and the specific database dialect you're using, ensuring compatibility and optimal performance.

Is SQL Agent suitable for beginners or experienced developers?

SQL Agent is designed for everyone from SQL beginners to senior database developers. The visual Web Workspace makes schema exploration and querying approachable without terminal experience, while the CLI supports terminal-native automation and local models. Both interfaces accelerate query development, reduce boilerplate, and help users understand unfamiliar schemas.

How does SQL Agent improve database productivity?

SQL Agent significantly boosts productivity for database-related tasks by reducing query development time from minutes to seconds. Instead of manually writing SQL code, consulting documentation, and debugging syntax errors, users can express their data needs in natural language and receive working queries instantly. The AI database assistant eliminates context switching by keeping you in the terminal rather than switching between SQL editors, schema documentation, and browser tabs. For teams working with multiple databases or frequent schema changes, SQL Agent's automatic schema discovery means you don't need to memorize table names, column names, or relationships—the AI analyzes your database structure in real-time. Read-only mode prevents costly mistakes and accidental data modifications that could require time-consuming recovery. Query history tracking allows you to reference previous queries without searching through notes or files. For data analysts running ad-hoc queries throughout the day, SQL Agent can save hours per week. Development teams report 40-60% faster database query development when using AI SQL tools compared to manual SQL writing, with the largest time savings occurring during database exploration and prototyping phases.

Can SQL Agent help with SQL query optimization?

SQL Agent generates queries that follow SQL best practices and use efficient patterns, but dedicated query optimization for high-performance production systems requires additional tools and expertise. The AI agent avoids common anti-patterns like SELECT * when specific columns are needed, uses appropriate JOIN types based on relationships, and structures WHERE clauses logically. However, SQL Agent doesn't currently provide EXPLAIN plan analysis, index recommendations, or detailed performance metrics. For query optimization, we recommend using SQL Agent to generate an initial working query, then using database-specific tools like PostgreSQL's EXPLAIN ANALYZE, MySQL Query Profiler, or SQLite's query planner to identify bottlenecks. Professional and Enterprise plans include performance analysis features that provide basic query metrics and execution time tracking. If your use case involves optimizing slow queries on large datasets, consider pairing SQL Agent with specialized database monitoring tools like pgBadger for PostgreSQL or dedicated database performance platforms. The combination of fast AI-generated queries plus manual optimization delivers the best results for production database workloads.