diff --git a/doc/datatypes.rst b/doc/datatypes.rst index 5022d7e..6a81fef 100644 --- a/doc/datatypes.rst +++ b/doc/datatypes.rst @@ -240,8 +240,8 @@ The CHARACTER VARYING, abbreviated CHAR VARYING or VARCHAR, data type stores str Example usage of ``VARCHAR(n)``:: - >>> cursor.execute("create table varchar_table (c1 NVARCHAR(128), c1 NVARCHAR(256)") - >>> cursor.execute("insert into varchar_table values (:a, :b)", ("Hey", "my string"))) + >>> cursor.execute("create table varchar_table (c1 VARCHAR(128), c2 VARCHAR(256))") + >>> cursor.execute("insert into varchar_table values (:a, :b:null)", {'a':"Hey", 'b':None}) NCHAR(n) ---------------- @@ -251,8 +251,8 @@ When Mimer SQL stores values in a column defined as NATIONAL CHARACTER, it right Example usage of ``NVARCHAR``:: - >>> cursor.execute("create table nchar_table(c1 nchar(5), c2 nchar(12))") - >>> cursor.execute("insert into nchar_table values (:a,:b)", "nchar table")) + >>> cursor.execute("create table nchar_table(c1 nchar(5), c2 nchar(6))") + >>> cursor.execute("insert into nchar_table values (?,?)", ("nchar", "tables")) NVARCHAR(n) ---------------- @@ -262,8 +262,8 @@ The NATIONAL CHARACTER VARYING, abbreviated NVARCHAR, NATIONAL CHAR VARYING or N Example usage of ``NVARCHAR(n)``:: - >>> cursor.execute("create table nvarchar_table (c1 NVARCHAR(128), c1 NVARCHAR(256)") - >>> cursor.execute("insert into nvarchar_table values (:a, :b)", ("Hey", "my string")) + >>> cursor.execute("create table nvarchar_table (c1 NVARCHAR(128), c2 NVARCHAR(256))") + >>> cursor.execute("insert into nvarchar_table values (:a, :b:null)", {'a':"Hey", 'b':None}) DATE ---------- diff --git a/doc/userguide.rst b/doc/userguide.rst index 6d86f06..075c408 100644 --- a/doc/userguide.rst +++ b/doc/userguide.rst @@ -96,9 +96,8 @@ With parameter markers Executing queries with parameter markers should be done following a few rules. According to the `PEP 249`_ parameter markers should be a list of tuples. -Mimer SQL uses the ``qmark`` parameter style. This means parameter markers are of -question mark style, e.g...WHERE name=?. Dictionaries can also be used as parameter markers. -The key(s) in the dictionary have to match up with the corresponding column you want to manipulate. +Mimer SQL uses the either ``qmark`` or ``named`` parameter style. Parameter markers in `qmark`` style are of +question mark style, e.g...WHERE name=?. In ``named`` parameter style follows the format :name and you specify values using dictionaries where the key(s) have to match up with the corresponding column you want to manipulate. When executing to a single column, the rules can be bent a bit:: @@ -106,11 +105,12 @@ When executing to a single column, the rules can be bent a bit:: >>> cur.execute("create table ptable(c1 NVARCHAR(128))") # Executing a statement using parametermarkers - >>> cur.execute("INSERT INTO ptable VALUES (?)", "bar") # Correct - >>> cur.execute("INSERT INTO ptable VALUES (?)", ("bar")) # Correct - >>> cur.execute("INSERT INTO ptable VALUES (?)", ("bar",)) # Correct - >>> cur.execute("INSERT INTO ptable VALUES (?)", ["bar"]) # Correct - >>> cur.execute("INSERT INTO ptable VALUES (:a)", {'a':bar}) # Correct + >>> cur.execute("INSERT INTO ptable VALUES (?)", "bar") # Correct + >>> cur.execute("INSERT INTO ptable VALUES (?)", ("bar")) # Correct + >>> cur.execute("INSERT INTO ptable VALUES (?)", ("bar",)) # Correct + >>> cur.execute("INSERT INTO ptable VALUES (?)", ["bar"]) # Correct + >>> cur.execute("INSERT INTO ptable VALUES (:a)", {'a':bar}) # Correct + >>> cur.execute("INSERT INTO ptable VALUES (:a:null)", {'a':None}) # Correct When executing to multiple columns, the rules are more strict:: @@ -118,14 +118,16 @@ When executing to multiple columns, the rules are more strict:: >>> cur.execute("create table ptable(c1 NVARCHAR(128), c2 INTEGER, c3 FLOAT)") # Executing a statement using parametermarkers - >>> cur.execute("INSERT INTO ptable VALUES (?,?,?)", ("bar",314,41.23)) # Correct - >>> cur.execute("INSERT INTO ptable VALUES (?,?,?)", ["bar",314,41.23]) # Correct - >>> cur.execute("INSERT INTO ptable VALUES (?,?,?)", "bar",314,41.23) # Incorrect - >>> cur.execute("INSERT INTO ptable VALUES (:a,:b,:c)", {'a':"bar",'b':314,'c':41.23}) # Correct + >>> cur.execute("INSERT INTO ptable VALUES (?,?,?)", ("bar",314,41.23)) # Correct + >>> cur.execute("INSERT INTO ptable VALUES (?,?,?)", ["bar",314,41.23]) # Correct + >>> cur.execute("INSERT INTO ptable VALUES (?,?,?)", "bar",314,41.23) # Incorrect + >>> cur.execute("INSERT INTO ptable VALUES (:a,:b,:c)", {'a':"bar",'b':314,'c':41.23}) # Correct + >>> cur.execute("INSERT INTO ptable VALUES (:a:null,:b,:c)", {'a':None,'b':314,'c':41.23}) # Correct The same rules apply when using :meth:`~executemany`. For an example, see :ref:`Executemany`. +.. note:: Named parameter markers must specify if null values are to be allowed by adding a ``:null`` after the parameter marker name. For example ``:a:null``. If you do not specify this, the default is ``NOT NULL``. .. Common mistakes .. ------------------------