To get consistent doc comments we should consistently use LuaDoc instead of EmmyDoc.
While EmmyDoc has better editor support in VSCode and IntelliJ, this differs between different VSCode plugins. Additionally it's not possible to generate HTML documentation from EmmyDoc.

That's why we need to migrate all comments to LuaDoc.

Acceptance Criteria

• 1. Consistently use LuaDoc comments
• 2. Update build to generate LuaDoc documentation
• 3. Build must fail for invalid comments
• 4. Publish on github pages: https://exasol.github.io/exasol-driver-lua/api/
• 5. Add link from user guide to API doc

Known issues

Source links to classes in the API doc are broken. This will be fixed in #57

• User guide
• Lua comments
• List of dependencies: #54
• List of features

In order to reduce dependencies we want to replace luasec (used by the Websocket module luws) with luaossl.

See https://keplerproject.github.io/luasql/manual.html

• cur:close(): throw error if closing fails
• env:close(): return boolean
• conn:close(): return boolean
• cur:close(): return boolean

Repeated tests take a long time running, see example log: https://github.com/exasol/exasol-driver-lua/runs/6224913449?check_suite_focus=true

Activate repeated tests and fix the long runtime.

In #23 we added tests for running the driver inside an Exasol UDF. This requires an Exasol 8 docker-db.

See exasol/virtual-schema-common-lua#3 for an example

Some luacheck rules are excluded during static code analysis. Most of these exceptions should be removed to avoid hiding potential bugs.

See comment #70 (comment)

See

• https://github.com/exasol/websocket-api/blob/master/docs/commands/executeV1.md
• https://github.com/exasol/websocket-api/blob/master/docs/commands/fetchV1.md

Instead of returning a helpful error about which TLS option is invalid, the wsopen() function always returns "Failed SSL negotation".

The new version has breaking changes that require migration.
See

• https://luarocks.org/modules/exasol/exaerror/2.0.1-1
• https://github.com/exasol/error-reporting-lua/releases/tag/2.0.1

Automatically maintain list of dependencies incl. licenses and dependency changes.

Source links to classes are broken.

To fix this we need to rename files containing classes to CamelCase. This also includes tests.

Allow specifiying TLS certificate fingerprint

Ensure correct timezone handling for timestamps

Investigate sporadically failing integration tests: https://github.com/exasol/exasol-driver-lua/runs/5445284214?check_suite_focus=true

 Running test ./itest_cursor.lua
# XML output to /home/runner/work/exasol-driver-lua/exasol-driver-lua/target/luaunit-reports/itest_cursor.xml
# Started on Mon Mar  7 08:40:03 2022
# Starting class: TestCursor
# Starting test: TestCursor.test_closing_closed_cursor_succeeds
# Starting test: TestCursor.test_query_fails
# Starting test: TestCursor.test_select_multiple_columns_multiple_rows
#   Error:  ...river-lua/exasol-driver-lua/src/websocket_connection.lua:62: E-EDL-2: Did not receive response for payload. Username or password may be wrong.
# Starting test: TestCursor.test_select_multiple_columns_single_row
#   Error:  ...river-lua/exasol-driver-lua/src/websocket_connection.lua:62: E-EDL-2: Did not receive response for payload. Username or password may be wrong.
# Starting test: TestCursor.test_select_single_column_single_row
# Starting test: TestCursor.test_using_closed_cursor_fails
# Ran 6 tests in 0.239 seconds, 4 successes, 2 errors

To ensure that the driver runs inside an Exasol database we need to add integration tests.

Precondition: Exasol Docker container that includes dependencies.

INTERVAL, GEOMETRY, ...

Currently the method returns nil|table|string as second return value. To simplify the interface, it should only return nil|table.

See #30 (comment)

Upgrade dependencies to latest release.

Blocked by:

• exasol/error-reporting-lua#17
• exasol/remotelog-lua#18
• toggledbits/LuWS#3

Situation

error-reporting-lua recently got a breaking overhaul to improve the object orientation it uses. The driver still uses the old exaerror instead of the new ExaError

Acceptance Criteria

1. Error reporting ported to ExaError.

Version numbers are specified in constants.lua and exasol-driver-lua-0.1.0-1.rockspec. We need to ensure they are equal in order to avoid confusion.

See build https://github.com/exasol/exasol-driver-lua/runs/8174276172?check_suite_focus=true

ERROR: 1 dead links found!
[✖] http://olivinelabs.com/busted/ → Status: 404

Integration tests are instable with older Exasol versions. Upgrade to 7.1.10 to fix these issues.

This requires support in integration-test-docker-environment.

Add missing functions, see https://keplerproject.github.io/luasql/manual.html

• conn:commit(): #41
• conn:rollback(): #42
• conn:setautocommit(boolean): #24
• cur:getcolnames(): #43
• cur:getcoltypes(): #44
• #45

Currently all modules are located in the same namespace. To avoid polluting the global module namespace we need to move all modules to a sub-module, e.g. luasql.exasol.

Fetching data requires specifying a fetch size in bytes.
We need to add an integration test to check what happens when a line does not fit into the given fetch size.
In case this results in an error we need to add appropriate error handling.

In the LuaSQL API, conn:setautocommit(boolean) allows changing autocommit behavior of a connection. Autocommit is on by default for Exasol sessions and can be changed for a websocket connection using setAttributes to set attribute autocommit=true

The Exasol WebSocket API supports prepared statements but the LuaSQL API has no interface for this.

We should extend the Connection class and add support for prepared statements with parameters.

Currently we use lunajson, but lua-cjson is already available in Exasol.

Building lua-cjson on mac fails currently:

% luarocks install lua-cjson                 
Installing https://luarocks.org/lua-cjson-2.1.0.6-1.src.rock

lua-cjson 2.1.0.6-1 depends on lua >= 5.1 (5.4-1 provided by VM)
env MACOSX_DEPLOYMENT_TARGET=10.8 gcc -O2 -fPIC -I/usr/local/opt/lua/include/lua5.4 -c lua_cjson.c -o lua_cjson.o
lua_cjson.c:743:19: error: implicit declaration of function 'lua_objlen' is invalid in C99 [-Werror,-Wimplicit-function-declaration]
            len = lua_objlen(l, -1);
                  ^
1 error generated.

See mpx/lua-cjson#54 for a potential solution.

Root cause: mpx/lua-cjson#56

Workarounds: Install it with flag -DLUA_COMPAT_5_3

luarocks install lua-cjson --local "CFLAGS=-O3 -Wall -pedantic -DNDEBUG -DLUA_COMPAT_5_3"

or pin the version: "lua-cjson == 2.1.0" in rockspec.

Add tests that verify, that the exasol driver API is compatible with the LuaSQL API, e.g. by creating a test that runs the same code with Sqlite and Exasol driver.

Complete requirements tracing

See https://keplerproject.github.io/luasql/manual.html:

cur:fetch([table[,modestring]])
Retrieves the next row of results.
If fetch is called without parameters, the results will be returned directly to the caller. If fetch is called with a table, the results will be copied into the table and the changed table will be returned. In this case, an optional modestring parameter can be used. It is just a string indicating how the resulting table should be constructed. The mode string can contain:

"n"
    the resulting table will have numerical indices (default)
"a"
    the resulting table will have alphanumerical indices 

Currently null values returned from the database are returned to the user as cjson.null which exposes cjson. This should be an internal implementation detail. That's why we need to replace it with a custom value not depending on cjson.

See #30 (comment)

• Specify additional properties (client name, driver name, ...) at login (https://github.com/exasol/websocket-api/blob/master/docs/commands/loginV3.md)
• Allow specifying attributes when connecting to Exasol (https://github.com/exasol/websocket-api/blob/master/docs/WebsocketAPIV3.md#attributes-session-and-database-properties)

Add __close() metamethod to environment, connection and cursor to allow using <close> in Lua 5.4, see https://lwn.net/Articles/826134/ for details.

2023-04-13: This ticket was already solved about a year ago. Closing.

Currently the default TLS options are not secure. We should pick safe defaults that verify the certificate.
See #50 (comment)