Use SurrealDB in GitHub Actions

This guide will show you how to set up and use the official GitHub Action for SurrealDB in your CI/CD pipeline.

Step 1: Create a new GitHub workflow file

Create a new YAML file in your repository's .github/workflows directory. You can name the file surrealdb-ci.yml.

name: SurrealDB CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - name: Git checkout
      uses: actions/checkout@v4
    - name: Start SurrealDB
      uses: surrealdb/setup-surreal@v3
      with:
        surrealdb_version: latest
        surrealdb_port: 8000
        surrealdb_username: root
        surrealdb_password: secret
        surrealdb_auth: false
        surrealdb_strict: false
        surrealdb_log: info
        surrealdb_additional_args: --allow-all
        surrealdb_retry_count: 30

Step 2: Customise workflow arguments

The official SurrealDB GitHub Action accepts several arguments to configure the SurrealDB setup. Here's a breakdown of the available arguments and their defaults:

The file passed to surrealdb_import_file selects its own namespace and database, so it should begin with a USE NS ... DB ...; statement.

Workflow outputs

The action exposes the details of the instance it started, so that later steps do not have to reconstruct them:

Example configuration

Here is an example configuration that sets specific values for each argument:

name: SurrealDB CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - name: Git checkout
      uses: actions/checkout@v4
    - name: Start SurrealDB
      id: surrealdb
      uses: surrealdb/setup-surreal@v3
      with:
        surrealdb_version: latest
        surrealdb_port: 8000
        surrealdb_username: root
        surrealdb_password: secret
        surrealdb_auth: false
        surrealdb_strict: false
        surrealdb_log: info
        surrealdb_additional_args: --allow-all
        surrealdb_retry_count: 30
    - name: Run the tests
      run: ./run-tests.sh
      env:
        SURREALDB_ENDPOINT: ${{ steps.surrealdb.outputs.endpoint }}

Tips for customisation

1. 1.

   Version Control: Use specific versions to avoid unexpected changes. Example: surrealdb_version: v3.2.4.

2. 2.

   Security: Always use strong passwords for surrealdb_password and avoid using default credentials in production.

3. 3.

   Logs: Set an appropriate log level based on your needs. For debugging, use debug or trace.

4. 4.

   Additional Arguments: Utilise surrealdb_additional_args to pass any additional CLI arguments required by your setup.

Step 3: Commit and push

After creating and customising your workflow file, commit and push it to your repository:

git add .github/workflows/surrealdb-ci.yml
git commit -m "Add SurrealDB CI workflow"
git push origin main

Step 4: Verify workflow execution

Go to your repository on GitHub and navigate to the "Actions" tab. You should see your workflow running when you push changes or create a pull request. Check the logs to verify that SurrealDB is starting up correctly and that all steps are executed successfully.

Conclusion

Using the official GitHub Action for SurrealDB simplifies the process of setting up and running SurrealDB in your CI/CD pipeline. Customise the workflow as per your project requirements, and ensure you follow best practices for security and version control. Happy coding!