Skip to content

Getting Started 🚀

This guide will walk you through setting up Jetbase from scratch. By the end, you'll have a fully working migration system for your database!

Prerequisites

Before you begin, make sure you have:

  • Python 3.10+ installed
  • A database (PostgreSQL, SQLite, Snowflake)
  • pip or uv for installing packages

Installation

Install Jetbase using pip:

pip install jetbase

Note for Snowflake Users:
To use Jetbase with Snowflake, install the Snowflake extras:

pip install "jetbase[snowflake]"

Verify the installation:

jetbase --help

You should see a list of available commands. 🎉

Setting Up Your Project

Step 1: Initialize Jetbase

Navigate to your project directory and run:

jetbase init

This creates a jetbase/ directory with the following structure:

jetbase/
├── migrations/     # Your SQL migration files go here
└── env.py          # Database configuration

Step 2: Navigate to the Jetbase Directory

cd jetbase

Important

All Jetbase commands must be run from inside the jetbase/ directory.

Step 3: Configure Your Database Connection

Open env.py and update the sqlalchemy_url with your database connection string:

sqlalchemy_url = "postgresql+psycopg2://user:password@localhost:5432/mydb"

sqlalchemy_url = "sqlite:///mydb.db"

Creating Your First Migration

Step 1: Generate a Migration File

Use the new command to create a migration file:

jetbase new "create users table"

This creates a file like:

migrations/V20251225.143022__create_users_table.sql

The filename format is: V{timestamp}__{description}.sql

Manual Migration Files

You can also create migration files manually if you prefer! Simply add your migration file to the jetbase/migrations/ folder and follow the required filename format:
V{version}__{description}.sql
Example:
V2.4__create_users_table.sql

Be sure your file starts with V, followed by a version (like 2.4), then __, a short description (use underscores for spaces), and ends with .sql.

Step 2: Write Your Migration SQL

Open the newly created file and add your SQL statements:

-- upgrade
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL
);

CREATE TABLE items (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
);

-- rollback
DROP TABLE items;
DROP TABLE users;

Migration File Structure

  • The -- rollback section contains only SQL to undo the migration, and any rollback statements must go after -- rollback

Step 3: Apply the Migration

Run the upgrade command:

jetbase upgrade

Output:

Migration applied successfully: V20251225.143022__create_users_table.sql

Note:
Jetbase uses SQLAlchemy under the hood to manage database connections.
For any database other than SQLite, you must install the appropriate Python database driver.
For example, to use Jetbase with PostgreSQL: 

pip install psycopg2
You can also use another compatible driver if you prefer (such as asyncpg, pg8000, etc.).

Step 4: Verify the Migration

Check the migration status:

jetbase status

You'll see a table showing:

  • ✅ Applied migrations
  • 📋 Pending migrations (if any)

What's Next?

Now that you've set up your first migration, explore these topics:

Quick Command Reference

Command Description
init Initialize Jetbase in current directory
new Create a new migration file
upgrade Apply pending migrations
rollback Undo migrations
status Show migration status of all migration files (applied vs. pending)
history Show migration history
current Show latest version migrated
lock-status Check if migrations are locked
unlock Remove migration lock
validate-checksums Verify migration file integrity
validate-files Check for missing migration files
fix Fix migration issues
fix-files Fix missing migration files (same as validate-files --fix)
fix-checksums Fix migration file checksums (same as validate-checksums --fix)