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.

To get started, follow the steps below:

1. Import modules

To initialize a ResourceManager object, import the modules shown below.

from firebolt.client import DEFAULT_API_URL
from firebolt.client.auth import ClientCredentials
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=ClientCredentials("your_service_account_id", "your_service_account_secret"),
    account_name="your_acc_name",
)
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. This function is useful as a starting point to create a database object that can be called in other database functions.

In the example below, replace the values for database_name with your database name.

Locating by name

database = rm.databases.get("database_name")

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("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. This function is useful as a starting point to create an engine object that can be called in other engine functions.

In the example below, replace the value for engine_name with your engine name.

Locating by name

engine = rm.engines.get("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("engine_name")
engine.attach_to_database(
    rm.databases.get("database_name")
)

Dropping an engine

Delete an engine by calling the delete function. The engine is removed from its attached database and deleted.

engine.delete()

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()

Updating an engine

Update an engine to change its specifications, returning an updated version of the engine. The engine must be stopped in order to be updated.

For a list of engine parameters that can be updated, see update()

engine.update(description = "This is a new description.")

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)