{"id":19434474,"url":"https://github.com/mlin/ai4sqlite3","last_synced_at":"2025-07-16T09:33:18.928Z","repository":{"id":216214306,"uuid":"626201399","full_name":"mlin/ai4sqlite3","owner":"mlin","description":"Natural language query assistant for SQLite databases","archived":false,"fork":false,"pushed_at":"2025-06-06T05:58:52.000Z","size":44,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-01T05:40:26.165Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/mlin.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}},"created_at":"2023-04-11T02:08:27.000Z","updated_at":"2025-06-06T05:58:54.000Z","dependencies_parsed_at":"2024-01-09T03:38:22.324Z","dependency_job_id":"82d5eb15-651a-42d2-aeda-83ecbc89eb13","html_url":"https://github.com/mlin/ai4sqlite3","commit_stats":null,"previous_names":["mlin/ai4sqlite3"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/mlin/ai4sqlite3","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlin%2Fai4sqlite3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlin%2Fai4sqlite3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlin%2Fai4sqlite3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlin%2Fai4sqlite3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mlin","download_url":"https://codeload.github.com/mlin/ai4sqlite3/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlin%2Fai4sqlite3/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265499990,"owners_count":23777390,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-11-10T14:46:32.939Z","updated_at":"2025-07-16T09:33:18.892Z","avatar_url":"https://github.com/mlin.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ai4sqlite3\n**Natural language query assistant for [SQLite databases](https://www.sqlite.org/index.html)**\n\nUsing any local SQLite3 database file, the command-line interface asks for your query intentions, uses OpenAI's ChatGPT API to formulate SQL fulfilling them, and then runs the SQL on your database. Bring your own [OpenAI API key](https://www.howtogeek.com/885918/how-to-get-an-openai-api-key/) ($ / free trial).\n\nThe tool sends your database *schema* and written query intentions to OpenAI. But NOT the result sets nor any other database *content*. The database is opened in read-only mode so that the AI cannot damage it.\n\n### Quick start\n\nWe'll use the [Chinook database](https://github.com/lerocha/chinook-database) as a small starting example.\n\n\u003cpre\u003e\n$ \u003cb\u003eexport OPENAI_API_KEY=xxx\u003c/b\u003e\n$ \u003cb\u003epip3 install ai4sqlite3\u003c/b\u003e\n$ \u003cb\u003ewget https://github.com/lerocha/chinook-database/raw/master/ChinookDatabase/DataSources/Chinook_Sqlite.sqlite\u003c/b\u003e\n$ \u003cb\u003eai4sqlite3 Chinook_Sqlite.sqlite --yes\u003c/b\u003e\nAnalyzing schema of Chinook_Sqlite.sqlite in 4.9s \n\nThis database models a digital music store. It includes tables for artists, albums,\ntracks, genres, media types, invoices, customers, employees, playlists, and playlist\ntracks. The tables are linked through foreign keys to form relationships, such as an\nartist being associated with an album, an invoice being linked to a customer, and a\nplaylist being composed of multiple tracks. The database is designed to enable the store\nto manage and track music sales, customer information, and employee records, as well as\norganizing and categorizing the available music.\n\nPlease state the nature of the desired database query.\n\u003e \u003cb\u003etop five customer countries by 2011 revenue (round to cents)\u003c/b\u003e\n\nGenerating SQL in 2.8s \n\nSELECT c.Country, ROUND(SUM(i.Total), 2) AS 'Revenue 2011'\nFROM Customer c\nJOIN Invoice i ON c.CustomerId = i.CustomerId\nWHERE strftime('%Y', i.InvoiceDate) = '2011'\nGROUP BY c.Country\nORDER BY SUM(i.Total) DESC\nLIMIT 5;\n\nExecuting query in 0.1s \n+---------+--------------+\n| Country | Revenue 2011 |\n+---------+--------------+\n|   USA   |    103.01    |\n|  Canada |    55.44     |\n| Germany |    48.57     |\n|  France |    42.61     |\n| Ireland |    32.75     |\n+---------+--------------+\n\nNext query?\n\u003e \u003cb\u003epercentage of all revenue from sales to North American customers\u003c/b\u003e\n\nGenerating SQL in 3.3s \n\nSELECT \n    ROUND(SUM(i.Total) / (SELECT SUM(Total) FROM Invoice)*100, 2) AS \"North American Revenue Percentage\"\nFROM \n    Invoice i\n    INNER JOIN Customer c ON i.CustomerId = c.CustomerId\nWHERE \n    c.Country = 'USA' OR c.Country = 'Canada';\n\nExecuting query in 0.1s \n+-----------------------------------+\n| North American Revenue Percentage |\n+-----------------------------------+\n|               35.52               |\n+-----------------------------------+\n\nNext query?\n\u003e\n\u003c/pre\u003e\n\n### Advice\n\n* We reset the AI memory between `Next query?` prompts, so you can't implicitly refer back to prior queries.\n* But you can use the up arrow key to recall a prior input to edit or add to.\n* Remember the AI knows your database *schema* but not *contents*.\n  * e.g. if you want to filter the `Country` column then you should be specific (or lucky) about whether it's populated with `US`, `USA`, `United States`, etc.\n  * it's great at text/SQL pidgin: *top 10 customers by revenue, last || ', ' || first where Country = 'USA'*\n* If SQLite rejects the AI's SQL, then we automatically request corrections (up to `--revisions` attempts).\n* You can (usually) get general questions aswered with something like: *about the schema, what does each invoice line item refer to?*\n* You might enjoy exploring your [Firefox](https://www.foxtonforensics.com/browser-history-examiner/firefox-history-location) or [Chrome](https://www.foxtonforensics.com/browser-history-examiner/chrome-history-location) history database (you might need to copy the file if your browser has it open).\n\n### More-challenging examples\n\n\u003cpre\u003e\n\u003e \u003cb\u003eConsidering sales to USA customers, find the top-grossing artist in each state.\u003c/b\u003e\n\nGenerating SQL in 13.4s \n\nWITH StateArtistSales AS (\n  SELECT\n    i.BillingState AS State,\n    ar.ArtistId,\n    ar.Name AS ArtistName,\n    SUM(il.UnitPrice * il.Quantity) AS TotalSales\n  FROM Invoice i\n  JOIN InvoiceLine il ON il.InvoiceId = i.InvoiceId\n  JOIN Track t ON il.TrackId = t.TrackId\n  JOIN Album al ON t.AlbumId = al.AlbumId\n  JOIN Artist ar ON al.ArtistId = ar.ArtistId\n  WHERE i.BillingCountry = 'USA'\n  GROUP BY i.BillingState, ar.ArtistId\n),\nMaxSales AS (\n  SELECT\n    State,\n    MAX(TotalSales) AS MaxTotalSales\n  FROM StateArtistSales\n  GROUP BY State\n)\nSELECT\n  s.State,\n  s.ArtistName\nFROM StateArtistSales s\nJOIN MaxSales m\n  ON s.State = m.State\n AND s.TotalSales = m.MaxTotalSales\nORDER BY s.State;\n\nExecuting query in 0.1s \n+-------+--------------------------------+\n| State |          ArtistName            |\n+-------+--------------------------------+\n|   AZ  |          Iron Maiden           |\n|   CA  |          Iron Maiden           |\n|   FL  |           Metallica            |\n|   IL  |           The Office           |\n|   MA  |       Milton Nascimento        |\n|   NV  |          Cidade Negra          |\n|   NY  |          Deep Purple           |\n|   TX  |              Lost              |\n|   UT  | Battlestar Galactica (Classic) |\n|   WA  |           Metallica            |\n|   WI  |           The Office           |\n+-------+--------------------------------+\n\nNext query?\n\u003e \u003cb\u003eCol 1: employee name. Col 2: subordinate employee name. Subordinates include transitive as well as direct reports.\u003c/b\u003e\n\nGenerating SQL in 5.6s \n\nWITH RECURSIVE cte_subordinates AS (\n  SELECT e1.FirstName || ' ' || e1.LastName AS EmployeeName, \n         e2.FirstName || ' ' || e2.LastName AS SubordinateName\n  FROM Employee e1\n  INNER JOIN Employee e2 ON e2.ReportsTo = e1.EmployeeId\n  UNION\n  SELECT cte.EmployeeName, e.FirstName || ' ' || e.LastName AS SubordinateName\n  FROM cte_subordinates cte\n  INNER JOIN Employee e ON e.ReportsTo = (\n    SELECT EmployeeId FROM Employee WHERE FirstName || ' ' || LastName = cte.SubordinateName\n  )\n)\nSELECT * FROM cte_subordinates ORDER BY EmployeeName, SubordinateName LIMIT 25;\n\nExecuting query in 0.1s \n+------------------+------------------+\n|   EmployeeName   | SubordinateName  |\n+------------------+------------------+\n|   Andrew Adams   |   Jane Peacock   |\n|   Andrew Adams   |  Laura Callahan  |\n|   Andrew Adams   |  Margaret Park   |\n|   Andrew Adams   | Michael Mitchell |\n|   Andrew Adams   |  Nancy Edwards   |\n|   Andrew Adams   |   Robert King    |\n|   Andrew Adams   |  Steve Johnson   |\n| Michael Mitchell |  Laura Callahan  |\n| Michael Mitchell |   Robert King    |\n|  Nancy Edwards   |   Jane Peacock   |\n|  Nancy Edwards   |  Margaret Park   |\n|  Nancy Edwards   |  Steve Johnson   |\n+------------------+------------------+\n\u003c/pre\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlin%2Fai4sqlite3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmlin%2Fai4sqlite3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlin%2Fai4sqlite3/lists"}