databricks_sql 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fb1784eb43d904710d121f1718ce325b43fad687ca320fa0b5bbe2d370dcefd0
+  data.tar.gz: e4ea467babed9260d712d7f566921ad1dbcf4a6fb2a5c7bf1acf7fee3b13974a
+SHA512:
+  metadata.gz: 28a3767b8b015dddd8c26140d3911906858b20c677188c9e78999d119c08915f8f66f37aef294be3e3b006e025ec6085f204b39425f7f78d9709e891c9cc132a
+  data.tar.gz: ddd0c3ecb4725068cd3605db468ce1c0bee0472f262eeb63b91403f6a76337d798b593cdfcc3d60bee9fa83cc9a3462f18fce45546b7fb221cf82ebe5fb4efba

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+## [0.1.0] - 2026-04-06
+
+- First public release of the gem.
+- Client for executing SQL queries on Databricks.
+- Flexible configuration via code.
+- Custom error handling.
+- Automatic type coercion for query results.
+- Support for external links in results.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"databricks_sql" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["lairton.mendes@gmail.com"](mailto:"lairton.mendes@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Lairton Mendes
+
+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.

data/README.md

@@ -0,0 +1,215 @@
+# databricks_sql
+
+Ruby gem for the Databricks SQL Statements API with support for:
+
+- Personal Access Token (PAT) authentication
+- synchronous and asynchronous execution (polling)
+- format: JSON_ARRAY
+- disposition: INLINE
+- disposition: EXTERNAL_LINK with automatic file download and parsing
+- HTTP and SQL execution error handling
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "databricks_sql"
+```
+
+Or install directly:
+
+```bash
+gem install databricks_sql
+```
+
+## Global Configuration (Recommended)
+
+Configure connection settings once and reuse them across your application:
+
+```ruby
+require "databricks_sql"
+
+Databricks.configure do |config|
+	config.host = "https://adb-1234567890123456.7.azuredatabricks.net"
+	config.token = ENV.fetch("DATABRICKS_TOKEN")
+	config.warehouse_id = ENV.fetch("DATABRICKS_WAREHOUSE_ID")
+	config.timeout = 30
+	config.open_timeout = 10
+	config.external_link_require_https = true
+	config.external_link_allowed_hosts = ["files.example.com", "s3.amazonaws.com"]
+end
+```
+
+Security notes:
+
+- The API host must use HTTPS.
+- EXTERNAL_LINK URLs are HTTPS-only by default.
+- If `external_link_allowed_hosts` is set, downloads are allowed only from those domains.
+
+Then initialize your client without passing credentials again:
+
+```ruby
+client = DatabricksSql::Client.new
+```
+
+You can also configure through DatabricksSql.configure:
+
+```ruby
+DatabricksSql.configure do |config|
+	config.host = "https://adb-1234567890123456.7.azuredatabricks.net"
+	config.token = ENV.fetch("DATABRICKS_TOKEN")
+	config.warehouse_id = ENV.fetch("DATABRICKS_WAREHOUSE_ID")
+end
+```
+
+If needed, override per client instance:
+
+```ruby
+client = DatabricksSql::Client.new(
+	host: "https://adb-1234567890123456.7.azuredatabricks.net",
+	token: ENV.fetch("DATABRICKS_TOKEN"),
+	warehouse_id: ENV.fetch("DATABRICKS_WAREHOUSE_ID")
+)
+```
+
+## Synchronous Usage
+
+execute_statement submits the query and waits for a terminal status (SUCCEEDED, FAILED, CANCELED, or CLOSED).
+
+```ruby
+result = client.execute_statement(
+	statement: "SELECT id, name FROM analytics.users LIMIT 5",
+	format: "JSON_ARRAY",
+	disposition: "INLINE"
+)
+
+puts result.status
+puts result.columns.inspect
+puts result.rows.inspect
+```
+
+### SQL Context (catalog/schema)
+
+```ruby
+result = client.execute_statement(
+	statement: "SELECT current_catalog(), current_schema()",
+	catalog: "main",
+	schema: "analytics"
+)
+```
+
+### Type Mapping with column_schema
+
+column_schema allows optional per-column coercion.
+
+```ruby
+result = client.execute_statement(
+	statement: "SELECT id, is_active, created_at FROM analytics.users LIMIT 2",
+	column_schema: {
+		"id" => :integer,
+		"is_active" => :boolean,
+		"created_at" => :datetime
+	}
+)
+
+result.rows.each do |row|
+	puts [row["id"].class, row["is_active"].class, row["created_at"].class].inspect
+end
+```
+
+## Asynchronous Usage (Polling)
+
+### 1) Submit without blocking
+
+```ruby
+submission = client.execute_statement_async(
+	statement: "SELECT * FROM large_table",
+	format: "JSON_ARRAY",
+	disposition: "EXTERNAL_LINK",
+	wait_timeout: "10s",
+	on_wait_timeout: "CONTINUE"
+)
+
+statement_id = submission.fetch("statement_id")
+puts "Statement ID: #{statement_id}"
+```
+
+### 2) Manual polling
+
+```ruby
+loop do
+	state = client.get_statement(statement_id: statement_id)
+	puts "Current status: #{state["status"]}"
+	break if %w[SUCCEEDED FAILED CANCELED CLOSED].include?(state["status"])
+	sleep 1
+end
+```
+
+### 3) Automatic polling with global timeout
+
+```ruby
+result = client.wait_for_statement(
+	statement_id: statement_id,
+	disposition: "EXTERNAL_LINK",
+	poll_interval: 1.0,
+	max_wait: 120,
+	cancel_on_timeout: true
+)
+
+puts result.rows.size
+```
+
+## INLINE vs EXTERNAL_LINK
+
+- INLINE returns results directly in the API payload.
+- EXTERNAL_LINK extracts the download URL, downloads the file, and returns parsed content.
+
+In EXTERNAL_LINK mode, JSON and CSV are parsed automatically.
+
+## Error Handling
+
+Main error classes:
+
+- DatabricksSql::AuthenticationError (401)
+- DatabricksSql::AuthorizationError (403)
+- DatabricksSql::NotFoundError (404)
+- DatabricksSql::RateLimitError (429)
+- DatabricksSql::ServerError (5xx)
+- DatabricksSql::TimeoutError
+- DatabricksSql::ConnectionError
+- DatabricksSql::ExecutionError (logical SQL execution failure)
+- DatabricksSql::ParseError
+
+Example:
+
+```ruby
+begin
+	result = client.execute_statement(statement: "SELECT * FROM missing_table")
+	p result.rows
+rescue DatabricksSql::ExecutionError => e
+	warn "SQL execution failed: #{e.message}"
+rescue DatabricksSql::HTTPError => e
+	warn "HTTP error #{e.status_code}: #{e.message}"
+rescue DatabricksSql::Error => e
+	warn "DatabricksSql error: #{e.message}"
+end
+```
+
+## Development
+
+```bash
+bin/setup
+bundle exec rubocop
+bundle exec rspec
+```
+
+Install locally:
+
+```bash
+bundle exec rake install
+```
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+RSpec::Core::RakeTask.new(:spec)
+
+task default: %i[rubocop spec]