Development Commands¶

All commands should be run from the project root directory.

Environment Management¶

make install-uv¶

Installs the latest version of UV package manager.

Usage:

make install-uv

make install¶

Creates a fresh virtual environment and installs all development dependencies (testing, linting, documentation, and version management).

Usage:

make install

What it does:

• Destroys any existing virtual environment

• Pins Python to version 3.12

• Creates .venv/ virtual environment

• Installs development dependencies with uv sync --dev

• Installs pre-commit hooks

make upgrade¶

Upgrades all dependencies to their latest stable versions and updates pre-commit hooks.

Usage:

make upgrade

What it does:

• Updates uv.lock with latest dependency versions

• Updates pre-commit hook versions

make destroy¶

Removes the virtual environment completely.

Usage:

make destroy

Building¶

make build / make build-collector¶

Builds database collection script packages (ZIP files) for all supported databases and copies the standalone collection masker script into dist/.

Usage:

make build
# or
make build-collector

Output: Creates in dist/:

• db-migration-assessment-collection-scripts-oracle.zip (includes masker/dma-collection-masker)

• db-migration-assessment-collection-scripts-sqlserver.zip (includes masker/dma-collection-masker)

• db-migration-assessment-collection-scripts-mysql.zip

• db-migration-assessment-collection-scripts-postgres.zip

• dma-collection-masker

make clean¶

Removes all build artifacts, test files, and temporary files.

Usage:

make clean

What it removes:

• dist/, build/, .eggs/

• *.egg-info, *.pyc, __pycache__/

• .pytest_cache, .ruff_cache, .mypy_cache

• .coverage, coverage.xml, htmlcov/

make deep-clean¶

Performs a deep clean including virtual environment and UV cache.

Usage:

make deep-clean

Testing¶

make test¶

Runs the full test suite with coverage reporting (Python 3.12).

Usage:

make test

Equivalent to:

uv run pytest -n 2 --dist loadgroup --cov

make test-unit¶

Runs fast unit tests without starting any database containers.

Usage:

make test-unit

make test-integration¶

Runs integration and collection script tests against database containers.

Usage:

make test-integration

make test-all-pythons¶

Runs tests against all supported Python versions (3.10, 3.11, 3.12, 3.13).

Usage:

make test-all-pythons

Note: This requires multiple Python versions to be installed on your system.

Run Specific Tests¶

# Run specific unit test file
uv run pytest tests/unit/test_sqlserver_collection_scripts.py

# Run with debugging
uv run pytest -s --pdb tests/unit/test_sqlserver_collection_scripts.py

# Run tests matching a pattern
uv run pytest -k "test_postgres"

# Run tests without coverage
uv run pytest --no-cov

Collection Script Tests¶

These tests execute the packaged collection scripts inside containers, then validate the output archives. They require Docker or Podman.

# Run all collection script tests
uv run pytest -m script_test

# Run Postgres script tests only
uv run pytest -m "script_test and postgres"

# Skip slow tests
uv run pytest -m "script_test and not slow"

Environment variables:

• DMA_TEST_KEEP_CONTAINER=1 keeps containers running after the test session.

• DMA_TEST_KEEP_VOLUMES=1 keeps container volumes for debugging.

Structure: Script tests live under tests/integration/<db>/test_collection_scripts.py and share session-scoped fixtures from tests/lib/collector_build.py and tests/lib/script_executor.py to avoid rebuilding artifacts per test.

Linting and Code Quality¶

make lint¶

Runs all pre-commit hooks including ruff linting, formatting, and codespell.

Usage:

make lint

What it runs:

• Python AST validation

• TOML/YAML/JSON validation

• Ruff linting and formatting

• Codespell spell checking

• Trailing whitespace fixes

• End-of-file fixes

Manual Linting Commands¶

# Run only ruff linting
uv run ruff check .

# Auto-fix ruff issues
uv run ruff check --fix .

# Format code
uv run ruff format .

# Run mypy type checking
uv run mypy

# Run codespell
uv run codespell

Documentation¶

make docs-build¶

Generates HTML documentation using Sphinx.

Usage:

make docs-build

Output: Creates documentation in docs/_build/html/

make docs-serve¶

Builds and serves documentation locally with auto-reload.

Usage:

make docs-serve

Access: Opens at http://localhost:8000

make doc-privs¶

Extracts Oracle privilege requirements from code and updates documentation.

Usage:

make doc-privs

Output: Updates docs/user_guide/shell_scripts/oracle/permissions.md

Version Management¶

make release¶

Bumps the version number across all collection scripts and builds documentation.

Usage:

# Bump patch version (e.g., 4.3.48 → 4.3.49)
make release bump=patch

# Bump minor version (e.g., 4.3.48 → 4.4.0)
make release bump=minor

# Bump major version (e.g., 4.3.48 → 5.0.0)
make release bump=major

What it does:

1. Generates documentation (make docs-build)

2. Cleans build artifacts (make clean)

3. Bumps version in all files using bump-my-version

Files updated:

• pyproject.toml

• scripts/masker/dma-collection-masker

• scripts/collector/oracle/collect-data.sh

• scripts/collector/mysql/collect-data.sh

• scripts/collector/postgres/collect-data.sh

• scripts/collector/sqlserver/instanceReview.ps1

Manual Version Commands¶

# Show current version
uv run bump-my-version show current_version

# Dry run version bump
uv run bump-my-version bump --dry-run patch

Database-Specific Testing¶

Start Test Databases¶

Test containers are managed automatically by pytest fixtures. Running tests will start and stop the required containers as needed.

To keep containers or volumes between runs, set DMA_TEST_KEEP_CONTAINER=1 or DMA_TEST_KEEP_VOLUMES=1 in the environment.

Run Database-Specific Tests¶

# MySQL tests only
uv run pytest -m mysql

# PostgreSQL tests only
uv run pytest -m postgres

# Oracle tests only
uv run pytest -m oracle

# SQL Server tests only
uv run pytest -m mssql

Dependency Groups¶

The project uses UV dependency groups defined in pyproject.toml:

• dev: All development dependencies (lint, test, docs, and bump-my-version)

• test: Test dependencies (pytest, pytest-cov, pytest-xdist, filelock, etc.)

• lint: Linting tools (ruff, mypy, pre-commit, etc.)

• docs: Documentation tools (sphinx, sphinx-immaterial, myst-parser, sphinx-design, etc.)

• build: Version management tools (bump-my-version)

Install Specific Groups¶

# Install only docs dependencies
uv sync --group docs

# Install only lint dependencies
uv sync --group lint

# Install multiple groups
uv sync --group docs --group lint

Quick Reference¶