{"id":50724192,"url":"https://github.com/wiseql/wiseql","last_synced_at":"2026-06-13T06:01:09.490Z","repository":{"id":363006661,"uuid":"1261595899","full_name":"wiseql/wiseql","owner":"wiseql","description":"The wise data browser — run SQL recipes as small, observable, debuggable steps","archived":false,"fork":false,"pushed_at":"2026-06-11T00:24:23.000Z","size":370,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T04:21:33.868Z","etag":null,"topics":["data","debugging","duckdb","oracle","quality","sql","tui"],"latest_commit_sha":null,"homepage":"https://wiseql.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wiseql.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-06T22:47:20.000Z","updated_at":"2026-06-11T00:24:27.000Z","dependencies_parsed_at":"2026-06-10T03:00:24.746Z","dependency_job_id":null,"html_url":"https://github.com/wiseql/wiseql","commit_stats":null,"previous_names":["wiseql/wiseql"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/wiseql/wiseql","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wiseql%2Fwiseql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wiseql%2Fwiseql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wiseql%2Fwiseql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wiseql%2Fwiseql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wiseql","download_url":"https://codeload.github.com/wiseql/wiseql/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wiseql%2Fwiseql/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34229624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data","debugging","duckdb","oracle","quality","sql","tui"],"created_at":"2026-06-10T03:00:15.864Z","updated_at":"2026-06-12T05:00:50.566Z","avatar_url":"https://github.com/wiseql.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WiseQL\n\n**The wise data browser.** A terminal app that runs **SQL recipes** — a complex\ndatabase read broken into a DAG of small, observable steps — with a live run\nview, per-step reports, assertions that catch data issues automatically,\ncheckpoint/resume, run diffing, an in-app data explorer, and an optional local\nAI layer that explains what a run did.\n\nA 400-line SQL query is a black box. WiseQL turns it into a glass box.\n\n\u003e Early but usable. Oracle first (thin mode — no Instant Client needed),\n\u003e PostgreSQL next; DuckDB inside; read-only by default.\n\n## Install\n\nRequires Python 3.12+ and [uv](https://docs.astral.sh/uv/) (or pipx).\n\n```bash\n# from GitHub (with the optional AI add-on)\nuv tool install \"wiseql[ai] @ git+https://github.com/wiseql/wiseql.git\"\n\n# …or without AI\nuv tool install \"git+https://github.com/wiseql/wiseql.git\"\n\n# …or from a local clone\ngit clone https://github.com/wiseql/wiseql.git \u0026\u0026 cd wiseql\nuv tool install '.[ai]'\n```\n\nThis puts `wiseql` on your PATH. Check it:\n\n```bash\nwiseql version\nwiseql --help\n```\n\n(`pipx install \"wiseql[ai] @ git+https://github.com/wiseql/wiseql.git\"` works too.)\n\n## Connect to your database\n\nConnections live in `~/.config/wiseql/config.toml` and hold everything **except**\nthe password (recipes reference them by name, so they stay shareable):\n\n```toml\n[connections.main]\ndriver  = \"oracle\"\nhost    = \"db.example.com\"\nport    = 1521\nservice = \"PROD\"\nuser    = \"me_readonly\"\nauth    = \"keyring\"          # OS keychain (default) · or \"env\" · or \"wallet\"\n\n[defaults]\nconnection = \"main\"\n```\n\nThen store the password and test reachability:\n\n```bash\nwiseql conn login main      # prompts once, stores in your OS keyring\nwiseql conn test main       # connects, reports latency + DB version\nwiseql conn list            # see configured connections\n```\n\n\u003e Use a **read-only** database user. WiseQL refuses non-SELECT SQL, but a\n\u003e read-only user is the real guarantee.\n\n## Create a project and run a recipe\n\n```bash\nwiseql init returns-monitoring -c main           # scaffolds project.toml, recipes/, context/, runs/\ncd returns-monitoring\nwiseql context sync returns-monitoring -c main   # introspect the schema into context/tables.md\n```\n\nAdd a recipe under `recipes/` (write one by hand — see\n[RECIPE_SPEC.md](./RECIPE_SPEC.md) — or generate them, below). Then:\n\n```bash\nwiseql validate recipes/*.toml     # structural validation (add --ai for a semantic second opinion)\nwiseql                             # open the TUI → pick the project → pick a recipe → F2 to run\nwiseql run recipes/late-returns.toml --param run_date=2026-06-01   # …or headless (cron/CI; exit code is the contract)\n```\n\nIn the TUI: **F2** run · **Enter** drill into a step's data · **Ctrl+R** resume a\nfailed run · **Ctrl+D** diff vs the previous run · **Ctrl+E** explore a run's\ndata with ad-hoc SQL · **F4** (on a run) AI-explain what happened · **F9**\nsettings.\n\n## Generate recipes with AI\n\nIf you have an AI assistant with access to your schema/SQL, paste the prompt in\n[docs/recipe-generator-prompt.md](./docs/recipe-generator-prompt.md) — it emits a\ncomplete WiseQL project (project.toml + recipes + context) for your database.\nThen `wiseql validate recipes/*.toml` and run them.\n\n## Optional: the local AI add-on\n\nAI is **off by default** and never required. It runs locally via\n[Ollama](https://ollama.com) — nothing leaves your machine.\n\n```bash\n# install Ollama, then:\nollama serve \u0026\nollama pull gemma3            # or any local model tag you prefer\nwiseql ai setup --model gemma3\nwiseql ai status             # should say: ✓ ready\n```\n\nWith it enabled, **F4** on a run streams an explanation (what the run did, what\nlooks correct, what's wrong and where to look), and `wiseql validate --ai` adds\na semantic recipe review. If Ollama is off or the model is missing, AI features\nshow a hint and the rest of the app is unaffected.\n\n## Docs\n\n- [RECIPE_SPEC.md](./RECIPE_SPEC.md) — the recipe format (authoritative)\n- [docs/recipe-generator-prompt.md](./docs/recipe-generator-prompt.md) — generate recipes from your schema\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwiseql%2Fwiseql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwiseql%2Fwiseql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwiseql%2Fwiseql/lists"}