Guide to set up MariaDB with Velvet

In this guide, we outline the steps required to securely connect your MariaDB database to your Velvet workspace. You may be able to skip some of these steps if you've previously connected your database to other services.

Depending on whether you're starting a new project from scratch, or connecting a database that's already configured for a third-party tool - this will take between 10 minutes and 2 hours.

  1. Create read-only user
  2. Set up static IP
  3. Add connection string
  4. Configure tables

1. Create a read-only user

It's best practice to create a user with read-only permissions for products like Velvet. Create a user with read-only permissions in MariaDB.

Connect to your MariaDB server

Run the following SQL commands in a MariaDB client or command-line interface.

  1. Create a Velvet read-only user with your password.

    CREATE USER 'velvet_readonly'@'%' IDENTIFIED BY 'mypassword';

    The % in the command above means that user velvet_readonly can be used to connect from any host or IP. You can limit the access by defining the host or IP from where the user can connect.

  2. Grant read-only permissions to the user. Replace database_name with the name of your database.

    GRANT SELECT ON database_name.* TO 'velvet_readonly'@'%';

    If you want the user to have read-only access to all databases:

    GRANT SELECT ON *.* TO 'velvet_readonly'@'%';

    The % in the command above gives the user velvet_readonly read-only access to the database from any host or IP. You can limit the access by defining the host or IP from where the user can connect. To grant access to a single table, specify the table name instead of *.

  3. After granting permissions, reload the privileges to ensure the changes take effect:


2. Set up static IP

Configure network restrictions to allow Velvet's static IP addresses. Follow our static IP configuration guide.

3. Identify and copy your connection string

Read our general guide on URI construction here. The MariaDB-specific overview is below.

If you already have a connection string, skip to step #4.

Build your connection string (URI)

Ensure all characters that require encoding are converted to their percent encoded counterparts.

Characters to percent-encode:

  • %%25
  • &%26
  • /%2F
  • :%3A
  • =%3D
  • ?%3F
  • @%40
  • [%5B
  • ]%5D

The MariaDB connection string requires a username, followed by an optional password in the following format:


If you prefer to specify only the username, you can use:


The host (a name resolved by an external name system like DNS, an IP address or other direct address) and the port (port number on which the database server is running):


If the MariaDB server is running on the default port (3306) you can omit the port component:


The schema name is required and is provided after the host and port. The database name begins with a forward slash.


You can also include additional parameters to customize the connection. These parameters are appended to the connection string and start with a question mark (?).


Common parameters::

  • charset
  • sslmode
  • timeout

Examples to illustrate these formats:

  1. Only Username on Localhost


  2. Default port with Username and Password


  3. Multiple Additional Parameters


Once done, copy your connection string to paste it into Velvet.

4. Configure your database and tables on Velvet

Configure MariaDB as a remote database connection and select which tables you want connected.

  1. Tap into a workspace in your Velvet dashboard
  2. Tap "Add a data source"
  3. Select type "Remote database"
  4. Name your database
  5. Paste in your database URI. Note: After providing your database credentials for the first time, we manage the connection using ClickHouse. If required, you can add ClickHouse's Static IPs to an allowlist - Read their API documentation here.
  1. Select and configure the table you want to connect as a source.
  1. Name your table and create the source.
  1. Repeat steps 6 and 7 to add each table you want included as a data source.
  2. You can now view, search, and filter data inside your database source.

Great job, you’ve connected your internal database as a data source. We’ll capture data from your connected tables so you can query them in your Velvet workspace.

Email [email protected] for support or feedback.