# Flight SQL WebSocket Proxy Server - by [GizmoData](https://gizmodata.com)™
[<img src="https://img.shields.io/badge/GitHub-gizmodata%2Fflight--sql--websocket--proxy-blue.svg?logo=Github">](https://github.com/gizmodata/flight-sql-websocket-proxy)
[<img src="https://img.shields.io/badge/dockerhub-image-green?logo=Docker">](https://hub.docker.com/r/gizmodata/flight-sql-websocket-proxy)
[](https://github.com/gizmodata/flight-sql-websocket-proxy/actions/workflows/ci.yml)
[](https://badge.fury.io/py/flight-sql-websocket-proxy)
[](https://pypi.org/project/flight-sql-websocket-proxy/)
An Arrow Flight SQL WebSocket Proxy Server
For a convenient way to run an Arrow Flight SQL Server (powered by DuckDB) - see [GizmoSQL](https://gizmodata.com/gizmosql) - with instructions on how to run in Docker, here: https://github.com/gizmodata/gizmosql-public
# Setup (to run locally)
## Install package
You can install `flight-sql-websocket-proxy` from PyPi or from source.
### Option 1 - from PyPi (recommended)
```shell
# Create the virtual environment
python3 -m venv .venv
# Activate the virtual environment
. .venv/bin/activate
# Install the package
pip install flight-sql-websocket-proxy
```
### Option 2 - from source - for development
```shell
git clone https://github.com/gizmodata/flight-sql-websocket-proxy
cd flight-sql-websocket-proxy
# Create the virtual environment
python3 -m venv .venv
# Activate the virtual environment
. .venv/bin/activate
# Upgrade pip, setuptools, and wheel
pip install --upgrade pip setuptools wheel
# Install the Python package - in editable mode with dev dependencies
pip install --editable .[dev]
```
### Note
For the following commands - if you running from source and using `--editable` mode (for development purposes) - you will need to set the PYTHONPATH environment variable as follows:
```shell
export PYTHONPATH=$(pwd)/src
```
### Setting up your .env (environment) file
Create a text file named `.env` in the root of the project directory. This file will contain the environment variables needed to run the application.
Example:
```text
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxxxxxxxxxx
CLERK_SECRET_KEY=XXXXXXXXX
CLERK_API_URL=https://api.clerk.dev
JWKS_URL=https://something.clerk.accounts.dev/.well-known/jwks.json
SESSION_TOKEN_ISSUER=https://something.clerk.accounts.dev
DATABASE_SERVER_URI=grpc+tls://localhost:31337
DATABASE_USERNAME=gizmosql_username
DATABASE_PASSWORD=gizmosql_password
DATABASE_TLS_SKIP_VERIFY=TRUE
```
### Running the server locally
You can run the Flight SQL WebSocket Proxy Server executable locally - here is the help output:
```shell
flight-sql-websocket-proxy-server --help
Usage: flight-sql-websocket-proxy-server [OPTIONS]
Options:
--version / --no-version Prints the Arrow Flight SQL WebSocket Proxy
Server version and exits. [required]
--port INTEGER Run the websocket server on this port.
Defaults to environment variable SERVER_PORT
if set, or 8765 if not set. [default: 8765;
required]
--tls ('CERTFILE', 'KEYFILE') Enable transport-level security (TLS/SSL).
Provide a Certificate file path, and a Key
file path - separated by a space. Defaults
to environment variable TLS if set.
Example: tls/server.crt tls/server.key
--database-server-uri TEXT The URI of the Arrow Flight SQL server.
Defaults to environment variable
DATABASE_SERVER_URI if set, or
grpc+tls://localhost:31337 if not set.
[required]
--database-username TEXT The username to authenticate with the Arrow
Flight SQL server. Defaults to environment
variable DATABASE_USERNAME if set.
[required]
--database-password TEXT The password to authenticate with the Arrow
Flight SQL server. Defaults to environment
variable DATABASE_PASSWORD if set.
[required]
--database-tls-skip-verify / --no-database-tls-skip-verify
Skip TLS verification of the Arrow Flight
SQL server. Defaults to environment
variable DATABASE_TLS_SKIP_VERIFY if set, or
FALSE if not set. [default: database-tls-
skip-verify; required]
--clerk-api-url TEXT The CLERK API URL - for user authentication.
Defaults to environment variable
CLERK_API_URL if set, or
https://api.clerk.dev if not set.
[required]
--clerk-secret-key TEXT The CLERK Secret Key - for user
authentication. Defaults to environment
variable CLERK_SECRET_KEY if set.
[required]
--jwks-url TEXT The JWKS URL used for client session JWT
token validation - for user authentication.
Defaults to environment variable JWKS_URL if
set. Example: https://wise-
cattle-777.clerk.accounts.dev/.well-
known/jwks.json [required]
--session-token-issuer TEXT The issuer used for client session JWT token
validation - for user authentication.
Defaults to environment variable
SESSION_TOKEN_ISSUER if set. Example:
https://wise-cattle-777.clerk.accounts.dev
[required]
--max-process-workers INTEGER Max process workers. Defaults to
environment variable MAX_PROCESS_WORKERS if
set. [default: 10; required]
--websocket-ping-timeout INTEGER
Web-socket ping timeout. Defaults to
environment variable PING_TIMEOUT if set.
[default: 60; required]
--max-websocket-message-size INTEGER
Maximum Websocket message size [default:
1073741824; required]
--client-default-fetch-size INTEGER
The default websocket client fetch size for
queries. [default: 50; required]
--help Show this message and exit.
```
### Running the server via Docker
You can optionally run the Flight SQL WebSocket Proxy Server via Docker:
Open a terminal, then pull and run the published Docker image which has everything setup - with command:
```bash
# Pull and run the Docker image
docker run --name flight-sql-websocket-proxy \
--interactive \
--rm \
--tty \
--init \
--publish 8765:8765 \
--pull missing \
--env-file .env \
gizmodata/flight-sql-websocket-proxy:latest
```
### Running the client
You can run the Flight SQL WebSocket Proxy Client executable locally - here is the help output:
```bash
flight-sql-websocket-proxy-client --help
Usage: flight-sql-websocket-proxy-client [OPTIONS]
Options:
--version / --no-version Prints the Arrow Flight SQL Websocket Proxy
Client version and exits. [required]
--server-protocol [wss|ws] The protocol of the Arrow Flight SQL
Websocket Proxy server. Defaults to
environment variable SERVER_PROTOCOL if set,
or wss if not set. [required]
--server-hostname TEXT The hostname of the Arrow Flight SQL
Websocket Proxy server. Defaults to
environment variable SERVER_HOSTNAME if set,
or localhost if not set. [required]
--server-port INTEGER The port of the Arrow Flight SQL Websocket
Proxy server. Defaults to environment
variable SERVER_PORT if set, or 8765 if not
set. [required]
--server-base-path TEXT The base path of the Arrow Flight SQL
Websocket Proxy server. Defaults to
environment variable SERVER_BASE_PATH if
set, or / if not set. [required]
--tls-verify / --no-tls-verify Verify the server's TLS certificate hostname
and signature. Using --no-tls-verify is
insecure, only use for development purposes!
[default: tls-verify]
--tls-roots TEXT 'Path to trusted TLS certificate(s).
Defaults to environment variable TLS_ROOTS
if set. If not set, the system default
trusted certificates will be used.
--token TEXT The client clerk JWT token to authenticate
with. Defaults to environment variable
TOKEN if set. [required]
--max-result-set-rows INTEGER The maximum number of rows to show in result
sets. A value of 0 means no limit.
[default: 100; required]
--autocommit / --no-autocommit Enable autocommit mode. [default:
autocommit]
--help Show this message and exit.
```
### Handy development commands
#### Version management
##### Bump the version of the application - (you must have installed from source with the [dev] extras)
```bash
bumpver update --patch
```
Raw data
{
"_id": null,
"home_page": null,
"name": "flight-sql-websocket-proxy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "arrow, flight, sql, websocket, proxy, server",
"author": null,
"author_email": "Philip Moore <philip@gizmodata.com>",
"download_url": "https://files.pythonhosted.org/packages/18/cf/b948f6e3f733136ec7acf579c13614680a0705083dac83a008818a8c85ea/flight_sql_websocket_proxy-0.0.12.tar.gz",
"platform": null,
"description": "# Flight SQL WebSocket Proxy Server - by [GizmoData](https://gizmodata.com)\u2122\n\n[<img src=\"https://img.shields.io/badge/GitHub-gizmodata%2Fflight--sql--websocket--proxy-blue.svg?logo=Github\">](https://github.com/gizmodata/flight-sql-websocket-proxy)\n[<img src=\"https://img.shields.io/badge/dockerhub-image-green?logo=Docker\">](https://hub.docker.com/r/gizmodata/flight-sql-websocket-proxy)\n[](https://github.com/gizmodata/flight-sql-websocket-proxy/actions/workflows/ci.yml)\n[](https://badge.fury.io/py/flight-sql-websocket-proxy)\n[](https://pypi.org/project/flight-sql-websocket-proxy/)\n\nAn Arrow Flight SQL WebSocket Proxy Server\n\nFor a convenient way to run an Arrow Flight SQL Server (powered by DuckDB) - see [GizmoSQL](https://gizmodata.com/gizmosql) - with instructions on how to run in Docker, here: https://github.com/gizmodata/gizmosql-public\n\n# Setup (to run locally)\n\n## Install package\nYou can install `flight-sql-websocket-proxy` from PyPi or from source.\n\n### Option 1 - from PyPi (recommended) \n\n```shell\n# Create the virtual environment\npython3 -m venv .venv\n\n# Activate the virtual environment\n. .venv/bin/activate\n\n# Install the package \npip install flight-sql-websocket-proxy\n```\n\n### Option 2 - from source - for development\n```shell\ngit clone https://github.com/gizmodata/flight-sql-websocket-proxy\n\ncd flight-sql-websocket-proxy\n\n# Create the virtual environment\npython3 -m venv .venv\n\n# Activate the virtual environment\n. .venv/bin/activate\n\n# Upgrade pip, setuptools, and wheel\npip install --upgrade pip setuptools wheel\n\n# Install the Python package - in editable mode with dev dependencies\npip install --editable .[dev]\n```\n\n### Note\nFor the following commands - if you running from source and using `--editable` mode (for development purposes) - you will need to set the PYTHONPATH environment variable as follows:\n```shell\nexport PYTHONPATH=$(pwd)/src\n```\n\n### Setting up your .env (environment) file\nCreate a text file named `.env` in the root of the project directory. This file will contain the environment variables needed to run the application. \n\nExample:\n```text\nNEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxxxxxxxxxx\nCLERK_SECRET_KEY=XXXXXXXXX\nCLERK_API_URL=https://api.clerk.dev\nJWKS_URL=https://something.clerk.accounts.dev/.well-known/jwks.json\nSESSION_TOKEN_ISSUER=https://something.clerk.accounts.dev\nDATABASE_SERVER_URI=grpc+tls://localhost:31337\nDATABASE_USERNAME=gizmosql_username\nDATABASE_PASSWORD=gizmosql_password\nDATABASE_TLS_SKIP_VERIFY=TRUE\n```\n\n### Running the server locally\nYou can run the Flight SQL WebSocket Proxy Server executable locally - here is the help output:\n```shell\nflight-sql-websocket-proxy-server --help\nUsage: flight-sql-websocket-proxy-server [OPTIONS]\n\nOptions:\n --version / --no-version Prints the Arrow Flight SQL WebSocket Proxy\n Server version and exits. [required]\n --port INTEGER Run the websocket server on this port.\n Defaults to environment variable SERVER_PORT\n if set, or 8765 if not set. [default: 8765;\n required]\n --tls ('CERTFILE', 'KEYFILE') Enable transport-level security (TLS/SSL).\n Provide a Certificate file path, and a Key\n file path - separated by a space. Defaults\n to environment variable TLS if set.\n Example: tls/server.crt tls/server.key\n --database-server-uri TEXT The URI of the Arrow Flight SQL server.\n Defaults to environment variable\n DATABASE_SERVER_URI if set, or\n grpc+tls://localhost:31337 if not set.\n [required]\n --database-username TEXT The username to authenticate with the Arrow\n Flight SQL server. Defaults to environment\n variable DATABASE_USERNAME if set.\n [required]\n --database-password TEXT The password to authenticate with the Arrow\n Flight SQL server. Defaults to environment\n variable DATABASE_PASSWORD if set.\n [required]\n --database-tls-skip-verify / --no-database-tls-skip-verify\n Skip TLS verification of the Arrow Flight\n SQL server. Defaults to environment\n variable DATABASE_TLS_SKIP_VERIFY if set, or\n FALSE if not set. [default: database-tls-\n skip-verify; required]\n --clerk-api-url TEXT The CLERK API URL - for user authentication.\n Defaults to environment variable\n CLERK_API_URL if set, or\n https://api.clerk.dev if not set.\n [required]\n --clerk-secret-key TEXT The CLERK Secret Key - for user\n authentication. Defaults to environment\n variable CLERK_SECRET_KEY if set.\n [required]\n --jwks-url TEXT The JWKS URL used for client session JWT\n token validation - for user authentication.\n Defaults to environment variable JWKS_URL if\n set. Example: https://wise-\n cattle-777.clerk.accounts.dev/.well-\n known/jwks.json [required]\n --session-token-issuer TEXT The issuer used for client session JWT token\n validation - for user authentication.\n Defaults to environment variable\n SESSION_TOKEN_ISSUER if set. Example:\n https://wise-cattle-777.clerk.accounts.dev\n [required]\n --max-process-workers INTEGER Max process workers. Defaults to\n environment variable MAX_PROCESS_WORKERS if\n set. [default: 10; required]\n --websocket-ping-timeout INTEGER\n Web-socket ping timeout. Defaults to\n environment variable PING_TIMEOUT if set.\n [default: 60; required]\n --max-websocket-message-size INTEGER\n Maximum Websocket message size [default:\n 1073741824; required]\n --client-default-fetch-size INTEGER\n The default websocket client fetch size for\n queries. [default: 50; required]\n --help Show this message and exit.\n```\n\n### Running the server via Docker\nYou can optionally run the Flight SQL WebSocket Proxy Server via Docker:\n\nOpen a terminal, then pull and run the published Docker image which has everything setup - with command:\n\n```bash\n# Pull and run the Docker image \ndocker run --name flight-sql-websocket-proxy \\\n --interactive \\\n --rm \\\n --tty \\\n --init \\\n --publish 8765:8765 \\\n --pull missing \\\n --env-file .env \\\n gizmodata/flight-sql-websocket-proxy:latest\n```\n\n### Running the client\nYou can run the Flight SQL WebSocket Proxy Client executable locally - here is the help output:\n```bash\nflight-sql-websocket-proxy-client --help\nUsage: flight-sql-websocket-proxy-client [OPTIONS]\n\nOptions:\n --version / --no-version Prints the Arrow Flight SQL Websocket Proxy\n Client version and exits. [required]\n --server-protocol [wss|ws] The protocol of the Arrow Flight SQL\n Websocket Proxy server. Defaults to\n environment variable SERVER_PROTOCOL if set,\n or wss if not set. [required]\n --server-hostname TEXT The hostname of the Arrow Flight SQL\n Websocket Proxy server. Defaults to\n environment variable SERVER_HOSTNAME if set,\n or localhost if not set. [required]\n --server-port INTEGER The port of the Arrow Flight SQL Websocket\n Proxy server. Defaults to environment\n variable SERVER_PORT if set, or 8765 if not\n set. [required]\n --server-base-path TEXT The base path of the Arrow Flight SQL\n Websocket Proxy server. Defaults to\n environment variable SERVER_BASE_PATH if\n set, or / if not set. [required]\n --tls-verify / --no-tls-verify Verify the server's TLS certificate hostname\n and signature. Using --no-tls-verify is\n insecure, only use for development purposes!\n [default: tls-verify]\n --tls-roots TEXT 'Path to trusted TLS certificate(s).\n Defaults to environment variable TLS_ROOTS\n if set. If not set, the system default\n trusted certificates will be used.\n --token TEXT The client clerk JWT token to authenticate\n with. Defaults to environment variable\n TOKEN if set. [required]\n --max-result-set-rows INTEGER The maximum number of rows to show in result\n sets. A value of 0 means no limit.\n [default: 100; required]\n --autocommit / --no-autocommit Enable autocommit mode. [default:\n autocommit]\n --help Show this message and exit.\n```\n\n### Handy development commands\n\n#### Version management\n\n##### Bump the version of the application - (you must have installed from source with the [dev] extras)\n```bash\nbumpver update --patch\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python-based Apache Arrow Flight SQL WebSocket Proxy Server",
"version": "0.0.12",
"project_urls": {
"Homepage": "https://github.com/gizmodata/flight-sql-websocket-proxy"
},
"split_keywords": [
"arrow",
" flight",
" sql",
" websocket",
" proxy",
" server"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cc1584daa3796f3be06dcdcf85e063dc3703fcf06b32d1db207831a1251e3c7f",
"md5": "3d5020f71053b863a3ddef08c06845e8",
"sha256": "11409e5532e077cd8f2600c88b59ba9aba3ddf2cd4ce2a7bfc4415c1d831d507"
},
"downloads": -1,
"filename": "flight_sql_websocket_proxy-0.0.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3d5020f71053b863a3ddef08c06845e8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 23952,
"upload_time": "2025-07-08T14:00:48",
"upload_time_iso_8601": "2025-07-08T14:00:48.443843Z",
"url": "https://files.pythonhosted.org/packages/cc/15/84daa3796f3be06dcdcf85e063dc3703fcf06b32d1db207831a1251e3c7f/flight_sql_websocket_proxy-0.0.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "18cfb948f6e3f733136ec7acf579c13614680a0705083dac83a008818a8c85ea",
"md5": "8be5c2f289089444af4df569a76b428e",
"sha256": "7e98681ec84bfa64dfb33272979a380b3d83d33d331168bb6a747416fc30f0ed"
},
"downloads": -1,
"filename": "flight_sql_websocket_proxy-0.0.12.tar.gz",
"has_sig": false,
"md5_digest": "8be5c2f289089444af4df569a76b428e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 22133,
"upload_time": "2025-07-08T14:00:50",
"upload_time_iso_8601": "2025-07-08T14:00:50.148017Z",
"url": "https://files.pythonhosted.org/packages/18/cf/b948f6e3f733136ec7acf579c13614680a0705083dac83a008818a8c85ea/flight_sql_websocket_proxy-0.0.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-08 14:00:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gizmodata",
"github_project": "flight-sql-websocket-proxy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "flight-sql-websocket-proxy"
}
JSON
