5 steps to bring DevX automation to your company
Get the guide

Connecting to your Databases using Port Forwarding

One of the big benefits of Okteto Cloud is the ability to deploy Cloud Native Stores with a single click. Via the Okteto Cloud catalog you can deploy things like Redis, PostgreSQL, CockroadDB, RabbitMQ and many more.

These stores are normally meant to support your application, and are typically only accessible to applications and services running on the same namespace. But when managing them, sometimes it's convenient to be able to use CLI or GUI-based clients running on your own local machine.

In this post, we'll show you how you can use the port forwarding features of Kubernetes and okteto to securely access your database directly from your local machine, just as if you were developing on your local machine.

Deploying a PostgreSQL instance

For this example, we are going to deploy a PostgreSQL database directly from the Okteto Cloud catalog. Keep in mind that this approach is not specific to databases, but works with any application running in Okteto Cloud.

To deploy your database, log in to Okteto Cloud, click on the Deploy button, select the Deploy from Helm Chart option. Once there, scroll down and click on PostgreSQL. This will open the Deploy configuration dialog for PostgreSQL. Leave the default values for now, and directly press on the Deploy button.

Deploy your PostgreSQL instance

Wait for a few seconds. Your database will be ready once it reaches the "Running" state. It will look something like this:

Your PostgreSQL instance is running

Now that we have our database up and running, we are going to connect to it from our local machine.

Configuring your Credentials

In order to access the database, we are going to create a port forwarding tunnel. This approach creates a temporary connection from your local machine to the database instance through a specific port. This will only be available for your machine, and only while the process is running, making it a lot more secure than publicly exposing your database.

In order to create the tunnel, first you'll need to download your Kubernetes credentials from your Okteto Cloud account. There are two ways of doing it. You can do this by doing to by clicking on the Settings on the left, and then clicking on the Download Config File button in the Kubernetes Credentials section, or by running the namespace command of the Okteto CLI. This document contains more information on this.

Starting the Port Forwarding tunnel

To start the port forwarding connection between the database running in Okteto Cloud and your local machine, we are going to use the kubectl port-forward command (if you don't have kubectl installed, follow [this document[https://kubernetes.io/docs/tasks/tools/install-kubectl/]). You'll need to pass the name of the kubernetes service, and the local and remote ports.

The format of the command is:

kubectl port-forward service/<service name> <local-port>:<remote-port>

In our example, the name of the service is postgresql, and the port is 5432 (the standard PostreSQL port). To create the port forwarding connection we run:

kubectl port-forward service/postgresql 5432:5432
Forwarding from -> 5432
Forwarding from [::1]:5432 -> 5432

As long as this process is running, the port forwarding tunnel will be active.

If you don't know the name of the service, or the port in use, you can run kubectl get svc to get this information.

Accessing the Database from your Local Machine

With the port forward running, we can now access the database with any tool in our local machine. For this example, we are going to use PostgreSQL's command line tool psql (If you don't have it installed locally, this tutorial shows you how).

Open a new terminal window (so that we don't interrupt the port forwarding process), and run psql with the parameters shown below. When asked for the password, type okteto.

psql --dbname okteto --host localhost --port 5432 --username okteto
Password for user okteto:
psql (12.3, server 11.5)
Type "help" for help.


You are now connected to the database running in Okteto Cloud. You could now directly create tables, run scripts, or modify existing data.

okteto=> CREATE TABLE messages (id int, message text);
okteto=> INSERT INTO messages(id, message) VALUES(1, 'hello');
okteto=> SELECT * FROM messages;
 id | message
  1 | hello
(1 row)

To exit psql, type /q and press enter. And to stop the port forward, go to the terminal running kubectl port-forward, and press ctrl+C.


In this post we showed you how you can use kubectl to enable secure, local and temporary access to any service running in Okteto Cloud. This allows to do useful things such using CLI or GUI-based database client running on your own local machine. But that's just the beginning. This technique can also be used for other scenarios such as connecting to remote debuggers, accessing metric ports, and many other cool things.

This is not the only way to create port forwarding tunnels. In a future post, we'll show you how you can also use the okteto CLI to do the same thing automatically as part of your remote development environment.

Head over to Okteto Cloud and start building your next Cloud Native Application. Our catalog is full of applications to help you get started 🚀.

Ramiro BerrellezaCEO & Co-founder View all posts

Automate Provisioning Any Dev Resource on Any Cloud Provider With Pulumi and Okteto

The Value It is common in today's landscape to build microservices-based applications that leverage resources like RDS databases, storage buckets, etc...

October 19, 2023
Avatar of Arsh SharmaAvatar of Arsh SharmaArsh Sharma

How Developers Can Seamlessly Collaborate When Building Microservice Apps

Building microservices based applications is inherently challenging. Given the multitude of components involved, it is unrealistic to expect any individual...

October 10, 2023
Avatar of Arsh SharmaAvatar of Arsh SharmaArsh Sharma