queryapigate 0.6.1__tar.gz → 0.7.1__tar.gz

queryapigate-0.7.1/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2024-2026 Anantha Raju C
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{queryapigate-0.6.1/queryapigate.egg-info → queryapigate-0.7.1}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: queryapigate
-Version: 0.6.1
+Version: 0.7.1
 Summary: Turn SQL into a REST API: run queries against MySQL, PostgreSQL, ClickHouse, SQLite or H2 over HTTP and get JSON, CSV, XML, YAML or XLSX back.
 Author-email: Anantha Raju C <arcswdev@gmail.com>
-License-Expression: MIT
+License-Expression: FSL-1.1-MIT
 Project-URL: Homepage, https://github.com/AnanthaRajuC/QueryAPIGate
 Project-URL: Documentation, https://AnanthaRajuC.github.io/QueryAPIGate/
 Project-URL: Repository, https://github.com/AnanthaRajuC/QueryAPIGate
@@ -64,7 +64,7 @@ Dynamic: license-file
 [![codecov](https://codecov.io/gh/AnanthaRajuC/QueryAPIGate/branch/main/graph/badge.svg)](https://codecov.io/gh/AnanthaRajuC/QueryAPIGate)
 [![PyPI](https://img.shields.io/pypi/v/queryapigate.svg)](https://pypi.org/project/queryapigate/)
 [![PyPI downloads](https://img.shields.io/pypi/dm/queryapigate.svg)](https://pypi.org/project/queryapigate/)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/AnanthaRajuC/QueryAPIGate/blob/main/LICENSE)
+[![License: FSL-1.1-MIT](https://img.shields.io/badge/license-FSL--1.1--MIT-blue.svg)](https://github.com/AnanthaRajuC/QueryAPIGate/blob/main/LICENSE)
 ![Python](https://img.shields.io/badge/python-3.9%2B-blue)
 
 ### Turn SQL queries into secure, governed REST APIs.
@@ -73,6 +73,12 @@ Dynamic: license-file
 
 [**Full documentation**](https://AnanthaRajuC.github.io/QueryAPIGate/)
 
+<p align="center">
+  <a href="https://www.youtube.com/watch?v=aiVbAkA2LS8">
+    <img src="https://raw.githubusercontent.com/AnanthaRajuC/QueryAPIGate/main/documentation/screenshots/demo-thumbnail.png" alt="Watch the 60-second demo: saved SQL queries as REST endpoints, scoped API keys, and the Move preview showing which keys gain or lose access" width="640">
+  </a>
+</p>
+
 **QueryAPIGate** is a self-hosted, single Flask service that runs SQL against your databases and returns the results as
 JSON, NDJSON, XML, YAML, CSV, TSV or Excel. Save a query once and it becomes a versioned endpoint with typed,
 injection-safe parameters and run history - without writing a controller, a repository layer, pagination, auth or
@@ -81,13 +87,13 @@ serialization boilerplate for it.
 Write SQL. Configure the query. Apply access controls. Get an API.
 
 ~~~bash
-$ curl 'http://127.0.0.1:5000/q/actor_by_id?id=7'
-[{"actor_id": 7, "first_name": "GRACE", "last_name": "MOSTEL"}]
+$ curl 'http://127.0.0.1:5000/q/example_film_search?text=Harbor&page_size=2'
+[{"film_id":48,"title":"Broken Harbor","category":"Action","rating":"PG-13"},{"film_id":44,"title":"Electric Harbor","category":"Documentary","rating":"G"}]
 
-$ curl 'http://127.0.0.1:5000/q/films_by_rating?rating=PG&max_length=60&format=csv&page_size=2'
-film_id,title,rating,length
-410,HEAVEN FREEDOM,PG,48
-443,HURRICANE AFFAIR,PG,49
+$ curl 'http://127.0.0.1:5000/q/example_top_films?top_n=2&category=Comedy&format=csv'
+title,category,rating,rentals,rank
+Electric Signal,Comedy,PG,977,1
+Crimson Garden,Comedy,PG-13,631,2
 ~~~
 
 <p align="center">
@@ -273,11 +279,11 @@ version rather than overwriting the old one, so a change to the SQL doesn't sile
 ### Bound query parameters
 
 ```sql
-SELECT * FROM actor WHERE actor_id = :id
+SELECT * FROM film WHERE film_id = :id
 ```
 
 ```http
-GET /q/actor_by_id?id=7
+GET /q/film_by_id?id=7
 ```
 
 Values are sent to the database separately from the SQL text, so they cannot be injected into it. Parameters can
@@ -416,8 +422,8 @@ and CI on every push. See [Development](#development) below.
 without building a service per query:
 
 ```http
-GET /q/actor_by_id?id=7
-GET /q/films_by_rating?rating=PG&max_length=90
+GET /q/film_by_id?id=7
+GET /q/example_top_films?top_n=5&category=Comedy
 ```
 
 **Reporting APIs.** Turn an existing analytical SQL report into a reusable endpoint that dashboards or scheduled
@@ -483,17 +489,17 @@ From a clone: `pip install -e ".[dev]"`. Or use Docker - see [below](#docker).
 Fastest: `queryapigate examples load && queryapigate serve` installs four worked [example APIs](documentation/EXAMPLES.md)
 (reporting, dashboard, export, partner) you can try, and `queryapigate examples unload` removes them again.
 
-Or, from a clone, the repository ships two sample SQLite databases and a couple of saved queries:
-
 ~~~bash
-cd examples
-cp db_connections.example.json db_connections.json
+queryapigate examples load
 queryapigate serve                            # http://127.0.0.1:5000
 ~~~
 
+The examples come with a small generated `examples` database (films, customers and rentals), so you can also run ad-hoc SQL
+straight away:
+
 ~~~bash
 curl -X POST 'http://127.0.0.1:5000/execute_sql?page_size=3' -H 'Content-Type: application/json' \
-     -d '{"sql": "SELECT * FROM actor WHERE actor_id > :min", "params": {"min": 10}, "connection_name": "sakila-sqlite"}'
+     -d '{"sql": "SELECT film_id, title, rating FROM film WHERE film_id > :min", "params": {"min": 10}, "connection_name": "examples"}'
 ~~~
 
 Open <http://127.0.0.1:5000/docs> for the interactive API reference, or <http://127.0.0.1:5000/ui> for a small
@@ -504,24 +510,26 @@ every supported database) and `saved_sql/`. Edit the file, set `"active": true`,
 
 ## Saving a query as an endpoint
 
+This uses the `examples` connection that `queryapigate examples load` sets up:
+
 ~~~bash
 curl -X PATCH http://127.0.0.1:5000/save_sql_to_file -H 'Content-Type: application/json' -d '{
-  "filename": "actor_by_id",
-  "sql_query": "SELECT * FROM actor WHERE actor_id = :id",
-  "query_parameters": {"id": {"type": "int", "min": 1, "max": 200, "description": "Actor id"}},
-  "connection_name": "sakila-sqlite",
-  "author": "me", "description": "Look up an actor"
+  "filename": "film_by_id",
+  "sql_query": "SELECT * FROM film WHERE film_id = :id",
+  "query_parameters": {"id": {"type": "int", "min": 1, "max": 60, "description": "Film id"}},
+  "connection_name": "examples",
+  "author": "me", "description": "Look up a film"
 }'
 
-curl 'http://127.0.0.1:5000/q/actor_by_id?id=7&format=yaml'
-curl 'http://127.0.0.1:5000/q/actor_by_id?id=0'
+curl 'http://127.0.0.1:5000/q/film_by_id?id=7&format=yaml'
+curl 'http://127.0.0.1:5000/q/film_by_id?id=0'
 # {"error": "Invalid parameters: id must be at least 1", "errors": {"id": "must be at least 1"}}
 ~~~
 
 Rules: `type` (`int`, `float`, `str`, `bool`), `default`, `required`, `enum`, `min`/`max`, `min_length`/`max_length`,
 `pattern` and `description` - see [the API reference](documentation/API.md#parameter-rules).
 
-Saving again under the same name adds version 2; `DELETE /saved_sql/actor_by_id?version=1` removes one version.
+Saving again under the same name adds version 2; `DELETE /saved_sql/film_by_id?version=1` removes one version.
 
 Add `"cache_ttl": 60` to cache a response for that many seconds (`X-Cache: HIT`/`MISS`, `ETag`, `Cache-Control`) -
 opt-in, and never used for a query that writes. See
@@ -608,7 +616,7 @@ instead of it - a request has to pass both. See [Per-key rate limiting](document
 Every release is published to GitHub Container Registry for `linux/amd64` and `linux/arm64`:
 
 ~~~bash
-docker run -p 5000:5000 -v "$PWD/data:/data" -e QUERYAPIGATE_API_KEY=change-me ghcr.io/anantharajuc/queryapigate:latest
+docker run -p 5000:5000 -v queryapigate-data:/data -e QUERYAPIGATE_API_KEY=change-me ghcr.io/anantharajuc/queryapigate:latest
 ~~~
 
 | Tag | Contents |
@@ -617,7 +625,10 @@ docker run -p 5000:5000 -v "$PWD/data:/data" -e QUERYAPIGATE_API_KEY=change-me g
 | `X.Y.Z-h2`, `latest-h2` | The same plus Java and the H2 driver - also the variant to use for a generic `jdbc` connection (mount your vendor's jar) |
 
 The container keeps `db_connections.json` and `saved_sql/` in `/data` (create a starter with
-`docker run --rm -v "$PWD/data:/data" ghcr.io/anantharajuc/queryapigate queryapigate init`). It runs as a non-root user under
+`docker run --rm -v queryapigate-data:/data ghcr.io/anantharajuc/queryapigate queryapigate init`). The named volume above works
+out of the box. To use a folder on the host instead (`-v "$PWD/data:/data"`), create it yourself first (`mkdir data`) and make sure
+it is writable by uid 1000, the container's user - a folder that Docker creates for you is owned by root, which the container
+cannot write to (or run with `--user "$(id -u):$(id -g)"`). It runs as a non-root user under
 gunicorn with one worker (the files are protected by an in-process lock) and a health check on `/health`. Behind a
 reverse proxy or load balancer, set `QUERYAPIGATE_TRUST_PROXY=1`. To build it yourself:
 `docker build -t queryapigate .` (add `--build-arg WITH_H2=true` for H2).
@@ -715,12 +726,28 @@ observability are all useful areas. Please review [CONTRIBUTING.md](CONTRIBUTING
 
 ## Third-party components
 
-The wheel bundles the [H2 Database](https://h2database.com) JDBC driver (MPL 2.0 / EPL 1.0). The sample SQLite
-databases in `examples/` derive from the Sakila and Chinook sample datasets.
+The wheel bundles the [H2 Database](https://h2database.com) JDBC driver (MPL 2.0 / EPL 1.0). The example data is generated
+locally by `queryapigate examples load`; no third-party datasets are included.
 
 ## License
 
-[MIT](https://github.com/AnanthaRajuC/QueryAPIGate/blob/main/LICENSE) © Anantha Raju C
+QueryAPIGate is **source-available**, under the
+[Functional Source License, Version 1.1, MIT Future License](https://github.com/AnanthaRajuC/QueryAPIGate/blob/main/LICENSE)
+(`FSL-1.1-MIT`) © Anantha Raju C. It is not an OSI-approved open source license.
+
+In plain terms - the [LICENSE](https://github.com/AnanthaRajuC/QueryAPIGate/blob/main/LICENSE) is the only authoritative text:
+
+- **You may** use, copy, modify and redistribute it for any purpose that is not a *Competing Use* - including running it
+  inside your own company, non-commercial education and research, and professional services you provide to someone who
+  is themselves licensed to use it.
+- **You may not** make it available to others in a commercial product or service that substitutes for QueryAPIGate or
+  offers the same or substantially similar functionality (for example, selling it, or hosting it as a paid service).
+- **Each version becomes MIT** on the second anniversary of the date it was released, and can then be used under MIT terms.
+- **Versions up to and including 0.6.1** were released under the MIT license. They are no longer distributed (and the
+  repository history was reset in 0.7.0), but a copy you already obtained under MIT remains yours under those terms.
+
+Need something the license does not cover, such as offering it as part of a hosted service? Get in touch - commercial
+licensing may be available. This is a summary, not legal advice.
 
 ## Contact
 

{queryapigate-0.6.1 → queryapigate-0.7.1}/README.md

@@ -4,7 +4,7 @@
 [![codecov](https://codecov.io/gh/AnanthaRajuC/QueryAPIGate/branch/main/graph/badge.svg)](https://codecov.io/gh/AnanthaRajuC/QueryAPIGate)
 [![PyPI](https://img.shields.io/pypi/v/queryapigate.svg)](https://pypi.org/project/queryapigate/)
 [![PyPI downloads](https://img.shields.io/pypi/dm/queryapigate.svg)](https://pypi.org/project/queryapigate/)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/AnanthaRajuC/QueryAPIGate/blob/main/LICENSE)
+[![License: FSL-1.1-MIT](https://img.shields.io/badge/license-FSL--1.1--MIT-blue.svg)](https://github.com/AnanthaRajuC/QueryAPIGate/blob/main/LICENSE)
 ![Python](https://img.shields.io/badge/python-3.9%2B-blue)
 
 ### Turn SQL queries into secure, governed REST APIs.
@@ -13,6 +13,12 @@
 
 [**Full documentation**](https://AnanthaRajuC.github.io/QueryAPIGate/)
 
+<p align="center">
+  <a href="https://www.youtube.com/watch?v=aiVbAkA2LS8">
+    <img src="https://raw.githubusercontent.com/AnanthaRajuC/QueryAPIGate/main/documentation/screenshots/demo-thumbnail.png" alt="Watch the 60-second demo: saved SQL queries as REST endpoints, scoped API keys, and the Move preview showing which keys gain or lose access" width="640">
+  </a>
+</p>
+
 **QueryAPIGate** is a self-hosted, single Flask service that runs SQL against your databases and returns the results as
 JSON, NDJSON, XML, YAML, CSV, TSV or Excel. Save a query once and it becomes a versioned endpoint with typed,
 injection-safe parameters and run history - without writing a controller, a repository layer, pagination, auth or
@@ -21,13 +27,13 @@ serialization boilerplate for it.
 Write SQL. Configure the query. Apply access controls. Get an API.
 
 ~~~bash
-$ curl 'http://127.0.0.1:5000/q/actor_by_id?id=7'
-[{"actor_id": 7, "first_name": "GRACE", "last_name": "MOSTEL"}]
+$ curl 'http://127.0.0.1:5000/q/example_film_search?text=Harbor&page_size=2'
+[{"film_id":48,"title":"Broken Harbor","category":"Action","rating":"PG-13"},{"film_id":44,"title":"Electric Harbor","category":"Documentary","rating":"G"}]
 
-$ curl 'http://127.0.0.1:5000/q/films_by_rating?rating=PG&max_length=60&format=csv&page_size=2'
-film_id,title,rating,length
-410,HEAVEN FREEDOM,PG,48
-443,HURRICANE AFFAIR,PG,49
+$ curl 'http://127.0.0.1:5000/q/example_top_films?top_n=2&category=Comedy&format=csv'
+title,category,rating,rentals,rank
+Electric Signal,Comedy,PG,977,1
+Crimson Garden,Comedy,PG-13,631,2
 ~~~
 
 <p align="center">
@@ -213,11 +219,11 @@ version rather than overwriting the old one, so a change to the SQL doesn't sile
 ### Bound query parameters
 
 ```sql
-SELECT * FROM actor WHERE actor_id = :id
+SELECT * FROM film WHERE film_id = :id
 ```
 
 ```http
-GET /q/actor_by_id?id=7
+GET /q/film_by_id?id=7
 ```
 
 Values are sent to the database separately from the SQL text, so they cannot be injected into it. Parameters can
@@ -356,8 +362,8 @@ and CI on every push. See [Development](#development) below.
 without building a service per query:
 
 ```http
-GET /q/actor_by_id?id=7
-GET /q/films_by_rating?rating=PG&max_length=90
+GET /q/film_by_id?id=7
+GET /q/example_top_films?top_n=5&category=Comedy
 ```
 
 **Reporting APIs.** Turn an existing analytical SQL report into a reusable endpoint that dashboards or scheduled
@@ -423,17 +429,17 @@ From a clone: `pip install -e ".[dev]"`. Or use Docker - see [below](#docker).
 Fastest: `queryapigate examples load && queryapigate serve` installs four worked [example APIs](documentation/EXAMPLES.md)
 (reporting, dashboard, export, partner) you can try, and `queryapigate examples unload` removes them again.
 
-Or, from a clone, the repository ships two sample SQLite databases and a couple of saved queries:
-
 ~~~bash
-cd examples
-cp db_connections.example.json db_connections.json
+queryapigate examples load
 queryapigate serve                            # http://127.0.0.1:5000
 ~~~
 
+The examples come with a small generated `examples` database (films, customers and rentals), so you can also run ad-hoc SQL
+straight away:
+
 ~~~bash
 curl -X POST 'http://127.0.0.1:5000/execute_sql?page_size=3' -H 'Content-Type: application/json' \
-     -d '{"sql": "SELECT * FROM actor WHERE actor_id > :min", "params": {"min": 10}, "connection_name": "sakila-sqlite"}'
+     -d '{"sql": "SELECT film_id, title, rating FROM film WHERE film_id > :min", "params": {"min": 10}, "connection_name": "examples"}'
 ~~~
 
 Open <http://127.0.0.1:5000/docs> for the interactive API reference, or <http://127.0.0.1:5000/ui> for a small
@@ -444,24 +450,26 @@ every supported database) and `saved_sql/`. Edit the file, set `"active": true`,
 
 ## Saving a query as an endpoint
 
+This uses the `examples` connection that `queryapigate examples load` sets up:
+
 ~~~bash
 curl -X PATCH http://127.0.0.1:5000/save_sql_to_file -H 'Content-Type: application/json' -d '{
-  "filename": "actor_by_id",
-  "sql_query": "SELECT * FROM actor WHERE actor_id = :id",
-  "query_parameters": {"id": {"type": "int", "min": 1, "max": 200, "description": "Actor id"}},
-  "connection_name": "sakila-sqlite",
-  "author": "me", "description": "Look up an actor"
+  "filename": "film_by_id",
+  "sql_query": "SELECT * FROM film WHERE film_id = :id",
+  "query_parameters": {"id": {"type": "int", "min": 1, "max": 60, "description": "Film id"}},
+  "connection_name": "examples",
+  "author": "me", "description": "Look up a film"
 }'
 
-curl 'http://127.0.0.1:5000/q/actor_by_id?id=7&format=yaml'
-curl 'http://127.0.0.1:5000/q/actor_by_id?id=0'
+curl 'http://127.0.0.1:5000/q/film_by_id?id=7&format=yaml'
+curl 'http://127.0.0.1:5000/q/film_by_id?id=0'
 # {"error": "Invalid parameters: id must be at least 1", "errors": {"id": "must be at least 1"}}
 ~~~
 
 Rules: `type` (`int`, `float`, `str`, `bool`), `default`, `required`, `enum`, `min`/`max`, `min_length`/`max_length`,
 `pattern` and `description` - see [the API reference](documentation/API.md#parameter-rules).
 
-Saving again under the same name adds version 2; `DELETE /saved_sql/actor_by_id?version=1` removes one version.
+Saving again under the same name adds version 2; `DELETE /saved_sql/film_by_id?version=1` removes one version.
 
 Add `"cache_ttl": 60` to cache a response for that many seconds (`X-Cache: HIT`/`MISS`, `ETag`, `Cache-Control`) -
 opt-in, and never used for a query that writes. See
@@ -548,7 +556,7 @@ instead of it - a request has to pass both. See [Per-key rate limiting](document
 Every release is published to GitHub Container Registry for `linux/amd64` and `linux/arm64`:
 
 ~~~bash
-docker run -p 5000:5000 -v "$PWD/data:/data" -e QUERYAPIGATE_API_KEY=change-me ghcr.io/anantharajuc/queryapigate:latest
+docker run -p 5000:5000 -v queryapigate-data:/data -e QUERYAPIGATE_API_KEY=change-me ghcr.io/anantharajuc/queryapigate:latest
 ~~~
 
 | Tag | Contents |
@@ -557,7 +565,10 @@ docker run -p 5000:5000 -v "$PWD/data:/data" -e QUERYAPIGATE_API_KEY=change-me g
 | `X.Y.Z-h2`, `latest-h2` | The same plus Java and the H2 driver - also the variant to use for a generic `jdbc` connection (mount your vendor's jar) |
 
 The container keeps `db_connections.json` and `saved_sql/` in `/data` (create a starter with
-`docker run --rm -v "$PWD/data:/data" ghcr.io/anantharajuc/queryapigate queryapigate init`). It runs as a non-root user under
+`docker run --rm -v queryapigate-data:/data ghcr.io/anantharajuc/queryapigate queryapigate init`). The named volume above works
+out of the box. To use a folder on the host instead (`-v "$PWD/data:/data"`), create it yourself first (`mkdir data`) and make sure
+it is writable by uid 1000, the container's user - a folder that Docker creates for you is owned by root, which the container
+cannot write to (or run with `--user "$(id -u):$(id -g)"`). It runs as a non-root user under
 gunicorn with one worker (the files are protected by an in-process lock) and a health check on `/health`. Behind a
 reverse proxy or load balancer, set `QUERYAPIGATE_TRUST_PROXY=1`. To build it yourself:
 `docker build -t queryapigate .` (add `--build-arg WITH_H2=true` for H2).
@@ -655,12 +666,28 @@ observability are all useful areas. Please review [CONTRIBUTING.md](CONTRIBUTING
 
 ## Third-party components
 
-The wheel bundles the [H2 Database](https://h2database.com) JDBC driver (MPL 2.0 / EPL 1.0). The sample SQLite
-databases in `examples/` derive from the Sakila and Chinook sample datasets.
+The wheel bundles the [H2 Database](https://h2database.com) JDBC driver (MPL 2.0 / EPL 1.0). The example data is generated
+locally by `queryapigate examples load`; no third-party datasets are included.
 
 ## License
 
-[MIT](https://github.com/AnanthaRajuC/QueryAPIGate/blob/main/LICENSE) © Anantha Raju C
+QueryAPIGate is **source-available**, under the
+[Functional Source License, Version 1.1, MIT Future License](https://github.com/AnanthaRajuC/QueryAPIGate/blob/main/LICENSE)
+(`FSL-1.1-MIT`) © Anantha Raju C. It is not an OSI-approved open source license.
+
+In plain terms - the [LICENSE](https://github.com/AnanthaRajuC/QueryAPIGate/blob/main/LICENSE) is the only authoritative text:
+
+- **You may** use, copy, modify and redistribute it for any purpose that is not a *Competing Use* - including running it
+  inside your own company, non-commercial education and research, and professional services you provide to someone who
+  is themselves licensed to use it.
+- **You may not** make it available to others in a commercial product or service that substitutes for QueryAPIGate or
+  offers the same or substantially similar functionality (for example, selling it, or hosting it as a paid service).
+- **Each version becomes MIT** on the second anniversary of the date it was released, and can then be used under MIT terms.
+- **Versions up to and including 0.6.1** were released under the MIT license. They are no longer distributed (and the
+  repository history was reset in 0.7.0), but a copy you already obtained under MIT remains yours under those terms.
+
+Need something the license does not cover, such as offering it as part of a hosted service? Get in touch - commercial
+licensing may be available. This is a summary, not legal advice.
 
 ## Contact
 

{queryapigate-0.6.1 → queryapigate-0.7.1}/pyproject.toml

@@ -8,7 +8,7 @@ dynamic = ["version"]
 description = "Turn SQL into a REST API: run queries against MySQL, PostgreSQL, ClickHouse, SQLite or H2 over HTTP and get JSON, CSV, XML, YAML or XLSX back."
 readme = "README.md"
 requires-python = ">=3.9"
-license = "MIT"
+license = "FSL-1.1-MIT"
 authors = [{ name = "Anantha Raju C", email = "arcswdev@gmail.com" }]
 keywords = ["sql", "api", "rest", "flask", "database", "mysql", "postgresql", "clickhouse", "sqlite", "h2", "jdbc"]
 classifiers = [

{queryapigate-0.6.1 → queryapigate-0.7.1}/queryapigate/__init__.py

@@ -1,5 +1,5 @@
 """QueryAPIGate - expose SQL databases as a REST API."""
-__version__ = '0.6.1'
+__version__ = '0.7.1'
 
 from .app import create_app  # noqa: E402  (app imports __version__)
 

{queryapigate-0.6.1 → queryapigate-0.7.1}/queryapigate/app.py

@@ -76,6 +76,10 @@ def load_examples_at_startup():
         log.warning('QUERYAPIGATE_LOAD_EXAMPLES is set but the examples could not be loaded: %s',
                     getattr(error, 'message', error))
         return
+    except Exception as error:  # a convenience must never take the server down, whatever went wrong
+        log.warning('QUERYAPIGATE_LOAD_EXAMPLES is set but the examples could not be loaded (unexpected error: %s)',
+                    error, exc_info=True)
+        return
     if added['connection'] or added['queries'] or added['roles']:
         store.record_audit('startup', 'load_examples', 'examples', added)
         log.info('Loaded the example APIs: %d queries, %d roles', len(added['queries']), len(added['roles']))

{queryapigate-0.6.1 → queryapigate-0.7.1}/queryapigate/examples.py

@@ -19,6 +19,7 @@ walkthrough in ``documentation/EXAMPLES.md`` shows how to create one from the ex
 """
 import os
 import random
+import sqlite3
 from datetime import datetime, timedelta, timezone
 from typing import Any
 
@@ -78,7 +79,6 @@ CREATE INDEX rental_film_idx ON rental(film_id);
 def build_database(path, now=None, seed=42):
     """Create the example SQLite database at ``path`` (which must not exist). Deterministic for a given ``now`` and
     ``seed``. Dates are UTC, to match SQLite's own ``'now'`` that the example queries compare against."""
-    import sqlite3
     rng = random.Random(seed)
     now = now or datetime.now(timezone.utc).replace(tzinfo=None)
     titles = [f'{a} {n}' for a in _ADJECTIVES for n in _NOUNS]
@@ -274,7 +274,11 @@ def load(now=None):
         db_path = config.home() / DB_FILE
         if _marked_connection() is None:
             if not db_path.exists():
-                build_database(str(db_path), now)
+                try:
+                    build_database(str(db_path), now)
+                except sqlite3.Error as error:  # SQLite's own error type - not an OSError, so callers would miss it
+                    raise ApiError(f'Could not create the example database in {config.home()} ({error}). Is the data '
+                                   'folder writable by the user QueryAPIGate runs as?', 500) from None
             store.update_connections({CONNECTION: {'db': 'sqlite', 'database': DB_FILE, 'active': True,
                                                    'example': True}})
             added['connection'] = True

{queryapigate-0.6.1 → queryapigate-0.7.1/queryapigate.egg-info}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: queryapigate
-Version: 0.6.1
+Version: 0.7.1
 Summary: Turn SQL into a REST API: run queries against MySQL, PostgreSQL, ClickHouse, SQLite or H2 over HTTP and get JSON, CSV, XML, YAML or XLSX back.
 Author-email: Anantha Raju C <arcswdev@gmail.com>
-License-Expression: MIT
+License-Expression: FSL-1.1-MIT
 Project-URL: Homepage, https://github.com/AnanthaRajuC/QueryAPIGate
 Project-URL: Documentation, https://AnanthaRajuC.github.io/QueryAPIGate/
 Project-URL: Repository, https://github.com/AnanthaRajuC/QueryAPIGate
@@ -64,7 +64,7 @@ Dynamic: license-file
 [![codecov](https://codecov.io/gh/AnanthaRajuC/QueryAPIGate/branch/main/graph/badge.svg)](https://codecov.io/gh/AnanthaRajuC/QueryAPIGate)
 [![PyPI](https://img.shields.io/pypi/v/queryapigate.svg)](https://pypi.org/project/queryapigate/)
 [![PyPI downloads](https://img.shields.io/pypi/dm/queryapigate.svg)](https://pypi.org/project/queryapigate/)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/AnanthaRajuC/QueryAPIGate/blob/main/LICENSE)
+[![License: FSL-1.1-MIT](https://img.shields.io/badge/license-FSL--1.1--MIT-blue.svg)](https://github.com/AnanthaRajuC/QueryAPIGate/blob/main/LICENSE)
 ![Python](https://img.shields.io/badge/python-3.9%2B-blue)
 
 ### Turn SQL queries into secure, governed REST APIs.
@@ -73,6 +73,12 @@ Dynamic: license-file
 
 [**Full documentation**](https://AnanthaRajuC.github.io/QueryAPIGate/)
 
+<p align="center">
+  <a href="https://www.youtube.com/watch?v=aiVbAkA2LS8">
+    <img src="https://raw.githubusercontent.com/AnanthaRajuC/QueryAPIGate/main/documentation/screenshots/demo-thumbnail.png" alt="Watch the 60-second demo: saved SQL queries as REST endpoints, scoped API keys, and the Move preview showing which keys gain or lose access" width="640">
+  </a>
+</p>
+
 **QueryAPIGate** is a self-hosted, single Flask service that runs SQL against your databases and returns the results as
 JSON, NDJSON, XML, YAML, CSV, TSV or Excel. Save a query once and it becomes a versioned endpoint with typed,
 injection-safe parameters and run history - without writing a controller, a repository layer, pagination, auth or
@@ -81,13 +87,13 @@ serialization boilerplate for it.
 Write SQL. Configure the query. Apply access controls. Get an API.
 
 ~~~bash
-$ curl 'http://127.0.0.1:5000/q/actor_by_id?id=7'
-[{"actor_id": 7, "first_name": "GRACE", "last_name": "MOSTEL"}]
+$ curl 'http://127.0.0.1:5000/q/example_film_search?text=Harbor&page_size=2'
+[{"film_id":48,"title":"Broken Harbor","category":"Action","rating":"PG-13"},{"film_id":44,"title":"Electric Harbor","category":"Documentary","rating":"G"}]
 
-$ curl 'http://127.0.0.1:5000/q/films_by_rating?rating=PG&max_length=60&format=csv&page_size=2'
-film_id,title,rating,length
-410,HEAVEN FREEDOM,PG,48
-443,HURRICANE AFFAIR,PG,49
+$ curl 'http://127.0.0.1:5000/q/example_top_films?top_n=2&category=Comedy&format=csv'
+title,category,rating,rentals,rank
+Electric Signal,Comedy,PG,977,1
+Crimson Garden,Comedy,PG-13,631,2
 ~~~
 
 <p align="center">
@@ -273,11 +279,11 @@ version rather than overwriting the old one, so a change to the SQL doesn't sile
 ### Bound query parameters
 
 ```sql
-SELECT * FROM actor WHERE actor_id = :id
+SELECT * FROM film WHERE film_id = :id
 ```
 
 ```http
-GET /q/actor_by_id?id=7
+GET /q/film_by_id?id=7
 ```
 
 Values are sent to the database separately from the SQL text, so they cannot be injected into it. Parameters can
@@ -416,8 +422,8 @@ and CI on every push. See [Development](#development) below.
 without building a service per query:
 
 ```http
-GET /q/actor_by_id?id=7
-GET /q/films_by_rating?rating=PG&max_length=90
+GET /q/film_by_id?id=7
+GET /q/example_top_films?top_n=5&category=Comedy
 ```
 
 **Reporting APIs.** Turn an existing analytical SQL report into a reusable endpoint that dashboards or scheduled
@@ -483,17 +489,17 @@ From a clone: `pip install -e ".[dev]"`. Or use Docker - see [below](#docker).
 Fastest: `queryapigate examples load && queryapigate serve` installs four worked [example APIs](documentation/EXAMPLES.md)
 (reporting, dashboard, export, partner) you can try, and `queryapigate examples unload` removes them again.
 
-Or, from a clone, the repository ships two sample SQLite databases and a couple of saved queries:
-
 ~~~bash
-cd examples
-cp db_connections.example.json db_connections.json
+queryapigate examples load
 queryapigate serve                            # http://127.0.0.1:5000
 ~~~
 
+The examples come with a small generated `examples` database (films, customers and rentals), so you can also run ad-hoc SQL
+straight away:
+
 ~~~bash
 curl -X POST 'http://127.0.0.1:5000/execute_sql?page_size=3' -H 'Content-Type: application/json' \
-     -d '{"sql": "SELECT * FROM actor WHERE actor_id > :min", "params": {"min": 10}, "connection_name": "sakila-sqlite"}'
+     -d '{"sql": "SELECT film_id, title, rating FROM film WHERE film_id > :min", "params": {"min": 10}, "connection_name": "examples"}'
 ~~~
 
 Open <http://127.0.0.1:5000/docs> for the interactive API reference, or <http://127.0.0.1:5000/ui> for a small
@@ -504,24 +510,26 @@ every supported database) and `saved_sql/`. Edit the file, set `"active": true`,
 
 ## Saving a query as an endpoint
 
+This uses the `examples` connection that `queryapigate examples load` sets up:
+
 ~~~bash
 curl -X PATCH http://127.0.0.1:5000/save_sql_to_file -H 'Content-Type: application/json' -d '{
-  "filename": "actor_by_id",
-  "sql_query": "SELECT * FROM actor WHERE actor_id = :id",
-  "query_parameters": {"id": {"type": "int", "min": 1, "max": 200, "description": "Actor id"}},
-  "connection_name": "sakila-sqlite",
-  "author": "me", "description": "Look up an actor"
+  "filename": "film_by_id",
+  "sql_query": "SELECT * FROM film WHERE film_id = :id",
+  "query_parameters": {"id": {"type": "int", "min": 1, "max": 60, "description": "Film id"}},
+  "connection_name": "examples",
+  "author": "me", "description": "Look up a film"
 }'
 
-curl 'http://127.0.0.1:5000/q/actor_by_id?id=7&format=yaml'
-curl 'http://127.0.0.1:5000/q/actor_by_id?id=0'
+curl 'http://127.0.0.1:5000/q/film_by_id?id=7&format=yaml'
+curl 'http://127.0.0.1:5000/q/film_by_id?id=0'
 # {"error": "Invalid parameters: id must be at least 1", "errors": {"id": "must be at least 1"}}
 ~~~
 
 Rules: `type` (`int`, `float`, `str`, `bool`), `default`, `required`, `enum`, `min`/`max`, `min_length`/`max_length`,
 `pattern` and `description` - see [the API reference](documentation/API.md#parameter-rules).
 
-Saving again under the same name adds version 2; `DELETE /saved_sql/actor_by_id?version=1` removes one version.
+Saving again under the same name adds version 2; `DELETE /saved_sql/film_by_id?version=1` removes one version.
 
 Add `"cache_ttl": 60` to cache a response for that many seconds (`X-Cache: HIT`/`MISS`, `ETag`, `Cache-Control`) -
 opt-in, and never used for a query that writes. See
@@ -608,7 +616,7 @@ instead of it - a request has to pass both. See [Per-key rate limiting](document
 Every release is published to GitHub Container Registry for `linux/amd64` and `linux/arm64`:
 
 ~~~bash
-docker run -p 5000:5000 -v "$PWD/data:/data" -e QUERYAPIGATE_API_KEY=change-me ghcr.io/anantharajuc/queryapigate:latest
+docker run -p 5000:5000 -v queryapigate-data:/data -e QUERYAPIGATE_API_KEY=change-me ghcr.io/anantharajuc/queryapigate:latest
 ~~~
 
 | Tag | Contents |
@@ -617,7 +625,10 @@ docker run -p 5000:5000 -v "$PWD/data:/data" -e QUERYAPIGATE_API_KEY=change-me g
 | `X.Y.Z-h2`, `latest-h2` | The same plus Java and the H2 driver - also the variant to use for a generic `jdbc` connection (mount your vendor's jar) |
 
 The container keeps `db_connections.json` and `saved_sql/` in `/data` (create a starter with
-`docker run --rm -v "$PWD/data:/data" ghcr.io/anantharajuc/queryapigate queryapigate init`). It runs as a non-root user under
+`docker run --rm -v queryapigate-data:/data ghcr.io/anantharajuc/queryapigate queryapigate init`). The named volume above works
+out of the box. To use a folder on the host instead (`-v "$PWD/data:/data"`), create it yourself first (`mkdir data`) and make sure
+it is writable by uid 1000, the container's user - a folder that Docker creates for you is owned by root, which the container
+cannot write to (or run with `--user "$(id -u):$(id -g)"`). It runs as a non-root user under
 gunicorn with one worker (the files are protected by an in-process lock) and a health check on `/health`. Behind a
 reverse proxy or load balancer, set `QUERYAPIGATE_TRUST_PROXY=1`. To build it yourself:
 `docker build -t queryapigate .` (add `--build-arg WITH_H2=true` for H2).
@@ -715,12 +726,28 @@ observability are all useful areas. Please review [CONTRIBUTING.md](CONTRIBUTING
 
 ## Third-party components
 
-The wheel bundles the [H2 Database](https://h2database.com) JDBC driver (MPL 2.0 / EPL 1.0). The sample SQLite
-databases in `examples/` derive from the Sakila and Chinook sample datasets.
+The wheel bundles the [H2 Database](https://h2database.com) JDBC driver (MPL 2.0 / EPL 1.0). The example data is generated
+locally by `queryapigate examples load`; no third-party datasets are included.
 
 ## License
 
-[MIT](https://github.com/AnanthaRajuC/QueryAPIGate/blob/main/LICENSE) © Anantha Raju C
+QueryAPIGate is **source-available**, under the
+[Functional Source License, Version 1.1, MIT Future License](https://github.com/AnanthaRajuC/QueryAPIGate/blob/main/LICENSE)
+(`FSL-1.1-MIT`) © Anantha Raju C. It is not an OSI-approved open source license.
+
+In plain terms - the [LICENSE](https://github.com/AnanthaRajuC/QueryAPIGate/blob/main/LICENSE) is the only authoritative text:
+
+- **You may** use, copy, modify and redistribute it for any purpose that is not a *Competing Use* - including running it
+  inside your own company, non-commercial education and research, and professional services you provide to someone who
+  is themselves licensed to use it.
+- **You may not** make it available to others in a commercial product or service that substitutes for QueryAPIGate or
+  offers the same or substantially similar functionality (for example, selling it, or hosting it as a paid service).
+- **Each version becomes MIT** on the second anniversary of the date it was released, and can then be used under MIT terms.
+- **Versions up to and including 0.6.1** were released under the MIT license. They are no longer distributed (and the
+  repository history was reset in 0.7.0), but a copy you already obtained under MIT remains yours under those terms.
+
+Need something the license does not cover, such as offering it as part of a hosted service? Get in touch - commercial
+licensing may be available. This is a summary, not legal advice.
 
 ## Contact
 

{queryapigate-0.6.1 → queryapigate-0.7.1}/tests/test_examples.py

@@ -39,6 +39,14 @@ class ExamplesTestCase(unittest.TestCase):
         store.save_version(name, {'sql_query': 'SELECT 1', 'author': 'me', 'description': 'mine', 'tags': [],
                                   'query_parameters': {}}, collection)
 
+    def make_home_unwritable(self):
+        """A real read-only data folder - what a Docker bind mount created by root looks like to the container's
+        non-root user. (Mocking an OSError would not do: SQLite raises its own error type here.)"""
+        if os.geteuid() == 0:
+            self.skipTest('root ignores directory permissions')
+        os.chmod(self.home, 0o555)
+        self.addCleanup(os.chmod, self.home, 0o755)
+
     def run_cli(self, *argv):
         out, err = io.StringIO(), io.StringIO()
         with redirect_stdout(out), redirect_stderr(err):
@@ -47,6 +55,13 @@ class ExamplesTestCase(unittest.TestCase):
 
 
 class DatabaseTests(ExamplesTestCase):
+    def test_an_unwritable_folder_is_an_apierror_with_a_hint(self):
+        self.make_home_unwritable()
+        with self.assertRaises(ApiError) as caught:
+            examples.load()
+        self.assertEqual(caught.exception.status, 500)
+        self.assertIn('writable', caught.exception.message)
+
     def build(self, **kwargs):
         path = os.path.join(self.home, 'x.db')
         examples.build_database(path, FIXED_NOW, **kwargs)
@@ -450,6 +465,24 @@ class StartupTests(ExamplesTestCase):
         self.assertEqual(app.test_client().get('/health').status_code, 200)
         self.assertEqual(self.saved_files(), ['example_top_films.json'])
 
+    def test_a_really_unwritable_home_is_a_warning_not_a_crash(self):
+        # This crashed the container: examples.load() let SQLite's own OperationalError escape, which the startup hook
+        # (catching only ApiError/OSError) did not handle, so the worker died and gunicorn kept restarting it.
+        self.make_home_unwritable()
+        os.environ['QUERYAPIGATE_LOAD_EXAMPLES'] = 'yes'
+        with self.assertLogs('queryapigate', level='WARNING') as captured:
+            app = create_app()
+        self.assertTrue(any('could not be loaded' in line for line in captured.output), captured.output)
+        self.assertEqual(app.test_client().get('/health').status_code, 200)
+
+    def test_an_unexpected_failure_while_loading_is_still_only_a_warning(self):
+        os.environ['QUERYAPIGATE_LOAD_EXAMPLES'] = 'yes'
+        with mock.patch.object(examples, 'load', side_effect=RuntimeError('something new')):
+            with self.assertLogs('queryapigate', level='WARNING') as captured:
+                app = create_app()
+        self.assertTrue(any('something new' in line for line in captured.output), captured.output)
+        self.assertEqual(app.test_client().get('/health').status_code, 200)
+
     def test_a_read_only_home_is_a_warning_not_a_startup_failure(self):
         os.environ['QUERYAPIGATE_LOAD_EXAMPLES'] = 'yes'
         with mock.patch.object(examples, 'load', side_effect=OSError('read-only file system')):
@@ -489,6 +522,13 @@ class CliTests(ExamplesTestCase):
         _, out, _ = self.run_cli('examples', 'unload')
         self.assertIn('partner-key', out)
 
+    def test_an_unwritable_home_is_a_clean_message_not_a_traceback(self):
+        self.make_home_unwritable()
+        code, _, err = self.run_cli('examples', 'load')
+        self.assertEqual(code, 1)
+        self.assertIn('queryapigate examples load:', err)
+        self.assertNotIn('Traceback', err)
+
     def test_bare_command_shows_help_and_a_leftover_old_setting_still_stops_it(self):
         code, out, _ = self.run_cli('examples')
         self.assertEqual((code, 'load' in out), (2, True))

queryapigate-0.6.1/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2024 Anantha Raju C
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.