Home

The URL spec extends on RFC 3986, by adding the following:

• Multiple-hosts support, in the form of hostA:123,hostB:456,hostC:789
• Fully optional syntax, allows any section of the URL on its own

See also:

• Frequently Asked Questions.
• Database Adapters.

optional format

The connection-string protocol is ultimately flexible, and allows everything to be optional.

See from examples below how various parameters can be passed in, while skipping others. For simplicity of all examples below, we use a shorter syntax:

const {ConnectionString} = require('connection-string');
const parse = cn => new ConnectionString(cn);

protocol only

ends with ://

parse('abc://'); //=> {protocol: 'abc'}
parse('my%20protocol://'); //=> {protocol: 'my protocol'}
parse('one:two://'); //=> {protocol: 'one:two'}

protocol + hostname + port

parse('abc://server:12345');
/* => {
    protocol: 'abc',
    hosts: [{name: 'server', port: 12345, type: 'domain'}]
}*/

hostname + port

parse('server:12345');
/* => {
    hosts: [{name: 'server', port: 12345, type: 'domain'}]
}*/

hostname only

parse('server');
/* => {
    hosts: [{name: 'server', type: 'domain'}]
}*/

port only

starts with :, followed by digits

parse(':12345');
/* => {
    hosts: [{port: 12345}]
}*/

password + port

parse(':pass@:12345');
/* => {
    password: 'pass',
    hosts: [{port: 12345}]
}*/

user only

ends with @

parse('username@'); //=> {user: 'username'}

password only

starts with : and ends with @

parse(':pass123@'); //=> {password: 'pass123'}

path only

starts with /

parse('/one/two'); //=> {path: ['one', 'two']}

parameters only

starts with ?

parse('?param1=value1&param2=value2');
/* => {
    params: {
        param1: value1,
        param2: value2
    }
}*/

protocol + path

parse('abc:///one/two');
/* => {
    protocol: 'abc',
    path: ['one', 'two']
}*/

protocol + parameters

parse('abc://?param1=one&param2=two');
/* => {
    protocol: 'abc',
    params: {
        param1: 'one',
        param2: 'two'
    }
}*/

user + parameters

parse('name@?param1=one&param2=two');
/* => {
    user: 'name',
    params: {
        param1: 'one',
        param2: 'two'
    }
}*/

user + path

parse('name@/first/second');
/* => {
    user: 'name',
    path: ['first', 'second']
    }
}*/

The list of examples above shows only the most interesting cases, but you can combine them as you like, and the parser will recognize all the right parameters.