From 9f826269c893083ba3482d8aaf87cee7115dd66f Mon Sep 17 00:00:00 2001 From: Elliot Chance Date: Mon, 20 Jun 2022 14:29:54 -0400 Subject: [PATCH] Documentation fixes (#96) - Added a "SQL Compliance" page (that is not yet complete) but it enough to get the ball rolling on fleshing out exactly which features are missing before we can claim a v1.0.0 - Updated the README to be a lot more helpful with quick links. - Fixed some formatting that was previously breaking the build. - Added a "Transactions" and "Installing & Updating" documentation pages. - Added the readthedocs.yaml configuration file which is the recommended way and also cleaned up the existing conf files and pinned the python dependencies (as recommended). --- Makefile | 26 +++- README.md | 34 ++++- cmd/vsql.v | 4 +- docs/appendix.rst | 1 + docs/conf.py | 278 +++--------------------------------- docs/contributing.rst | 27 ++++ docs/custom-functions.rst | 2 +- docs/features.rst | 1 + docs/getting-started.rst | 1 + docs/in-memory-database.rst | 2 +- docs/install.rst | 18 +++ docs/requirements.txt | 3 + docs/select.rst | 2 +- docs/sql-compliance.rst | 259 +++++++++++++++++++++++++++++++++ docs/sqlstate.rst | 6 +- docs/transactions.rst | 40 ++++++ docs/v-module.rst | 2 +- docs/virtual-tables.rst | 2 +- readthedocs.yaml | 17 +++ vsql/.gitignore | 1 - vsql/page.v | 5 +- vsql/virtual_table.v | 2 +- 22 files changed, 453 insertions(+), 280 deletions(-) create mode 100644 docs/install.rst create mode 100644 docs/requirements.txt create mode 100644 docs/sql-compliance.rst create mode 100644 docs/transactions.rst create mode 100644 readthedocs.yaml delete mode 100644 vsql/.gitignore diff --git a/Makefile b/Makefile index 5fb63f9..4e00ddc 100644 --- a/Makefile +++ b/Makefile @@ -1,15 +1,27 @@ -.PHONY: bench bench-on-disk bench-memory fmt fmt-verify test examples vsql grammar sql-test docs +.PHONY: bench bench-on-disk bench-memory fmt fmt-verify test examples vsql grammar sql-test docs clean-docs + +# Is not used at the moment. It is useful for testing options like different +# `-gc` values. +BUILD_OPTIONS = + +# Ideally we compile with "-prod" because it should make the resulting binaries +# faster. However, this has to be disabled for now. +# See https://github.com/elliotchance/vsql/issues/97 +PROD = # -prod # Binaries vsql: - v -prod cmd/vsql.v + v $(BUILD_OPTIONS) $(PROD) cmd/vsql.v # Documentation docs: cd docs && make html +clean-docs: + cd docs && make clean + # Grammar (BNF) grammar: @@ -27,13 +39,13 @@ fmt-verify: # Tests test: - v -stats -prod test vsql + v -stats $(BUILD_OPTIONS) $(PROD) test vsql btree-test: - v -stats -prod test vsql/btree_test.v + v -stats $(BUILD_OPTIONS) $(PROD) test vsql/btree_test.v sql-test: - v -stats test vsql/sql_test.v + v -stats $(BUILD_OPTIONS) $(PROD) test vsql/sql_test.v # Examples @@ -50,7 +62,7 @@ examples/%: bench: bench-on-disk bench-memory bench-on-disk: - v run cmd/vsql.v bench + v run $(PROD) cmd/vsql.v bench bench-memory: - v run cmd/vsql.v bench -file ':memory:' + v run $(PROD) cmd/vsql.v bench -file ':memory:' diff --git a/README.md b/README.md index 7ff59f5..2d238f8 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,31 @@ -vsql -==== +✌️ vsql +====== -vsql is a single-file SQL database written in pure [V](https://vlang.io) with -no dependencies. +vsql is a [single-file](https://vsql.readthedocs.io/en/latest/cli.html) or +[PostgreSQL-server compatible](https://vsql.readthedocs.io/en/latest/server.html), +[transactional](https://vsql.readthedocs.io/en/latest/transaction.html), +[SQL-compliant](https://vsql.readthedocs.io/en/latest/sql-compliance.html) +database written in pure [V](https://vlang.io) with zero dependencies. -View documentation at [vsql.readthedocs.io](https://vsql.readthedocs.io/). +After +[installing or updating](https://vsql.readthedocs.io/en/latest/install.html), +you can use vsql +[within your V applications](https://vsql.readthedocs.io/en/latest/v-module.html), +interact with database files using the +[CLI](https://vsql.readthedocs.io/en/latest/cli.html), or connect to a database +using the +[built-in PostgreSQL-compatible server](https://vsql.readthedocs.io/en/latest/server.html). + +See the full documentation at [vsql.readthedocs.io](https://vsql.readthedocs.io/) +or use one of the quick links: + +- [FAQ](https://vsql.readthedocs.io/en/latest/faq.html) +- [CLI](https://vsql.readthedocs.io/en/latest/cli.html) +- [Supported PostgreSQL clients](https://vsql.readthedocs.io/en/latest/supported-clients.html) +- [Features](https://vsql.readthedocs.io/en/latest/features.html) +- [SQL Reference](https://vsql.readthedocs.io/en/latest/features.html) +- [Contributing](https://vsql.readthedocs.io/en/latest/contributing.html) +- [Data Types](https://vsql.readthedocs.io/en/latest/data-types.html) +- [Functions](https://vsql.readthedocs.io/en/latest/functions.html) +- [SQLSTATE](https://vsql.readthedocs.io/en/latest/sqlstate.html) +- [SQL Compliance](https://vsql.readthedocs.io/en/latest/sql-compliance.html) diff --git a/cmd/vsql.v b/cmd/vsql.v index f41ad5a..57941ae 100644 --- a/cmd/vsql.v +++ b/cmd/vsql.v @@ -63,12 +63,12 @@ fn cli_command(cmd cli.Command) ? { print_version() mut db := vsql.open(cmd.args[0])? - + for { print('vsql> ') query := os.get_line() - if query != "" { + if query != '' { start := time.ticks() result := db.query(query)? for row in result { diff --git a/docs/appendix.rst b/docs/appendix.rst index cfedd85..34a30a4 100644 --- a/docs/appendix.rst +++ b/docs/appendix.rst @@ -9,4 +9,5 @@ Appendix functions.rst keywords.rst operators.rst + sql-compliance.rst sqlstate.rst diff --git a/docs/conf.py b/docs/conf.py index 05e1d8a..28998d6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,284 +1,52 @@ -# -*- coding: utf-8 -*- +# Configuration file for the Sphinx documentation builder. # -# vsql documentation build configuration file, created by -# sphinx-quickstart on Sun Oct 10 10:59:01 2021. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html -import sys -import os -import shlex +# -- Path setup -------------------------------------------------------------- # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + -# -- General configuration ------------------------------------------------ +# -- Project information ----------------------------------------------------- -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' +project = 'vsql' +copyright = '2022, Elliot Chance' +author = 'Elliot Chance' + + +# -- General configuration --------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = [] +extensions = [ +] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# source_suffix = ['.rst', '.md'] -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'vsql' -copyright = u'2021, Elliot Chance' -author = u'Elliot Chance' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = 'latest' -# The full version, including alpha/beta/rc tags. -release = 'latest' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['_build'] - -# The reST default role (used for this markup: `text`) to use for all -# documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - -# If true, keep warnings as "system message" paragraphs in the built documents. -#keep_warnings = False - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = False - - -# -- Options for HTML output ---------------------------------------------- +# -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. +# html_theme = 'sphinx_rtd_theme' -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] - -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -#html_extra_path = [] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Language to be used for generating the HTML full-text search index. -# Sphinx supports the following languages: -# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' -#html_search_language = 'en' - -# A dictionary with options for the search language support, empty by default. -# Now only 'ja' uses this config value -#html_search_options = {'type': 'default'} - -# The name of a javascript file (relative to the configuration directory) that -# implements a search results scorer. If empty, the default will be used. -#html_search_scorer = 'scorer.js' - -# Output file base name for HTML help builder. -htmlhelp_basename = 'vsqldoc' - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', - -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', - -# Additional stuff for the LaTeX preamble. -#'preamble': '', - -# Latex figure (float) alignment -#'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, 'vsql.tex', u'vsql Documentation', - u'Elliot Chance', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'vsql', u'vsql Documentation', - [author], 1) -] - -# If true, show URL addresses after external links. -#man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - (master_doc, 'vsql', u'vsql Documentation', - author, 'vsql', 'One line description of project.', - 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' - -# If true, do not generate a @detailmenu in the "Top" node's menu. -#texinfo_no_detailmenu = False diff --git a/docs/contributing.rst b/docs/contributing.rst index 837cfc5..fece0b7 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -22,6 +22,33 @@ by using the ``lldb`` debugger: v examples/memory.v && lldb -o run examples/memory +Documentation +------------- + +Documentation is built and published automatically at +`vsql.readthedocs.com `_. + +You can generate the documentation locally with: + +.. code-block:: sh + + make docs + +If you receive an error, you might be missing some dependencies: + +.. code-block:: sh + + pip3 install sphinx + cd docs && python3 -m pip install -r requirements.txt + pip3 install sphinx_rtd_theme + +``make docs`` will only regenerate the parts that it thinks have changed. To +rebuild the entire docs you can use: + +.. code-block:: sh + + make clean-docs docs + Parser & SQL Grammar -------------------- diff --git a/docs/custom-functions.rst b/docs/custom-functions.rst index 8319f45..fddad78 100644 --- a/docs/custom-functions.rst +++ b/docs/custom-functions.rst @@ -3,7 +3,7 @@ Custom Functions You can create custom functions to use in expressions: -.. code-block:: v +.. code-block:: text // no_pennies will round to 0.05 denominations. db.register_function('no_pennies(float) float', fn (a []vsql.Value) ?vsql.Value { diff --git a/docs/features.rst b/docs/features.rst index 858843a..3c8ebba 100644 --- a/docs/features.rst +++ b/docs/features.rst @@ -8,4 +8,5 @@ Features in-memory-database.rst prepared-statements.rst server.rst + transactions.rst virtual-tables.rst diff --git a/docs/getting-started.rst b/docs/getting-started.rst index 4dc7925..6d8906c 100644 --- a/docs/getting-started.rst +++ b/docs/getting-started.rst @@ -4,6 +4,7 @@ Getting Started .. toctree:: :maxdepth: 1 + install.rst faq.rst v-module.rst cli.rst diff --git a/docs/in-memory-database.rst b/docs/in-memory-database.rst index 3be0e43..3ec0bcb 100644 --- a/docs/in-memory-database.rst +++ b/docs/in-memory-database.rst @@ -4,6 +4,6 @@ In Memory Database Opening a database with the special file name ":memory:" will use an entirely in-memory database: -.. code-block:: v +.. code-block:: text mut db := vsql.open(':memory:') ? diff --git a/docs/install.rst b/docs/install.rst new file mode 100644 index 0000000..582b990 --- /dev/null +++ b/docs/install.rst @@ -0,0 +1,18 @@ +Installing & Updating +===================== + +vsql can be installed or updated using [V](https://vlang.io): + +``` +v install elliotchance.vsql +``` + +Or, if you don't have V installed you can also download standalone binaries from +the [Releases](https://github.com/elliotchance/vsql/releases) page. + +See Also +-------- + +- :doc:`cli` +- :doc:`contributing` +- :doc:`v-module` diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..9d1272d --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +sphinx==4.2.0 +sphinx_rtd_theme==1.0.0 +readthedocs-sphinx-search==0.1.1 diff --git a/docs/select.rst b/docs/select.rst index 420364c..84e9750 100644 --- a/docs/select.rst +++ b/docs/select.rst @@ -52,7 +52,7 @@ Otherwise, aggregation expressions are calculated from each set defined by the SELECT city, AVG(price) FROM products GROUP BY city; -See full list of :doc:`functions`. +See full list of :doc:`functions`. ORDER BY -------- diff --git a/docs/sql-compliance.rst b/docs/sql-compliance.rst new file mode 100644 index 0000000..a80a251 --- /dev/null +++ b/docs/sql-compliance.rst @@ -0,0 +1,259 @@ +SQL Compliance +============== + +.. contents:: + +vsql aims to be SQL compliant by following the 2016 SQL Standard in both BNF +syntax and mandatory features. + +There are still many features to be implemented before it can be considered +fully compliant - as shown by the Mandatory Features table below. + +Mandatory Features +------------------ + +The following table is **not complete** and will be filled in as time goes on. + +.. list-table:: Table 43 — Feature taxonomy and definition for mandatory features + :header-rows: 1 + + * - Feature ID + - Supported + - Feature Name + + * - **E011** + - **Partial** + - **Numeric data types** + + * - E011-01 + - Yes + - ``INTEGER`` and ``SMALLINT`` data types (including all spellings) + + * - E011-02 + - Yes + - ``REAL``, ``DOUBLE PRECISON``, and ``FLOAT`` data types + + * - E011-03 + - No + - ``DECIMAL`` and ``NUMERIC`` data types + + * - E011-04 + - Yes + - Arithmetic operators + + * - E011-05 + - Yes + - Numeric comparison + + * - E011-06 + - No + - Implicit casting among the numeric data types + + * - **E021** + - **Partial** + - **Character string types** + + * - E021-01 + - Yes + - ``CHARACTER`` data type (including all its spellings) + + * - E021-02 + - Yes + - ``CHARACTER VARYING`` data type (including all its spellings) + + * - E021-03 + - Yes + - Character literals + + * - E021-04 + - Yes + - ``CHARACTER_LENGTH`` function + + * - E021-05 + - Yes + - ``OCTET_LENGTH`` function + + * - E021-06 + - No + - ``SUBSTRING`` function + + * - E021-07 + - Yes + - Character concatenation + + * - E021-08 + - Yes + - ``UPPER`` and ``LOWER`` functions + + * - E021-09 + - No + - ``TRIM`` function + + * - E021-10 + - No + - Implicit casting among the fixed-length and variable-length character string types + + * - E021-11 + - Yes + - ``POSITION`` function + + * - E021-12 + - Partial + - Character comparison + + * - **E031** + - **Unknown** + - **Identifiers** + + * - **E051** + - **Unknown** + - **Basic query specification** + + * - **E061** + - **Unknown** + - **Basic predicates and search conditions** + + * - **E071** + - **Unknown** + - **Basic query expressions** + + * - **E081** + - **Unknown** + - **Basic Privileges** + + * - **E091** + - **Unknown** + - **Set functions** + + * - **E071** + - **Unknown** + - **Basic query expressions** + + * - **E101** + - **Unknown** + - **Basic data manipulation** + + * - **E111** + - **Unknown** + - **Single row SELECT statement** + + * - **E121** + - **Unknown** + - **Basic cursor support** + + * - **E131** + - **Unknown** + - **Null value support (nulls in lieu of values)** + + * - **E141** + - **Unknown** + - **Basic integrity constraints** + + * - **E151** + - **Unknown** + - **Transaction support** + + * - **E152** + - **Unknown** + - **Basic SET TRANSACTION statement** + + * - **E153** + - **Unknown** + - **Updatable queries with subqueries** + + * - **E161** + - **Unknown** + - **SQL comments using leading double minus** + + * - **E171** + - **Unknown** + - **SQLSTATE support** + + * - **E182** + - **Unknown** + - **Host language binding** + + * - **F031** + - **Unknown** + - **Basic schema manipulation** + + * - **F041** + - **Unknown** + - **Basic joined table** + + * - **F051** + - **Unknown** + - **Basic date and time** + + * - **F081** + - **Unknown** + - **UNION and EXCEPT in views** + + * - **F131** + - **Unknown** + - **Grouped operations** + + * - **F181** + - **Unknown** + - **Multiple module support** + + * - **F201** + - **Unknown** + - **CAST function** + + * - **F221** + - **Unknown** + - **Explicit defaults** + + * - **F261** + - **Unknown** + - **CASE expression** + + * - **F311** + - **Unknown** + - **Schema definition statement** + + * - **F471** + - **Unknown** + - **Scalar subquery values** + + * - **F481** + - **Unknown** + - **Expanded NULL predicate** + + * - **F812** + - **Unknown** + - **Basic flagging** + + * - **S011** + - **Unknown** + - **Distinct data types** + + * - **T321** + - **Unknown** + - **Basic SQL-invoked routines** + + * - **T631** + - **Unknown** + - **IN predicate with one list element** + +Optional Features +----------------- + +The following table has not been filled in. It is here as a placeholder. + +.. list-table:: Table 44 — Feature taxonomy for optional features + :header-rows: 1 + + * - Feature ID + - Supported + - Feature Name + + * - **B011** + - No + - **Embedded Ada** + +See Also +-------- + +- https://en.wikipedia.org/wiki/SQL_compliance diff --git a/docs/sqlstate.rst b/docs/sqlstate.rst index 8ce57e5..28b2c8f 100644 --- a/docs/sqlstate.rst +++ b/docs/sqlstate.rst @@ -14,7 +14,7 @@ for struct definitions. You can match on these to inspect the error further: -.. code-block:: v +.. code-block:: text db.query('SELECT * FROM bar') or { match err { @@ -27,7 +27,7 @@ You can match on these to inspect the error further: The ``err.code()`` contains the integer representation of the SQLSTATE: -.. code-block:: v +.. code-block:: text db.query('SELECT * FROM bar') or { sqlstate := vsql.sqlstate_from_int(err.code()) @@ -41,7 +41,7 @@ The ``err.code()`` contains the integer representation of the SQLSTATE: Or handling errors by class (first two letters): -.. code-block:: v +.. code-block:: text db.query('SELECT * FROM bar') or { if err.code() >= vsql.sqlstate_to_int('42000') && diff --git a/docs/transactions.rst b/docs/transactions.rst new file mode 100644 index 0000000..8448f68 --- /dev/null +++ b/docs/transactions.rst @@ -0,0 +1,40 @@ +Transactions +============ + +vsql supports transactions through the :doc:`start-transaction`, :doc:`commit` +and :doc:`rollback` statements. + +Internally, transactions use :doc:`mvcc` that allow multiple connections to both +read and write to the database at the same time. This is different from SQLite +which serializes all transactions by having a write transaction have an +exclusive write lock on the file until it is comitted or rolled back. + +Examples +-------- + +.. code-block:: sql + + -- From connection 1: + START TRANSACTION; + + INSERT INTO products (name, price) + VALUES ('Coffee Machine', 150); + + -- From connection 2: + SELECT * FROM products; + -- empty + + -- From connection 1: + COMMIT; + + -- From connection 2: + SELECT * FROM products; + -- NAME: Coffee Machine PRICE: 150 + +See Also +-------- + +- :doc:`commit` +- :doc:`mvcc` +- :doc:`rollback` +- :doc:`start-transaction` diff --git a/docs/v-module.rst b/docs/v-module.rst index 9629729..19528b1 100644 --- a/docs/v-module.rst +++ b/docs/v-module.rst @@ -7,7 +7,7 @@ Install or update to the latest with: v install elliotchance.vsql -.. code-block:: v +.. code-block:: text import elliotchance.vsql.vsql diff --git a/docs/virtual-tables.rst b/docs/virtual-tables.rst index 12e12e4..e87f8bf 100644 --- a/docs/virtual-tables.rst +++ b/docs/virtual-tables.rst @@ -4,7 +4,7 @@ Virtual Tables Virtual tables allow you to register tables that have their rows provided at the time of a ``SELECT``: -.. code-block:: v +.. code-block:: text db.register_virtual_table( 'CREATE TABLE foo ( "num" INT, word VARCHAR (32) )', diff --git a/readthedocs.yaml b/readthedocs.yaml new file mode 100644 index 0000000..1006cd5 --- /dev/null +++ b/readthedocs.yaml @@ -0,0 +1,17 @@ +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +version: 2 + +build: + os: ubuntu-20.04 + tools: + python: "3.9" + +sphinx: + configuration: docs/conf.py + fail_on_warning: true + +python: + install: + - requirements: docs/requirements.txt diff --git a/vsql/.gitignore b/vsql/.gitignore deleted file mode 100644 index e43b0f9..0000000 --- a/vsql/.gitignore +++ /dev/null @@ -1 +0,0 @@ -.DS_Store diff --git a/vsql/page.v b/vsql/page.v index 3323af3..19a5a56 100644 --- a/vsql/page.v +++ b/vsql/page.v @@ -12,7 +12,10 @@ const ( // combination of all fixed width meta for the page object. const page_object_prefix_length = 14 -struct PageObject { +// TODO(elliotchance): This does not need to be public. It was required for a +// bug at the time with V not being able to pass this to the shuffle function. +// At some point in the future remove the pub and see if it works. +pub struct PageObject { // The key is not required to be unique in the page. It becomes unique when // combined with tid. However, no more than two version of the same key can // exist in a page. See the caveats at the top of btree.v. diff --git a/vsql/virtual_table.v b/vsql/virtual_table.v index 66e2051..b9a0977 100644 --- a/vsql/virtual_table.v +++ b/vsql/virtual_table.v @@ -2,7 +2,7 @@ module vsql type VirtualTableProviderFn = fn (mut t VirtualTable) ? -struct VirtualTable { +pub struct VirtualTable { create_table_sql string create_table_stmt CreateTableStmt data VirtualTableProviderFn