This provider makes it possible to integrate Alembic database migrations into
your Terraform deployment flow natively. In the past, I've used external Python
scripts to do this, but that has the downside of invoking the script on state
updates, which is not ideal for things like Alembic which may modify the
databae.
Requirements
Building The Provider
- Clone the repository
- Enter the repository directory
- Build the provider using the Go
install
command:
go install
Adding Dependencies
This provider uses Go modules.
Please see the Go documentation for the most up to date information about using Go modules.
To add a new dependency github.com/author/dependency
to your Terraform provider:
go get github.com/author/dependency
go mod tidy
Then commit the changes to go.mod
and go.sum
.
Using the provider
See the generated documentation for usage examples. You will need a project
using SQLAlchemy and Alembic as well as a database instance which is accessible
from the host running terraform (optionally through a proxy of some sort).
Developing the Provider
If you wish to work on the provider, you'll first need Go installed on your machine (see Requirements above).
To compile the provider, run go install
. This will build the provider and put the provider binary in the $GOPATH/bin
directory.
To generate or update documentation, run go generate
.
In order to run the full suite of Acceptance tests, run make testacc
.
Note: Acceptance tests create real resources, and often cost money to run.
make testacc
Note on Proxy Commands
Both the alembic_upgrade
and alembic_stamp
resources provide an optional
attribute named proxy_command
which is an argument list to be executed
for the duration of your Alembic execution. The intent is to start some
form of proxy needed to access your database server directly. In the case
of Google Cloud Platform deployments, this is commonly cloud_sql_proxy
,
but could be anything that proxies traffic to your database instance. For
example, it could be an SSH command to tunnel traffic to an internal instance.
Because this is a free-form argument list for a process, there are a few
things worth noting:
- Obviously, this allows execution of arbitrary other binaries through
your terraform configuration. Care should be taken with what you
execute through this configuration.
- There is another optional configuration named
proxy_sleep
which
controls how long the provider should sleep after invoking the proxy
command before attempting to execute Alembic commands. This is because
the proxy may not be up immediately, and attempting to start Alembic
quickly normally results in connection timeouts. The default value
of this configuration is 5s
which will cause each operation
(Read, Update, Create, etc) to sleep for 5 seconds before starting
execution.
- The third-party command must obvioulsy be installed on the system
running terraform. In the case of
cloud_sql_proxy
, that requires
you to go and download the static binary provided by Google, and
placing it either in your PATH
or providing the fully qualified
path as the first element in your proxy_command
array.