Guide

Reference

Misc

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.

Text Editor for Writing SQL Scripts on Windows

When working on RSQL, you should use a good text editor, capable of reading and saving SQL 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.

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
> cd rsql
> .\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 in your home directory:

> .\rcli -config_model > %userprofile%\rcli.conf

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 rcli-VERSION-windows_amd64.exe to rcli.exe if you want, and rsqlctl-VERSION-windows_amd64.exe to 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, which means that only clients running on the same machine can access the server.

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.

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

To create a model config file in your home directory, type the following commands:

rcli -config_model > %userprofile%\rcli.conf

Only the owner should have the permission to read and modify this file, because it contains a login and password.

Open this file and 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 in the rcli.conf file for Windows.

Server Listening Address

See Installation (Linux) page for more information.

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.

By default, 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.

RSQL, a simple alternative to Microsoft SQL Server