sqlsaber 0.33.0__tar.gz → 0.35.0__tar.gz

{sqlsaber-0.33.0 → sqlsaber-0.35.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlsaber
-Version: 0.33.0
+Version: 0.35.0
 Summary: SQLsaber - Open-source agentic SQL assistant
 License-File: LICENSE
 Requires-Python: >=3.12

{sqlsaber-0.33.0 → sqlsaber-0.35.0}/docs/src/content/docs/changelog.md

@@ -9,6 +9,33 @@ All notable changes to SQLsaber will be documented here.
 
 ---
 
+### v0.35.0 - 2025-10-22
+
+#### Added
+
+- Table and column comment support across all databases
+  - Comments are now included in schema introspection to provide richer context to LLM
+  - PostgreSQL: Uses `obj_description()` and `col_description()` functions
+  - MySQL: Retrieves `table_comment` and `column_comment` from `information_schema`
+  - DuckDB: Joins with `duckdb_tables()` and `duckdb_columns()` for comment data
+  - SQLite: Returns `None` for comments (SQLite doesn't support native comments)
+  - Comments are conditionally included in tool output only when present, avoiding clutter
+  - Updated `ColumnInfo` and `SchemaInfo` TypedDicts with optional comment fields
+
+#### Fixed
+
+- Strip leading/trailing whitespace and new lines from submitted user inputs
+
+### v0.34.0 - 2025-10-17
+
+#### Changed
+
+- Improved `auth setup` command: Reworked to select the provider first, offer to reset existing credentials per provider, and allow configuring multiple providers in one session without manual cleanup.
+- PostgreSQL schema introspection: Exclude TimescaleDB internal schemas by default and add env-based filtering
+  - Default exclusions now include `pg_catalog`, `information_schema`, `_timescaledb_internal`, `_timescaledb_cache`, `_timescaledb_config`, `_timescaledb_catalog`
+  - New environment variable `SQLSABER_PG_EXCLUDE_SCHEMAS` allows excluding additional schemas (comma-separated)
+  - Applies to both `list_tables` and `introspect_schema` tools
+
 ### v0.33.0 - 2025-10-16
 
 #### Changed
@@ -61,7 +88,7 @@ All notable changes to SQLsaber will be documented here.
 
   > `sqlsaber` can still be used as a cli in coding agents like Claude Code, Codex, or Amp.
   >
-  > Just *ask* the coding agent to invoke `sqlsaber` cli with your question.
+  > Just _ask_ the coding agent to invoke `sqlsaber` cli with your question.
 
 ### v0.29.1 - 2025-10-05
 
@@ -356,6 +383,7 @@ All notable changes to SQLsaber will be documented here.
 #### Added
 
 - Table name autocomplete with "@" prefix in interactive mode
+
   - Type "@" followed by table name to get fuzzy matching completions
   - Supports schema-aware completions (e.g., "@sample" matches "public.sample")
 

{sqlsaber-0.33.0 → sqlsaber-0.35.0}/docs/src/content/docs/guides/database-setup.mdx

@@ -3,7 +3,7 @@ title: Database Setup
 description: Configure database connections in SQLsaber
 ---
 
-import { Aside } from '@astrojs/starlight/components';
+import { Aside } from "@astrojs/starlight/components";
 
 SQLsaber supports PostgreSQL, MySQL, SQLite, DuckDB, and CSV data sources. This guide covers all the ways to configure database connections.
 
@@ -66,7 +66,8 @@ saber -d "./customers.csv" "How many customers are from each state?"
 ```
 
 <Aside type="note">
-For CSV files, first row should contain column headers. SQLsaber will infer data types automatically.
+  For CSV files, first row should contain column headers. SQLsaber will infer
+  data types automatically.
 </Aside>
 
 ### Managing Connections
@@ -86,7 +87,7 @@ saber db set-default my-database
 ```
 
 <Aside type="note">
-By default, SQLsaber will set the first added connection as default.
+  By default, SQLsaber will set the first added connection as default.
 </Aside>
 
 #### Test Connections
@@ -115,10 +116,13 @@ While SQLsaber ensures, via checks before executing queries, that only read quer
 If you have a read-replica of your production database, consider using those credentials to setup connection.
 
 In addition to the read-only role, this will provide additional layer of security and ensure no data modifying queries are executed.
+
 </Aside>
 
 <Aside type="note">
-For development setups, this isn't required but is a good practice if you wish to ensure with absolute certainty that no data modifying queries are ever executed.
+  For development setups, this isn't required but is a good practice if you wish
+  to ensure with absolute certainty that no data modifying queries are ever
+  executed.
 </Aside>
 
 #### Password Storage
@@ -129,6 +133,27 @@ SQLsaber stores database passwords securely using your operating system's creden
 
 Store SSL certificates in a secure location and use absolute paths when configuring connections.
 
+### Schema Introspection Filters (PostgreSQL)
+
+By default, SQLsaber excludes system and TimescaleDB internal schemas during schema discovery to keep results focused and fast.
+
+Excluded by default:
+
+- `pg_catalog`
+- `information_schema`
+- `_timescaledb_internal`
+- `_timescaledb_cache`
+- `_timescaledb_config`
+- `_timescaledb_catalog`
+
+You can exclude additional schemas via environment variable before running `saber`:
+
+```bash
+export SQLSABER_PG_EXCLUDE_SCHEMAS="schema1,schema2"
+```
+
+Both the `list_tables` and `introspect_schema` tools respect these filters.
+
 ### Troubleshooting
 
 Always test new connections after adding them.

{sqlsaber-0.33.0 → sqlsaber-0.35.0}/docs/src/content/docs/guides/getting-started.mdx

@@ -15,72 +15,50 @@ Before you begin, make sure you have:
 
 ### Quick Setup
 
-#### 1. Set Up Authentication
+#### 1. Launch the Onboarding Flow
 
-First, configure your AI provider.
-
-SQLsaber uses Claude Sonnet 4 as the model by default, but supports models from [multiple providers](/guides/models).
+Run SQLsaber with no arguments to start the guided setup:
 
 ```bash
-saber auth setup
+saber
 ```
 
-This will prompt you to:
+On your first run, SQLsaber walks you through two guided steps:
 
-- Choose a provider (We recommend Anthropic)
-- Enter your API key
+1. **Database connection**:
+   Choose the database type and provide connection details.
 
-<Aside type="tip">
-  If you have a Claude Pro or Max subscription, you can use it with SQLsaber. It
-  is one of the most cost-effective options.
-</Aside>
+2. **Authentication**:
+   Sign in to your preferred AI provider and pick a model. We recommend Sonnet 4.5, 4 or GPT-5.
 
-<Aside type="note">
-  If you choose a provider other than Anthropic, please select the appropriate
-  model for the provider by running `saber models set`.
-</Aside>
+   `sqlsaber` will store your API key securely using your OS credential store.
 
-#### 2. Add Your Database
+When both steps succeed you'll see a confirmation screen, and SQLsaber immediately opens an interactive session.
 
-Add a database connection:
-
-```bash
-saber db add my-database
-```
-
-This interactive command will ask you for:
+<Aside type="tip">
+  If you have a Claude Pro or Max subscription, you can use it with SQLsaber for
+  a cost-effective setup.
+</Aside>
 
-- Database type
-  - PostgreSQL
-  - MySQL
-  - SQLite
-  - DuckDB
-- Connection details (host, port, database name, username)
-- SSL configuration (if needed)
+<Aside type="tip">
+    If you already have a connection string handy, pass it via `saber -d <connection-string>` to skip the onboarding flow.
+</Aside>
 
 <Aside type="note">
-If you don't have a database handy, you can use a sample `legislators` SQLite database from SQLsaber repository:
+  Need a sample database?
+
+Download the `legislators` SQLite file, then choose `sqlite` when the onboarding flow prompts for a database location (or add it with `saber db add`):
 
 ```bash
 curl -L -o legislators.db https://github.com/SarthakJariwala/sqlsaber/raw/refs/heads/main/legislators.db
-
-# Add it to SQLsaber
-saber db add legislators --type sqlite --database ./legislators.db
 ```
 
 </Aside>
 
-#### 3. Your First Query
-
-Now you're ready to ask your first question!
-
-Start SQLsaber in interactive mode:
-
-```bash
-saber
-```
+#### 2. Ask Your First Question
 
-Try asking a question:
+Once onboarding completes, you're already in interactive mode. Try asking a
+question:
 
 ```
 > How many VPs have become presidents via election in 20th century?

{sqlsaber-0.33.0 → sqlsaber-0.35.0}/docs/src/content/docs/guides/models.mdx

@@ -3,7 +3,7 @@ title: Models
 description: Configure and select AI models for SQLsaber
 ---
 
-import { Aside } from '@astrojs/starlight/components';
+import { Aside } from "@astrojs/starlight/components";
 
 SQLsaber supports many LLM models across different providers.
 
@@ -11,19 +11,19 @@ This guide covers model selection, configuration, and recommendations for the be
 
 ### Default Model
 
-SQLsaber uses **Claude Sonnet 4** by default, which provides excellent SQL generation capabilities with good speed and accuracy.
+SQLsaber uses **Claude Sonnet 4.5** by default, which provides excellent SQL generation capabilities with good speed and accuracy.
 
 ### Recommended Models
 
 While SQLsaber supports a lot of models, we recommend the following for best results:
 
-- Claude Sonnet 4, 3.7, 3.5
-- Claude Opus 4, 4.1
 - GPT-5
+- Claude Sonnet 4.5, 4.0, 3.7
+- Claude Opus 4, 4.1
 - Gemini 2.5 Pro
 
 <Aside type="tip">
-Consider using one of the recommended models for best results.
+  Consider using one of the recommended models for best results.
 </Aside>
 
 ### Model Management
@@ -43,12 +43,13 @@ saber models set
 ```
 
 This interactive command lets you:
+
 1. Choose from configured providers
 2. Select a specific model
 3. Set it as your default
 
 <Aside type="tip">
-    This list is long - type to search and filter the list.
+  This list is long - type to search and filter the list.
 </Aside>
 
 #### Reset to Default

{sqlsaber-0.33.0 → sqlsaber-0.35.0}/docs/src/content/docs/reference/commands.md

@@ -436,3 +436,12 @@ When in interactive mode (`saber` with no arguments), you have access to a few a
 
 - **Table names** - Type `@table_name[TAB]` for completions
 - **Slash commands** - Type `/[TAB]` for command completions
+
+---
+
+### Environment Variables
+
+These environment variables adjust runtime behavior:
+
+- `SQLSABER_THEME` — Override the configured theme for the session.
+- `SQLSABER_PG_EXCLUDE_SCHEMAS` — Comma-separated list of PostgreSQL schemas to exclude from schema discovery and introspection. Defaults already exclude `pg_catalog`, `information_schema`, `_timescaledb_internal`, `_timescaledb_cache`, `_timescaledb_config`, `_timescaledb_catalog`.

{sqlsaber-0.33.0 → sqlsaber-0.35.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlsaber"
-version = "0.33.0"
+version = "0.35.0"
 description = "SQLsaber - Open-source agentic SQL assistant"
 readme = "README.md"
 requires-python = ">=3.12"

{sqlsaber-0.33.0 → sqlsaber-0.35.0}/src/sqlsaber/application/auth_setup.py

@@ -1,6 +1,7 @@
 """Shared auth setup logic for onboarding and CLI."""
 
 import asyncio
+import os
 
 from questionary import Choice
 
@@ -9,6 +10,7 @@ from sqlsaber.config import providers
 from sqlsaber.config.api_keys import APIKeyManager
 from sqlsaber.config.auth import AuthConfigManager, AuthMethod
 from sqlsaber.config.oauth_flow import AnthropicOAuthFlow
+from sqlsaber.config.oauth_tokens import OAuthTokenManager
 from sqlsaber.theme.manager import create_console
 
 console = create_console()
@@ -102,24 +104,49 @@ async def setup_auth(
     Returns:
         Tuple of (success: bool, provider: str | None)
     """
-    # Check if auth is already configured
-    if auth_manager.has_auth_configured():
-        console.print("[success]✓ Authentication already configured![/success]")
-        return True, None
+    oauth_manager = OAuthTokenManager()
 
-    # Select provider
     provider = await select_provider(prompter, default=default_provider)
 
     if provider is None:
         return False, None
 
+    env_var = api_key_manager.get_env_var_name(provider)
+    api_key_in_env = bool(os.getenv(env_var))
+    api_key_in_keyring = api_key_manager.has_stored_api_key(provider)
+    has_oauth = (
+        oauth_manager.has_oauth_token("anthropic")
+        if provider == "anthropic" and allow_oauth
+        else False
+    )
+
+    if api_key_in_env or api_key_in_keyring or has_oauth:
+        parts: list[str] = []
+        if api_key_in_keyring:
+            parts.append("stored API key")
+        if api_key_in_env:
+            parts.append(f"{env_var} environment variable")
+        if has_oauth:
+            parts.append("OAuth token")
+        summary = ", ".join(parts)
+        console.print(
+            f"[info]Existing authentication found for {provider}: {summary}[/info]"
+        )
+
     # For Anthropic, offer OAuth or API key
     if provider == "anthropic" and allow_oauth:
+        api_key_label = "API Key"
+        if api_key_in_keyring or api_key_in_env:
+            api_key_label += " [configured]"
+        oauth_label = "Claude Pro/Max (OAuth)"
+        if has_oauth:
+            oauth_label += " [configured]"
+
         method_choice = await prompter.select(
             "Authentication method:",
             choices=[
-                Choice("API Key", value=AuthMethod.API_KEY),
-                Choice("Claude Pro/Max (OAuth)", value=AuthMethod.CLAUDE_PRO),
+                Choice(api_key_label, value=AuthMethod.API_KEY),
+                Choice(oauth_label, value=AuthMethod.CLAUDE_PRO),
             ],
         )
 
@@ -127,6 +154,28 @@ async def setup_auth(
             return False, None
 
         if method_choice == AuthMethod.CLAUDE_PRO:
+            if has_oauth:
+                reset = await prompter.confirm(
+                    "Anthropic OAuth is already configured. Reset before continuing?",
+                    default=False,
+                )
+                if not reset:
+                    console.print(
+                        "[warning]No changes made to Anthropic OAuth credentials.[/warning]"
+                    )
+                    return True, None
+
+                removal_success = oauth_manager.remove_oauth_token("anthropic")
+                if not removal_success:
+                    console.print(
+                        "[error]Failed to remove existing Anthropic OAuth credentials.[/error]"
+                    )
+                    return False, None
+
+                current_method = auth_manager.get_auth_method()
+                if current_method == AuthMethod.CLAUDE_PRO:
+                    auth_manager.clear_auth_method()
+
             console.print()
             oauth_success = await configure_oauth_anthropic(
                 auth_manager, run_in_thread=run_oauth_in_thread
@@ -136,12 +185,35 @@ async def setup_auth(
                     "[green]✓ Anthropic OAuth configured successfully![/green]"
                 )
                 return True, provider
-            else:
-                console.print("[error]✗ Anthropic OAuth setup failed.[/error]")
-                return False, None
+
+            console.print("[error]✗ Anthropic OAuth setup failed.[/error]")
+            return False, None
 
     # API key flow
-    env_var = api_key_manager.get_env_var_name(provider)
+    if api_key_in_keyring:
+        reset_api_key = await prompter.confirm(
+            f"{provider.title()} API key is stored in your keyring. Reset before continuing?",
+            default=False,
+        )
+        if not reset_api_key:
+            console.print(
+                "[warning]No changes made to stored API key credentials.[/warning]"
+            )
+            return True, None
+        if not api_key_manager.delete_api_key(provider):
+            console.print(
+                "[error]Failed to remove existing API key credentials.[/error]"
+            )
+            return False, None
+        console.print(
+            f"[muted]{provider.title()} API key removed from keyring.[/muted]"
+        )
+        api_key_in_keyring = False
+
+    if api_key_in_env:
+        console.print(
+            f"[muted]{env_var} is set in your environment. Update it there if you need a new value.[/muted]"
+        )
 
     console.print()
     console.print(f"[dim]To use {provider.title()}, you need an API key.[/dim]")

{sqlsaber-0.33.0 → sqlsaber-0.35.0}/src/sqlsaber/cli/auth.py

@@ -167,7 +167,9 @@ def reset():
             pass
         except Exception as e:
             console.print(f"Warning: Could not remove API key: {e}", style="warning")
-            logger.warning("auth.reset.api_key_remove_failed", provider=provider, error=str(e))
+            logger.warning(
+                "auth.reset.api_key_remove_failed", provider=provider, error=str(e)
+            )
 
     # Optionally clear global auth method if removing Anthropic OAuth configuration
     if provider == "anthropic" and oauth_present:

{sqlsaber-0.33.0 → sqlsaber-0.35.0}/src/sqlsaber/cli/display.py

@@ -406,9 +406,17 @@ class DisplayManager:
             for table_name, table_info in data.items():
                 self.console.print(f"\n[heading]Table: {table_name}[/heading]")
 
+                table_comment = table_info.get("comment")
+                if table_comment:
+                    self.console.print(f"[muted]Comment: {table_comment}[/muted]")
+
                 # Show columns
                 table_columns = table_info.get("columns", {})
                 if table_columns:
+                    include_column_comments = any(
+                        col_info.get("comment") for col_info in table_columns.values()
+                    )
+
                     # Create a table for columns
                     columns = [
                         {"name": "Column Name", "style": "column.name"},
@@ -416,6 +424,8 @@ class DisplayManager:
                         {"name": "Nullable", "style": "info"},
                         {"name": "Default", "style": "muted"},
                     ]
+                    if include_column_comments:
+                        columns.append({"name": "Comment", "style": "muted"})
                     col_table = self._create_table(columns, title="Columns")
 
                     for col_name, col_info in table_columns.items():
@@ -425,9 +435,15 @@ class DisplayManager:
                             if col_info.get("default")
                             else ""
                         )
-                        col_table.add_row(
-                            col_name, col_info.get("type", ""), nullable, default
-                        )
+                        row = [
+                            col_name,
+                            col_info.get("type", ""),
+                            nullable,
+                            default,
+                        ]
+                        if include_column_comments:
+                            row.append(col_info.get("comment") or "")
+                        col_table.add_row(*row)
 
                     self.console.print(col_table)
 

{sqlsaber-0.33.0 → sqlsaber-0.35.0}/src/sqlsaber/cli/interactive.py

@@ -20,6 +20,7 @@ from sqlsaber.cli.completers import (
 )
 from sqlsaber.cli.display import DisplayManager
 from sqlsaber.cli.streaming import StreamingQueryHandler
+from sqlsaber.config.logging import get_logger
 from sqlsaber.database import (
     CSVConnection,
     DuckDBConnection,
@@ -30,7 +31,6 @@ from sqlsaber.database import (
 from sqlsaber.database.schema import SchemaManager
 from sqlsaber.theme.manager import get_theme_manager
 from sqlsaber.threads import ThreadStorage
-from sqlsaber.config.logging import get_logger
 
 if TYPE_CHECKING:
     from sqlsaber.agents.pydantic_ai_agent import SQLSaberAgent
@@ -309,6 +309,8 @@ class InteractiveSession:
                         style=self.tm.pt_style(),
                     )
 
+                user_query = user_query.strip()
+
                 if not user_query:
                     continue
 
@@ -325,7 +327,7 @@ class InteractiveSession:
 
                 # Handle memory addition
                 if user_query.strip().startswith("#"):
-                    await self._handle_memory(user_query.strip()[1:].strip())
+                    await self._handle_memory(user_query[1:].strip())
                     continue
 
                 # Execute query with cancellation support

{sqlsaber-0.33.0 → sqlsaber-0.35.0}/src/sqlsaber/config/api_keys.py

@@ -41,6 +41,29 @@ class APIKeyManager:
         # 3. Prompt user for API key
         return self._prompt_and_store_key(provider, env_var_name, service_name)
 
+    def has_stored_api_key(self, provider: str) -> bool:
+        """Check if an API key is stored for the provider."""
+        service_name = self._get_service_name(provider)
+        try:
+            return keyring.get_password(service_name, provider) is not None
+        except Exception:
+            return False
+
+    def delete_api_key(self, provider: str) -> bool:
+        """Remove stored API key for the provider."""
+        service_name = self._get_service_name(provider)
+        try:
+            keyring.delete_password(service_name, provider)
+            return True
+        except keyring.errors.PasswordDeleteError:
+            return True
+        except Exception as e:
+            console.print(
+                f"Warning: Could not remove API key: {e}",
+                style="warning",
+            )
+            return False
+
     def get_env_var_name(self, provider: str) -> str:
         """Get the expected environment variable name for a provider."""
         # Normalize aliases to canonical provider keys

{sqlsaber-0.33.0 → sqlsaber-0.35.0}/src/sqlsaber/config/auth.py

@@ -81,6 +81,12 @@ class AuthConfigManager:
         config["auth_method"] = auth_method.value
         self._save_config(config)
 
+    def clear_auth_method(self) -> None:
+        """Clear any configured authentication method."""
+        config = self._load_config()
+        config["auth_method"] = None
+        self._save_config(config)
+
     def has_auth_configured(self) -> bool:
         """Check if authentication method is configured."""
         return self.get_auth_method() is not None

{sqlsaber-0.33.0 → sqlsaber-0.35.0}/src/sqlsaber/config/logging.py

@@ -193,4 +193,3 @@ __all__ = [
     "default_log_dir",
     "default_log_file",
 ]
-

{sqlsaber-0.33.0 → sqlsaber-0.35.0}/src/sqlsaber/database/base.py

@@ -24,6 +24,7 @@ class ColumnInfo(TypedDict):
     max_length: int | None
     precision: int | None
     scale: int | None
+    comment: str | None
 
 
 class ForeignKeyInfo(TypedDict):
@@ -48,6 +49,7 @@ class SchemaInfo(TypedDict):
     schema: str
     name: str
     type: str
+    comment: str | None
     columns: dict[str, ColumnInfo]
     primary_keys: list[str]
     foreign_keys: list[ForeignKeyInfo]