sql2api 0.1.0__tar.gz → 0.3.0__tar.gz

{sql2api-0.1.0/sql2api.egg-info → sql2api-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql2api
-Version: 0.1.0
+Version: 0.3.0
 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: MIT
@@ -37,6 +37,7 @@ Requires-Dist: gunicorn>=21; extra == "server"
 Provides-Extra: dev
 Requires-Dist: sql2api[all]; extra == "dev"
 Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: openapi-spec-validator>=0.7; extra == "dev"
 Dynamic: license-file
 
 # SQL2API
@@ -74,7 +75,15 @@ film_id,title,rating,length
   (or `?version=1`). Each run is recorded in the query's execution history.
 - **Bound parameters** - write `WHERE id = :id` and the value is sent to the database separately from the SQL, so it
   cannot inject anything. Declare types (`{"id": "int"}`) and query-string values are converted for you.
+- **Parameter rules** - saved queries can declare defaults, optional parameters, allowed values, numeric ranges and
+  text patterns. Bad input is rejected with a field-by-field `400` before it reaches the database.
+- **A live catalogue of your endpoints** - `/docs` lists every saved query as its own endpoint with its parameters and
+  rules. The SQL itself is never shown, and with an API key set the list is hidden from anonymous readers.
 - **Pagination** - `?page=2&page_size=50`, with `X-Has-More` telling you whether another page exists.
+- **Connection pooling** - MySQL, PostgreSQL, ClickHouse and H2 connections are reused between requests instead of
+  opened for each one (about 30x lower per-request overhead on MySQL and H2 against a local server; more over a network).
+- **Query time limit** - runaway queries are cancelled on the database (30 s by default, `?timeout=` per request) so
+  they cannot tie up the service.
 - **Read-only by default** - only single `SELECT`/`WITH`/`SHOW`/`DESCRIBE`/`EXPLAIN` statements run, and sessions are
   opened read-only where the database supports it.
 - **Secrets stay out of files** - `"password": "${PG_PASSWORD}"` in `db_connections.json` reads the environment.
@@ -116,14 +125,19 @@ every supported database) and `saved_sql/`. Edit the file, set `"active": true`,
 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": "int"},
+  "query_parameters": {"id": {"type": "int", "min": 1, "max": 200, "description": "Actor id"}},
   "connection_name": "sakila-sqlite",
   "author": "me", "description": "Look up an actor"
 }'
 
 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'
+# {"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.
 
 ## Configuration
@@ -136,6 +150,12 @@ Everything is configured through environment variables (all optional):
 | `SQL2API_ALLOW_WRITES` | off | Allow `INSERT`/`UPDATE`/DDL. Otherwise only single read-only statements are accepted. |
 | `SQL2API_API_KEY` | unset | When set, every request (except `/health` and `/docs`) needs a matching `X-API-Key` header. |
 | `SQL2API_MAX_PAGE_SIZE` | `1000` | Upper limit for `page_size`. |
+| `SQL2API_CORS_ORIGINS` | unset | Websites allowed to call the API from a browser: comma-separated origins such as `https://app.example.com`, or `*`. Off by default. |
+| `SQL2API_RATE_LIMIT` | unset | Requests allowed per client address, e.g. `60/minute` (also `second`, `hour`, `day`). Off by default; a malformed value stops startup. |
+| `SQL2API_TRUST_PROXY` | `0` | Number of reverse proxies in front of the app whose `X-Forwarded-*` headers are trusted. Set it (usually `1`) behind nginx, a load balancer or a platform router, or every client looks like the proxy. |
+| `SQL2API_POOL_SIZE` | `5` | Idle connections kept per distinct connection setting. `0` turns pooling off. |
+| `SQL2API_POOL_IDLE_TIMEOUT` | `300` | Seconds an idle pooled connection is kept before it is closed. |
+| `SQL2API_QUERY_TIMEOUT` | `30` | Seconds a query may run before it is cancelled (HTTP 504). `0` disables the limit. A request can lower it with `?timeout=`, never raise it. |
 | `SQL2API_HOST` / `SQL2API_PORT` | `127.0.0.1` / `5000` | Bind address for `sql2api serve`. |
 | `SQL2API_DEBUG` | off | Flask debug mode. Never enable on a reachable host. |
 | `SQL2API_H2_JAR` | bundled | Path to a different H2 JDBC jar. |
@@ -153,15 +173,59 @@ SQL2API runs whatever SQL it is given against your databases, so it ships locked
 
 See [SECURITY.md](SECURITY.md) to report a vulnerability.
 
+### Calling the API from a browser
+
+Browsers refuse cross-origin JSON calls unless the server allows them. List the sites that may call the API:
+
+~~~bash
+SQL2API_API_KEY=change-me SQL2API_CORS_ORIGINS=https://app.example.com sql2api serve
+~~~
+
+Preflight checks are answered automatically, and the pagination headers (`X-Has-More` etc.) are exposed to the page's
+JavaScript. CORS only tells the *browser* which sites may call; it is not authentication, so keep the API key. Avoid
+`*` without a key: any website a visitor opens could then reach your databases through their browser (the server logs
+a warning if you start that way).
+
+### Rate limiting
+
+`SQL2API_RATE_LIMIT=60/minute` gives each client address a bucket of 60 requests that refills steadily, so short bursts
+work but the sustained rate is capped. Over the limit, requests get `429` with a `Retry-After` header, and every
+response carries `X-RateLimit-Limit` and `X-RateLimit-Remaining`. The limit is applied before the API key check, so
+guessing keys is throttled too; `/health` and CORS preflights are never counted. State is per process: with several
+workers, the effective limit is multiplied by the number of workers.
+
 ## Docker
 
+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 SQL2API_API_KEY=change-me ghcr.io/anantharajuc/sql2api:latest
+~~~
+
+| Tag | Contents |
+|-----|----------|
+| `X.Y.Z`, `latest` | SQL2API with the MySQL, PostgreSQL and ClickHouse drivers (SQLite is built in) |
+| `X.Y.Z-h2`, `latest-h2` | The same plus Java and the H2 driver |
+
+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/sql2api sql2api init`). 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 `SQL2API_TRUST_PROXY=1`. To build it yourself:
+`docker build -t sql2api .` (add `--build-arg WITH_H2=true` for H2).
+
+### Try it with one command
+
+[`docker-compose.yml`](docker-compose.yml) starts SQL2API in front of a PostgreSQL database seeded with sample films:
+
 ~~~bash
-docker build -t sql2api .                          # add --build-arg WITH_H2=true for H2 support
-docker run -p 5000:5000 -v "$PWD/data:/data" -e SQL2API_API_KEY=change-me sql2api
+docker compose up --build
+curl -H 'X-API-Key: demo-key' 'http://127.0.0.1:5000/q/films_by_rating?rating=PG&max_length=90'
 ~~~
 
-The container keeps `db_connections.json` and `saved_sql/` in `/data`. It runs gunicorn with a single worker
-(the files are protected by an in-process lock).
+Open <http://127.0.0.1:5000/docs>, paste `demo-key` into the box at the top, and both saved queries appear as endpoints.
+The demo listens on localhost only, mounts its configuration read-only, and reads the database password from an
+environment variable (`${DEMO_DB_PASSWORD}` in [`demo/data/db_connections.json`](demo/data/db_connections.json)).
+Clean up with `docker compose down -v`.
 
 ## API overview
 

{sql2api-0.1.0 → sql2api-0.3.0}/README.md

@@ -33,7 +33,15 @@ film_id,title,rating,length
   (or `?version=1`). Each run is recorded in the query's execution history.
 - **Bound parameters** - write `WHERE id = :id` and the value is sent to the database separately from the SQL, so it
   cannot inject anything. Declare types (`{"id": "int"}`) and query-string values are converted for you.
+- **Parameter rules** - saved queries can declare defaults, optional parameters, allowed values, numeric ranges and
+  text patterns. Bad input is rejected with a field-by-field `400` before it reaches the database.
+- **A live catalogue of your endpoints** - `/docs` lists every saved query as its own endpoint with its parameters and
+  rules. The SQL itself is never shown, and with an API key set the list is hidden from anonymous readers.
 - **Pagination** - `?page=2&page_size=50`, with `X-Has-More` telling you whether another page exists.
+- **Connection pooling** - MySQL, PostgreSQL, ClickHouse and H2 connections are reused between requests instead of
+  opened for each one (about 30x lower per-request overhead on MySQL and H2 against a local server; more over a network).
+- **Query time limit** - runaway queries are cancelled on the database (30 s by default, `?timeout=` per request) so
+  they cannot tie up the service.
 - **Read-only by default** - only single `SELECT`/`WITH`/`SHOW`/`DESCRIBE`/`EXPLAIN` statements run, and sessions are
   opened read-only where the database supports it.
 - **Secrets stay out of files** - `"password": "${PG_PASSWORD}"` in `db_connections.json` reads the environment.
@@ -75,14 +83,19 @@ every supported database) and `saved_sql/`. Edit the file, set `"active": true`,
 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": "int"},
+  "query_parameters": {"id": {"type": "int", "min": 1, "max": 200, "description": "Actor id"}},
   "connection_name": "sakila-sqlite",
   "author": "me", "description": "Look up an actor"
 }'
 
 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'
+# {"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.
 
 ## Configuration
@@ -95,6 +108,12 @@ Everything is configured through environment variables (all optional):
 | `SQL2API_ALLOW_WRITES` | off | Allow `INSERT`/`UPDATE`/DDL. Otherwise only single read-only statements are accepted. |
 | `SQL2API_API_KEY` | unset | When set, every request (except `/health` and `/docs`) needs a matching `X-API-Key` header. |
 | `SQL2API_MAX_PAGE_SIZE` | `1000` | Upper limit for `page_size`. |
+| `SQL2API_CORS_ORIGINS` | unset | Websites allowed to call the API from a browser: comma-separated origins such as `https://app.example.com`, or `*`. Off by default. |
+| `SQL2API_RATE_LIMIT` | unset | Requests allowed per client address, e.g. `60/minute` (also `second`, `hour`, `day`). Off by default; a malformed value stops startup. |
+| `SQL2API_TRUST_PROXY` | `0` | Number of reverse proxies in front of the app whose `X-Forwarded-*` headers are trusted. Set it (usually `1`) behind nginx, a load balancer or a platform router, or every client looks like the proxy. |
+| `SQL2API_POOL_SIZE` | `5` | Idle connections kept per distinct connection setting. `0` turns pooling off. |
+| `SQL2API_POOL_IDLE_TIMEOUT` | `300` | Seconds an idle pooled connection is kept before it is closed. |
+| `SQL2API_QUERY_TIMEOUT` | `30` | Seconds a query may run before it is cancelled (HTTP 504). `0` disables the limit. A request can lower it with `?timeout=`, never raise it. |
 | `SQL2API_HOST` / `SQL2API_PORT` | `127.0.0.1` / `5000` | Bind address for `sql2api serve`. |
 | `SQL2API_DEBUG` | off | Flask debug mode. Never enable on a reachable host. |
 | `SQL2API_H2_JAR` | bundled | Path to a different H2 JDBC jar. |
@@ -112,15 +131,59 @@ SQL2API runs whatever SQL it is given against your databases, so it ships locked
 
 See [SECURITY.md](SECURITY.md) to report a vulnerability.
 
+### Calling the API from a browser
+
+Browsers refuse cross-origin JSON calls unless the server allows them. List the sites that may call the API:
+
+~~~bash
+SQL2API_API_KEY=change-me SQL2API_CORS_ORIGINS=https://app.example.com sql2api serve
+~~~
+
+Preflight checks are answered automatically, and the pagination headers (`X-Has-More` etc.) are exposed to the page's
+JavaScript. CORS only tells the *browser* which sites may call; it is not authentication, so keep the API key. Avoid
+`*` without a key: any website a visitor opens could then reach your databases through their browser (the server logs
+a warning if you start that way).
+
+### Rate limiting
+
+`SQL2API_RATE_LIMIT=60/minute` gives each client address a bucket of 60 requests that refills steadily, so short bursts
+work but the sustained rate is capped. Over the limit, requests get `429` with a `Retry-After` header, and every
+response carries `X-RateLimit-Limit` and `X-RateLimit-Remaining`. The limit is applied before the API key check, so
+guessing keys is throttled too; `/health` and CORS preflights are never counted. State is per process: with several
+workers, the effective limit is multiplied by the number of workers.
+
 ## Docker
 
+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 SQL2API_API_KEY=change-me ghcr.io/anantharajuc/sql2api:latest
+~~~
+
+| Tag | Contents |
+|-----|----------|
+| `X.Y.Z`, `latest` | SQL2API with the MySQL, PostgreSQL and ClickHouse drivers (SQLite is built in) |
+| `X.Y.Z-h2`, `latest-h2` | The same plus Java and the H2 driver |
+
+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/sql2api sql2api init`). 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 `SQL2API_TRUST_PROXY=1`. To build it yourself:
+`docker build -t sql2api .` (add `--build-arg WITH_H2=true` for H2).
+
+### Try it with one command
+
+[`docker-compose.yml`](docker-compose.yml) starts SQL2API in front of a PostgreSQL database seeded with sample films:
+
 ~~~bash
-docker build -t sql2api .                          # add --build-arg WITH_H2=true for H2 support
-docker run -p 5000:5000 -v "$PWD/data:/data" -e SQL2API_API_KEY=change-me sql2api
+docker compose up --build
+curl -H 'X-API-Key: demo-key' 'http://127.0.0.1:5000/q/films_by_rating?rating=PG&max_length=90'
 ~~~
 
-The container keeps `db_connections.json` and `saved_sql/` in `/data`. It runs gunicorn with a single worker
-(the files are protected by an in-process lock).
+Open <http://127.0.0.1:5000/docs>, paste `demo-key` into the box at the top, and both saved queries appear as endpoints.
+The demo listens on localhost only, mounts its configuration read-only, and reads the database password from an
+environment variable (`${DEMO_DB_PASSWORD}` in [`demo/data/db_connections.json`](demo/data/db_connections.json)).
+Clean up with `docker compose down -v`.
 
 ## API overview
 

{sql2api-0.1.0 → sql2api-0.3.0}/pyproject.toml

@@ -29,7 +29,7 @@ clickhouse = ["clickhouse-driver>=0.2"]
 h2 = ["JayDeBeApi>=1.2", "JPype1>=1.4"]  # also needs a Java runtime
 all = ["sql2api[mysql,postgres,clickhouse,h2]"]
 server = ["gunicorn>=21"]
-dev = ["sql2api[all]", "ruff>=0.5"]
+dev = ["sql2api[all]", "ruff>=0.5", "openapi-spec-validator>=0.7"]
 
 [project.urls]
 Homepage = "https://github.com/AnanthaRajuC/SQL2API"

{sql2api-0.1.0 → sql2api-0.3.0}/sql2api/__init__.py

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

{sql2api-0.1.0 → sql2api-0.3.0}/sql2api/app.py

@@ -1,21 +1,26 @@
 """The Flask application: HTTP routes on top of the store, engine and formatters."""
 import hmac
 import logging
+import math
 
-from flask import Blueprint, Flask, Response, jsonify, redirect, request, url_for
+from flask import Blueprint, Flask, Response, current_app, g, jsonify, redirect, request, url_for
 from flask.json.provider import DefaultJSONProvider
 from werkzeug.exceptions import HTTPException
+from werkzeug.middleware.proxy_fix import ProxyFix
 
-from . import config, engine, openapi, sqltools, store
+from . import config, cors, engine, openapi, pool, sqltools, store
+from . import params as param_rules
 from .errors import ApiError
 from .formats import FORMATTERS, json_default
+from .ratelimit import RateLimiter
 
 log = logging.getLogger('sql2api')
 bp = Blueprint('api', __name__)
 
 # Query-string arguments that control a request rather than supplying query parameters.
-RESERVED_ARGS = {'format', 'page', 'page_size', 'connection_name', 'version'}
+RESERVED_ARGS = {'format', 'page', 'page_size', 'connection_name', 'version', 'timeout'}
 PUBLIC_ENDPOINTS = {'api.index', 'api.favicon', 'api.health', 'api.docs', 'api.openapi_spec'}
+RATE_LIMIT_EXEMPT = {'api.health'}  # so monitoring keeps working while a client is being throttled
 
 
 class JSONProvider(DefaultJSONProvider):
@@ -25,7 +30,15 @@ class JSONProvider(DefaultJSONProvider):
 
 def create_app():
     from . import __version__
+    config.check_settings()
     app = Flask(__name__)
+    hops = config.proxy_hops()
+    if hops:  # behind reverse proxies: take the client address and scheme from their X-Forwarded-* headers
+        app.wsgi_app = ProxyFix(app.wsgi_app, x_for=hops, x_proto=hops, x_host=hops)
+    app.extensions['sql2api_limiter'] = RateLimiter()
+    if config.cors_origins() == '*' and not config.api_key():
+        log.warning('SQL2API_CORS_ORIGINS=* without SQL2API_API_KEY: any website a user visits can call this API '
+                    'from their browser and reach every active connection. Set an API key or list the origins.')
     app.json = JSONProvider(app)
     app.config['SQL2API_VERSION'] = __version__
 
@@ -43,13 +56,25 @@ def create_app():
         return jsonify({'error': 'An error occurred'}), 500
 
     @app.before_request
-    def require_api_key():
-        expected = config.api_key()
-        if expected and request.endpoint not in PUBLIC_ENDPOINTS:
-            # compare_digest rejects non-ASCII str, so compare bytes
-            supplied = request.headers.get('X-API-Key', '').encode('utf-8', 'replace')
-            if not hmac.compare_digest(supplied, expected.encode('utf-8')):
-                return jsonify({'error': 'Unauthorized'}), 401
+    def gate():
+        # Order matters: a browser's preflight cannot carry the API key, and rate limiting comes before the key
+        # check so that guessing keys is throttled too.
+        if cors.is_preflight(request):
+            return cors.preflight_response(request.headers.get('Origin'))
+        limited = check_rate_limit()
+        if limited is not None:
+            return limited
+        if request.endpoint not in PUBLIC_ENDPOINTS and not has_valid_key():
+            return jsonify({'error': 'Unauthorized'}), 401
+
+    @app.after_request
+    def decorate(response):
+        cors.add_headers(response, request.headers.get('Origin'))
+        if g.get('rate_limit'):
+            limit, remaining = g.rate_limit
+            response.headers['X-RateLimit-Limit'] = str(limit)
+            response.headers['X-RateLimit-Remaining'] = str(remaining)
+        return response
 
     app.register_blueprint(bp)
     return app
@@ -59,6 +84,33 @@ def create_app():
 # Request helpers
 # --------------------------------------------------------------------------------------
 
+def check_rate_limit():
+    """Count this request against its client's quota; returns a 429 response when it is over the limit."""
+    limit = config.rate_limit()
+    if limit is None or request.method == 'OPTIONS' or request.endpoint in RATE_LIMIT_EXEMPT:
+        return None
+    count, period = limit
+    client = request.remote_addr or 'unknown'
+    allowed, remaining, retry_after = current_app.extensions['sql2api_limiter'].hit(client, count, period)
+    g.rate_limit = (count, remaining)
+    if allowed:
+        return None
+    response = jsonify({'error': 'Rate limit exceeded', 'retry_after': retry_after})
+    response.status_code = 429
+    response.headers['Retry-After'] = str(retry_after)
+    return response
+
+
+def has_valid_key():
+    """True when no API key is configured, or the request carries the right X-API-Key header."""
+    expected = config.api_key()
+    if not expected:
+        return True
+    # compare_digest rejects non-ASCII str, so compare bytes
+    supplied = request.headers.get('X-API-Key', '').encode('utf-8', 'replace')
+    return hmac.compare_digest(supplied, expected.encode('utf-8'))
+
+
 def get_json_body(required=True):
     data = request.get_json(silent=True)
     if data is None and not required:
@@ -105,6 +157,20 @@ def get_output_format(body=None):
     return output_format
 
 
+def get_timeout(body=None):
+    """Seconds allowed for the query: ?timeout= may lower the server limit but never raise it."""
+    raw = request.args.get('timeout', (body or {}).get('timeout'))
+    if raw in (None, ''):
+        return config.effective_timeout(None)
+    try:
+        value = float(raw)
+    except (TypeError, ValueError):
+        raise ApiError('timeout must be a number of seconds') from None
+    if not math.isfinite(value) or value <= 0:
+        raise ApiError('timeout must be a positive number of seconds')
+    return config.effective_timeout(value)
+
+
 def render(result, output_format, page, page_size):
     response = jsonify({'message': 'No results returned'}) if not result else FORMATTERS[output_format](result)
     response.headers['X-Page'] = str(page)
@@ -126,8 +192,9 @@ def execute_sql_endpoint():
         raise ApiError('Connection name is missing')
     params = get_object(data.get('params'), 'params')
     output_format = get_output_format(data)
+    timeout = get_timeout(data)
     limit, offset, page = get_pagination()
-    result = engine.execute_sql(data['sql'], data['connection_name'], limit, offset, params)
+    result = engine.execute_sql(data['sql'], data['connection_name'], limit, offset, params, timeout)
     return render(result, output_format, page, limit)
 
 
@@ -145,14 +212,16 @@ def run_saved(ref, body, url_params):
 
     raw = {**url_params, **get_object(body.get('params'), 'params'),
            **get_object(body.get('placeholders'), 'placeholders')}
-    params = sqltools.coerce_params(saved.get('query_parameters'), raw)
-    sql = sqltools.fill_placeholders(saved['sql_query'], params)
+    used = set(sqltools.placeholder_names(saved['sql_query']))
+    values = param_rules.resolve(saved.get('query_parameters'), raw, used=used)
+    sql = sqltools.fill_placeholders(saved['sql_query'], values)
     output_format = get_output_format(body)
+    timeout = get_timeout(body)
     limit, offset, page = get_pagination()
 
     entry = {'executed_at': store.now(), 'connection_name': connection_name}
     try:
-        result, elapsed_ms = engine.timed(engine.execute_sql, sql, connection_name, limit, offset, params)
+        result, elapsed_ms = engine.timed(engine.execute_sql, sql, connection_name, limit, offset, values, timeout)
     except ApiError as error:
         store.record_execution(path, number, {**entry, 'status': 'error', 'error': error.message})
         raise
@@ -197,6 +266,11 @@ def save_sql_to_file():
     if not isinstance(tags, (list, str)):
         raise ApiError('tags must be a string or a list')
     query_parameters = get_object(data.get('query_parameters'), 'query_parameters')
+    param_rules.parse_definitions(query_parameters)
+    unused = sorted(set(query_parameters) - set(sqltools.placeholder_names(data['sql_query'])))
+    if unused:
+        raise ApiError(f"query_parameters declares {', '.join(unused)}, which sql_query does not use "
+                       '(write :name in the SQL, or remove the declaration)')
     connection_name = data.get('connection_name')
     if connection_name is not None and not isinstance(connection_name, str):
         raise ApiError('connection_name must be a string')
@@ -256,12 +330,14 @@ def update_connections():
     if not connections or not isinstance(connections, dict):
         raise ApiError('Connections data is missing')
     store.update_connections(connections)
+    pool.close_pooled_connections()  # new settings or credentials must not be served by old connections
     return jsonify({'message': 'Connections updated successfully'}), 200
 
 
 @bp.route('/connections/<name>', methods=['DELETE'])
 def delete_connection(name):
     store.delete_connection(name)
+    pool.close_pooled_connections()  # a removed connection must not keep serving from idle sockets
     return jsonify({'message': f"Connection '{name}' deleted"}), 200
 
 
@@ -285,10 +361,31 @@ def health():
     return jsonify({'status': 'ok', 'version': current_app.config['SQL2API_VERSION']})
 
 
+def describe_saved_queries():
+    """What the OpenAPI document needs to know about each saved query (never its SQL text)."""
+    described = []
+    for name, number, data in store.latest_versions():
+        sql = data.get('sql_query')
+        if not isinstance(sql, str):
+            continue
+        declared = param_rules.read_definitions(data.get('query_parameters'))
+        used = sqltools.placeholder_names(sql)
+        parameters = {}
+        for param in used:  # what the SQL needs, in order; undeclared ones are plain required text
+            parameters[param] = declared.get(param) or param_rules.read_definition({})
+        described.append({'name': name, 'version': number, 'description': data.get('description'),
+                          'tags': data.get('tags'), 'connection_name': data.get('connection_name'),
+                          'parameters': parameters})
+    return described
+
+
 @bp.route('/openapi.json', methods=['GET'])
 def openapi_spec():
     from flask import current_app
-    return jsonify(openapi.build_spec(current_app.config['SQL2API_VERSION']))
+    # The generic API description is public. The list of saved queries (names, descriptions, parameters) is only
+    # shown to callers who could list them anyway, so an API key protects it too.
+    saved = describe_saved_queries() if has_valid_key() else None
+    return jsonify(openapi.build_spec(current_app.config['SQL2API_VERSION'], saved))
 
 
 @bp.route('/docs', methods=['GET'])

{sql2api-0.1.0 → sql2api-0.3.0}/sql2api/cli.py

@@ -2,6 +2,7 @@
 import argparse
 import logging
 import os
+import sys
 
 from . import __version__, config, store
 from .app import create_app
@@ -10,7 +11,11 @@ LOOPBACK_HOSTS = ('127.0.0.1', 'localhost', '::1')
 
 
 def _serve(args):
-    app = create_app()
+    try:
+        app = create_app()
+    except ValueError as error:  # a malformed setting, e.g. SQL2API_RATE_LIMIT
+        print(f'sql2api: {error}', file=sys.stderr)
+        return 2
     if args.host not in LOOPBACK_HOSTS and not config.api_key():
         logging.getLogger('sql2api').warning(
             'Listening on %s without SQL2API_API_KEY set: anyone who can reach this port can run SQL '