Documentation Source Text

<title>The Use Of assert() In SQLite</title>

<table_of_contents>

<h1 style="color:red;">Work In Progress - Do Not Link!</h1>
<p style="color:red;font-size:150%;">
This document is a work-in-progress and is not yet ready for release.
Please do not link to it, yet.
</p>

<h1>Assert() And Other Assert()-like Macros In SQLite</h1>

<p>
The assert(X) macro is 
[https://en.wikipedia.org/wiki/Assert.h|part of standard C], in the the
&lt;assert.h&gt; header file.
SQLite adds three other assert()-like macros named NEVER(X), ALWAYS(X),
and testcase(X).

<ul>
<li><p><b>assert(X)</b> &rarr;
The assert(X) statement indicates that the condition X is always true.
In other words, X is an invariant.  The assert(X) macro works like a
procedure in that it has no return value.

<li><p><b>ALWAYS(X)</b> &rarr;
The ALWAYS(X) function indicates that condition X is always true as far
as the developers know, but there is not proof the X is true, or the
proof is complex and error-prone, or the proof depends on implementation
details that are likely to change in the future.  ALWAYS(X) behaves like
a function that returns the boolean value X, and is intended to be used
within the conditional of an "if" statement.

<li><p><b>NEVER(X)</b> &rarr;
The NEVER(X) function indicates that condition X is never true.  This
is the negative analog of the ALWAYS(X) function.

<li><p><b>testcase(X)</b> &rarr;
The testcase(X) statement indicates that X is sometimes true and sometimes
false.  In other words, testcase(X) indicates that X is definitely not an
invariant.  Since SQLite uses 100% [MC/DC testing], the presence of a
testcase(X) macro indicates that not only is it possible for X to be either
true or false, but there are test cases to demonstrate this.
</ul>

<p>
SQLite version 3.22.0 ([dateof:3.22.0]) contains 5290 assert() macros,
839 testcase() macros, 88 ALWAYS() macros, and 63 NEVER() macros.

<h2>Philosophy of assert()</h2>

<p>In SQLite, the presence of assert(X) means that the developers have
a proof that X is always true.  Readers can depend upon X being true to
help them reason about the code.  An assert(X) is a strong statement
about the truth of X.  There is no doubt.

<p>The ALWAYS(X) and NEVER(X) macros are a weaker statement about the
truth of X.  The presence of ALWAYS(X) or NEVER(X) means that the developers
believe X is always or never true, but there is no proof, or the proof
is complex and error-prone, or the proof depends on other aspects 
of the system that seem likely to change.

<p>In other systems, developers sometimes use assert(X) in a way that is
similar to the use of ALWAYS(X) in SQLite.  Developers will add an
assert(X) as a 
[https://blog.regehr.org/archives/1576|tacit acknowledgement that they
do not fully believe that X is always true].
We believe that this use of assert(X) is wrong and violates the intent
and purpose of having assert(X) available in C in the first place.
An assert(X) should not be seen as a safety-net or top-rope used to
guard against mistakes.  Nor is assert(X) appropriate for defense-in-depth.
An ALWAYS(X) macro, or something similar, should be used in those cases
because ALWAYS(X) is followed by code to actually deal with the problem.

<p>The [https://golang.org|Go programming language] omits assert().
The Go developers
[https://golang.org/doc/faq#assertions|recognize this is contentious].
Disallowing assert() is essentially telling developers that they are
not allowed to expression invariants.  It is as if the developers of
Go do not want coders to prove that the software is correct.
The SQLite developers believe that the lack of assert() disqualifies
Go as a language for serious development work.

<h2>Different Behaviors According To Build Type</h2>

<p>Three separate builds are used to validate the SQLite software.
A functionality testing build is used to validate the source code.
A coverage testing build is used to validate the test suite, to confirm
that the test suite provides 100% MC/DC.  The release build is used
to validate the machine code.  
All tests must give the same answer in all three
builds. See the [testing|"How SQLite Is Tested"] document for more detail.

<p>The assert() macros behave differently according to how SQLite is built.

<center>
<table border=1>
<tr><th><th>Functionality Testing<th>Coverage Testing<th>Release</tr>
<tr><th valign="top">assert(X)
<td>abort() if X is false
<td>no-op
<td>no-op
</tr>
<tr><th valign="top">ALWAYS(X)
<td>abort() if X is false
<td>always true
<td>pass through the value X
</tr>
<tr><th valign="top">NEVER(X)
<td>abort() if X is true
<td>always false
<td>pass through the value X
</tr>
<tr><th valign="top">testcase(X)
<td>no-op
<td>do some harmless work if X is true
<td>no-op
</tr>
</table>
</center>

<p>The default behavior of assert(X) in standard C is that it is enabled
for release builds.  We find this acceptable in general.  However, the
SQLite code base has many assert() statements in performance-sensitive
areas of the code.  Leaving assert(X) turned causes SQLite to run about
three times slower.  Also, SQLite strives to provide 100% MC/DC in an
as-delivered configuration, which is obviously impossible if assert(X)
statements are enabled.  For these reasons, assert(X) is a no-op for
release builds in SQLite.

<title>Code Of Conduct</title>

<fancy_format>

<h1>Overview</h1>

<p>The code of conduct for developers of the SQLite 
project is the 72 "instruments of good works" from the 6th century
[https://en.wikipedia.org/wiki/Rule_of_Saint_Benedict|Rule of St. Benedict],
shown below.
This code of conduct has proven its mettle in use by many thousands of
communities for 1,500 years, and has served as a baseline for many civil
law codes since the time of Charlemagne.

<p>
The SQLite developers are not monks.
None are able to adhere perfectly to this code of conduct.
All will fall short.  The goal of this code of conduct is
not to describe the minimum acceptable behavior below which
none transgress,
but rather to describe the highest standard of behavior
to which all aspire.
We grant grace to one another and request forgiveness and
promise to amend our ways when we stumble.

<p>
This code of conduct applies to the SQLite developers only.
Everyone is free to use the SQLite source code, object code,
and/or documentation without having to agree
with the behavioral standards outlined below.
You are encouraged to follow these standards as
in doing so you will live a happier, healthier, and more
productive life.
Nevertheless, this is a choice that you must make for yourself,
and is not a precondition for using SQLite.

<h1>The Code</h1>

<ol>
<li> First of all, love the Lord God with your whole heart,
     your whole soul, and your whole strength.
<li> Then, love your neighbor as yourself.
<li> Do not murder.
<li> Do not commit adultery.
<li> Do not steal.
<li> Do not covet.
<li> Do not bear false witness.
<li> Honor all (1 Peter 2:17).
<li> Do not do to another what you would not have done to yourself.
<li> Deny oneself in order to follow Christ.
<li> Chastise the body.
<li> Do not become attached to pleasures.
<li> Love fasting.
<li> Relieve the poor.
<li> Clothe the naked.
<li> Visit the sick.
<li> Bury the dead.
<li> Be a help in times of trouble.
<li> Console the sorrowing.
<li> Be a stranger to the world's ways.
<li> Prefer nothing more than the love of Christ.
<li> Do not give way to anger.
<li> Do not nurse a grudge.
<li> Do not entertain deceit in your heart.
<li> Do not give a false peace.
<li> Do not forsake charity.
<li> Do not swear, for fear of perjuring yourself.
<li> Utter only truth from heart and mouth.
<li> Do not return evil for evil.
<li> Do no wrong to anyone, and bear patiently wrongs done to yourself.
<li> Love your enemies.
<li> Do not curse those who curse you, but rather bless them.
<li> Bear persecution for justice's sake.
<li> Be not proud.
<li> Be not addicted to wine.
<li> Be not a great eater.
<li> Be not drowsy.
<li> Be not lazy.
<li> Be not a grumbler.
<li> Be not a detractor.
<li> Put your hope in God.
<li> Attribute to God, and not to self, whatever good you see in yourself.
<li> Recognize always that evil is your own doing,
     and to impute it to yourself.
<li> Fear the Day of Judgment.
<li> Be in dread of hell.
<li> Desire eternal life with all the passion of the spirit.
<li> Keep death daily before your eyes.
<li> Keep constant guard over the actions of your life.
<li> Know for certain that God sees you everywhere.
<li> When wrongful thoughts come into your heart, dash them against
     Christ immediately.
<li> Disclose wrongful thoughts to your spiritual mentor.
<li> Guard your tongue against evil and depraved speech.
<li> Do not love much talking.
<li> Speak no useless words or words that move to laughter.
<li> Do not love much or boisterous laughter.
<li> Listen willingly to holy reading.
<li> Devote yourself frequently to prayer.
<li> Daily in your prayers, with tears and sighs, confess your
     past sins to God, and amend them for the future.
<li> Fulfill not the desires of the flesh; hate your own will.
<li> Obey in all things the commands of those whom God has placed
     in authority over you even though they (which God forbid) should 
     act otherwise, mindful of the Lord's precept, "Do what they say, 
     but not what they do."
<li> Do not wish to be called holy before one is holy; but first to be
     holy, that you may be truly so called.
<li> Fulfill God's commandments daily in your deeds.
<li> Love chastity.
<li> Hate no one.
<li> Be not jealous, nor harbor envy.
<li> Do not love quarreling.
<li> Shun arrogance.
<li> Respect your seniors.
<li> Love your juniors.
<li> Pray for your enemies in the love of Christ.
<li> Make peace with your adversary before the sun sets.
<li> Never despair of God's mercy.
</ol>

No code has been taken from other projects or from the open
internet.  Every line of code can be traced back to its original
author, and all of those authors have public domain dedications
on file.  So the SQLite code base is clean and is
uncontaminated with licensed code from other projects.
</p>































<div class="rightsidebar">
<form method="GET" action="https://www.hwaci.com/cgi-bin/license-step1">
<input type="submit" value="Buy An SQLite License">
</form>
</div>

<h2>Obtaining A License To Use SQLite</h2>

<p>
Even though SQLite is in the public domain and does not require
a license, some users want to obtain a license anyway.  Some reasons
for obtaining a license include:
</p>

<ul>
<li> Your company desires warranty of title and/or
     indemnity against claims of copyright infringement.
<li> You are using SQLite in a jurisdiction that does not recognize
     the public domain.  </li>
<li> You are using SQLite in a jurisdiction that does not recognize
     the right of an author to dedicate their work to the public
     domain. </li>
<li> You want to hold a tangible legal document
     as evidence that you have the legal right to use and distribute
     SQLite. </li>
<li> Your legal department tells you that you have to purchase a license.
     </li>
</ul>

<p>
If you feel like you really need to purchase a license for SQLite,
<a href="https://www.hwaci.com/">Hwaci</a>, the company that employs 
all the developers of SQLite, will 
<a href="https://www.hwaci.com/cgi-bin/license-step1">sell you
one</a>.




All proceeds from the sale of SQLite licenses are used to fund
continuing improvement and support of SQLite.
</p>

<h2>Contributed Code</h2>

<p>
In order to keep SQLite completely free and unencumbered by copyright,
all new contributors to the SQLite code base are asked to dedicate
their contributions to the public domain.
If you want to send a patch or enhancement for possible inclusion in the
SQLite source tree, please accompany the patch with the following statement:
</p>

<blockquote><i>
The author or authors of this code dedicate any and all copyright interest
in this code to the public domain.  We make this dedication for the benefit
of the public at large and to the detriment of our heirs and successors.
We intend this dedication to be an overt act of relinquishment in
perpetuity of all present and future rights to this code under copyright law.
</i></blockquote>

<p>
We are not able to accept patches or changes to 
SQLite that are not accompanied by a statement such as the above.
In addition, if you make
changes or enhancements as an employee, then a simple statement such as the
above is insufficient.  You must also send by surface mail a copyright release
signed by a company officer.
A signed original of the copyright release should be mailed to:</p>

<blockquote>
Hwaci<br>
6200 Maple Cove Lane<br>
Charlotte, NC 28269<br>
USA
</blockquote>

<p>
A template copyright release is available
in <a href="copyright-release.pdf">PDF</a> or
<a href="copyright-release.html">HTML</a>.
You can use this release to make future changes. 
</p>

No code has been taken from other projects or from the open
internet.  Every line of code can be traced back to its original
author, and all of those authors have public domain dedications
on file.  So the SQLite code base is clean and is
uncontaminated with licensed code from other projects.
</p>

<tcl>hd_fragment notopencontrib {not open-contributin}</tcl>
<h2>Open-Source, not Open-Contribution</h2>

<p>
SQLite is open-source, meaning that you can make as many copies of it as
you want and do whatever you want with those copies, without limitation.
But SQLite is not open-contribution.  The project does not accept patches.
Only 27 individuals have ever contributed any code to SQLite, and of those
only 16 still have traces in the latest release.  
Only 3 developers have contributed
non-comment changes within the previous five years and 96.4% of the latest
release code was written by just two people.
(The statistics in this paragraph were gathered on 2018-02-05.)

<p>
Furthermore, all of the code in SQLite is original, having been written
specifically for use by SQLite.  No code has been copied from unknown
sources on the internet.

<p>
Many people associated "open-source" software with software that has
grown organically through contributions from countless individuals.
And, indeed, there is some open-source software that works that way.
But not SQLite.  SQLite uses the the
[https://en.wikipedia.org/wiki/The_Cathedral_and_the_Bazaar|cathedral development philosopy]
not the bazaar approach.  All of the SQLite code has been written
by people who are well known to each other.

<tcl>hd_fragment warrantyoftitle {Warranty of Title}</tcl>

<div class="rightsidebar">
<form method="GET" action="https://www.hwaci.com/cgi-bin/license-step1">
<input type="submit" value="Buy An SQLite License">
</form>
</div>

<h2>Warranty of Title</h2>

<p>
SQLite is in the public domain and does not require a license.
Even so, some organizations want legal proof of their right to use
SQLite.  Circumstances where this occurs include the following:
</p>

<ul>

<li> Your company desires indemnity against claims of copyright infringement.
<li> You are using SQLite in a jurisdiction that does not recognize
     the public domain.  </li>
<li> You are using SQLite in a jurisdiction that does not recognize
     the right of an author to dedicate their work to the public
     domain. </li>
<li> You want to hold a tangible legal document
     as evidence that you have the legal right to use and distribute
     SQLite. </li>
<li> Your legal department tells you that you have to purchase a license.
     </li>
</ul>

<p>
If any of the above circumstances apply to you,
<a href="https://www.hwaci.com/">Hwaci</a>, the company that employs 
all the developers of SQLite, will 
<a href="https://www.hwaci.com/cgi-bin/license-step1">sell you
a Warranty of Title for SQLite</a>.
A Warranty of Title is a legal document that asserts that the claimed
authors of SQLite are the true authors, and that the authors 
have the legal right to dedicate the SQLite to the public domain, and 
that Hwaci will vigorously defend against challenges to those claims.
All proceeds from the sale of SQLite Warranties of Title are used to fund
continuing improvement and support of SQLite.
</p>

<h2>Contributed Code</h2>

<p>
In order to keep SQLite completely free and unencumbered by copyright,
the project does not accept patches.  If you would like to make a
suggested change, and include a patch as a proof-of-concept, that would
be great.  However please do not be offended if we rewrite your patch
from scratch.

<codeblock>
   SELECT * FROM dbstat;
</codeblock>

<p>A virtual table is eponymous if its [xCreate] method is the exact same
function as the [xConnect] method, or if the [xCreate] method is NULL.
The [xCreate] method is called when a virtual table is first created
using the [CREATE VIRTUAL TABLE] statement.  The [xConnect] method whenever

a database connection attaches to or reparses a schema. When these two methods
are the same, that indicates that the virtual table has no persistent
state that needs to be created and destroyed.

<tcl>hd_fragment epoonlyvtab {eponymous-only virtual table}</tcl>
<h3>Eponymous-only virtual tables</h3>
<p>If the [xCreate] method is NULL, then

<codeblock>
   SELECT * FROM dbstat;
</codeblock>

<p>A virtual table is eponymous if its [xCreate] method is the exact same
function as the [xConnect] method, or if the [xCreate] method is NULL.
The [xCreate] method is called when a virtual table is first created
using the [CREATE VIRTUAL TABLE] statement.  The [xConnect] method 
is invoked whenever
a database connection attaches to or reparses a schema. When these two methods
are the same, that indicates that the virtual table has no persistent
state that needs to be created and destroyed.

<tcl>hd_fragment epoonlyvtab {eponymous-only virtual table}</tcl>
<h3>Eponymous-only virtual tables</h3>
<p>If the [xCreate] method is NULL, then