python-package.yml

# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions

name: Python package

on:
  push:
    branches: [main]
    tags: ["*"]
    paths:
      - .github/**
      - src/**
      - tests/**
      - pyproject.toml
  pull_request:
    branches: [main]
    paths:
      - .github/**
      - src/**
      - tests/**
      - pyproject.toml

permissions:
  contents: write # Required for GitHub Release creation
  id-token: write # Required for Trusted Publishing (only used in publish job)

jobs:
  validate-tag:
    name: Validate Tag
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.check.outputs.version }}
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Check tag format (PEP 440)
        id: check
        run: |
          python3 -m pip install --disable-pip-version-check packaging
          python3 .github/scripts/validate_version.py
        env:
          GITHUB_REF: ${{ github.ref }}

  lint:
    name: Code style check
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Lint check with ruff
        uses: astral-sh/ruff-action@v3

  type-check:
    name: Type Check (Python ${{ matrix.python-version }})
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
    steps:
      - uses: actions/checkout@v6

      - name: Install uv
        uses: astral-sh/setup-uv@v6
        with:
          enable-cache: true
          cache-dependency-glob: "pyproject.toml"
          python-version: ${{ matrix.python-version }}

      - name: Install dependencies
        run: uv sync --group typecheck

      - name: Static check with mypy
        run: uv run --no-dev mypy

  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]

    services:
      # MSSQL is slowest (start-period 60s), put first
      mssql:
        image: mcr.microsoft.com/mssql/server:2022-latest
        env:
          MSSQL_SA_PASSWORD: "YourStrongPassword123"
          MSSQL_PID: "Developer"
          ACCEPT_EULA: "Y"
        options: >-
          --health-cmd "/opt/mssql-tools18/bin/sqlcmd -C -S localhost -U sa -P YourStrongPassword123 -Q 'SELECT 1'"
          --health-interval 10s
          --health-timeout 30s
          --health-retries 5
          --health-start-period 60s
        ports:
          - 1433:1433

      mysql:
        image: mysql
        env:
          MYSQL_RANDOM_ROOT_PASSWORD: "1"
          MYSQL_DATABASE: test
          MYSQL_USER: test
          MYSQL_PASSWORD: test
        options: >-
          --health-cmd "mysqladmin ping -h 127.0.0.1 -u $$MYSQL_USER --password=$$MYSQL_PASSWORD"
        ports:
          - 3306:3306

      # PostgreSQL alpine is fastest, put last
      postgres:
        image: postgres:alpine
        env:
          POSTGRES_PASSWORD: test
        options: >-
          --health-cmd "pg_isready -U postgres -h 127.0.0.1"
        ports:
          - 5432:5432

      # NOTE: Oracle is set up via gvenzl/setup-oracle-free@v1 action
      # instead of service container, for better reliability

    steps:
      - uses: actions/checkout@v6

      - name: Install MSSQL ODBC driver
        run: |
          # Download and install Microsoft package repository
          wget -qO- https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
          sudo dpkg -i packages-microsoft-prod.deb
          # Update and install ODBC driver
          sudo apt-get update
          sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18

      - name: Install uv
        uses: astral-sh/setup-uv@v6
        with:
          enable-cache: true
          python-version: ${{ matrix.python-version }}

      # NOTE: Oracle testing requires full Oracle Database installation
      # Oracle Database Free (23c/23ai) does NOT support DBMS_LOCK.REQUEST
      # which is required for distributed lock functionality. This is a known
      # limitation of the Free/Express edition. CI cannot test Oracle; use
      # local testing with a full Oracle Database installation.
      #
      # For local Oracle testing:
      #   docker compose -f db.docker-compose.yml up
      #   OR use a self-hosted runner with access to Oracle Enterprise/Standard
      #
      # Reference: https://github.com/gvenzl/oci-oracle-free
      # The "slim" and "full" flavors of gvenzl/oracle-free both lack
      # DBMS_LOCK.REQUEST support as it's not included in Oracle Free edition.

      - name: Install the project
        env:
          SETUPTOOLS_SCM_PRETEND_VERSION: "0"
        run: |
          uv sync --no-dev --group test
          uv pip install mysqlclient aiomysql psycopg2 asyncpg pyodbc aioodbc oracledb

      - name: Run tests
        shell: bash
        env:
          TEST_URLS: mysql://test:test@127.0.0.1:3306/test postgresql://postgres:test@127.0.0.1:5432/ mssql+pyodbc://sa:YourStrongPassword123@127.0.0.1:1433/master?driver=ODBC+Driver+18+for+SQL+Server&TrustServerCertificate=yes
          TEST_ASYNC_URLS: mysql+aiomysql://test:test@127.0.0.1:3306/test postgresql+asyncpg://postgres:test@127.0.0.1:5432/ mssql+aioodbc://sa:YourStrongPassword123@127.0.0.1:1433/master?driver=ODBC+Driver+18+for+SQL+Server&TrustServerCertificate=yes
        run: |
          uv run --no-dev coverage run -m unittest -cfv
          uv run --no-dev coverage report -m
          uv run --no-dev coverage xml

      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v5
        with:
          token: ${{ secrets.CODECOV_TOKEN }}

  build:
    name: Build Distribution
    runs-on: ubuntu-latest
    needs: [lint, type-check, test, validate-tag]
    if: needs.validate-tag.outputs.version != ''

    steps:
      - uses: actions/checkout@v6

      - name: Install uv
        uses: astral-sh/setup-uv@v7
        with:
          enable-cache: true
          cache-dependency-glob: "pyproject.toml"

      - name: Build package
        run: uv build
        env:
          SETUPTOOLS_SCM_PRETEND_VERSION: ${{ needs.validate-tag.outputs.version }}

      - name: Store the distribution packages
        uses: actions/upload-artifact@v6
        with:
          name: python-package-distributions
          path: dist/

  publish:
    name: Publish to PyPI
    runs-on: ubuntu-latest
    needs: [validate-tag, build]
    if: needs.validate-tag.outputs.version != ''
    environment:
      name: pypi
      url: https://pypi.org/p/sqlalchemy-dlock

    steps:
      - name: Download distribution packages
        uses: actions/download-artifact@v7
        with:
          name: python-package-distributions
          path: dist/

      - name: Publish to PyPI
        uses: pypa/gh-action-pypi-publish@release/v1
        with:
          skip-existing: true
          verbose: true

  github-release:
    name: Create GitHub Release
    runs-on: ubuntu-latest
    needs: [validate-tag, build]
    if: needs.validate-tag.outputs.version != ''
    permissions:
      contents: write

    steps:
      - uses: actions/checkout@v5

      - name: Download distribution packages
        uses: actions/download-artifact@v7
        with:
          name: python-package-distributions
          path: dist/

      - name: Generate release notes from CHANGELOG
        id: release_notes
        run: |
          VERSION="${{ needs.validate-tag.outputs.version }}"
          awk -v version="$VERSION" '
            /^##[[:space:]]*$version/ { in_release=1; next }
            in_release && /^##[[:space:]]/ { exit }
            in_release { print }
          ' CHANGELOG.md > release_notes.md
          {
            echo "notes<<EOF"
            cat release_notes.md
            echo "EOF"
          } >> "$GITHUB_OUTPUT"

      - name: Create GitHub Release
        uses: softprops/action-gh-release@v2
        with:
          tag_name: ${{ github.ref }}
          name: v${{ needs.validate-tag.outputs.version }}
          body: ${{ steps.release_notes.outputs.notes }}
          files: dist/*
          generate_release_notes: false
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}