Managing engines and databases
This topic provides a walkthrough and examples for using the Firebolt Python SDK to create and modify Firebolt databases and engines.
Setting up a ResourceManager object
You can perform various functions on Firebolt databases and engines by calling a
ResourceManager
object, which must be configured with its own user credentials
through the imported Settings
class.
To get started, follow the steps below:
1. Import modules
To initialize a
ResourceManager
object, import the modules shown below.
from firebolt.client.auth import UsernamePassword from firebolt.service.manager import ResourceManager
2. Initialize a ResourceManager object
A ResourceManager object contains the user credentials and other information needed to manage Firebolt databases and engines.
ResourceManager uses the following parameters:
auth
Auth object, containing your credentials. See Auth for more details.
api_endpoint
The API hostname for logging in. Defaults to
api.app.firebolt.io
if not included.
account_name
The name of the account you’re using to connect to Firebolt. Must be specified in order to authenticate.
rm = ResourceManager( auth=UsernamePassword("your_username", "your_password"), account_name="your_acc_name", )
Setting up a ResourceManager object (legacy)
1. Import modules
To initialize a
ResourceManager
object, import the modules shown below.
from firebolt.client.auth import UsernamePassword from firebolt.service.manager import ResourceManager
2. Initialize a Settings object
A Settings object contains the user credentials and other information needed to manage Firebolt databases and engines.
The Settings object uses the following parameters:
user
The email address associated with your Firebolt user profile.
password
The password used for connecting to Firebolt.
server
The API hostname for logging in. Defaults to
api.app.firebolt.io
if not included.
default_region
The default region for creating new databases and engines.
For more information, see Available AWS Regions.
A
Settings
object can be configured with parameters by multiple methods.
Add the parameters manually in your command script:
settings = Settings( user="your_username", password="your_password", server="api.app.firebolt.io" default_region="your_region" )Use a
.env
file located in your root directory containing the following parameters:FIREBOLT_USER="your_username", FIREBOLT_PASSWORD="your_password", FIREBOLT_SERVER="api.app.firebolt.io" FIREBOLT_DEFAULT_REGION="your_region"In your application file, the
Settings
object can read the values from the.env
file if it is set toNone
instead of having values, as shown below:settings = None
3. Initialize a ResourceManager object
After the
Settings
are configured, create aResourceManager
object, which is given the variable namerm
in the example below.rm = ResourceManager(settings=settings)
Note
Subsequent examples on this page use the rm
object for database and engine functions.
Database function examples
This section includes Python examples of various common functions for creating and managing Firebolt resources.
Listing out databases
List out the names of all databases under your account by using the get_many
function.
List out all databases and their metadata
This produces an inventory of all databases and their metadata from your account. The Python devtools module used in the example below helps format the metadata to be more readable.
from devtools import debug debug(rm.databases.get_many())Listing out databases by name
This function call lists out the names of your databases, but it can be modified to list out other attributes. This is helpful for tracking down a particular database in your account.
all_dbs = rm.databases.get_many() all_db_names = [d.name for d in all_dbs] for db in db_names: print(db)Note
For a list of all database attributes, see Database.
Creating a new database
Launch a new database and use it to create a database
object.
A newly created database uses the default region from your Settings unless you specify a different region as a parameter.
database = rm.databases.create(name="database_name", region="us-east-1")Note
For a list of all database parameters, see Database
Locating a database
Find a specific Firebolt database by using its name or ID. These functions are useful as
a starting point to create a database
object that can be called in other database functions.
In the examples below, replace the values for database_name
and database_id
with
your database name or ID.
Locating by name
database = rm.databases.get_by_name(name="database_name")Locating by ID
database = rm.databases.get_by_id(id="database_id")
Getting database status
Use the Python devtools module to format metadata
from a database
object. This is a helpful command to run after a database operation to
check if its execution was successful.
from devtools import debug debug(database)
Dropping a database
Delete a database by calling the delete
function. The database is deleted along with
all of its tables.
database.delete()
Engine function examples
This section includes Python examples of various common functions for creating and managing Firebolt engines.
Creating an engine
Launch a new Firebolt engine and create an engine
object. The created engine uses the
default region included in your Settings unless you specify a different region as a parameter.
engine = rm.engines.create(name="engine_name")
Note
For a list of all engine parameters, see Engine
Listing out engines
List out the names of all engines under your account by using the get_many
function.
List out all engines and metadata
This produces an inventory of all engines and their metadata from your account. The Python devtools module used in the example below helps format the metadata to be more readable.
from devtools import debug debug(rm.engines.get_many())List out engines by name
This function call lists out the names of your engines, but it can be modified to list out other attributes. This is helpful for tracking down a particular engine in your account.
all_engines = rm.engines.get_many() all_engine_names = [e.name for e in all_engines] for name in all_engine_names: print(name)Note
For a list of all engine attributes, see Engine
Locating an engine
Find a specific Firebolt engine by using its name or ID. These functions are useful as a
starting point to create an engine
object that can be called in other engine functions.
In the examples below, replace the values for engine_name
and engine_id
with your
engine name or ID.
Locating by name
engine = rm.engines.get_by_name(name="engine_name")
Attaching an engine
Attach an engine to a database. An engine must be attached to a database and started before it can run SQL commands or queries.
engine = rm.engines.get_by_name(name="engine_name") engine.attach_to_database( database=rm.databases.get_by_name(name="database_name") )
Starting an engine
Start an engine by calling the start
function on an engine
object. An engine must
be attached to a database and started before it can run SQL commands or queries.
engine.start()
Stopping an engine
Stop an engine by calling the stop
function. When stopped, an engine is not available
to run queries and does not accrue additional usage time on your account.
engine.stop()
Getting engine status
Use the Python devtools module to format metadata
from an engine
object. This is a helpful command to run after an engine operation to
check if its execution was successful.
from devtools import debug debug(engine)