Installation (Windows)

RSQL has been successfully compiled and runs on Windows.
However, it has not been as fully tested as the Linux version for the moment.

The server program is just one single executable binary file. There are no external dependencies. The client program is also just one single executable binary file.

The installation procedure is quite straightforward, and you can customize it at your convenience.

If You Want to Quickly Try the Program

For demonstration purpose, you can quickly install the program in your home directory. Just do the following:

You can append the path to the executables to your PATH environment variable if you want.

Then, open a Windows console in your home directory.

You will now create an instance directory and initialize it (replace C:/your/home_directory by the absolute path to your home directory).
You must initialize (-install flag) the instance directory only once.
Note that instead of rsql1, you can choose any other name for the instance directory.

> mkdir rsql1
> .\rsql_server -install -dir=C:/your/home_directory/rsql1 -server_default_collation=en_ci_ai -server_default_language=en_us

You can now run the server:

> .\rsql_server -dir=C:/your/home_directory/rsql1

The server is now waiting for connections.

To stop the server, just type ctrl-c. The server stops abruptly (no corruption will occur as the server has journal files).

To restart it, just type again:

> .\rsql_server -dir=C:/your/home_directory/rsql1

Open a new terminal, and send a query with the client program (at installation, the default password for sa is changeme):

> .\rcli -U=sa -P=changeme -Q="print 'Hello';"

To avoid typing the login and password, create a client configuration file named rcli.conf in your home directory, and containing the text below:

# usually, the name of this file is rcli.conf, located in the user's home directory

# this is the configuration file of the command line rsql client, "rcli", in TOML format.
# for TOML, see https://github.com/toml-lang/toml

[remote_server]
    address            = "127.0.0.1:7777"     # ip and port

[login]
    login_name         = "sa"                 # login name
    password           = "changeme"           # password for the login
    # default_database   = "trashdb"            # force the default database for connection. Else, the default database for the login is used.

[presentation]
    file_encoding      = "utf-8"              # encoding of input file
    null_string        = "NULL"               # string displayed by SELECT for NULL values
    width_limit        = 30                   # column width for displaying VARBINARY and VARCHAR
    fractional_second  = 3                    # number of fractional second digits, for displaying TIME and DATETIME
    print_mode         = 0                    # PRINT mode for multiple values. 0: normal mode, 1: column aligned
    error_level        = 0                    # level of details displayed when error is printed. 0, 1, 2
    error_wrap         = true                 # if true, error message is printed on a new line
    color              = false                # if true, error message is printed in color (Linux only)

[internal]
    keepalive_interval = 20                   # keepalive messages are sent to the server at this rate, in seconds. By default, 20 seconds.

You can now just type:

> .\rcli -Q="print 'Hello again';"

Create a new database:

> .\rcli -Q="create database mytest"

You can send SQL scripts by just passing the file name as argument:

> .\rcli my_batch_file.sql

For example, you can run the sample SQL scripts in the rsql_mytestdb_scripts directory:

> .\rcli rsql_mytestdb_scripts/mytest_country_create.sql
> .\rcli rsql_mytestdb_scripts/mytest_country_fill.sql
> .\rcli -Q="select * from mytest..country"

More info on rcli flags:

> .\rcli -h

In particular, the -width= flag is useful to display VARCHAR columns of SELECT statement in larger columns if strings are truncated (default width is 30).

Here is the info page on RSQL client rcli.

To continue, please read these documents:

If you want to make a serious installation, with the server running as a service, you should follow the whole procedure below.

Installation of Server and Client Executable Binaries

Create a directory named rsql in the directory containing the programs installed in your computer (usually, it is C:\Program Files, C:\Program, C:\Programme or other similar name).

Go to the Download page.

Download the latest available version of RSQL Server rsql-VERSION-windows_amd64.zip and decompress it.

This zip file contains the server and the client executable:

Copy these three executable files into the directory C:\Program Files\rsql you have created.

You can rename rsql/bin/rcli-VERSION-windows_amd64.exe to rsql/bin/rcli.exe if you want, and rsql/bin/rsqlctl-VERSION-windows_amd64.exe to rsql/bin/rsqlctl.exe.

Check the server version:

> "C:\Program Files\rsql\rsql_server-VERSION-windows_amd64.exe" -version
rsql server: version 0.6

Create the Instance Base Directory

This directory will contain all the database files.

This directory can be created in any location and have any name, e.g. rsql1.

So, you can e.g. create the directory C:/rsql1.

Initialize the Instance Base Directory

Now, we must initialize this directory.

The command rsql_server-VERSION-windows_amd64 -install will create several directories under the base directory, and initialize the master data dictionary (master.db file) containing the description of all instance objects (server parameters, logins, users, databases, tables, etc).

The following options are mandatory for installation:

The following command will initialize the instance base directory with english collation and language.

> "c:\Program Files\rsql\rsql_server-VERSION-windows_amd64" -install -dir=C:/rsql1 -server_default_collation=en_ci_ai -server_default_language=en_us

Run RSQL Server

Now, we run the server in a Windows console. Later, we will run it as a service.

As instance user rsql1, type the following command:

> "c:\Program Files\rsql\rsql_server-VERSION-windows_amd64" -dir=C:/rsql1

The server displays some startup information and waits, listening for requests.

By default, the server is listening on the address localhost:7777.

If you want to stop it abruptly, just type Ctrl-C.

All database modifications are written in a write-ahead journal, so database corruption won’t happen even if the server stops in the middle of an active transaction.

YOU SHOULD RUN ONLY ONE rsql_server PROCESS ON A SPECIFIC INSTANCE DIRECTORY. ELSE, DATABASE CORRUPTION WILL OCCUR !

Client

The RSQL Client rcli.exe is a utility that sends batches to the server, and displays the result on the terminal.

Open a new terminal and type:

> .\rcli -U=sa -P=changeme -Q="print 'Hello';"

This command should print Hello on your terminal.

The default password for login sa after installation is changeme.

We will change it now. Replace the new_password_here argument by the password of your choice:

> .\rcli -U=sa -P=changeme -Q="ALTER LOGIN sa WITH PASSWORD='new_password_here';"

To avoid writing the login and password each time, we can put them in the configuration file of the rcli client.

Open a text editor, copy-paste the following content, and save the file as rcli.conf in your home directory.

When working on RSQL, you should use a good text editor, capable of reading and saving text encoded in UTF-8, which is the default for RSQL.

One good editor is Notepad++, that you can download at https://notepad-plus-plus.org/.

Check that in the Encoding menu in the menu bar of Notepad++, the default encoding is set to Encode in UTF-8 without BOM.

# usually, the name of this file is rcli.conf, located in the user's home directory

# this is the configuration file of the command line rsql client, "rcli", in TOML format.
# for TOML, see https://github.com/toml-lang/toml

[remote_server]
    address            = "127.0.0.1:7777"     # ip and port

[login]
    login_name         = "sa"                 # login name
    password           = "changeme"           # password for the login
    # default_database   = "trashdb"            # force the default database for connection. Else, the default database for the login is used.

[presentation]
    file_encoding      = "utf-8"              # encoding of input file
    null_string        = "NULL"               # string displayed by SELECT for NULL values
    width_limit        = 30                   # column width for displaying VARBINARY and VARCHAR
    fractional_second  = 3                    # number of fractional second digits, for displaying TIME and DATETIME
    print_mode         = 0                    # PRINT mode for multiple values. 0: normal mode, 1: column aligned
    error_level        = 0                    # level of details displayed when error is printed. 0, 1, 2
    error_wrap         = true                 # if true, error message is printed on a new line
    color              = false                # if true, error message is printed in color (Linux only)

[internal]
    keepalive_interval = 20                   # keepalive messages are sent to the server at this rate, in seconds. By default, 20 seconds.

In this config file, don’t forget to change the password parameter with the new password. Now, you should be able to run the following command without the user and password options:

> .\rcli -Q="print 'Hello again';"

If you have troubles, use the -v option to check if the correct config file has been loaded.

> .\rcli -U=sa -P=new_password_here -v -Q="print 'Hello again';"

It is often more convenient to write SQL statements in a file.
Just pass the file name (e.g. myfile.sql) as argument to RSQL Client rcli.exe:

> .\rcli myfile.sql

Remark

On Linux, the default server address specified in rcli.conf is localhost:7777.

But on Windows, many users encounter 1 second or more delay when establishing the connection, because of some name resolution problem.

That’s why 127.0.0.1:7777 is used instead.

Server Listening Address

See Installation (Linux) page.

Setting the Global Cache Size

See Installation (Linux) page.

Logging Files

See Installation (Linux) page.

Run RSQL Server as a service

RSQL service can be managed with the rsqlctl.exe program.

You must enter the following command in a Windows console opened with administrator right.

Install an instance as a service

To install RSQL as a service, type the following command:

> "c:\Program Files\rsql\rsqlctl" -install -service_name=rsql1 -instance_dir="C:/rsql1" -exepath="C:\Program Files\rsql\rsql_server-VERSION-windows_amd64.exe"

This command creates a service named rsql1, which is an instance of rsql running on the directory C:/rsql1. It must be started manually.

To install a service that starts automatically, use the following command instead:

> "c:\Program Files\rsql\rsqlctl" -install -service_name=rsql1 -instance_dir="C:/rsql1" -exepath="C:\Program Files\rsql\rsql_server-VERSION-windows_amd64.exe" -start_type=automatic

You can create multiple services. E.g. a service named rsql2, for an instance of rsql running on the directory C:/rsql2.

The service will be run as the LocalSystem account.

Display the status of a service

This command displays the status of the service rsql1.

> "c:\Program Files\rsql\rsqlctl" -status rsql1

Start a service

This command starts the service rsql1.

> "c:\Program Files\rsql\rsqlctl" -start rsql1

Stop a service

This command stops the service rsql1.

> "c:\Program Files\rsql\rsqlctl" -stop rsql1

Remove a service

To uninstall the service rsql1 from your system, type:

> "c:\Program Files\rsql\rsqlctl" -remove rsql1

Use Windows Service Manager (SrvMan)

To start or stop a service, you can also use the Windows Service Manager, in the Windows Configuration Manager.

You can also use it to change the start type of the service to automatic or manual.