{"id":112214,"date":"2026-09-23T12:00:00","date_gmt":"2026-09-23T12:00:00","guid":{"rendered":"https:\/\/www.red-gate.com\/simple-talk\/?p=112214"},"modified":"2026-09-08T15:55:21","modified_gmt":"2026-09-08T15:55:21","slug":"how-to-run-postgresql-in-docker-getting-started-with-postgresql-part-one","status":"publish","type":"post","link":"https:\/\/www.red-gate.com\/simple-talk\/databases\/postgresql\/how-to-run-postgresql-in-docker-getting-started-with-postgresql-part-one\/","title":{"rendered":"How to run PostgreSQL in Docker (getting started with PostgreSQL, part one)"},"content":{"rendered":"\n

The goal of this guide is simple: get PostgreSQL<\/a> up and running in the fastest, easiest way. You’ll then learn how to create databases in PostgreSQL and the objects that live within them.<\/strong><\/p>\n\n\n\n

The two easiest ways to get started working in PostgreSQL are to either use containers<\/a>, or create an account with a cloud<\/a> provider. In this case, we’ll be using containers.<\/strong><\/p>\n\n\n\n

\n
\n\n

Important note before you continue…<\/strong><\/p>\n\n\n\n

This is the first part in Grant Fritchey’s complete set of step-by-step walkthroughs (guides) for getting started with PostgreSQL, designed for any IT professional or hobbyist who wants to add PostgreSQL to their existing skillset. Click here for the full series<\/a>.<\/p>\n\n\n\n

Originally intended to be proctored classes given in a live, in-person environment, Grant has aimed to make the documentation and scripts clear enough to walk through them independently from home.<\/p>\n\n\n\n

Before getting started, please check that you have everything you need.<\/a><\/p>\n\n<\/div>\n<\/div> \n\n\n

How to retrieve Docker images using Pull<\/h2>\n\n\n\n

The goal of this walkthrough is, of course, to have a running PostgreSQL container. However, before a container can be created, the necessary image for that container must be retrieved.<\/strong><\/p>\n\n\n\n

It’s possible to simply issue a\u00a0docker run<\/code>\u00a0command and, if no image is found, it’ll automatically attempt to first\u00a0pull<\/code>\u00a0that image. While this is fine, it’s actually better to issue the pull<\/code> command separately.<\/p>\n\n\n\n

Why use Docker Pull?<\/h3>\n\n\n\n

For a start, a run<\/code> command will only run a local version of the image – not necessarily the latest one. Second, a pull<\/code> command validates the image before<\/em> execution, ensuring that malformed or malicious containers are not<\/em> run. And finally, retrieving the image first makes it possible to work fully offline – a nice benefit in itself.<\/p>\n\n\n\n

For all these reasons, we’ll use pull<\/code> as the foundation for building out PostgreSQL containers.<\/p>\n\n\n\n

How to use Docker Pull<\/h3>\n\n\n\n

There are many possible Docker<\/a> images, but we’ll start with the most generic PostgreSQL one for now. Before getting started, make sure you’re connected to the internet, and that your Docker service is running. Then, run the docker pull postgres:latest<\/code> command.<\/p>\n\n\n\n

It’s worth noting that the :latest<\/code> part of the command isn’t actually necessary. By default, a\u00a0pull<\/code>\u00a0command, if given no other instruction, will get the latest, stable, image. <\/p>\n\n\n\n

Also, depending on the service you’re running, you substitute\u00a0podman<\/code>\u00a0or\u00a0nerdctl<\/code>\u00a0for the\u00a0docker<\/code>\u00a0command. All other aspects of the command will stay the same.<\/p>\n\n\n\n

And, to reiterate, the latest<\/code> image will not be the most cutting edge version under development. Rather, it’s just the newest stable release.<\/em><\/p>\n\n\n\n

This command could<\/em> take a while depending on the speed and bandwidth of your internet connection – the progress of which you’ll be able to see in your command line interface. When it’s done, you’re ready to validate the image.<\/p>\n\n\n\n

To validate that the Docker image was downloaded successfully, you can run the docker images<\/code> command.<\/p>\n\n\n\n

On a brand new machine, you’ll probably only see a REPOSITORY<\/code> (with one or two images), postgres<\/code>, and possibly hello-world<\/code>. <\/p>\n\n\n\n

Also pay attention to the TAG column. Your postgres<\/code> image should show a tag of ‘latest’. If that’s the case, you’re ready to create a container.<\/p>\n\n\n\n

How to pull a specific image with Docker Pull<\/h3>\n\n\n\n

<\/a>If you wanted to have a specific version of PostgreSQL, it’s possible by supplying the documented tag of that version. For a complete listing, the PostgreSQL community maintains the Docker PostgreSQL image on the Docker hub here.<\/a><\/p>\n\n\n\n

To pull a particular version, you just need to supply it. For example, to pull version 17.10, you’d run
docker pull postgres:17.10<\/code>.<\/p>\n\n\n\n

How to create a container using Docker Run<\/h2>\n\n\n\n

Once an image has been created locally, you can now use that image to create containers. As stated previously, you can simply use\u00a0docker run<\/code>\u00a0to both pull the image and create the container. <\/p>\n\n\n\n

We’ll also need to break down the core requirements for creating a PostgreSQL container using\u00a0docker run<\/code>. Here’s the full command we’ll be using:<\/p>\n\n\n\n

docker run -d --name StartingPostgreSQL \\\n    -p 5432:5432 \\\n    -e POSTGRES_PASSWORD=Some*Passw0rd \\\n    -v \/mnt\/c\/Users\/grant\/bu:\/var\/lib\/postgresql\/bu \\\n    -e POSTGRES_USER=postgres \\\n    postgres:latest<\/pre><\/div>\n\n\n\n
Before we run the script, though, let’s talk about a few important pieces of information here.<\/p>\n\n\n\n
How to create a volume on your container (and why you should)<\/h3>\n\n\n\n
First, I’m going to recommend you create at least one volume on your container<\/a> (the\u00a0-v<\/code>\u00a0flag.) A volume is way to map an external directory on your machine to a location within the container. <\/p>\n\n\n\n
Then, you can place files into that folder and they’ll be readable within the container and<\/em> outside, in your operating system. If you wanted to have *.sql<\/code> files or PostgreSQL dump files available within the container, this is the easy way to do it.<\/p>\n\n\n\n
Because of this, you’ll need to ensure that you have that folder already created on your local machine. The example script above is for a Rancher Desktop<\/a> path. You’d need a different path for Windows or Linux unless you’re running everything through WSL<\/a> on Windows.<\/p>\n\n\n\n
You can get very sophisticated with volumes if you choose but, for our purposes, just the ability to easily move scripts into the container is enough.<\/p>\n\n\n\n
Naming your container<\/h3>\n\n\n\n
You don’t have to supply a name to the container, but it does make managing it easier. This is the --name<\/code> flag.<\/p>\n\n\n\n
Port mapping<\/h3>\n\n\n\n
<\/a>Next, you have to map between an external and internal port. Since I’m only running one container, I’ll map it to the default PostgreSQL port, 5432 (-p 5432:5432<\/code>). If you want to run more than one container hosting PostgreSQL, you’ll need to provide a different external port value (the first number.)<\/p>\n\n\n\n
For example, if you already have PostgreSQL running within a container (or locally), you might substitute
-p 5433:5432<\/code>\u00a0to map to a different port. You’ll then need to provide that non-default<\/em> port value to any connection to that PostgreSQL cluster.<\/p>\n\n\n\n
Environment variable flags<\/h3>\n\n\n\n
<\/a>For a container, a simple role is all that’s needed to connect to the cluster running inside the container. I have to use the environment variable flag,\u00a0-e<\/code> to map to a particular key two times:\u00a0
POSTGRES_PASSWORD<\/code>\u00a0and\u00a0POSTGRES_USER<\/code>.<\/p>\n\n\n\n
The name supplied to\u00a0POSTGRES_USER<\/code>\u00a0is going to be the default super user (system administrator) of the PostgreSQL cluster<\/a> running in the container. In the example, I use the default value for the super user in most PostgreSQL installs: postgres<\/code>.<\/p>\n\n\n\n
Image<\/h3>\n\n\n\n
Finally, I supply the name of the Docker image: postgres:latest.<\/code><\/p>\n\n\n\n
How to execute the script <\/h3>\n\n\n\n
When you execute the command, you receive back an identifier for the container you created. You can either use this identifier or<\/em> the name of the container you created. I recommend the latter, simply because it’s easier.<\/p>\n\n\n\n
To validate that the container was successfully created, run this command:
docker ps -f 'name=StartingPostgreSQL'<\/code><\/p>\n\n\n\n
This should result in something similar to the following:<\/p>\n\n\n\n
CONTAINER ID   IMAGE             COMMAND                  CREATED         STATUS         PORTS                                         NAMES\n6ae8a06273fe   postgres:latest   \"docker-entrypoint.s\u2026\"   6 seconds ago   Up 5 seconds   0.0.0.0:5432->5432\/tcp, [::]:5432->5432\/tcp   StartingPostgreSQL<\/pre><\/div>\n\n\n\n
As you can see from the output, you get the ID for the container itself, as well as the name, the image used in creation, when it was created, and the current status along with any ports. And that’s it! You now have a functional PostgreSQL cluster running within a container.<\/p>\n\n\n\n
How to stop\/start the container<\/h3>\n\n\n\n
You can stop the container by issuing the docker stop StartingPostgreSQL<\/code> command. Then, to restart the container, issue the docker start StartingPostgreSQL<\/code> command. If you wish to continue following this guide, I advise leaving the container in a running state.<\/p>\n\n\n\n
\n    
\n        
\n            
\n                
Get started with PostgreSQL – free book download<\/h3>\n                
\n                                            ‘Introduction to PostgreSQL for the data professional’, written by Grant Fritchey and Ryan Booz, covers all the basics of how to get started with PostgreSQL.                                    <\/div>\n            <\/div>\n                                            Download your free copy<\/a>\n                    <\/div>\n    <\/div>\n<\/section>\n\n\n
How to gain access to the container operating system (OS)<\/h2>\n\n\n\n
While running PostgreSQL within a container, certain operations have to be completed with the minimal<\/em> Linux OS that supports PostgreSQL in its execution within the container. In this part of the guide, we’ll be connecting to PostgreSQL using psql<\/code><\/a> – the default command line utility for running SQL<\/a> within PostgreSQL.<\/p>\n\n\n\n
In other parts of the guide, we may need to change PostgreSQL configuration files or perform other actions within the Linux OS. Therefore, we’ll do a quick overview of how to connect to that OS within the container.<\/p>\n\n\n\n
The Docker exec<\/code> command<\/h3>\n\n\n\n
The exec<\/code> command in Docker is used at the command line to open a shell into the running container. From there, you can perform actions directly within the container. <\/p>\n\n\n\n
In our case, we’ll be using psql<\/code> to run SQL queries. The command to start a shell within a container is simple: docker exec -it StartingPostgreSQL \"bash\"<\/code><\/p>\n\n\n\n
The -it<\/code> flag tells Docker that we’re starting an interactive shell command. We have to supply the container to which we want to connect through the container name. Finally, we supply what we wish to execute: a Bash<\/a> shell.<\/p>\n\n\n\n
Running this from the command line, you’ll see your folder change from whatever it was to something like this:
root@6ae8a06273fe:\/#<\/code><\/p>\n\n\n\n
This shows that I’m at the root of the container within Bash. Do note that the numbered value is supplied by Docker so will likely be different on your container.<\/p>\n\n\n\n
You can validate that you’re not local by running some simple commands. For example, the ls<\/code> command will show you the folder and file listing within the container. These will undoubtedly be different than your machine.<\/p>\n\n\n\n
A more effective check would be to look for the docker environment values using the ls -l \/.dockerenv<\/code> command. The output should be something similar to this:
-rwxr-xr-x 1 root root 0 Jun 18 13:26 \/.dockerenv<\/code> (and of course, the date will be different in your output).<\/p>\n\n\n\n
Another way to validate that you’re running in the PostgreSQL container (assuming you’re not running PostgreSQL locally as a service) would be to look for the $POSTGRES_USER<\/code> value using 
echo $POSTGRES_USER<\/code>. <\/p>\n\n\n\n
If this returns postgres<\/code> and<\/em> you’ve followed the scripts as written, then you’re absolutely within a shell in your container.<\/p>\n\n\n\n
To leave the shell, simply issue the exit<\/code> command – dropping you out of the shell within your container and back to the command line. You can leave the shell open for the next part of the guide.<\/p>\n\n\n\n
\n    
\n\n
Important note<\/strong><\/p>\n\n\n\n
While the standard<\/em> PostgreSQL container does have a Bash shell, some others may not. You can simply run ‘sh’ as the shell to get access to a bare bones shell on most containers.<\/p>\n\n<\/div>\n<\/div> \n\n\n
How to connect to PostgreSQL<\/h2>\n\n\n\n
Now, let’s focus on how to connect to PostgreSQL for the first time. Here’s everything you need to know in this step-by-step walkthrough\/guide.<\/strong><\/p>\n\n\n\n
Before we continue on to executing psql<\/code>, it’s worth double checking that we’re actually connected to the shell in our container. To check this, run the docker exec -it StartingPostgreSQL \"bash\"<\/code> command.<\/p>\n\n\n\n
What is psql<\/code> in PostgreSQL?<\/h3>\n\n\n\n
psql<\/code> is considered to be the official interface for PostgreSQL. It’s a command line for interacting with, and administering, PostgreSQL clusters<\/a>. You can issue SQL commands as well as taking advantage of the utilities built into psql<\/code>. <\/p>\n\n\n\n
In this part of the guide, we’ll explore the basic connection to PostgreSQL using psql<\/code>. We’ll then use psql<\/code> to create objects within the cluster. If you’ve been following from the start, you’ll be running this within a Bash shell inside your container. However, you wouldn’t run it any differently from the command line of your host OS. <\/p>\n\n\n\n
For our container as configured, we connect to it through psql<\/code> with the psql -d postgres -h localhost -U postgres<\/code> command. When run inside a container, you won’t be prompted for a password; you’re in a trusted environment. <\/p>\n\n\n\n
Otherwise, when running psql<\/code>, you’ll need to supply the password used when creating the container (in the example, Some*Passw0rd). You’re forced to provide a password in order to keep the password out of the history of commands in your CLI (command line interface)<\/a> as a beneficial security measure. <\/p>\n\n\n\n
Meanwhile, if you’re running psql<\/code> from an external command line – not the Bash shell as we’re doing – there are a couple of ways to supply a password without typing it each time. One way is to create an environment variable on your machine, but that’s less secure than simply entering the password. <\/p>\n\n\n\n
Another way is to create a secured file (chmod 0600) in your file system. We’ll just stick to the password for our examples.<\/p>\n\n\n\n
We’re logging in to the default database, postgres<\/code>, and using the user we created earlier in the guide (postgres<\/code>).<\/p>\n\n\n\n
Your prompt should now change to something like this:<\/p>\n\n\n\n
psql (18.4 (Debian 18.4-1.pgdg13+1))\nType \"help\" for help.\n\npostgres=# \n<\/pre><\/div>\n\n\n\n
We can validate that we’re successfully connected to PostgreSQL several ways. First, we can use one of the meta commands (so designated by a backslash \\<\/code> before the command). All meta commands are stored in *.sql<\/code> files since they can only be run through psql<\/code>. <\/p>\n\n\n\n
To see the connection information of PostgreSQL, we can run the \\conninfo<\/code> command, which will return a bunch of information about your connection:<\/p>\n\n\n\n
      Connection Information\n      Parameter       |   Value   \n----------------------+-----------\n Database             | postgres\n Client User          | postgres\n Host                 | localhost\n Host Address         | ::1\n Server Port          | 5432\n Options              | \n Protocol Version     | 3.0\n Password Used        | false\n GSSAPI Authenticated | false\n Backend PID          | 87\n SSL Connection       | false\n Superuser            | on\n Hot Standby          | off\n(13 rows)<\/pre><\/div>\n\n\n\n
Do note that, if your CLI window has fewer than 13 lines available, it will ‘page’ the results by default. You’ll need to use q<\/code> to move to the next page.<\/p>\n\n\n\n
Since we’re connected to psql<\/code>, you can immediately run a query instead of a meta command. One thing to know up front, every connection to PostgreSQL is to a specific database and that database only – there’s no concept of cross-database queries<\/a>. Any query we issue is going to run against the database specified in the connection. <\/p>\n\n\n\n
In this case, it’ll be the postgres<\/code> database. For clarity, we can use the SELECT version();<\/code> query to understand exactly where<\/em> we’re connected at any given time.<\/p>\n\n\n\n
At the time of writing this guide, the output is:<\/p>\n\n\n\n
                                                     version                                                       \n--------------------------------------------------------------------------------------------------------------------\n PostgreSQL 18.4 (Debian 18.4-1.pgdg13+1) on x86_64-pc-linux-gnu, compiled by gcc (Debian 14.2.0-19) 14.2.0, 64-bit`\n\nA few things to note. First, in the query you'll see the end terminated with a semi-colon (;). In PostgreSQL, query statements must be terminated with a semi-colon. This is not like some data platforms where the statement terminator of a semi-colon is syntactic sugar. It's required for PostgreSQL. However, it's not required for the meta commands. Second, you get to see exactly how this container was created. Not simply that it's PostgreSQL. It's version 18.4. The next is not that it's Linux. It's Debian 14.2.0. You're supplied full information about this Postgres cluster. You'll also note the \"-1.pgdg13+1\" in the parenthesis. This is the version of the container and who compiled it. \n\nWhile we're here, let's try out a couple of more meta commands that are useful to know. First, and probably most important, you can get a full listing of all meta commands:\n\n`\\?<\/pre><\/div>\n\n\n\n
It’ll likely enter into paging. <\/p>\n\n\n\n
We can also get a list of databases using the \\l<\/code> command, but this is unlikely to page on our example container because there should only be three databases: postgres<\/code> (the one we’re connected to), template0<\/code>, and template1<\/code>. We’ll discuss templates more later in the series.<\/em><\/p>\n\n\n\n
To leave a psql<\/code> session such as this, use the meta command\u00a0\\q<\/code>. And that’s it: you now have the basics of psql<\/code> under your belt! In part two, we will start actually working within<\/em> PostgreSQL.<\/p>\n\n\n\n
\n    
\n        
\n            
\n                
Simple Talk is brought to you by Redgate Software<\/h3>\n                
\n                                            Take control of your databases with the trusted Database DevOps solutions provider. Automate with confidence, scale securely, and unlock growth through AI.                                    <\/div>\n            <\/div>\n                                            Discover how Redgate can help you<\/a>\n                    <\/div>\n    <\/div>\n<\/section>\n\n\n
\n    
FAQs<\/h2>\n\n                        
1. How do I run PostgreSQL in a Docker container?<\/h3>\n            
\n                
Pull the official image with docker pull postgres:latest<\/code>, then create a container using docker run<\/code> with flags for the container name, port mapping (5432:5432), and a POSTGRES_PASSWORD<\/code> environment variable.<\/p>\n            <\/div>\n                    
2. What's the difference between docker pull and docker run for PostgreSQL?<\/h3>\n            
\n                
docker pull<\/code> only downloads the image and validates it before use, while docker run<\/code> creates and starts a container from that image \u2014 run<\/code> will auto-pull if no image exists, but pulling first lets you work offline and confirms you’re not running malicious or corrupted images.<\/p>\n            <\/div>\n                    
3. How do I connect to PostgreSQL running in a Docker container?<\/h3>\n            
\n                
Open a shell in the container with docker exec -it <container_name> \"bash\"<\/code>, then connect using psql -d postgres -h localhost -U postgres<\/code> \u2014 no password prompt is needed inside a trusted container shell.<\/p>\n            <\/div>\n                    
4. Why should I use a volume with my PostgreSQL Docker container?<\/h3>\n            
\n                
A volume (the -v<\/code> flag) maps a folder on your local machine to a directory inside the container, letting you move SQL scripts or database dump files in and out easily without extra copying steps.<\/p>\n            <\/div>\n                    
5. How do I stop and restart a PostgreSQL Docker container?<\/h3>\n            
\n                
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
Run docker stop <container_name><\/code> to stop it and docker start <container_name><\/code> to bring it back up \u2014 your data and configuration persist as long as the container isn’t deleted.<\/p>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n            <\/div>\n            <\/section>\n","protected":false},"excerpt":{"rendered":"
Get PostgreSQL running in Docker in minutes with this step-by-step setup guide. Learn to pull the image, run a container, set up volumes, and connect with psql.…<\/p>\n","protected":false},"author":221792,"featured_media":105920,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[143523,53,143534],"tags":[4168,4170,159410,158978,4150],"coauthors":[6785],"class_list":["post-112214","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-databases","category-featured","category-postgresql","tag-database","tag-database-administration","tag-gettingstartedpostgresgrant","tag-postgresql","tag-sql"],"acf":[],"_links":{"self":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/112214","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/users\/221792"}],"replies":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/comments?post=112214"}],"version-history":[{"count":15,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/112214\/revisions"}],"predecessor-version":[{"id":112507,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/112214\/revisions\/112507"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/media\/105920"}],"wp:attachment":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/media?parent=112214"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/categories?post=112214"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/tags?post=112214"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/coauthors?post=112214"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}