Executing Raw SQL

Sometimes the built-in helpers aren’t enough.

That’s when you go raw!

The db module gives you two weapons:

query() – fire-and-forget raw SQL
query_bind() – raw SQL with proper parameter binding (the one you’ll use 99% of the time)

query_bind() – The Safe Choice

Always prefer this when user input is involved.

Named parameters (cleanest)

Unnamed parameters (using ? placeholders) are not supported in Trongate v2. All query parameters must use named placeholders (e.g., :category, :price).

This is a deliberate design decision. Named parameters make code more explicit and readable, and avoiding multiple approaches to the same problem helps maintain consistency across Trongate projects.

If any part of the query comes from user input → use query_bind() or one of the other database interaction methods. No exceptions.

query() – Only When You’re 100% Sure

Use this only for fully trusted, hard-coded queries (migrations, reporting, complex joins, etc.).

Never use query() with user input from the outside world:

Return Types

Both methods accept an optional third parameter:

'object' → rows returned as objects (the Trongate default)
'array' → rows returned as associative arrays
omit or null → no result set (perfect for INSERT/UPDATE/DELETE)

Debug Mode Works Here Too

Turn on debug mode → both methods display the fully bound SQL before execution. This makes debugging easy.

Need raw power or complex table joins? Use query_bind().

Need raw power and you wrote every character yourself? query() is fine.

For everything else, stick to the built-in helpers.