We're excited to announce the official release of the xata container image, designed to integrate the xata CLI into your containerized workflows. Whether you're running scheduled clones, automating database migrations, or building CI/CD pipelines, this lightweight image gives you everything you need to interact with your Xata databases from any container orchestration platform.

What's in the image?

Built on Debian Bookworm slim, the container image ships with the xata CLI pre-installed alongside PostgreSQL client tools. The image is optimized for minimal footprint while providing full CLI functionality, making it perfect for ephemeral workloads like Kubernetes CronJobs.

Getting started

Pull the image and authenticate with your API key:

From there, you can run any CLI command to manage projects, branches, backups, and more.

Now let’s look at examples for running xata CLI in your Kubernetes infrastructure.

Running xata in Kubernetes CronJobs

One of the most common use cases for this image is to automate scheduled database clones. Here's how you can set up a Kubernetes CronJob to run xata CLI commands:

Run a scheduled clone of your database

Apply outstanding migrations

Another powerful use case is running outstanding schema migrations in batch against your production branch. Using xata roll migrate, you can apply all pending migrations as part of a scheduled job or deployment pipeline:

Cleaning up stale branches

Development and preview branches can accumulate quickly. Automate nightly cleanup to delete all branches except main, keeping your project tidy and reducing clutter:

Customization

You can customize the args field to run any xata CLI command, from running database migrations to managing branches. The image uses xata as its entrypoint, so simply pass your command arguments directly.

Choosing the right PostgreSQL version

Here's something critical that often catches developers off guard: the PostgreSQL client version matters.

The Xata container image includes pg_dump and other PostgreSQL client tools for running clone and stream. However, pg_dump has a strict compatibility requirement: it cannot dump from a server running a newer PostgreSQL version than the client. For example, if your Xata database runs PostgreSQL 16 and you're using our image with PostgreSQL 18 client tools, you're fine. But if we flip that scenario, you'll encounter errors.

That’s why we provide multiple versions of xata for the last 3 released versions of PostgreSQL:

• xata:latest-pg16
• xata:latest-pg17
• xata:latest-pg18

We recommend matching the client version to your database's major PostgreSQL version to avoid any compatibility surprises. Check your Xata project settings to confirm which PostgreSQL version your branches are running.

We want your feedback

This release marks an important step in making Xata more accessible to teams running containerized infrastructure. But we're just getting started, and your input shapes what comes next.

Have ideas for improving the container image? Running into edge cases in your Kubernetes deployments? Want to see specific PostgreSQL versions supported out of the box? We'd love to hear from you.

If you haven’t tried our platform yet, click here to start.

Happy automating!