Migrating project definition files from version 1.x to 2.0

To convert a version 1.x project definition file to the version 2 format, do the following:

  1. Go to your project directory that contains the version 1.x snowflake.yml file.
  2. Enter the snow helpers v1-to-v2 command.

    • If the version 1.x file conversion succeeds, the command displays a message similar to the following:

      cd <project-directory>
snow helpers v1-to-v2
      Project definition migrated to version 2.

    • If your project definition file is already updated to version 2, the command displays the following message:

      cd <project-directory>
snow helpers v1-to-v2
      Project definition is already at version 2.
  • If you try to convert a project file that contains a snowflake.local.yml file, without using the --[no]-migrate-local-overrides option, the command generates an error similar to the following:

  • If you try to convert a project file that contains templates, without using the --accept-templates option, the command generates an error similar to the following:

    cd <project-directory>
snow helpers v1-to-v2
    +- Error-------------------------------------------------------------------+
| snowflake.local.yml file detected, please specify                        |
| --migrate-local-overrides to include or --no-migrate-local-overrides to  |
| exclude its values.                                                      |
+--------------------------------------------------------------------------+

  • If you convert a project definition file that contains templates, and use the --accept-templates option, the command converts the file and displays a warning message similar to the following:

    cd <project-directory>
snow helpers v1-to-v2
    WARNING  snowflake.cli._plugins.workspace.commands:commands.py:60 Your V1 definition contains templates. We cannot guarantee the correctness of the migration.
Project definition migrated to version 2

Convert Native App projects

This section shows an example from a V1 to V2 conversion of a Snowflake Native App project, lists the changes in property names, and offers some tips to help with migration.

Snowflake Native App conversion example

Native Apps project conversion example

V1 project fileV2 project file
definition_version: 1
native_app:
  name: myapp
  source_stage: app_src.stage
  artifacts:
    - src: app/*
      dest: ./
      processors:
        - native app setup
        - name: templates
          properties:
            foo: bar
  package:
    role: pkg_role
    distribution: external
  application:
    name: myapp_app
    warehouse: app_wh
definition_version: 2
entities:
  pkg:
    type: application package
    meta:
      role: pkg_role
    identifier: <% fn.concat_ids('myapp', '_pkg_', fn.sanitize_id(fn.get_username('unknown_user')) | lower) %>
    manifest: app/manifest.yml
    artifacts:
    - src: app/*
      dest: ./
      processors:
      - name: native app setup
      - name: templates
        properties:
          foo: bar
    stage: app_src.stage
  app:
    meta:
      warehouse: app_wh
    identifier: myapp_app
    type: application
    from:
      target: pkg

Native App project definition V1 to V2 property changes

Native App project definition V1 to V2 property changes

V1 propertyV2 property
native_app.nameNo equivalent. Use a template variable to port, if required.
native_app.deploy_root<package entity>.deploy_root
native_app.generated_root<package entity>.generated_root
native_app.bundle_root<package entity>.bundle_root
native_app.source_stage<package entity>.source_stage
native_app.scratch_stage<package entity>.scratch_stage
native_app.artifacts<package entity>.artifacts
native_app.application.debug<application entity>.debug
native_app.application.name<application entity>.identifier
native_app.application.post_deploy<application entity>.meta.post_deploy (see above notes)
native_app.application.role<application entity>.meta.role
native_app.application.warehouse<application entity>.meta.warehouse
native_app.package.distribution<package entity>.distribution
native_app.package.name<package entity>.identifier
native_app.package.post_deploy<package entity>.meta.post_deploy (see above notes)
native_app.package.role<package entity>.meta.role
native_app.package.scripts<package entity>.meta.post_deploy (see above notes)
native_app.package.warehouse<package entity>.meta.warehouse

Migration tips

  • When migrating Snowflake Native App package scripts, the v1-to-v2 command converts them to package post-deploy hooks and replaces {{package_name}} in the package script file with the equivalent template expression.
  • When migrating existing template expressions, ctx.native_app, ctx.streamlit, and ctx.snowpark variables are no longer accepted. The v1-to-v2 command with equivalent template expressions that reference the specific entity name instead. For example, ctx.native_app.package.name could be replaced with ctx.entities.pkg.identifier if the package was migrated to an entity named pkg in the snowflake.yml file.

Convert Streamlit projects

This section shows an example from a V1 to V2 conversion of a Streamlit project, lists the changes in property names, and offers some tips to help with migration.

Streamlit conversion example

Streamlit project conversion example

V1 project fileV2 project file
definition_version: 1
streamlit:
  name: test_streamlit
  stage: streamlit
  query_warehouse: test_warehouse
  main_file: "streamlit_app.py"
  title: "My Fancy Streamlit"
definition_version: 2
entities:
  test_streamlit:
    identifier:
      name: test_streamlit
    type: streamlit
    title: My Fancy Streamlit
    query_warehouse: test_warehouse
    main_file: streamlit_app.py
    pages_dir: None
    stage: streamlit
    artifacts:
    - streamlit_app.py

Streamlit project definition V1 to V2 property changes

Streamlit project definition V1 to V2 property changes

V1 propertyV2 property
streamlit.name<streamlit entity>.identifier.name
streamlit.schema<streamlit entity>.identifier.schema
streamlit.database<streamlit entity>.identifier.database
streamlit.comment<streamlit entity>.comment
streamlit.title<streamlit entity>.title
streamlit.query_warehouse<streamlit entity>.query_warehouse
streamlit.main_file<streamlit entity>.main_file and <streamlit entity>.artifacts
streamlit.stage<streamlit entity>.stage
streamlit.env_file<streamlit entity>.artifacts
streamlit.pages_dir<streamlit entity>.pages_dir and <streamlit entity>.artifacts
streamlit.additional_source_files<streamlit entity>.artifacts

Streamlit migration tips

None.

Convert Snowpark projects

This section shows an example from a V1 to V2 conversion of a Snowpark project, lists the changes in property names, and offers some tips to help with migration.

Snowpark conversion example

Snowpark project conversion example

V1 project fileV2 project file
definition_version: 1
snowpark:
  project_name: "my_snowpark_project"
  stage_name: "dev_deployment"
  src: "app/"
  functions:
    - name: func1
      handler: "app.func1_handler"
      signature:
        - name: "a"
          type: "string"
          default: "default value"
        - name: "b"
          type: "variant"
      returns: string
      runtime: 3.10
  procedures:
    - name: procedureName
      handler: "hello"
      signature:
        - name: "name"
          type: "string"
      returns: string
definition_version: 2
entities:
  procedureName:
    imports: []
    external_access_integrations: []
    secrets: {}
    meta:
      use_mixins:
      - snowpark_shared
    identifier:
      name: procedureName
    handler: hello
    returns: string
    signature:
    - name: name
      type: string
    stage: dev_deployment
    artifacts:
    - src: app
      dest: my_snowpark_project
    type: procedure
    execute_as_caller: false
  func1:
    imports: []
    external_access_integrations: []
    secrets: {}
    meta:
      use_mixins:
      - snowpark_shared
    identifier:
      name: func1
    handler: app.func1_handler
    returns: string
    signature:
    - name: a
      type: string
      default: default value
    - name: b
      type: variant
    runtime: '3.10'
    stage: dev_deployment
    artifacts:
    - src: app
      dest: my_snowpark_project
    type: function
mixins:
  snowpark_shared:
    stage: dev_deployment
    artifacts:
    - src: app/
      dest: my_snowpark_project

Snowpark project definition V1 to V2 property changes

Snowpark project definition V1 to V2 property changes

V1 propertyV2 property
snowpark.project_name<function or procedure entity>.artifacts.dest for each function and/or procedure migrated from the project. See above notes regarding Snowpark migration. Each function or procedure should declare an artifact with dest defined as the snowpark.project_name value, and src defined as the snowpark.src value. Use of a mixin is recommended.
snowpark.stage_name<function or procedure entity>.stage for each function and/or procedure migrated from the project.
snowpark.src<function or procedure entity>.artifacts.src for each function and/or procedure migrated from the project. (see snowpark.project_name above)
snowpark.functions (list)<function entities> (top-level)
snowpark.procedures (list)<procedure entities> (top-level)

Snowpark function and procedure definition V1 to V2 property changes

V1 propertyV2 property
nameidentifier.name
schemaidentifier.schema
databaseidentifier.database
handlerhandler
returnsreturns
signaturesignature
runtimeruntime
external_access_integrationsexternal_access_integrations
secretssecrets
importsimports
execute_as_callerexecute_as_caller (only for procedures)

Snowpark migration tips

  • When migrating Snowpark projects, each function (from the snowpark.functions array) or procedure (from the snowpark.procedures array) maps to a top-level entity.
  • All top-level Snowpark project properties (e.g. src) are now defined for each function and procedure. To reduce duplication, Snowflake recommends that you declare a mixin and include it in each of the migrated function and procedure entities.