queryapigate 0.7.0__tar.gz → 0.7.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: queryapigate
-Version: 0.7.0
+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: FSL-1.1-MIT
@@ -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
@@ -610,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 |
@@ -619,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).
@@ -734,9 +743,8 @@ In plain terms - the [LICENSE](https://github.com/AnanthaRajuC/QueryAPIGate/blob
 - **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 and remain available under it (the
-  releases on PyPI: [`queryapigate`](https://pypi.org/project/queryapigate/) 0.5.0-0.6.1 and
-  [`sql2api`](https://pypi.org/project/sql2api/) 0.1.0-0.4.0).
+- **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.

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

@@ -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
@@ -550,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 |
@@ -559,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).
@@ -674,9 +683,8 @@ In plain terms - the [LICENSE](https://github.com/AnanthaRajuC/QueryAPIGate/blob
 - **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 and remain available under it (the
-  releases on PyPI: [`queryapigate`](https://pypi.org/project/queryapigate/) 0.5.0-0.6.1 and
-  [`sql2api`](https://pypi.org/project/sql2api/) 0.1.0-0.4.0).
+- **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.

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

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

{queryapigate-0.7.0 → 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.7.0 → 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.7.0 → queryapigate-0.7.1/queryapigate.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: queryapigate
-Version: 0.7.0
+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: FSL-1.1-MIT
@@ -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
@@ -610,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 |
@@ -619,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).
@@ -734,9 +743,8 @@ In plain terms - the [LICENSE](https://github.com/AnanthaRajuC/QueryAPIGate/blob
 - **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 and remain available under it (the
-  releases on PyPI: [`queryapigate`](https://pypi.org/project/queryapigate/) 0.5.0-0.6.1 and
-  [`sql2api`](https://pypi.org/project/sql2api/) 0.1.0-0.4.0).
+- **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.

{queryapigate-0.7.0 → 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))