dbmate-deployer Development Guide

This skill provides comprehensive guidelines for developing, testing, and releasing dbmate-deployer - a tool that deploys database migrations from S3 to PostgreSQL using dbmate.

What This Skill Does

Guides AI agents through the complete development workflow for the dbmate-deployer project, including:

Instructions

1. Language and Communication Policy

**CRITICAL**: All project artifacts MUST be written in English:

2. Building the Project

Build the binary using one of these methods:

```bash

Preferred: Using Make

make build

Alternative: Direct Go build

go build -o dbmate-deployer ./cmd/dbmate-deployer

```

3. Running Locally

Test the application with these commands:

```bash

Show help

./dbmate-deployer --help

Run with local S3 (LocalStack) for testing

./dbmate-deployer watch \

--database-url="postgres://user:pass@localhost:5432/db" \

--s3-bucket=test-bucket \

--s3-path-prefix=migrations/ \

--s3-endpoint-url=http://localhost:4566

```

4. Testing Strategy

#### Test Types

**Unit Tests**: Fast tests using mocks, no external dependencies

**Integration Tests**: End-to-end tests using testcontainers-go

#### Running Tests

```bash

All tests (unit + integration)

make test

Unit tests only (fast, no Docker required)

make test-unit

Integration tests only (requires Docker)

make test-integration

```

#### Special Setup for Colima Users (macOS)

If using Colima as Docker runtime:

```bash

Set required environment variables

export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock"

export TESTCONTAINERS_RYUK_DISABLED=true

Run integration tests

make test-integration

Or as one-liner

DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock" TESTCONTAINERS_RYUK_DISABLED=true make test-integration

```

#### Adding New Tests

When creating tests:

1. Place unit tests alongside the code they test

2. Use `TestEnvironment` from `internal/shared/testhelpers/containers.go` for integration tests

3. Use mock S3 client from `internal/shared/testhelpers` for unit tests

4. Follow naming convention: integration tests end with `Integration` suffix

5. Code Quality

#### Linting

```bash

Run golangci-lint

make lint

Note: Install golangci-lint first from https://golangci-lint.run/usage/install/

```

#### Code Style Requirements

6. Documentation Standards

7. Migration Files Reference

This project uses dbmate for migrations. Files follow this convention:

**Naming**: `YYYYMMDDHHMMSS_description.sql`

**Example**:

```sql

-- migrate:up

CREATE TABLE users (

id SERIAL PRIMARY KEY,

email VARCHAR(255) UNIQUE NOT NULL,

created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP

);

-- migrate:down

DROP TABLE users;

```

See [dbmate documentation](https://github.com/amacneil/dbmate) for details.

8. Release Process

#### Branch Protection

#### Automated Release with tagpr

1. On each merge to `main`, tagpr creates/updates a release PR

2. When release PR is merged, git tag is automatically created

3. Docker images and binaries are automatically built and published

#### GitHub Actions Workflows

**`.github/workflows/docker.yml`** - CI builds:

**`.github/workflows/tagpr.yml`** - Version management:

**`.github/workflows/release.yml`** - Release builds (triggered by version tags):

#### Docker Image Tags

#### Binary Release Platforms

#### Release Artifacts

#### Making Container Images Public (First Release Only)

1. Go to **Packages** in GitHub repository

2. Click on `dbmate-deployer` package

3. Go to **Package settings**

4. Scroll to **Danger Zone**

5. Click **Change visibility** → **Public**

9. Available Make Targets

```bash

make help # Show all available targets

make build # Build the binary

make test # Run all tests (unit + integration)

make test-unit # Run unit tests only (fast, no Docker)

make test-integration # Run integration tests (requires Docker)

make lint # Run golangci-lint

make clean # Clean build artifacts

```

Constraints

Examples

Example: Running Full Test Suite

```bash

Run all tests with verbose output

make test

Expected output shows unit and integration tests passing

```

Example: Making a Code Change

```bash

1. Create feature branch

git checkout -b feat/add-retry-logic

2. Make changes

... edit code ...

3. Run tests

make test

4. Run linter

make lint

5. Commit with conventional format

git commit -m "feat: add exponential backoff retry logic for S3 operations"

6. Push and create PR

git push origin feat/add-retry-logic

```

Example: Creating a Release

```bash

1. Merge PR to main

2. tagpr automatically creates release PR

3. Review and merge release PR

4. GitHub Actions automatically:

- Creates git tag

- Builds binaries

- Publishes Docker images

```