> ## Documentation Index > Fetch the complete documentation index at: https://docs.firebolt.io/llms.txt > Use this file to discover all available pages before exploring further. # Connecting over HTTP > Submit SQL to a self-managed Firebolt engine over its HTTP endpoint, including output formats, session handling, transactions, and security. Each Firebolt engine accepts SQL over an HTTP endpoint: a client sends an HTTP `POST` whose body is a single SQL statement, and the engine returns the result in the response body. Any HTTP client works. This page describes that wire protocol: request format, output formats, session handling, transactions, and security. For the endpoints you send to, the instance gateway or an engine's own Service, see [Connect to engines](./firebolt-operator/instance/gateway/overview#connect-to-engines). The examples here reach an engine directly through its Service, so forward its port to your workstation: ```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}} kubectl -n firebolt port-forward svc/my-engine-service 3473:3473 ``` Then submit a query: ```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}} curl --silent "localhost:3473" --data-binary "SELECT 42" # 42 ``` ## System settings Set [system settings](/reference-sql/system-settings) per query by appending them to the HTTP query string. For example, set `timezone`: ```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}} curl --silent "localhost:3473/?timezone=utc" --data-binary "SELECT TIMESTAMPTZ '1996-09-03 11:19:33.123456 Europe/Berlin' AS ts" # ts # timestamptz # 1996-09-03 09:19:33.123456+00 ``` Separate multiple settings with an ampersand (`&`): ```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}} curl --silent "localhost:3473/?max_result_rows=1&timezone=utc" --data-binary "SELECT 1" ``` ## Output format Results are returned in the response body. By default they are a human-readable tab-separated string: ```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}} curl --silent "localhost:3473" --data-binary "SELECT x, 42 * x AS multiplied FROM generate_series(1,4) g(x)" ``` ``` x multiplied int int 1 42 2 84 3 126 4 168 ``` Set the `output_format` query-string parameter to choose another format. Use `JSON_Compact` when results are consumed by code rather than read by a human. The supported formats are: * `TabSeparatedWithNamesAndTypes` (default) * `JSON_Compact` * `JSON_CompactLimited` (same as `JSON_Compact`, capped at 10,000 rows) * `JSONLines_Compact` (chunked version of `JSON_CompactLimited`) `JSON_Compact` returns one JSON document: ```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}} curl --silent "localhost:3473/?output_format=JSON_Compact" --data-binary "SELECT x, 42 * x FROM generate_series(1,4) g(x)" ``` ```json theme={"theme":{"light":"css-variables","dark":"css-variables"}} { "query": { "query_id": "7487991c-d84c-40a4-bdaf-3bc4507f250a", "request_id": "a6a9f32d-8b3c-469e-a778-1ff27221781b", "query_label": null }, "meta": [ { "name": "x", "type": "int" }, { "name": "?column?", "type": "int" } ], "data": [ [1, 42], [2, 84], [3, 126], [4, 168] ], "rows": 4, "statistics": { "elapsed": 0.001598, "rows_read": 1, "bytes_read": 1, "time_before_execution": 0.000324689, "time_to_execute": 0.000205699, "scanned_bytes_cache": 0, "scanned_bytes_storage": 0 } } ``` `JSONLines_Compact` returns newline-delimited messages: ```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}} curl --silent "localhost:3473/?output_format=JSONLines_Compact" --data-binary "SELECT x, 42 * x FROM generate_series(1,4) g(x)" ``` ```json theme={"theme":{"light":"css-variables","dark":"css-variables"}} {"message_type":"START","query_id":"7487991c-d84c-40a4-bdaf-3bc4507f250a","query_label":null,"request_id":"a6a9f32d-8b3c-469e-a778-1ff27221781b","result_columns":[{"name":"x","type":"integer"},{"name":"?column?","type":"integer"}]} {"message_type":"DATA","data":[[1,42],[2,84],[3,126],[4,168]]} {"message_type":"FINISH_SUCCESSFULLY","statistics":{"bytes_read":1,"elapsed":0.001598,"result_rows":4,"rows_read":1,"scanned_bytes_cache":0,"scanned_bytes_storage":0}} ``` ## Sessions The protocol is stateless: the engine keeps no server-side session. Most statements need nothing more than a single request, but operations that carry state across statements, such as changing the current database or running an explicit transaction, need the client to maintain that state. The engine drives this through response headers and query-string parameters: * When a response carries `Firebolt-Update-Parameters: key=value`, include `key=value` in the query string of every later request on the same connection. * When a response carries `Firebolt-Remove-Parameters: key`, drop `key` from the query string of later requests. ### Changing the current database [`USE DATABASE`](/reference-sql/commands/data-definition/use-database) validates that the database exists and returns a `Firebolt-Update-Parameters: database=...` header. Because there is no server-side state, the change takes effect only once you start sending that parameter: ```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}} curl --silent "localhost:3473" --data-binary "SELECT current_database()" # firebolt curl --verbose "localhost:3473" --data-binary "USE DATABASE example" # < Firebolt-Update-Parameters: database=example curl --silent "localhost:3473" --data-binary "SELECT current_database()" # still firebolt: the returned parameter has not been applied yet curl --silent "localhost:3473/?database=example" --data-binary "SELECT current_database()" # example ``` ### Explicit transactions `BEGIN TRANSACTION` returns a `Firebolt-Update-Parameters: transaction_id=...` header. Send that `transaction_id` on every later request to run inside the transaction. `COMMIT` or `ROLLBACK` returns `Firebolt-Remove-Parameters: transaction_id`, after which you stop sending it. See [Explicit transactions](/reference-sql/explicit-transactions). ```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}} curl --verbose "localhost:3473" --data-binary "BEGIN TRANSACTION" # < Firebolt-Update-Parameters: transaction_id=0000000000000c04ba100 curl --silent "localhost:3473/?transaction_id=0000000000000c04ba100" --data-binary "INSERT INTO t1 VALUES (1)" curl --verbose "localhost:3473/?transaction_id=0000000000000c04ba100" --data-binary "COMMIT TRANSACTION" # < Firebolt-Remove-Parameters: transaction_id ``` ## Transactions Every statement runs in its own transaction that commits when the statement finishes and rolls back when it fails. There can be any number of concurrent read transactions, but only one write transaction can be active across the whole engine at a time. Submitting a write while another write transaction is active returns an error, so a client that issues concurrent writes serializes them itself, for example through a queue. ## Security A Firebolt engine's HTTP endpoint has no built-in authentication or transport security: * Traffic is unencrypted HTTP. Anyone who can observe it reads everything exchanged, including secrets passed to reach external resources such as S3 or GCS. * Requests are not authenticated and there is no role-based access control. Anyone who can reach the endpoint has full access to the engine. Treat network reachability as the security boundary. Restrict access to the gateway and engine Services with Kubernetes NetworkPolicies and your platform's network controls, and terminate TLS at an ingress in front of the deployment when clients connect from outside the cluster. See Security for the [Firebolt Operator](./firebolt-operator/security) and the [Helm chart](./helm-chart/security). ## Other ways to connect ### Firebolt CLI The [`fb` CLI](https://github.com/firebolt-db/fb-cli) (download from the [releases page](https://github.com/firebolt-db/fb-cli/releases)) speaks the same HTTP protocol. The `--core` preset targets `localhost:3473` with no authentication, which matches a port-forwarded engine endpoint: ```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}} fb --core => SELECT 42; ?column? --------- 42 ``` Pass `--host ` to connect to a different host, or a query as a positional argument to run it and exit (`fb --core 'SELECT 42'`). ```text theme={"theme":{"light":"css-variables","dark":"css-variables"}} fb command-line arguments: query Query to execute; with none, starts the REPL. -c, --command COMMAND Run a single command and exit. -C, --core Preset for a self-managed / Firebolt Core engine (localhost:3473, no auth). -h, --host HOSTNAME Hostname to connect to. -d, --database DATABASE Database to use. -f, --format FORMAT Output format (TabSeparatedWithNames, PSQL, JSONLines_Compact, Vertical, ...). -e, --extra EXTRA Extra settings, as --extra =. -l, --label LABEL Query label for tracking. --concise Suppress time statistics. --hide-pii Hide URLs that may contain PII in query parameters. --no-spinner Disable the spinner. -v, --verbose Verbose output. -V, --version Print version and exit. --help Show help and exit. Managed Firebolt cloud authentication flags, not used against a self-managed engine: -j/--jwt, --jwt-from-file, --sa-id, --sa-secret, --bearer, --oauth-env. ``` ### Client SDKs Firebolt's client SDKs connect to a self-managed engine over the same protocol. See the connection guide for each: * [Go](/guides/developing-with-firebolt/connecting-with-go) * [JDBC](/guides/developing-with-firebolt/connecting-with-jdbc) * [Node.js](/guides/developing-with-firebolt/connecting-with-nodejs) * [Python](/guides/developing-with-firebolt/connecting-with-python) ### Web UI A built-in web UI is available as an optional engine sidecar. See [Web UI](./web-ui).