Astro Studio

The Astro Studio web portal allows you to connect to and manage your remote hosted Astro DB databases through a web interface or using CLI commands.

From your Studio dashboard, you have access to account management, help articles and a support message console.

Visit Astro Studio to sign up or log in.

Create a new Studio project

Section titled Create a new Studio project

There are two ways to create a project in Astro Studio:

1. Use the Astro Studio web UI to create from a new or existing GitHub repository.

   To get started, click the “create project” button in the header and follow the instructions. Astro Studio will connect to your GitHub repository and create a new hosted database for your project.

2. Use the Astro Studio CLI to create from any local Astro project. You can run the following commands to get started:

   npm

   # Log in to Astro Studio with your GitHub account
   npx astro login
   
   # Link to a new project by following the prompts
   npx astro link
   
   # (Optional) Push your local db configuration to the remote database
   npx astro db push

   pnpm

   # Log in to Astro Studio with your GitHub account
   pnpm astro login
   
   # Link to a new project by following the prompts
   pnpm astro link
   
   # (Optional) Push your local db configuration to the remote database
   pnpm astro db push

   Yarn

   # Log in to Astro Studio with your GitHub account
   yarn astro login
   
   # Link to a new project by following the prompts
   yarn astro link
   
   # (Optional) Push your local db configuration to the remote database
   yarn astro db push

   Once you are logged in and linked successfully, you can run all Astro DB commands to manage your remote database.

   See the Astro DB CLI reference for all available commands.

Deploy with a Studio connection

Section titled Deploy with a Studio connection

You can deploy your Astro DB project with a live connection to your Studio database. This is possible with any deployment platform using static builds or an SSR adapter.

First, configure your build command to connect with Studio using the --remote flag. This example applies the flag to a "build" script in your project’s package.json. If your deployment platform accepts a build command, ensure this is set to npm run build.

package.json

{
  "scripts": {
    "build": "astro build --remote"
  }
}

Create a Studio app token

Section titled Create a Studio app token

You need to create an app token to access your Studio database from a production deploy. You can create an app token from your Studio project dashboard by navigating to the Settings tab and selecting Tokens.

Copy the generated token and apply as an environment variable / environment secret in your deployment platform using the name ASTRO_STUDIO_APP_TOKEN.

Set up the GitHub CI Action

Section titled Set up the GitHub CI Action

You can automatically push schema changes to your Studio database with the Studio CI action. This verifies changes can be made safely, and keeps your configuration up-to-date whenever you merge to main.

Follow GitHub’s documentation to configure a new secret in your repository with the name ASTRO_STUDIO_APP_TOKEN and your Studio app token as the value for the secret.

Once your secret is configured, create a new GitHub Actions workflow file in your project’s .github/workflows directory to checkout the repository and install Node.js as steps, and use the withastro/action-studio action to sync schema changes.

The action will run astro db verify on all event triggers to ensure schema changes can be applied safely. If you add the push trigger specifically, the action will push those changes to your Studio database.

This example GitHub Action _studio.yml pushes changes whenever the main branch is updated:

.github/workflows/_studio.yml

name: Astro Studio

env:
  ASTRO_STUDIO_APP_TOKEN: ${{secrets.ASTRO_STUDIO_APP_TOKEN }}

on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, reopened, synchronize]

jobs:
  DB:
    permissions:
      contents: read
      actions: read
      pull-requests: write
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - uses: jaid/action-npm-install@v1.2.1
      - uses: withastro/action-studio@main