> ## Documentation Index
> Fetch the complete documentation index at: https://developer.upsun.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add a database to Strapi

> Once Your Strapi application has been deployed on Upsun, you might want to add and configure a service to your application.


export const DynamicCodeBlock = ({language = 'yaml', filename, icon, lines, wrap, expandable, highlight, focus, children}) => {
  const STORAGE_KEY = 'upsun_versions_cache';
  const COMPOSABLE_STORAGE_KEY = 'upsun_composable_cache';
  const CACHE_TTL = 5 * 60 * 1000;
  const API_URL = 'https://meta.upsun.com/images';
  const COMPOSABLE_API_URL = 'https://meta.upsun.com/composable';
  const DEBUG_PREFIX = '[DynamicCodeBlock cache]';
  const [versionData, setVersionData] = useState(null);
  const [versionError, setVersionError] = useState(false);
  const [composableData, setComposableData] = useState(null);
  const [composableError, setComposableError] = useState(false);
  useEffect(() => {
    const fetchData = async () => {
      let cachedData = null;
      let cachedEtag = null;
      if (typeof localStorage !== 'undefined') {
        try {
          const cached = localStorage.getItem(STORAGE_KEY);
          if (cached) {
            const parsed = JSON.parse(cached);
            cachedData = parsed?.data || null;
            cachedEtag = parsed?.etag || null;
            if (cachedData && Date.now() - parsed.timestamp < CACHE_TTL) {
              return cachedData;
            }
          }
        } catch (err) {
          console.error('Failed to load from cache:', err);
        }
      }
      const requestHeaders = cachedEtag ? {
        'If-None-Match': cachedEtag
      } : {};
      console.debug(`${DEBUG_PREFIX} revalidating`, {
        storageKey: STORAGE_KEY,
        hasCachedData: Boolean(cachedData),
        hasCachedEtag: Boolean(cachedEtag)
      });
      const response = await fetch(API_URL, {
        headers: requestHeaders
      });
      if (response.status === 304 && cachedData) {
        console.debug(`${DEBUG_PREFIX} revalidated (304)`, {
          storageKey: STORAGE_KEY
        });
        if (typeof localStorage !== 'undefined') {
          try {
            const etag = response.headers.get('etag') || cachedEtag;
            localStorage.setItem(STORAGE_KEY, JSON.stringify({
              data: cachedData,
              etag,
              timestamp: Date.now()
            }));
          } catch (err) {
            console.error('Failed to refresh cache metadata:', err);
          }
        }
        return cachedData;
      }
      if (!response.ok) throw new Error(`API request failed: ${response.statusText}`);
      const data = await response.json();
      const etag = response.headers.get('etag');
      console.debug(`${DEBUG_PREFIX} refreshed (200)`, {
        storageKey: STORAGE_KEY,
        etag
      });
      if (typeof localStorage !== 'undefined') {
        try {
          localStorage.setItem(STORAGE_KEY, JSON.stringify({
            data,
            etag,
            timestamp: Date.now()
          }));
        } catch (err) {
          console.error('Failed to cache data:', err);
        }
      }
      return data;
    };
    fetchData().then(data => setVersionData(data)).catch(err => console.error('Failed to fetch version data:', err));
  }, []);
  const findHighestVersion = versionsMap => {
    if (!versionsMap || Object.keys(versionsMap).length === 0) return null;
    const entries = Object.entries(versionsMap);
    const active = entries.filter(([, v]) => v.upsun && v.upsun.status === 'supported' || v.upsun && v.upsun.status === 'deprecated');
    const candidates = active.length > 0 ? active : entries;
    let [highestName] = candidates[0];
    for (let i = 1; i < candidates.length; i++) {
      const [currentName] = candidates[i];
      const cp = currentName.split('.').map(Number);
      const hp = highestName.split('.').map(Number);
      for (let j = 0; j < Math.max(cp.length, hp.length); j++) {
        if ((cp[j] || 0) > (hp[j] || 0)) {
          highestName = currentName;
          break;
        } else if ((cp[j] || 0) < (hp[j] || 0)) {
          break;
        }
      }
    }
    return highestName;
  };
  const getVersion = (lang, requestedVersion = 'latest') => {
    if (lang === 'composable') {
      if (!composableData || !composableData.versions || Object.keys(composableData.versions).length === 0) return null;
      if (requestedVersion && requestedVersion !== 'latest') {
        return (requestedVersion in composableData.versions) ? requestedVersion : null;
      }
      return findHighestVersion(composableData.versions);
    }
    if (!versionData) return null;
    const imageData = versionData[lang];
    if (!imageData || !imageData.versions || Object.keys(imageData.versions).length === 0) {
      return null;
    }
    if (requestedVersion && requestedVersion !== 'latest') {
      return (requestedVersion in imageData.versions) ? requestedVersion : null;
    }
    return findHighestVersion(imageData.versions);
  };
  let code = typeof children === 'string' ? children : String(children || '');
  const codeLines = code.split('\n');
  while (codeLines.length > 0 && codeLines[0].trim() === '') codeLines.shift();
  while (codeLines.length > 0 && codeLines[codeLines.length - 1].trim() === '') codeLines.pop();
  if (codeLines.length > 0) {
    const indents = codeLines.filter(line => line.trim().length > 0).map(line => line.match(/^[ \t]*/)[0].length);
    const minIndent = Math.min(...indents);
    code = codeLines.map(line => line.slice(minIndent)).join('\n');
  }
  code = code.replace(/\{\{version:(.*?)\}\}/g, (match, params) => {
    const parts = params.split(':');
    const lang = parts[0];
    const ver = parts[1] || 'latest';
    const isComposable = lang === 'composable';
    const hasError = isComposable ? composableError : versionError;
    const dataReady = isComposable ? composableData !== null : versionData !== null;
    if (hasError) return '(unavailable)';
    if (dataReady) {
      const resolvedVersion = getVersion(lang, ver);
      return resolvedVersion || match;
    }
    return '...';
  });
  const codeBlockProps = {
    language,
    ...filename && ({
      filename
    }),
    ...icon && ({
      icon
    }),
    ...lines !== undefined && ({
      lines
    }),
    ...wrap !== undefined && ({
      wrap
    }),
    ...expandable !== undefined && ({
      expandable
    }),
    ...highlight && ({
      highlight
    }),
    ...focus && ({
      focus
    })
  };
  return <CodeBlock {...codeBlockProps}>{code}</CodeBlock>;
};

This guide will show you how to provision and connect to two different databases on Upsun:

* PostgreSQL
* Oracle MySQL

## 1. Branch

Like all updates to your Upsun projects, first create a new dedicated environment to test this change.

```bash theme={null}
git checkout -b upgrade-db
```

## 2. Install the Node.js package

<Tabs>
  <Tab title="PostgreSQL">
    ```bash theme={null}
    yarn add pg
    ```
  </Tab>

  <Tab title="Oracle MySQL">
    ```bash theme={null}
    yarn add mysql
    ```
  </Tab>
</Tabs>

## 3. Add a new service

Add a new service to your `.upsun/config.yaml` file:

<Tabs>
  <Tab title="PostgreSQL">
    <DynamicCodeBlock language="yaml" filename=".upsun/config.yaml">
      {`
              applications:
                <APP_NAME>:
                  source:
                    root: "/"
                  type: "nodejs:{{version:nodejs:latest}}"

                  [...]

              services:
                database:
              	  type: postgresql:{{version:postgresql:latest}}`
          }
    </DynamicCodeBlock>
  </Tab>

  <Tab title="Oracle MySQL">
    <DynamicCodeBlock language="yaml" filename=".upsun/config.yaml">
      {`
              applications:
                <APP_NAME>:
                  source:
                    root: "/"
                  type: "nodejs:{{version:nodejs:latest}}"

                  [...]

              services:
                database:
              	  type: oracle-mysql:{{version:oracle-mysql:latest}}`
          }
    </DynamicCodeBlock>
  </Tab>
</Tabs>

## 4. Add a new relationship

Add a new relationship to your `.upsun/config.yaml` file to allow access to the new service

<Tabs>
  <Tab title="PostgreSQL">
    <DynamicCodeBlock language="yaml" filename=".upsun/config.yaml">
      {`
              applications:
                <APP_NAME>:
                  source:
                    root: "/"
                  type: "nodejs:{{version:nodejs:latest}}"

                  [...]

                  relationships:
                    database:

              services:
                database:
              	  type: postgresql:{{version:postgresql:latest}}`
          }
    </DynamicCodeBlock>
  </Tab>

  <Tab title="Oracle MySQL">
    <DynamicCodeBlock language="yaml" filename=".upsun/config.yaml">
      {`
              applications:
                <APP_NAME>:
                  source:
                    root: "/"
                  type: "nodejs:{{version:nodejs:latest}}"

                  [...]

                  relationships:
                    database:

              services:
                database:
              	  type: oracle-mysql:{{version:oracle-mysql:latest}}`
          }
    </DynamicCodeBlock>
  </Tab>
</Tabs>

## 5. Update `.environment`

When you previously ran `upsun project:init`, the command generated some Strapi-specific environment variables:

```bash .environment theme={null}
# Set Strapi-specific environment variables
export DATABASE_HOST="$DB_HOST"
export DATABASE_PORT="$DB_PORT"
export DATABASE_NAME="$DB_PATH"
export DATABASE_USERNAME="$DB_USERNAME"
export DATABASE_PASSWORD="$DB_PASSWORD"
export DATABASE_SCHEME="$DB_SCHEME"

# Set secrets needed by Strapi, if they are not set
# Prefer setting these as project secret variables with upsun variable:create env:SECRET_NAME --sensitive=true
if [ -z "$ADMIN_JWT_SECRET" ]; then
  export ADMIN_JWT_SECRET="$PLATFORM_PROJECT_ENTROPY"
fi
if [ -z "$JWT_SECRET" ]; then
  export JWT_SECRET="$PLATFORM_PROJECT_ENTROPY"
fi
if [ -z "$API_TOKEN_SALT" ]; then
    export API_TOKEN_SALT="$PLATFORM_PROJECT_ENTROPY"
fi
if [ -z "$APP_KEYS" ]; then
    export APP_KEYS="$PLATFORM_PROJECT_ENTROPY"
fi
```

Upsun will actually generate service credentials automatically for you in the runtime container, so we don't need the first half of this file anymore.
Remove the first block (pertaining to `DATABASE` credentials).

Then, add a single additional variable that will set the `DATABASE_CLIENT` variable at the appropriate time:

<Tabs>
  <Tab title="PostgreSQL">
    ```bash .environment theme={null}
    # Set secrets needed by Strapi, if they are not set
    # Prefer setting these as project secret variables with upsun variable:create env:SECRET_NAME --sensitive=true
    if [ -z "$ADMIN_JWT_SECRET" ]; then
      export ADMIN_JWT_SECRET="$PLATFORM_PROJECT_ENTROPY"
    fi
    if [ -z "$JWT_SECRET" ]; then
      export JWT_SECRET="$PLATFORM_PROJECT_ENTROPY"
    fi
    if [ -z "$API_TOKEN_SALT" ]; then
        export API_TOKEN_SALT="$PLATFORM_PROJECT_ENTROPY"
    fi
    if [ -z "$APP_KEYS" ]; then
        export APP_KEYS="$PLATFORM_PROJECT_ENTROPY"
    fi

    # Switch to configure to the production database service _only_ at deploy time.
    if [ -z "$PLATFORM_ENVIRONMENT" ]; then
        export DATABASE_CLIENT="postgres"
    fi
    ```
  </Tab>

  <Tab title="Oracle MySQL">
    ```bash .environment theme={null}
    # Set secrets needed by Strapi, if they are not set
    # Prefer setting these as project secret variables with upsun variable:create env:SECRET_NAME --sensitive=true
    if [ -z "$ADMIN_JWT_SECRET" ]; then
      export ADMIN_JWT_SECRET="$PLATFORM_PROJECT_ENTROPY"
    fi
    if [ -z "$JWT_SECRET" ]; then
      export JWT_SECRET="$PLATFORM_PROJECT_ENTROPY"
    fi
    if [ -z "$API_TOKEN_SALT" ]; then
        export API_TOKEN_SALT="$PLATFORM_PROJECT_ENTROPY"
    fi
    if [ -z "$APP_KEYS" ]; then
        export APP_KEYS="$PLATFORM_PROJECT_ENTROPY"
    fi

    # Switch to configure to the production database service _only_ at deploy time.
    if [ -z "$PLATFORM_ENVIRONMENT" ]; then
        export DATABASE_CLIENT="mysql"
    fi
    ```
  </Tab>
</Tabs>

## 6. Push to the environment

Commit and push the changes to the Upsun environment:

```bash theme={null}
git commit -am "Add a new service"
git push origin upgrade-db
```

<Info>
  If you are using Upsun as your primary remote, you can use the `upsun branch` and `upsun push` commands directly.
  If instead you had already set up an integration to GitHub, GitLab or Bitbucket, make sure to open a pull/merge request to judge the revision.
</Info>