Database Connections 🔌¶

Jetbase supports multiple databases. This guide covers how to connect to each supported database using a SQLAlchemy url.

PostgreSQL¶

Installing a Driver¶

PostgreSQL requires a database driver. Examples:

pip install psycopg2-binary

pip install "psycopg[binary]"

Connection String¶

sqlalchemy_url = "postgresql+driver://username:password@host:port/database"

Example¶

# jetbase/env.py
sqlalchemy_url = "postgresql+psycopg2://myuser:mypassword@localhost:5432/myapp"

With a specific schema:

# jetbase/env.py
sqlalchemy_url = "postgresql://myuser:mypassword@localhost:5432/myapp"
postgres_schema = "public"

Snowflake¶

Snowflake is a cloud-based data warehouse. Jetbase supports both username/password and key pair authentication.

Installing the Driver¶

Snowflake requires additional dependencies. Install Jetbase with the Snowflake extra:

pip install "jetbase[snowflake]"

Connection String Format¶

sqlalchemy_url = "snowflake://username:password@account/database/schema?warehouse=WAREHOUSE_NAME"

Component	Description
`username`	Your Snowflake username
`password`	Your Snowflake password (omit for key pair auth)
`account`	Your Snowflake account identifier (e.g., `abc12345.us-east-1`)
`database`	Target database name
`schema`	Target schema name
`warehouse`	Compute warehouse to use

Username & Password Authentication¶

The simplest way to connect is with username and password:

# jetbase/env.py
sqlalchemy_url = "snowflake://myuser:mypassword@myaccount.us-east-1/my_db/public?warehouse=COMPUTE_WH"

Key Pair Authentication¶

For enhanced security, Snowflake supports key pair authentication. To use it, omit the password from your connection string and configure your private key.

Step 1: Create a connection string without a password:

# jetbase/env.py
sqlalchemy_url = "snowflake://myuser@myaccount.us-east-1/my_db/public?warehouse=COMPUTE_WH"

Step 2: Configure your private key as an environment variable:

# Set the private key (PEM format)
export JETBASE_SNOWFLAKE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
MIIEvgIBADANBgkqhkiG9w0BAQEFAASC...
-----END PRIVATE KEY-----"

# Optional: if your private key is encrypted
export JETBASE_SNOWFLAKE_PRIVATE_KEY_PASSWORD="your-key-password"

Tip

It's best to read your private key file directly into the environment variable locally:

export JETBASE_SNOWFLAKE_PRIVATE_KEY=$(cat snowflake_private_key.pem)

SQLite¶

Connection String¶

SQLite doesn't require any additional drivers. Just connect with the connection string.

sqlalchemy_url = "sqlite:///path/to/database.db"

Examples¶

Relative path (relative to where you run Jetbase):

# jetbase/env.py
sqlalchemy_url = "sqlite:///myapp.db"

In-memory database (useful for testing):

# jetbase/env.py
sqlalchemy_url = "sqlite:///:memory:"

MySQL¶

Installing a Driver¶

MySQL requires the PyMySQL driver:

pip install pymysql

Connection String¶

sqlalchemy_url = "mysql+pymysql://username:password@host:port/database"

Example¶

# jetbase/env.py
sqlalchemy_url = "mysql+pymysql://myuser:mypassword@localhost:3306/myapp"

Databricks¶

Installing the Driver¶

Databricks requires additional dependencies. Install Jetbase with the Databricks extra:

pip install "jetbase[databricks]"

Connection String Format¶

sqlalchemy_url = "databricks://token:ACCESS_TOKEN@HOSTNAME?http_path=HTTP_PATH&catalog=CATALOG&schema=SCHEMA"

Component	Description
`ACCESS_TOKEN`	Your Databricks personal access token
`HOSTNAME`	Your Databricks workspace hostname (e.g., `adb-1234567890123456.cloud.databricks.com`)
`HTTP_PATH`	The HTTP path to your SQL warehouse or cluster (e.g., `/sql/1.0/warehouses/abc`)
`CATALOG`	The Unity Catalog name to use
`SCHEMA`	The schema name within the catalog

Example¶

# jetbase/env.py
sqlalchemy_url = "databricks://token:dapi1234567890abcdef@adb-1234567890123456.cloud.databricks.comt?http_path=/sql/1.0/warehouses/abc123def456&catalog=main&schema=default"

ClickHouse¶

ClickHouse is a high-performance column-oriented OLAP database. Jetbase supports ClickHouse for managing schema migrations.

Installing the Driver¶

ClickHouse requires additional dependencies. Install Jetbase with the ClickHouse extra:

pip install "jetbase[clickhouse]"

Connection String Format¶

sqlalchemy_url = "clickhouse://username:password@host:port/database"

Component	Description
`username`	Your ClickHouse username (default: `default`)
`password`	Your ClickHouse password (can be empty for local development)
`host`	ClickHouse server hostname
`port`	HTTP port (default: `8123`)
`database`	Target database name (default: `default`)

Example¶

# jetbase/env.py
sqlalchemy_url = "clickhouse://user:password@localhost:8123/mydb"

Important Notes¶

ClickHouse

ClickHouse does not support migration locking.

Example Migration¶

-- upgrade
CREATE TABLE users
(
    id UUID DEFAULT generateUUIDv4(),
    name String,
    email String,
    created_at DateTime64(6) DEFAULT now64(6)
)
ENGINE = MergeTree()
ORDER BY id;

-- rollback
DROP TABLE users;