Skip to content

Add null-marker documentation to named parameters #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
richardwiden wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add null-marker documentation to named parameters #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4a0cde9
Add name_param:null examples to documentation.
richardwiden Jan 2, 2024
661b0be
Correct indentation in example in docs
richardwiden Jan 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions doc/datatypes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
----------------
Expand All @@ -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)
----------------
Expand All @@ -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
----------
Expand Down
26 changes: 14 additions & 12 deletions doc/userguide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,36 +96,38 @@ 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::

# Creating a table
>>> 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::

# Creating a table
>>> 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
.. ------------------------
Expand Down