Overview
The Firebolt Rust SDK enables Rust developers to connect to and interact with Firebolt databases seamlessly. It provides an async-first interface with comprehensive type safety, OAuth2 authentication, and structured error handling for all Firebolt data types.Prerequisites
You must have the following prerequisites before you can connect your Firebolt account to Rust:- Rust installed and configured on your system. The minimum supported version is 1.70 or higher. If you do not have Rust installed, you can download it from rustup.rs.
- Firebolt account – You need an active Firebolt account. If you do not have one, you can sign up for one.
- Firebolt service account – You must have access to an active Firebolt service account, which facilitates programmatic access to Firebolt, its ID and secret.
- Firebolt user – You must have a user that is associated with your service account. The user should have USAGE permission to query your database, and OPERATE permission to start and stop an engine if it is not already started.
- Firebolt database and engine (optional) – You can optionally connect to a Firebolt database and/or engine. If you do not have one yet, you can create a database and also create an engine. You would need a database if you want to access stored data in Firebolt and an engine if you want to load and query stored data.
Installation
Add the Firebolt SDK to yourCargo.toml
dependencies:
Connection Parameters
The Rust SDK uses a builder pattern to configure connections to Firebolt. The SDK supports the following parameters:client_id
: Client ID of your service account.client_secret
: Client secret of your service account.account_name
: The name of your Firebolt account.database
: (Optional) The name of the database to connect to.engine
: (Optional) The name of the engine to run SQL queries on.
Connect to Firebolt
To establish a connection to a Firebolt database, use the builder pattern with your credentials and database details. The following example shows how to connect to Firebolt:Run Queries
Once connected, you can execute SQL queries using thequery
method. The SDK returns results with type-safe parsing for all Firebolt data types. The following examples show you how to create a table, insert data, and retrieve data:
Type-Safe Result Parsing
The SDK provides comprehensive type conversion for all Firebolt data types. You can access column values by name or index with automatic type conversion:The Rust SDK does not currently support streaming queries for processing large result sets. All query results are loaded into memory at once. For large datasets, consider using LIMIT clauses or pagination techniques to manage memory usage.
Error Handling
The SDK provides comprehensive error handling through theFireboltError
enum:
Troubleshooting
When building a connection to Firebolt using the Rust SDK, follow these best practices to ensure correct configuration and avoid common errors: Guidelines- Ensure all required parameters (
client_id
,client_secret
,account_name
) are provided to the builder. - Use the exact account name as shown in the Firebolt Console URL, which is usually lowercase with no special characters.
- Use the exact engine and database names as shown in the Firebolt Workspace.
- Verify your service account has the necessary permissions for the database and engine you’re trying to access.
Common errors and solutions
Error message | Likely cause | Solution |
---|---|---|
Configuration error: client_id is required | Missing required parameter in builder | Ensure all required parameters are provided to the builder |
Authentication error: Invalid credentials | Incorrect client ID or secret | Verify your service account credentials in the Firebolt console |
Network error: Failed to get engine URL | Network connectivity issues | Check your internet connection and firewall settings |
Query error: relation "table_name" does not exist | Invalid SQL query or missing table | Verify your SQL query uses valid table and column names |
The Rust SDK does not currently support connecting to Firebolt Core. For Firebolt Core connections, use the Go SDK or other supported SDKs.