Edit

Share via


Create a GitHub Codespaces dev environment with FastAPI and Postgres

This article shows you how to run FastAPI and Postgres together in a GitHub Codespaces environment. Codespaces is a development environment hosted in the cloud. Codespaces enables you to create configurable and repeatable development environments.

You can open the sample repo in a browser or in an integrated development environment (IDE) like Visual Studio Code with the GitHub Codespaces extension.

You can also clone the sample repo locally and when you open the project in Visual Studio Code, you can run using Dev Containers. Dev Containers requires that Docker Desktop installed locally. If you don't have Docker installed, you can still use VS Code to run the project, but you're using GitHub Codespaces as the environment.

When using GitHub Codespaces, keep in mind that you have a fixed number of core hours free per month. This tutorial requires less than one core hour to complete. For more information, see About billing for GitHub Codespaces.

With the approach shown in this tutorial, you can start with the sample code and modify it to run other Python frameworks like Django or Flask.

Start the dev environment in Codespaces

There are many possible paths to create and use GitHub Codespaces. This tutorial shows one path you can start with.

  1. Go to sample app repo https://github.com/Azure-Samples/msdocs-fastapi-postgres-codespace.

    The sample repo has all the configuration needed to create an environment with a FastAPI app using a Postgres database. You can create a similar project following the steps in Setting up a Python project for GitHub Codespaces.

  2. Select Code, Codespaces tab, and + to create a new codespace.

    Screenshot showing how to create a codespace from the GitHub repo.

  3. When the container finishes building, confirm that you see Codespaces in the lower left corner of the browser, and that sample repo has loaded.

    The codespace key configuration files are devcontainer.json, Dockerfile, and docker-compose.yml. For more information, see GitHub Codespaces overview.

    Tip

    You can also run the codespace in Visual Studio Code. Select Codespaces in lower left corner of the browser or (Ctrl + Shift + P / Ctrl + Command + P) and type "Codespaces". Then select Open in VS Code. Also, if you stop the codespace and go back to the repo and open it again in GitHub Codespaces, you have the option to open it in VS Code or a browser.

  4. Select the .env.devcontainer file and create a copy called .env with the same contents.

    The .env contains environment variables that are used in the code to connect to the database.

  5. If a terminal window isn't already open, open one by opening the Command Palette (Ctrl + Shift + P / Ctrl + Command + P), typing "Terminal: Create New Terminal", and selecting it to create a new terminal.

  6. Select the PORTS tab in the terminal window to confirm that PostgreSQL is running on port 5432.

  7. In the terminal window, run the FastAPI app.

    uvicorn main:app --reload
    
  8. Select the notification Open in Browser.

    If you don't see or missed the notification, go to PORTS and find the Local Address for port 8000. Use the URL listed there.

  9. Add /docs on the end of the preview URL to see the Swagger UI, which allows you to test the API methods.

    The API methods are generated from the OpenAPI interface that FastAPI creates from the code.

    Screenshot showing the FastAPI Swagger UI.

  10. On the Swagger page, run the POST method to add a restaurant.

    1. Expand the POST method.

    2. Select Try it out.

    3. Fill in the request body.

      {
        "name": "Restaurant 1",
        "address": "Restaurant 1 address"
      }
      
    4. Select Execute to commit the change

Connect to the database and view the data

  1. Go back to the GitHub Codespace for the project, select the SQLTools extension, and then select Local database to connect.

    The SQLTools extension should be installed when the container is created. If the SQLTools extension doesn't appear in the Activity Bar, close the codespace and reopen.

  2. Expand the Local database node until you find the restaurants table, right select Show Table Records.

    You should see the restaurant you added.

    Screenshot showing how touUse SQLTools extension in Visual Studio Code to connect to Postgres local database and show table records.

Clean up

To stop using the codespace, close the browser. (Or, close VS Code if you opened it that way.)

If you plan on using the codespace again, you can keep it. Only running codespaces incur CPU charges. A stopped codespace incurs only storage costs.

If you want to remove the codespace, go to https://github.com/codespaces to manage your codespaces.

Next steps