Ampersand character being interpreted in comments in the deploy scripts

[ClementC]

Hi there, beginner users of sqitch here 👋

We had an issue, with a comment containing a URL to some wiki page, and the URL included the ampersand character.
This caused the execution of the sqitch deploy command to fail, and it was not immediately clear for us what caused the failure.

My question is: is there someplace in the documentation indicating explicitly what is interpreted by sqitch at different stages, and what are the best practices when it comes to documenting the deploy scripts?
I found this section to be somewhat related, but I felt it was not really answering the question I had.

[theory]

That's odd. Can you paste an example of the problematic line?

The Plan parser defines the format of a plan, but a note is allowed to be any character at all aside from a newline, which can be stored as the literal strings \r or \r\n. The regular expression that matches notes is here.

[ClementC]

Sure, here's a sanitized version of the deploy script:

-- Deploy misc script
-- Documentation link: https://jira_url.com/wiki/pages/viewpage.action?spaceKey=SPACE_NAME&title=PageTitle

USE WAREHOUSE &warehouse;

CREATE TABLE IF NOT EXISTS A.B (
    C DATE,
    D NUMBER(38,0)
);

This was causing an error with the following message:
Variable title is not defined

[theory]

Oh, I thought you mean in the plan file. This syntax is defined by the SnowSQL client. Note the &warehouse variable (which presumably you're setting on deploy). To use variables, you'll need to not use & in your snowSQL scripts. From the docs, it looks like you can escape the variable with… an ampersand, e.g., &&title=.

[ClementC]

Ok, thanks a lot then, you gave me all the info I needed! 👍
I'm closing the issue.

[theory]

You can also edit that line in the file directly, It's just informational, doesn't affect any business logic at all aside from the hash digest used to identify the file itself (so don't change it after you've tagged and released).

Mind if I move this issue to discussions? Might help others in the future.

[ClementC]

Yup, on our end it just means that having URLs in the scripts are a bad habit, and in the future it's better to put them in the plan for instance, where they would not be parsed in the comments.

No problem to move it to Discussions! And again thanks a lot for your quick and efficient answers! 🙂

[theory]

I think URLs in scripts are fine, you just need to escape ampersands. Not sure wha you mean by "in the plan", because the note for a change in the plan is used for a comment in the scripts, although you can change the template to omit them. Brief intro to change file templates here.

[ClementC]

I meant in the sqitch.plan file.
Good to know that the note is used in the script as well.
Thanks a lot! 🙂