Introduced prepared statement APIs

[Benjamin-Dobell]

Support for prepared statements.

API

New API exported SQLiteStatement class.

# Prepare a statement
var statement = db.prepare("SELECT id, name FROM company WHERE age >= :min_age ORDER BY id;")

# Bind SQL Parameters
statement.bind_named({"min_age": 30})

# Execute the statement
var rows = statement.fetch_all()

# Reuse the prepared statement
statement.reset() # Resets/clears the cursor
statement.clear_bindings() # Clears SQL parameter bindings

if not statement.bind_named({"min_age": 20}):
	print("Select re-bind failed: " + statement.get_error_message())
else:
	var rows: Array = []
	var step_result: int = statement.step()
	while step_result == SQLite.SQLITE_ROW:
		rows.append(statement.get_row())
		step_result = statement.step()
	if step_result != SQLite.SQLITE_DONE:
		print("Prepared step failed (" + str(step_result) + "): " + statement.get_error_message())
	print("Prepared step rows (age >= 20): " + str(rows))

# Free the statement
statement.finalize()

Please note that you really do want to call finalize() to avoid memory leaks. That said, the connection itself also tracks the prepared statements, so if you clean up the connection it will clean-up any left over prepared statements.

Tests

Tests have been updated to include code similar to the above.

Docs

XML docs have been updated too.

AI Disclosure

LLMs were used during development. If that's an concern for this repo, do not merge.

[2shady4u]

Hello @Benjamin-Dobell,

Thank you for implementing this feature; it has been long pending :)
Also thank you for the disclaimer:

LLMs were used during development. If that's an concern for this repo, do not merge.

Using LLMs is okay, as long as we do some rigorous reviewing before merging :)
I'll need some time to review it in more more depth...

[2shady4u]

I did a surface-level review; I need to review in more depth at some point.

[2shady4u]

Prefer to use auto

[2shady4u]

Prefer to use auto

[2shady4u]

Statement is already nullptr? Why assign again?

[Benjamin-Dobell]

As much as I'd love to blame AI. This was almost certainly me 😛 AI generated the first iteration but I made a heap of changes after the fact - mostly removing cruft like useless helper methods. So this was probably the direct body of a helper method that was (naively) inlined.

[2shady4u]

Should this method clear the column_names first before appending?
To make sure the column_names is actually empty.

[Benjamin-Dobell]

It bails out early if the array is not empty. Basically it's lazy initialization, so subsequent calls aren't expected to mutate the column names at all.

[Benjamin-Dobell]

Perhaps it's worth noting that since these are prepared statements, the columns themselves aren't mutable. Once the statement is prepared, the columns included in the query are final. You don't reuse a statement for a different query, only for re-execution or rebinding SQL arguments.

[2shady4u]

No need for if statement because SQLite docs say:
Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.

[2shady4u]

This method should be cleaned up a bit manually.

[2shady4u]

I don't get the point of this method? It always returns false if status of the statement is not INITIALIZED so why not use is_valid instead?

[Benjamin-Dobell]

It's a private method and sets the error message, where as is_valid is part of the public API designed for library consumers.

[Benjamin-Dobell]

First round of feedback addressed. Feel free to take your time on a more thorough review - just actioning this quickly because I happened to be at the start of a work session and easier for me to do this now than worry about context switching later 😅

Probably worth noting, whilst I used an LLM to generate the first iteration, I have made extensive changes to what the LLM spat out - even introducing some of the mistakes the good ol' fashion way 😉

However, I must admit, it did save me a good chunk of time. This isn't exactly novel engineering work 😂 Bindings, porting code, and somewhat surprisingly, reverse engineering, are the areas I've found LLMs to really excel at. First PR I've ever submitted where AI did more than auto-complete; so figured I better flag it.

[2shady4u]

Hello :)
Just wanted to give small update: I am currently swamped with other stuff and won't be able to progress on this MR for a bit.
But I do intend on getting back to it since it is a very valuable MR.