for SQL dialects RDBMSes may use, so it may be used for integration
and distribution of data on different RDBMSes, OSes, hosts etc., in
other words, in highly heterogeneous environment.
+.LP
+This backend is experimental.
.SH CONFIGURATION
These
.B slapd.conf
taken from the datasource.
Use them if you need to override datasource settings.
Also, several RDBMS' drivers tend to require explicit passing of user/password,
-even if those are given in datasource.
+even if those are given in datasource (Note:
+.B dbhost
+is currently ignored).
.RE
.TP
.B subtree_cond <SQL expression>
-Specifies a where-clause template used to form a subtree search condition.
+Specifies a where-clause template used to form a subtree search condition
+(dn=".*<dn>").
+It may differ from one SQL dialect to another (see samples).
+.TP
+.B children_cond <SQL expression>
+Specifies a where-clause template used to form a children search condition
+(dn="\.+,<dn>").
It may differ from one SQL dialect to another (see samples).
.TP
.B oc_query <SQL expression>
All these and subtree_cond should have the given default values.
For the current value it is recommended to look at the sources,
or in the log output when slapd starts with "-d 5" or greater.
+Note that the parameter number and order must not be changed.
.TP
.B upper_func <SQL function name>
Specifies the name of a function that converts a given value to uppercase.
This is used for CIS matching when the RDBMS is case sensitive.
.TP
+.B upper_needs_cast { yes | no }
+Set this directive to
+.B yes
+if
+.B upper_func
+needs an explicit cast when applied to literal strings. The form
+.B cast (<arg> as varchar(<max DN length>))
+is used, where
+.B <max DN length>
+is builtin.
+This is
+.B experimental
+and may change in future releases.
+.TP
+.B concat_pattern <pattern>
+This statement defines the
+.B pattern
+to be used to concatenate strings. The
+.B pattern
+MUST contain two question marks, '?', that will be replaced
+by the two strings that must be concatenated. The default value is
+.BR "CONCAT(?,?)";
+a form that is known to be highly portable is
+.BR "?||?",
+but an explicit cast may be required when operating on literal strings:
+.BR "cast(?||? as varchar(<length>))".
+On some RDBMSes the form
+.B "?+?"
+is known to work.
+Carefully check the documentation of your RDBMS or stay with the examples
+for supported ones.
+This is
+.B experimental
+and may change in future releases.
+.TP
.B strcast_func <SQL function name>
Specifies the name of a function that converts a given value to a string
-for appropriate ordering. This is used when selecting distinct data.
+for appropriate ordering. This is used in "SELECT DISTINCT" statements
+for strongly typed RDBMSes with little implicit casting (like PostgreSQL),
+when a literal string is specified.
+This is
+.B experimental
+and may change in future releases.
.TP
.B has_ldapinfo_dn_ru { yes | no }
-Explicitly inform the backend whether the SQL schema has dn_ru or not.
-Overrides automatic check (required by PostgreSQL).
+Explicitly inform the backend whether the SQL schema has dn_ru column
+(dn in reverse uppercased form) or not.
+Overrides automatic check (required by PostgreSQL/unixODBC).
+This is
+.B experimental
+and may change in future releases.
+
+.TP
+.B fail_if_no_mapping { yes | no }
+When set to
+.B yes
+it forces write operations to fail if no appropriate mapping between LDAP
+attributes and SQL data is available. The default behavior is to ignore
+those changes that cannot be mapped correctly.
+This is
+.B experimental
+and may change in future releases.
.SH METAINFORMATION USED
.LP
Almost everything mentioned later is illustrated in examples located
in the
-.B slapd/back-sql/rdbms_depend/
+.B servers/slapd/back-sql/rdbms_depend/
directory in the OpenLDAP source tree, and contains scripts for
generating sample database for Oracle, MS SQL Server, mySQL and more
(including PostgreSQL and IBM db2).
ldap_attr_mappings (some columns are not listed for clarity)
-----------
id=1
- oc_id=1
+ oc_map_id=1
name="cn"
sel_expr="CONCAT(persons.first_name,' ',persons.last_name)"
from_tbls="persons"
into the most relaxed SQL condition to filter candidates), and send it to
the user.
.LP
-ADD, DELETE, MODIFY operations are also performed on per-attribute
+ADD, DELETE, MODIFY and MODRDN operations are also performed on per-attribute
metainformation (add_proc etc.).
In those fields one can specify an SQL statement or stored procedure
call which can add, or delete given values of a given attribute, using
information on this matter - they are self-explanatory for those familiar
with concept expressed above.
.LP
-.SH common techniques (referrals, multiclassing etc.)
-First of all, lets remember that among other major differences to the
+.SH Common techniques (referrals, multiclassing etc.)
+First of all, let's remember that among other major differences to the
complete LDAP data model, the concept above does not directly support
such things as multiple objectclasses per entry, and referrals.
Fortunately, they are easy to adopt in this scheme.
values of "ref" attribute), you will have slapd return a referral, as
described in the Administrators Guide.
.LP
+.SH Caveats
+As previously stated, this backend should not be considered
+a replacement of other data storage backends, but rather a gateway
+to existing RDBMS storages that need to be published in LDAP form.
+.LP
+The hasSubordintes operational attribute is honored by back-sql
+in search results and in compare operations; it is partially honored
+also in filtering. Owing to design limitations, a (braindead) filter
+of the form
+\fB(!(hasSubordinates=TRUE))\fP
+will give no results instead of returning all the leaf entries.
+If you need to find all the leaf entries, please use
+\fB(hasSubordinates=FALSE)\fP
+instead.
+.LP
+\fBAttribute\fP and \fBObjectClass\fP inheritance is honored neither
+in filters nor in search results.
+So you may search for \fB(givenName=Mitya)\fP in the examples,
+but not for \fB(name=Mitya)\fP.
+.LP
.SH EXAMPLES
There are example SQL modules in the slapd/back-sql/rdbms_depend/
directory in the OpenLDAP source tree.
projects / openldap / blobdiff