improve doc & tests

docs/source/defining-sql-queries.rst

@@ -149,7 +149,7 @@ modifications to database rows without a necessary return value.
 
 .. literalinclude:: ../../tests/blogdb/sql/blogs/blogs.sql
    :language: sql
-   :lines: 64-66, 31,34
+   :lines: 64-66,32,34
 
 The methods generated are:
 
@@ -243,3 +243,5 @@ An example usecase is using data definition statements like create table in orde
 
     queries = aiosql.from_path("create_schema.sql", "sqlite3")
     queries.create_table_blogs(conn)
+
+Note: SQL scripts do not accept parameters.

docs/source/versions.rst

@@ -17,6 +17,8 @@ TODO
 ? on ?
 ------
 
+- improve documentation with declared parameters in examples.
+- homogeneise test consistency wrt attribute and parameter names.
 - fix doc typos.
 
 13.0 on 2024-11-10

tests/blogdb/sql/blogs/blogs.sql

@@ -11,7 +11,7 @@ DROP TABLE IF EXISTS blogs;
 -- name: drop-table-comments#
 DROP TABLE IF EXISTS comments;
 
--- name: get-all-blogs
+-- name: get-all-blogs()
 -- Fetch all fields for every blog in the database.
 select * from blogs;
 
@@ -25,11 +25,11 @@ insert into blogs (
 values (
   :userid,
   :title,
-  :contents,
+  :content,
   :published
 );
 
--- name: remove-blog!
+-- name: remove-blog(blogid)!
 -- Remove a blog from the database
 delete from blogs where blogid = :blogid;
 
@@ -61,13 +61,13 @@ select blogid, title from blogs where blogid = :blogid;
 -- name: with-params^
 select length(:name), :x.real + x.imaj;
 
--- name: new-blog!
+-- name: new-blog(userid, title, content)!
 insert into blogs (userid, title, content)
-  values (:userid, :title, :contents);
+  values (:userid, :title, :content);
 
--- name: publish-new-blog$
+-- name: publish-new-blog(userid, title, content)$
 insert into blogs (userid, title, content)
-  values (:userid, :title, :contents)
+  values (:userid, :title, :content)
   returning blogid;
 
 -- name: add_many_blogs*!

tests/blogdb/sql/blogs/ms/blogs.sql

@@ -49,7 +49,7 @@ output inserted.blogid, inserted.title
 values (
   :userid,
   :title,
-  :contents,
+  :content,
   :published
 );
 
@@ -62,4 +62,4 @@ where 0 = 1;
 -- name: bulk-publish*!
 -- Insert many blogs at once
 insert into blogs (userid, title, content, published)
-  values (:userid, :title, :contents, :published);
+  values (:userid, :title, :content, :published);

tests/blogdb/sql/blogs/pg/blogs.sql

@@ -36,7 +36,7 @@ insert into blogs (
 values (
   :userid,
   :title,
-  :contents,
+  :content,
   :published
 )
 returning blogid, title;
@@ -50,4 +50,4 @@ where false;
 -- name: bulk-publish*!
 -- Insert many blogs at once
 insert into blogs (userid, title, content, published)
-  values (:userid, :title, :contents, :published);
+  values (:userid, :title, :content, :published);

tests/blogdb/sql/users/users.sql

@@ -5,7 +5,7 @@
 -- Get all user records
 select * from users order by 1;
 
--- name: get-by-username^
+-- name: get-by-username(username)^
 select userid,
        username,
        firstname,
@@ -27,7 +27,7 @@ order by username asc;
 select * from users order by username asc;
 
 
--- name: get-count$
+-- name: get-count()$
 -- Get number of users
 select count(*) as cnt from users;
 

tests/run_tests.py

@@ -50,19 +50,19 @@ def _insert_blogs(todate):
         {
             "userid": 2,
             "title": "Blog Part 1",
-            "contents": "content - 1",
+            "content": "content - 1",
             "published": todate(2018, 12, 4),
         },
         {
             "userid": 2,
             "title": "Blog Part 2",
-            "contents": "content - 2",
+            "content": "content - 2",
             "published": todate(2018, 12, 5),
         },
         {
             "userid": 2,
             "title": "Blog Part 3",
-            "contents": "content - 3",
+            "content": "content - 3",
             "published": todate(2018, 12, 6),
         },
     ]
@@ -278,7 +278,7 @@ def run_insert_returning(conn, queries, date):
             conn,
             userid=2,
             title="My first blog",
-            contents="Hello, World!",
+            content="Hello, World!",
             published=date(2018, 12, 4),
         )
 
@@ -538,7 +538,7 @@ async def run_async_insert_returning(aconn, queries, date):
         aconn,
         userid=2,
         title="My first blog",
-        contents="Hello, World!",
+        content="Hello, World!",
         published=date(2018, 12, 4),
     )