DEV Community: Eric Santana

Stop Your AI Agents from Clashing: Meet Worktree Wizardry 🧙‍♂️

Eric Santana — Sun, 29 Mar 2026 23:17:26 +0000

If you are experimenting with AI coding agents, or maybe you are just trying to work with many feature branches at the same time, you probably found this big problem. It is very hard to start local environments for multiple git worktrees in the exact same repository.

What usually happens? You try to run the project and you get that terrible error: bind: address already in use.

When multiple agents or developers try to run different stacks at the same time, they conflict with each other. The ports are the same, the database state gets messy, and your automated workflow turns into a big headache.

To solve this, I developed something called Worktree Wizardry.

What is it exactly?

Worktree Wizardry is a public starter kit for creating isolated per-worktree environments that uses Docker Compose. It is designed specifically for AI-assisted workflows where each worktree can run and test a different stack without collisions.

It is basically a skill. It is simply a public repository that allows people to run agents to create for them a worktree sandbox. This makes it possible for them to test multiple worktrees at the same time without worrying with port numbers and other environment conflicts.

Main Features

Isolated Port Allocation: Every worktree gets a different port automatically. No more conflicts!
Shared Git State: It safely manages the shared state in the git common dir while keeping the execution isolated.
Smart Integrations: It comes with optional lifecycle hooks for AI tools like Conductor and Superset.
Custom Scripts: Repo-specific setup and archive behavior is controlled via simple bash hook scripts.

How to use it

It is very easy to start. You just use the template/ folder as the starting point for your new or existing repository.

1. Copy the template into your target repo:

bash install.sh /path/to/target-repo

2. Customize your environment:
In the target repo, you just need to edit these files for your app:

worktree-wizardry/config.env
worktree-wizardry/hooks/setup.sh
worktree-wizardry/hooks/archive.sh
docker-compose.worktree-wizardry.yml

3. Run the magic:
It is one setup command per worktree:

bash scripts/worktree-wizardry-setup.sh
# And to clean up later:
bash scripts/worktree-wizardry-archive.sh

If you want to see an example, the repository has a demo/ folder that shows a concrete adapter. It runs Postgres on port + 1 and an Nginx demo app on port + 2, generates the .env.local files automatically, and cleans up everything in the archive step.

Try it out!

If you are building tools for agents or just want a better way to test multiple worktrees locally, please take a look.

🔗 https://github.com/ericbsantana/worktree-wizardry

Creating a free-tier AWS RDS PostgreSQL instance using Terraform

Eric Santana — Sat, 06 Apr 2024 19:14:25 +0000

One of the most powerful tools to use as a DevOps engineer is Terraform. Simply put, Terraform is

an infrastructure as code (IaC) tool that lets you define both cloud and on-prem resources in human-readable configuration files that you can version, reuse, and share.

This means that you can actually create a whole infrastructure using declarative code. In other words, you are able to manage resources like storages as well as databases using only code.

One of the main benefits in using IaC is to have a better control of your resources and make them scalable. Even more: if you are interested in using multiple cloud services, you can control all the resources from one place, saving you time from clicking and opening multiple tabs in your browser to access each cloud service console.

In this article, I will provide a guide on how to create a free-tier AWS RDS database instance using Terraform. I write for you who want to create a RDS database instance but don't want to deal too much with AWS console. Or if you just want to learn a bit the basics of Terraform. Let's get started!

Prerequisites

First of all, you need to have:

An AWS account eligible to use RDS free-tier
An AWS Access Key and Secret Key with Full Access to RDS associated to a new IAM user (or use root at your own risk)
The Terraform CLI installed

Selecting and pointing to AWS provider

First of all, let's create a folder to initialize a Terraform template:

mkdir terraform-aws-free-rds
cd terraform-aws-free-rds

In this folder, create a provider.tf that is going to be our entry point to declare which provider are we going to use. This is where we define For now, its content will be:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "5.43.0"
    }
  }
}

provider "aws" {}

This will tell Terraform: "I want to use the AWS provider to start my infrastructure!"

But still Terraform don't know to which region we are going to create our resources or even how to access our AWS account to make these changes. In order to do so, we are going to create an AWS access key and secret key.

We also do not want to use it explicitly in our provider.tf file. So we are going to create a variables.tf file and put this:

variable "aws_access_key" {
  type        = string
  description = "AWS access key"
}

variable "aws_secret_key" {
  type        = string
  description = "AWS secret key"
}

This will declare to Terraform that we have these two variables that can be accessed using var.aws_secret_key and var.aws_access_key and set using a terraform.tfvars file.

Create your terraform.tfvars and put your credentials:

aws_access_key = "your-access-key"
aws_secret_key = "your-secret-keys"

This way, Terraform will know which values these variables have and use it on our provider.tf file. Terraform will able to create, update or delete resources using this account. One more step and our provider will be completely set:

# on `provider.tf`

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "5.43.0"
    }
  }
}

provider "aws" {
  region     = "us-east-1"
  access_key = var.aws_access_key
  secret_key = var.aws_secret_key
}

Now Terraform will indeed know to which region and which account the resources are going to be created.

Declare your RDS resource

Now we just need to tell Terraform to create a RDS resource. As we are using aws provider to Terraform, you may check this documentation to understand a bit more of what we are going to write on the main.tf file.

resource "aws_db_instance" "my-free-rds-db-instance" {
  allocated_storage        = 20
  engine                   = "postgres"
  engine_version           = "16.1"
  identifier               = "my-free-rds-db-instance"
  instance_class           = "db.t3.micro"
  storage_encrypted        = false
  publicly_accessible      = true
  delete_automated_backups = true
  skip_final_snapshot      = true
  db_name                  = "database_name"
  username                 = "database_username"
  password                 = "database_password"
  apply_immediately        = true
  multi_az                 = false
}

Basically, what is happening here is that:

We tell Terraform to use AWS provider, using the credentials we set in terraform.tfvars
We declare a aws_db_instance called my-free-rds-db-instance and specify all the instance configuration that would be also specified via AWS console if we were creating using it.

This configuration is known to be a free tier in RDS for 12 months. There are other configurations but for the PostgreSQL is this one:

750 hours of Amazon RDS Single-AZ db.t2.micro, db.t3.micro, and db.t4g.micro Instances usage running MySQL, MariaDB, PostgreSQL databases each month. ... 20 GB of General Purpose SSD (gp2) storage per month.

If you check in the main.tf file, we define this configuration in a declarative way.

Spinning up your Terraform resources

Now run

terraform init # to initialize the dependency lock file

Initializing the backend...

Initializing provider plugins...
- Finding hashicorp/aws versions matching "5.43.0"...
- Installing hashicorp/aws v5.43.0...
- Installed hashicorp/aws v5.43.0 (signed by HashiCorp)

Terraform has created a lock file .terraform.lock.hcl to record the provider
selections it made above. Include this file in your version control repository
so that Terraform can guarantee to make the same selections by default when
you run "terraform init" in the future.

Terraform has been successfully initialized!

...

Now we have our AWS provider set in our Terraform context, which will enable us to tell our local Terraform CLI commands which version of the provider to use.

We may see the execution plan of the resources we have declared:

terraform plan

The output should be something like this:

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # aws_db_instance.my-free-rds-db-instance will be created
  + resource "aws_db_instance" "my-free-rds-db-instance" {
      + address                               = (known after apply)
      + allocated_storage                     = 20
      + apply_immediately                     = true
      + arn                                   = (known after apply)
      + auto_minor_version_upgrade            = true
      + availability_zone                     = (known after apply)
      + backup_retention_period               = (known after apply)
      + backup_target                         = (known after apply)
      + backup_window                         = (known after apply)
      + ca_cert_identifier                    = (known after apply)
      + character_set_name                    = (known after apply)
      + copy_tags_to_snapshot                 = false
      + db_name                               = "database_name"
      + db_subnet_group_name                  = (known after apply)
      + delete_automated_backups              = true
      + domain_fqdn                           = (known after apply)
      + endpoint                              = (known after apply)
      + engine                                = "postgres"
      + engine_version                        = "16.1"
      + engine_version_actual                 = (known after apply)
      + hosted_zone_id                        = (known after apply)
      + id                                    = (known after apply)
      + identifier                            = "my-free-rds-db-instance"
      + identifier_prefix                     = (known after apply)
      + instance_class                        = "db.t3.micro"
      + iops                                  = (known after apply)
      + kms_key_id                            = (known after apply)
      + latest_restorable_time                = (known after apply)
      + license_model                         = (known after apply)
      + listener_endpoint                     = (known after apply)
      + maintenance_window                    = (known after apply)
      + master_user_secret                    = (known after apply)
      + master_user_secret_kms_key_id         = (known after apply)
      + monitoring_interval                   = 0
      + monitoring_role_arn                   = (known after apply)
      + multi_az                              = false
      + nchar_character_set_name              = (known after apply)
      + network_type                          = (known after apply)
      + option_group_name                     = (known after apply)
      + parameter_group_name                  = (known after apply)
      + password                              = (sensitive value)
      + performance_insights_enabled          = false
      + performance_insights_kms_key_id       = (known after apply)
      + performance_insights_retention_period = (known after apply)
      + port                                  = (known after apply)
      + publicly_accessible                   = true
      + replica_mode                          = (known after apply)
      + replicas                              = (known after apply)
      + resource_id                           = (known after apply)
      + skip_final_snapshot                   = true
      + snapshot_identifier                   = (known after apply)
      + status                                = (known after apply)
      + storage_encrypted                     = false
      + storage_throughput                    = (known after apply)
      + storage_type                          = (known after apply)
      + tags_all                              = (known after apply)
      + timezone                              = (known after apply)
      + username                              = "database_username"
      + vpc_security_group_ids                = (known after apply)
    }

Plan: 1 to add, 0 to change, 0 to destroy.

This tells us which resources we declared and that are going to be created, changed or destroyed using the code we wrote.

As Bane said in The Dark Knight Rises: "It doesn't matter who we are, what matters is our plan", after reviewing and check the plan Terraform showed us, it is time to apply it:

terraform apply -auto-approve

This will apply the plan and should take like three minutes to AWS make the health check of the instance available.

aws_db_instance.my-free-rds-db-instance: Creating...
aws_db_instance.my-free-rds-db-instance: Still creating... [10s elapsed]
aws_db_instance.my-free-rds-db-instance: Still creating... [20s elapsed]
...

If you log in to your AWS account and go to RDS, you'll see that the instance is going to be in the creating state:

After a few minutes, it will be available and Terraform will tell us:

...
aws_db_instance.my-free-rds-db-instance: Still creating... [3m30s elapsed]
aws_db_instance.my-free-rds-db-instance: Still creating... [3m40s elapsed]
aws_db_instance.my-free-rds-db-instance: Creation complete after 3m49s [id=db-UZADWSYL266LYV2W6D6H7CUM4U]

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

You may check the endpoint to the instance via AWS Console or just accessing your terraform.tfstate and looking for the address. To connect, you just connect like it was a usual database.

Remember to use SSL to make the connection, otherwise you'll get an error. You could also add a parameter group in your Terraform files to make the force_ssl to 0 in your db instance.

Conclusion

This was a simple guide to introduce the readers on Terraform and also help them to create a free PostgreSQL RDS instance in AWS.

I hope this helps you to spin up a free PostgresQL to simulate a production-ready application and learn a bit more about using Terraform.

This project code is available on Github: terraform-aws-free-rds

ericbsantana / terraform-aws-free-rds

💰 A PostgreSQL free tier RDS instance using Terraform

A testable Go API using Gin + MongoDB + Testcontainers

Eric Santana — Tue, 02 Apr 2024 01:46:43 +0000

At my day-to-day, I work mainly with Node.js. Installing npm packages, using webpack to bundle stuff and importing named exports in a lot of .ts files. NoSQL databases are not too far away from me too.

But in my free time I like to explore new technologies. The Go realm is one of them. When doing this, I feel like I am in a new town: getting to know new places and meeting new people.

After years working with MongoDB and having few experiences when reading and learning about Go, I thought it was time to create something to the Go community. So here it is: a minimal Go boilerplate that is equipped with Gin + MongoDB and testable with Testcontainers.

Why another-boilerplate-in-an-open-source-repository?

Starting a project from scratch in Go can be a bit painful, especially when you came from other programming languages like TypeScript.

Considering this and how I read "learn in public" sentence as a moral rule, I have decided to create a Go repository for me which contains Gin + MongoDB to accelerate the creation of APIs using these tools.

Feel free to use this repository to learn more about Testcontainers, which I consider to be the more powerful thing in this boilerplate. If you want to know more about the template, keep reading. Want to jump directly to the code? Feel free to do so!

What are these Testcontainers and why should I use them?

The chef's kiss of this template is the usage of Testcontainers to make integration tests in the application's handlers.

This will help me in the future when building a more complex structure using another services like Kafka or Redis.

The best thing about using Testcontainers is to able to make integration tests and maintain your codebase fully testable if you use it correctly.

What were your difficulties when developing this project?

The most painful one was that I was not able to make Air work well with Docker: for some reason, my docker-compose file was not making the live-reload work correctly.

Still, the project works fine running go run main.go or install Air and run with air natively.

I have also tried to follow a dependency injection pattern in this boilerplate, which helped a lot when creating the tests for the handlers.

Conclusion

We could indeed use other tools to make tests. You could mock the repositories or find an library that helps to do them. I honestly do not know if there is a mongodb-memory-server like or equivalent to Go, but would be very happy to know if that is the case.

If you are interested in using Testcontainers in Go and do not want to do all the groundwork, feel free to use my template that is available here: gogimon.

Build your own curl in Golang

Eric Santana — Wed, 27 Mar 2024 23:05:00 +0000

In this tutorial, we'll walk through the process of creating a simple command-line tool similar to curl using Go and Cobra, a CLI library for Go.

Disclaimer: Here we are going to use the net package instead of the http that is available natively in Go. The reason for using net is to get a bit into the basics of creating a HTTP request to a server from scrach. You could easily use http package to enjoy all that stuff that is a pain to make from scratch. For instance, http already handles HTTPS requests.

It is a challenge because handling TCP connections and HTTP requests can be complex, but we'll keep it simple and focus on the basics. But will be a good start to understand how curl works under the hood and how to build a simple HTTP client using Go.

Prerequisites

Before we begin, make sure you have the following installed:

Go (version 1.22)

Setting Up Your Project

First, let's create a new Go module for our project:

mkdir build-your-own-curl
cd build-your-own-curl
go mod init build-your-own-curl

Next, let's install Cobra:

go get -u github.com/spf13/cobra/cobra

Now, let's initialize Cobra in our project:

cobra-cli init

This will create the structure for our CLI application with the following files:

├── cmd/
│   ├── root.go
├── go.mod
├── go.sum
├── main.go
├── LICENSE

The cmd directory contains the root command file, which is where we'll define our whole application. It is also possible to create subcommands in separate files within the cmd directory. For now, we'll keep it simple and define everything in the root.go file.

Building the Root Command

Now that we have our project set up, let's define our CLI commands using Cobra. We'll create a simple command to make HTTP GET requests.

To achieve this, we need to parse the URL provided as an argument, extract the hostname, port, and path, and then make an HTTP GET request to the specified URL. Firstly, we should parse the URL and extract the necessary information to create our TCP connection.

// cmd/root.go
package cmd

import (
    "net/url"
    "os"

    "github.com/spf13/cobra"
)

var rootCmd = &cobra.Command{
    Use:   "build-your-own-curl",
    Short: "A brief description of your application",
    Long: `A longer description that spans multiple lines and likely contains
examples and usage of using your application. For example:
Cobra is a CLI library for Go that empowers applications.
This application is a tool to generate the needed files
to quickly create a Cobra application.`,
    Args: cobra.ExactArgs(1),

    Run: func(cmd *cobra.Command, args []string) {
        u, err := url.Parse(args[0])

        if err != nil {
            panic(err)
        }

        host := u.Hostname()
        port := u.Port()
        path := u.Path

        println("Host:", host)
        println("Port:", port)
        println("Path:", path)
    },
}

// rest of the code

The Args field specifies the number of arguments the command expects. In this case, we expect exactly one argument, which is the URL we want to make a request to. You may want to add custom validators or other Cobra built-in validators if you want to expand this functionality. If you run the application without an argument, you should see an error message printed to the console.

go run main.go

Error: accepts 1 arg(s), received 0
Usage:
  build-your-own-curl [flags]

Flags:
  -h, --help     help for build-your-own-curl
  -t, --toggle   Help message for toggle

exit status 1

But if you run the application with an URL as an argument, you should see that hostname, port, and path are printed to the console.

go run main.go https://example.com/get

Host: example.com
Port:
Path: /get

As you probably have noticed, the port is not being extracted correctly. This is because the url.Parse function does not return the port if it is not specified in the URL.

Most of us do not specify the port when making a day-to-day HTTP request using curl or a browser. To make our UX better, let's set the default port to 80 if it is not specified in the URL. In this tutorial, I will not handle HTTPS requests, which is why we are going to use only port HTTP (80) for now.

// cmd/root.go
// ...
  Run: func(cmd *cobra.Command, args []string) {
    u, err := url.Parse(args[0])

    if err != nil {
      panic(err)
    }

    host := u.Hostname()
    port := u.Port()

    if port == "" {
      port = "80"
    }

    path := u.Path

    println("Host:", host)
    println("Port:", port)
    println("Path:", path)
  },
}
// ...

Run the application to see the default port bring printed to the console.

go run main.go https://example.com/get

Host: example.com
Port: 80
Path: /get

Now that we have the necessary information to create a TCP connection, let's make an HTTP GET request to the specified URL.

A basic HTTP GET request header consists of the following:

Request line: GET /path HTTP/1.0
Host header: Host: hostname

We will send this request to the server using net.Dial and read the response. We will then print the response to the console.

// cmd/root.go
package cmd

import (
    "fmt"
    "net"
    "net/url"
    "os"

    "github.com/spf13/cobra"
)

var rootCmd = &cobra.Command{
    Use:   "build-your-own-curl",
    Short: "A brief description of your application",
    Long: `A longer description that spans multiple lines and likely contains
examples and usage of using your application. For example:
Cobra is a CLI library for Go that empowers applications.
This application is a tool to generate the needed files
to quickly create a Cobra application.`,
    Args: cobra.ExactArgs(1),

    Run: func(cmd *cobra.Command, args []string) {
        u, err := url.Parse(args[0])

        if err != nil {
            panic(err)
        }

        host := u.Hostname()
        port := u.Port()
        path := u.Path

        if port == "" {
            port = "80"
        }

        conn, err := net.Dial("tcp", fmt.Sprintf("%s:%s", host, port))

        if err != nil {
            panic(err)
        }

        defer conn.Close()

        fmt.Fprintf(conn, "GET %s HTTP/1.0\r\nHost: %s\r\n\r\n", path, host)

        buf := make([]byte, 1024)
        n, err := conn.Read(buf)

        if err != nil {
            panic(err)
        }

        fmt.Println(string(buf[:n]))
    },
}

// ...

In the code above, we create a TCP connection to the specified host and port. We then send an HTTP GET request to the server and read the response. Finally, we print the response to the console. If you run the application with a valid URL, you should see the HTTP response printed to the console.

go run main.go http://eu.httpbin.org/get
HTTP/1.1 200 OK
Date: Wed, 27 Mar 2024 22:35:13 GMT
Content-Type: application/json
Content-Length: 203
Connection: close
Server: gunicorn/19.9.0
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true

{
  "args": {},
  "headers": {
    "Host": "eu.httpbin.org",
    "X-Amzn-Trace-Id": "Root=1-66049f21-305d0735393fd4ae2bc554a0"
  },
  "url": "http://eu.httpbin.org/get"
}

And you have it! A command-line tool to make GET requests to any URL using Go and Cobra. Additional changes can be made to handle different HTTP methods, headers, and more.

A challenge for you:

Add support for different HTTP methods (e.g., POST, PUT, DELETE).
Add support for custom headers.
Add support for HTTPS requests.

The first and second were made in my project gurl. You can check it out for more inspiration or even to contribute and improve it!

Another project that worth to mention here is go-curling from @chriswiegand

It uses http package instead of net which shows a more simple and fast way to implement a cURL client in Go without making requests from scratch using net.Dial.

Conclusion

Congratulations! You've built a simple command-line tool similar to curl using Go and Cobra. Feel free to expand upon this project by adding more features like handling different HTTP methods, headers, and more.

I have made a project called gurl that is a simple CLI tool that can make HTTP requests using Go. You can check it out for more inspiration.