From f52b99c41f2e6f6ae5e1b5f70f864520b0786e5a Mon Sep 17 00:00:00 2001
From: dimitr <dimitr@users.sourceforge.net>
Date: Sun, 18 Oct 2015 11:59:12 +0000
Subject: [PATCH] Some new docs.

---
 doc/README.connection_strings | 156 ++++++++++++++++++++++++++++++++++
 1 file changed, 156 insertions(+)
 create mode 100644 doc/README.connection_strings

diff --git a/doc/README.connection_strings b/doc/README.connection_strings
new file mode 100644
index 0000000000..d23d50724b
--- /dev/null
+++ b/doc/README.connection_strings
@@ -0,0 +1,156 @@
+------------------
+Connection strings
+------------------
+
+Connection string is a local or remote path to the database being attached.
+
+The legacy syntax (supported by all Firebird versions) is the following:
+
+For TCP (aka INET) protocol:
+
+  <host> [ / <port>] : <file path to database or alias>
+
+For named pipes (aka NetBEUI, aka WNET) protocol:
+
+  \\ <host> [ @ <port>] \ <file path to database or alias>
+
+For local connections as simple as:
+
+  <file path to database or alias>
+
+If host name is omitted, local connection is implied. Depending on settings,
+platform and Firebird version, it could be performed via either the embedded
+engine or XNET (shared memory) protocol or TCP localhost loopback.
+
+Examples:
+
+  Connect via TCP using database name:
+
+    192.168.0.11:/db/mydb.fdb
+    192.168.0.11:C:\db\mydb.fdb
+    myserver:C:\db\mydb.fdb
+    localhost:/db/mydb.fdb
+
+  Connect via TCP using database alias:
+
+    192.168.0.11:mydb
+    myserver:mydb
+    localhost:mydb
+
+  Connect via TCP using non-default port 3051:
+
+    192.168.0.11/3051:C:\db\mydb.fdb
+    192.168.0.11/3051:mydb
+    myserver/3051:/db/mydb.fdb
+    localhost/3051:/db/mydb.fdb
+    myserver/3051:mydb
+    localhost/3051:mydb
+
+  Connect via TCP using non-default service name:
+
+    192.168.0.11/fb_db:C:\db\mydb.fdb
+    192.168.0.11/fb_db:mydb
+    localhost/fb_db:/db/mydb.fdb
+    myserver/fb_db:/db/mydb.fdb
+    myserver/fb_db:mydb
+    localhost/fb_db:mydb
+
+  Connect via named pipes:
+
+    \\myserver\C:\db\mydb.fdb
+    \\myserver@fb_db\C:\db\mydb.fdb
+
+  Local connection:
+
+    /db/mydb.fdb
+    C:\db\mydb.fdb
+    mydb
+
+Additionally, Firebird 3.0 introduces generalized URL-like syntax for
+connection strings:
+
+  [ <protocol> : // [ <host> [ : <port> ] ] ] / <file path to database or alias>
+
+Where protocol is one of: INET (means TCP), WNET (means named pipes) or XNET
+(means shared memory).
+
+Examples:
+
+  Connect via TCP using database name:
+
+    inet://192.168.0.11//db/mydb.fdb
+    inet://192.168.0.11/C:\db\mydb.fdb
+    inet://myserver/C:\db\mydb.fdb
+    inet://localhost//db/mydb.fdb
+
+  Connect via TCP using database alias:
+
+    inet://192.168.0.11/mydb
+    inet://myserver/mydb
+    inet://localhost/mydb
+
+  Connect via TCP using non-default port 3051:
+
+    inet://192.168.0.11:3051/C:\db\mydb.fdb
+    inet://192.168.0.11:3051/mydb
+    inet://myserver:3051//db/mydb.fdb
+    inet://localhost:3051//db/mydb.fdb
+    inet://myserver:3051/mydb
+    inet://localhost:3051/mydb
+
+  Connect via TCP using non-default service name:
+
+    inet://192.168.0.11:fb_db/C:\db\mydb.fdb
+    inet://192.168.0.11:fb_db/mydb
+    inet://localhost:fb_db//db/mydb.fdb
+    inet://myserver:fb_db//db/mydb.fdb
+    inet://myserver:fb_db/mydb
+    inet://localhost:fb_db/mydb
+
+  Connect via named pipes:
+
+    wnet://myserver/C:\db\mydb.fdb
+    wnet://myserver:fb_db/C:\db\mydb.fdb
+
+  Loopback connection via TCP:
+
+    inet:///db/mydb.fdb
+    inet://C:\db\mydb.fdb
+    inet://mydb
+
+  Loopback connection via named pipes:
+
+    wnet://C:\db\mydb.fdb
+    wnet://mydb
+
+  Local connection via shared memory:
+
+    xnet://C:\db\mydb.fdb
+    xnet://mydb
+
+  Local (embedded by default) connection:
+
+    /db/mydb.fdb
+    C:\db\mydb.fdb
+    mydb
+
+If protocol and host name are omitted, local connection is implied. Depending on settings,
+it could be performed via either the embedded engine or XNET (shared memory) protocol
+or TCP localhost loopback.
+
+On the server side, default provider configuration is:
+
+  Providers = Remote, Engine12, Loopback
+
+It means that if the remote provider fails to match the connection string (because of missing
+protocol / host parts), then the embedded engine handles the hostless connection. If you need
+to connect locally using a specific transport protocol, please specify:
+
+  inet://<file path to database or alias>
+  or
+  wnet://<file path to database or alias>
+  or
+  xnet://<file path to database or alias>
+
+Note: WNET (named pipes) and XNET (shared memory) protocols are available on Windows only.
+