Skip to main content

Project Configuration

Introduction​

Project Configuration being a core concept in Atlas, It allows you to manage your database schema in a more advanced way. In Atlas Operator, you can inject your project configuration into the Atlas Operator to customize the behavior of the Operator.

How it works​

By providing a config / configForm field in the Atlas resources, Atlas Operator will use the provided configuration to override the default behavior.

Guide: Using composite_schema with custom configurations​

In this guide, we will demonstrate how to use custom configuration to setup a composite schema

Step 1: Install the Operator with allowCustomConfig enabled​

Install the Atlas Operator using Helm:

helm install atlas-operator oci://ghcr.io/ariga/charts/atlas-operator --set allowCustomConfig=true

The allowCustomConfig flag is set to true to allow custom configuration to be injected into the Operator.

Step 2: Provision a local database​

Next, we will install a PostgreSQL database to manage using the Atlas Operator:

kubectl apply -f https://gist.githubusercontent.com/rotemtam/a7489d7b019f30aff7795566debbedcc/raw/53bac2b9d18577fed9e858642092a7f4bcc44a60/db.yaml

This command will install a few resources in your cluster:

  • A Deployment for the PostgreSQL database running the postgres:latest image.
  • A Service to expose the database to the cluster.
  • A Secret containing the database credentials in the Atlas URL format.

Step 3: Create a secret with the Atlas token​

The custom configuration feature requires atlas login. Let's create a secret with the token:

kubectl create secret generic atlas-token --from-literal=ATLAS_TOKEN="your-atlas-token"

This secret will be used to login to Atlas Cloud.

Step 4: Create the AtlasSchema resource​

atlas-schema.yaml
apiVersion: db.atlasgo.io/v1alpha1
kind: AtlasSchema
metadata:
  name: atlasschema-pg
spec:
  urlFrom:
    secretKeyRef:
      key: url
      name: postgres-credentials
  cloud:
    tokenFrom:
      secretKeyRef:
        key: ATLAS_TOKEN
        name: atlas-token
  envName: custom-env
  config: |
    data "external_schema" "users" {
      program = [
        "echo",
        "CREATE TABLE users (id INT, name TEXT);"
      ]
    }
    data "external_schema" "posts" {
      program = [
        "echo",
        "CREATE TABLE posts (id INT, user_id INT, title TEXT);"
      ]
    }
    data "composite_schema" "default" {
      schema "public" {
        url = data.external_schema.users.url
      }
      schema "public" {
        url = data.external_schema.posts.url
      }
    }
    env "custom-env" {
      schema {
        src = data.composite_schema.default.url
      }
    }

The custom configuration block contains a composite_schema block that defines two external schemas, users and posts, and a composite schema that combines them.

note

envName is a required field in the AtlasSchema resource. It is used to reference the environment in the custom configuration.

Step 5: Apply the schema and verify the result​

Run the following command to apply the schema:

kubectl apply -f atlas-schema.yaml

You can verify the result by querying the database to list the tables:

kubectl exec -it $(kubectl get pods -l app=postgres -o jsonpath='{.items[0].metadata.name}') -- psql -U postgres -d postgres -c "\dt"

You should see both the users and posts being created:

         List of relations
 Schema | Name  | Type  |  Owner   
--------+-------+-------+----------
 public | posts | table | postgres
 public | users | table | postgres