Ensure insert API has good tests for rowid and compound primark key tables

[simonw]

Following:

• API for bulk inserting records into a table #1866

I need to design and implement various edge-cases or primary keys:

• Table without an auto-incrementing primary key
• Table with compound primary keys
• Table with just a rowid

[simonw]

Relevant TODO:

datasette/datasette/views/table.py

Lines 1131 to 1135 in c35859a

	# Validate columns of each row
	columns = await db.table_columns(table_name)
	# TODO: There are cases where pks are OK, if not using auto-incrementing pk
	pks = await db.primary_keys(table_name)
	allowed_columns = set(columns) - set(pks)

[simonw]

If a table has an auto-incrementing primary key, should you be allowed to insert records with an explicit key into it?

I'm torn on this one. It's something you can do with direct database access, but it's something I very rarely want to do.

I'm inclined to disallow it and say that if you want that you can get it using a writable canned query instead.

Likewise, I'm not going to provide a way to set the rowid explicitly on a freshly inserted row.

[simonw]

I checked and SQLite itself does allow you to set the rowid on that kind of table - it then increments from whatever you inserted:

% sqlite3 /tmp/t.db
SQLite version 3.39.4 2022-09-07 20:51:41
Enter ".help" for usage hints.
sqlite> create table docs (title text);
sqlite> insert into docs (title) values ('one');
sqlite> select rowid, title from docs;
1|one
sqlite> insert into docs (rowid, title) values (3, 'three');
sqlite> select rowid, title from docs;
1|one
3|three
sqlite> insert into docs (title) values ('another');
sqlite> select rowid, title from docs;
1|one
3|three
4|another

[simonw]

Some notes on what Datasette does already

https://latest.datasette.io/fixtures/tags.json?_shape=array returns:

[
  {
    "tag": "canine"
  },
  {
    "tag": "feline"
  }
]

That table is defined like this:

CREATE TABLE tags (
    tag TEXT PRIMARY KEY
);

Here's a rowid table with no explicit primary key: https://latest.datasette.io/fixtures/binary_data

https://latest.datasette.io/fixtures/binary_data.json?_shape=array

[
  {
    "rowid": 1,
    "data": {
      "$base64": true,
      "encoded": "FRwCx60F/g=="
    }
  },
  {
    "rowid": 2,
    "data": {
      "$base64": true,
      "encoded": "FRwDx60F/g=="
    }
  },
  {
    "rowid": 3,
    "data": null
  }
]

CREATE TABLE binary_data (
    data BLOB
);

https://latest.datasette.io/fixtures/simple_primary_key has a text primary key:

https://latest.datasette.io/fixtures/simple_primary_key.json?_shape=array

[
  {
    "id": "1",
    "content": "hello"
  },
  {
    "id": "2",
    "content": "world"
  },
  {
    "id": "3",
    "content": ""
  },
  {
    "id": "4",
    "content": "RENDER_CELL_DEMO"
  },
  {
    "id": "5",
    "content": "RENDER_CELL_ASYNC"
  }
]

CREATE TABLE simple_primary_key (
  id varchar(30) primary key,
  content text
);

https://latest.datasette.io/fixtures/compound_primary_key is a compound primary key.

https://latest.datasette.io/fixtures/compound_primary_key.json?_shape=array

[
  {
    "pk1": "a",
    "pk2": "b",
    "content": "c"
  },
  {
    "pk1": "a/b",
    "pk2": ".c-d",
    "content": "c"
  }
]

CREATE TABLE compound_primary_key (
  pk1 varchar(30),
  pk2 varchar(30),
  content text,
  PRIMARY KEY (pk1, pk2)
);

[simonw]

Actually, for simplicity I'm going to say that you can always set the primary key, even for auto-incrementing primary key columns... but you cannot set it on pure rowid columns.

[simonw]

One last case to consider: WITHOUT ROWID tables.

https://www.sqlite.org/withoutrowid.html

By default, every row in SQLite has a special column, usually called the "rowid", that uniquely identifies that row within the table. However if the phrase "WITHOUT ROWID" is added to the end of a CREATE TABLE statement, then the special "rowid" column is omitted. There are sometimes space and performance advantages to omitting the rowid.

...

Every WITHOUT ROWID table must have a PRIMARY KEY. An error is raised if a CREATE TABLE statement with the WITHOUT ROWID clause lacks a PRIMARY KEY.

[simonw]

So maybe they're not actually worth worrying about separately, because they are guaranteed to have a primary key set.

[simonw]

I think the key feature I need here is going to be the equivalent of ignore=True and replace=True for dealing with primary key collisions, see https://sqlite-utils.datasette.io/en/stable/reference.html#sqlite_utils.db.Table.insert

[simonw]

Design decision:

{
  "rows": [{"id": 1, "title": "The title"}],
  "ignore": true
}

Or "replace": true.

[simonw]

It's a bit surprising that you can send "ignore": true, "return_rows": true and the returned "inserted" key will list rows that were NOT inserted (since they were ignored).

Three options:

1. Ignore that and document it
2. Fix it so "inserted" only returns rows that were actually inserted (bit tricky)
3. Change the name of "inserted" to something else

I'm picking 3 - I'm going to change it to be called "rows" instead.

[simonw]

I forgot to document ignore and replace. Also I need to add tests that cover:

• Forgetting to include a primary key on a non-autoincrement table
• Compound primary keys
• Rowid only tables with and without rowid specified

I think my validation logic here will get caught out by the fact that rowid does not show up as a valid column name:

datasette/datasette/views/table.py

Lines 1151 to 1160 in 9bec7c3

	# Validate columns of each row
	columns = set(await db.table_columns(table_name))
	for i, row in enumerate(rows):
	invalid_columns = set(row.keys()) - columns
	if invalid_columns:
	errors.append(
	"Row {} has invalid columns: {}".format(
	i, ", ".join(sorted(invalid_columns))
	)
	)