ignore:true/replace:true options for /db/-/create API

[simonw]

See also:

• Docs for replace:true and ignore:true options for insert API #1924

It turns out I want to be able to call /db/-/create multiple times with the rows argument, so that I don't have to worry about creating the table first.

As such I find myself wanting support for the "insert": true and "replace": true options as well.

Still TODO:

• A test for the case where you call /-/create twice with rows without using these options
• pk should be required if you are using these options
• Error if you pass pk and the table exists already but has a different pk
• Documentation for insert and replace - and what happens if you repeat a /-/create with rows generally
• Documentation should explain that you are allowed to call /-/create more than once using rows.

[simonw]

Also: the documentation should clarify that you can call this API multiple times when using the rows option.

(It will probably grow "alter": true soon too).

[simonw]

Neither of these options make sense if you didn't pass a "pk".

My initial implementation spotted if the pk was missing and looked it up from the table, but actually I don't think that makes sense - if you know the table exists and hence don't pass the pk you should be using /-/insert or /-/upsert instead.

So maybe this work should expanded to include validation that checks if the table exists already - and if it does, confirms that the primary key (and maybe even the columns) are the same as for that existing table.

Of course if you only send row or rows then checking columns doesn't completely make sense - but we could check that the rows you have sent are equal to or a subset of the columns in the table. We could even check the column types as well, as seen in:

• Check incoming column types on various write APIs #1910

[simonw]

I'm going to push what I have anyway. I'll keep this issue open while I think through the above comment.

[simonw]

I have not yet documented the new insert and replace options.

[simonw]

I'll finish this after I land:

• /db/table/-/upsert #1931