ldap2pg is released as a Go binary with no requirements.

On runtime, ldap2pg requires an unprivileged role with CREATEDB and CREATEROLE options or a superuser access. ldap2pg does not require to run on the same host as the synchronized PostgreSQL cluster.

With 2MiB of RAM and one vCPU, ldap2pg can synchronize several thousands of roles in seconds, depending on PostgreSQL instance and LDAP directory response time.

On RHEL and compatible clone, Dalibo Labs YUM repository offer RPM package for ldap2pg.

For using Dalibo Labs packaging:

ldap2pg has no CLI switch to configure Postgres connection. However, ldap2pg supports libpq PG* env vars.

See psql(1) for details on libpq env vars.

The same goes for LDAP, ldap2pg supports standard LDAP* env vars and ldaprc files. See ldap.conf(5) for further details on how to configure. ldap2pg accepts one extra variable: LDAPPASSWORD.

ldap2pg loads .env file in the lda2pg.yml’s parent directory if exists.

Use true or false for boolean values in environment. e.g. LDAP2PG_SKIPPRIVILEGES=true.

ldap2pg have several levels of logging:

The --quiet and --verbose switches respectively decrease and increase verbosity.

You can select the highest level of verbosity with LDAP2PG_VERBOSITY envvar. For example:

$ LDAP2PG_VERBOSITY=DEBUG ldap2pg
12:23:45 INFO   Starting ldap2pg                                 version=v6.0-alpha5 runtime=go1.21.0 commit=<none>
12:23:45 WARN   Running a prerelease! Use at your own risks!
12:23:45 DEBUG  Searching configuration file in standard locations.
12:23:45 DEBUG  Found configuration file.                        path=./ldap2pg.yml
$

ldap2pg output varies whether it’s running with a TTY or not. If standard error is a TTY, logging is colored and tweaked for human reading. Otherwise, logging format is pure logfmt, for machine processing. You can force human-readable output by using --color CLI switch.

ldap2pg searches for configuration file in the following order :

If LDAP2PG_CONFIG or --config is set, ldap2pg skips searching the standard file locations. You can specify - to read configuration from standard input. This is helpful to feed ldap2pg with dynamic configuration.

ldap2pg.yml is split in several sections :

The project provides a simple well commented ldap2pg.yml, tested on CI. If you don’t know how to begin, it is a good starting point.

The postgres section defines custom SQL queries for Postgres inspection.

The postgres section contains several *_query parameters. These parameters can be either a string containing an SQL query or a YAML list to return a static list of values, skipping execution of a query on PostgreSQL cluster.

postgres:
  databases_query: "SELECT datname FROM pg_catalog.pg_databases;"
  # OR
  databases_query: [mydb]

postgres:
  managed_roles_query: |
    VALUES
      ('public'),
      ('ldap_roles')

    UNION

    SELECT DISTINCT role.rolname
    FROM pg_roles AS role
    JOIN pg_auth_members AS ms ON ms.member = role.oid
    JOIN pg_roles AS parent
      ON parent.rolname = 'ldap_roles' AND parent.oid = ms.roleid
    ORDER BY 1;

postgres:
  roles_blacklist_query:
  - postgres
  - "pg_*"
  - "rds_*"

postgres:
  schemas_query: |
    SELECT nspname FROM pg_catalog.pg_namespace

The privileges top level section is a mapping defining privilege profiles, referenced later in Synchronisation map’s grant rule. A privilege profile is a list of either a reference to a privilege type in a Postgres ACL or other profile. A privilege profile may include another profile, recursively. See Managing Privileges for details.

privileges:
  reading:
  - default: global
    type: SELECT
    on: TABLES

  writing:
  - reading
  - default: global
    type: SELECT
    on: TABLES

A privilege profile whose name starts with _ is inactive unless included in an active profile.

privileges:
  reading:
  - default: global
    type: SELECT
    on: TABLES

privileges:
  reading:
  - type: USAGE
    on: SCHEMAS

privileges:
  reading:
  - type: SELECT
    on: ALL TABLES

The top level rules section is a YAML list. This is the only mandatory parameter in ldap2pg.yaml. Each item of rules is called a mapping. A mapping is a YAML dict with any of role or grant subsection. A mapping can optionnaly have a description field and a ldapsearch section.

rules:
- description: "Define DBA roles"
  ldapsearch:
    base: ...
  roles:
  - name: "{cn}"
    options: LOGIN SUPERUSER

The ldapsearch subsection is optional. You can define roles and grants without querying a directory.

rules:
- ldapsearch:
    base: ou=people,dc=acme,dc=tld
    scope: sub
    filter: >
      (&
         (member=*)
         (cn=group_*)
      )

rules:
- ldapsearch:
    joins:
      member:
        filter: ...
        scope: ...
  role:
  - name: "{member.sAMAccountName}"

rules:
- role:
    name: dba
    options: SUPERUSER LOGIN
- roles:
  - name: group0
    options: NOLOGIN
  - name: group1
    options: NOLOGIN

rules:
- roles:
    names:
    - alice
    - bob
    comment: "Static roles from YAML."

rules:
- ldapsearch:
    ...
  role:
    name: "{cn}"
    comment: "Generated from LDAP entry {dn}."

rules:
- ldapsearch:
    ...
  role:
    name: "{member.cn}"
    comment: "Generated from LDAP entry {member}."

rules:
- roles:
    name: "my-role-name"

- roles:
  - name: my-dba
    options: LOGIN SUPERUSER
  - name: my-group
    options:
      LOGIN: no
      INHERIT: yes

- roles:
  - name: my-db-writer
    config:
      log_statement: mod
      log_min_duration_sample: 100

- roles:
  - name: reset-my-configuration
    config: {}

rules:
- role:
    name: myrole
    parent: myparent

rules:
- ldapsearch: ...
  role:
    name: "{cn}"
    before_create: "INSERT INTO log VALUES ({cn.string()})"

rules:
- ldapsearch: ...
  role:
    name: "{sAMAccountName}"
    after_create: "CREATE SCHEMA {sAMAccountName.identifier()} AUTHORIZATION {sAMAccountName.identifier()}"

rules:
- grant:
    privilege: reader
    databases: __all__
    schema: public
    role: myrole

databases_query returns the flat list of databases to manage. The databases_query must return the default database as defined in PGDATABASE. When dropping roles, ldap2pg loops the databases list to reassign objects and clean GRANTs of to be dropped role. This databases list also narrows the scope of GRANTs inspection. ldap2pg will revoke GRANTs only on these databases. See ldap2pg.yaml reference for details.

postgres:
  databases_query: |
    SELECT datname
    FROM pg_catalog.pg_database
    WHERE datallowconn IS TRUE;

By default, ldap2pg manages all roles from Postgres it has powers on, minus the default blacklist. If you want ldap2pg to synchronsize only a subset of roles, you need to customize inspection query in postgres:managed_roles_query. The following query excludes superusers from synchronization.

postgres:
  managed_roles_query: |
    SELECT 'public'
    UNION
    SELECT rolname
    FROM pg_catalog.pg_roles
    WHERE rolsuper IS FALSE
    ORDER BY 1;

ldap2pg will only drop, revoke, grant on roles returned by this query.

A common case for this query is to return only members of a group like ldap_roles. This way, ldap2pg is scoped to a subset of roles in the cluster.

The public role does not exists in the system catalog. Thus if you want ldap2pg to manage public privileges, you must include explicitly public in the set of managed roles. This is the default. Of course, even if public is managed, ldap2pg won’t drop or alter it if it’s not in the directory.

A safety net to completely ignore some roles is roles_blacklist_query.

postgres:
  roles_blacklist_query: [postgres, pg_*]  # This is the default.

For schema-wide privileges, ldap2pg needs to known managed schemas for each database. This is the purpose of schemas_query.

To configure default privileges, use the default keyword when referencing a privilege:

privileges:
  reading:
  - default: global
    type: SELECT
    on: TABLES

Then grant it using grant rule:

rules:
- grant:
  - privilege: reading
    role: readers
    schema: public
    owner: ownerrole

You can use __auto__ as owner. For each schema, ldap2pg will configure every managed role having CREATE privilege on schema.

rules:
- grant:
  - privilege: reading
    role: readers
    schema: public
    owner __auto__

ldap2pg configures default privileges last, after all effective privileges. Thus CREATE on schema is granted before ldap2pg inspects creators on schemas.

You can replace all queries with a static list in YAML. This list will be used as if returned by Postgres. That’s very handy to freeze a value like databases or schemas.

postgres:
  databases_query: [postgres]
  schemas_query: [public]

ldap2pg is designed to run unprivileged. Synchronization user needs CREATEROLE option to manage other unprivileged roles. CREATEDB options allows synchronization user to managed database owners.

ldap2pg user must have createrole_self_grant set to inherit,set to properly handle groups.

CREATE ROLE ldap2pg LOGIN CREATEDB CREATEROLE;
ALTER ROLE ldap2pg SET createrole_self_grant TO 'inherit,set;

Running unprivileged before Postgres 16 is actually flawed. You’d better just run ldap2pg with superuser privileges, you wont feel falsly secured.

ldap2pg totally ignores roles matching one of the glob pattern defined in roles_blacklist_query:

postgres:
  # This is the default value.
  roles_blacklist_query: [postgres, pg_*]

The role blacklist is also applied to grants. ldap2pg will never apply GRANT or REVOKE on a role matching one of the blacklist patterns.

ldap2pg blacklists its running user.

ldap2pg manages parents of roles. ldap2pg applies roles_blacklist_query to parents. However, ldap2pg grants unmanaged parents. This way, you can create a group manually and manages its members using ldap2pg.

ldap2pg reads directory configuration from ldaprc file and LDAP* environment variables. Known LDAP options are:

See ldap.conf(5) for the meaning and format of each options.

Several parameters accepts LDAP attribute injection using curly braces. To do this, wraps attribute name with curly braces like {cn} or {sAMAccountName}. ldap2pg expands to each value of the attribute for each entries of the search.

If the parameter has multiple LDAP attributes, ldap2pg expands to all combination of attributes for each entries.

Given the following LDAP entries:

dn: uid=dimitri,cn=Users,dc=bridoulou,dc=fr
objectClass: inetOrgPerson
uid: dimitri
sn: Dimitri
cn: dimitri
mail: dimitri@bridoulou.fr
company: external

dn: cn=domitille,cn=Users,dc=bridoulou,dc=fr
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: top
cn: domitille
sn: Domitille
company: acme
company: external

The format {company}_{cn} with the above LDAP entries generates the following strings:

The pseudo attribute dn is always available and references the Distinguished Name of the original LDAP entry.

- ldapsearch: ...
  role: "{cn.lower()}"

The base design of ldap2pg is ambitious. Instead of revoke-everything-regrant design, ldap2pg uses inspect-modify design. The process is the same as for roles synchronization, including the three following steps:

ldap2pg synchronizes privileges one at a time, database by database. ldap2pg synchronizes default privileges last.

By default, ldap2pg does not manage any privileges. To enable privilege management, you must define at least one active privilege profile in privileges section. The simplest way is to reuse [builtin privilege profiless] shipped with ldap2pg in an active group of privileges.

A privilege profile is a list of references to either a privilege type on an ACL or another profile. ldap2pg ships several predefined ACL like DATABASE, LANGUAGE, etc. A privilege type is USAGE, CONNECT and so on as describe in as documented in documentation Section 5.7. See privileges YAML section documentation for details on privilege profile format.

ldap2pg loads referenced ACL by inspecting PostgreSQL cluster with carefully crafted queries. An unreferenced ACL is ignored. Inspected grants are supposed to revokation unless explicitly wanted by a grant rule.

When managing privileges, ldap2pg has deeper inspection of Postgres instance. ldap2pg inspects schemas after roles synchronization and before synchronizing privileges. ldap2pg inspects objects owner after privileges synchronization and before synchronizing default privileges. An object owner is a role having CREATE privilege on a schema.

Inspecting privileges may consume a lot of resources on PostgreSQL instance. Revoking privileges is known to be slow in PostgreSQL. The best practice is to grant privileges to a group role and let user inherit privileges. With ldap2pg, you can define static groups in YAML and inherit them when creating roles from directory.

Use grant rule to grant a privilege profile to one or more roles. When granting privileges, you must define the grantee. You may scope the grant to one or more databases, one or more schemas. If the privilege profile includes default privileges, you may define the owners on which to configure default privileges.

By default, a grant applies to all managed databases as returned by databases_query, to all schema of each database as returned by schemas_query.

The following example defines three privileges profile. The rules defines three groups and grant the corresponding privilege profile:

privileges:
  reading:
  - __connect__
  - __usage_on_schemas__
  - __select_on_tables__

  writing:
  - reading  # include reading privileges
  - __insert_on_tables__
  - __update_on_tables__

  owning:
  - writing
  - __create_on_schemas__
  - __truncate_on_tables__

rules:
- role:
  - names:
    - readers
    - writers
    - owners
    options: NOLOGIN
- grant:
  - privilege: reading
    role: readers
  - privilege: writing
    role: writers
  - privilege: owning
    role: owners

Another way of including reading profile in writing is to writers group to inherit readers group.

PostgreSQL has a pseudo-role called public. It’s a wildcard roles meaning every users. All roles in PostgreSQL implicitly inherits from this public role. Granting a privilege to public role grants to every role now and in the future.

PostgreSQL also as the public schema. The public schema is a real schema available in all databases.

PostgreSQL has some built-in privileges for public role. Especially for the public schema. For example, public has CONNECT on all databases by default. This means that you only rely on pg_hba.conf to configure access to databases, which requires administrative access to the cluster and a pg_reload_conf() call.

By default, ldap2pg includes public role in managed roles. Predefined ACL knows how to inspect built-in privileges granted to public. If you want to preserve public role, rewrite managed_roles_query to not include public.

If you grant SELECT privileges on all tables in a schema to a role, this wont apply to new tables created afterward. Instead of reexecuting ldap2pg after the creation of every objects, PostgreSQL provides a way to define default privileges for future objects.

PostgreSQL attaches default privileges to the creator role. When the role creates an object, PostgreSQL apply the corresponding default privileges to the new object. e.g. ALTER DEFAULT PRIVILEGES FOR ROLE bob GRANT SELECT ON TABLES TO alice; ensures every new tables bob creates will be selectable by alice:

If ldap2pg creates and drops creator roles, you want ldap2pg to properly configure default privileges on these roles. If you wonder whether to manage privileges with ldap2pg, you should at least manage default privileges along creator.

ldap2pg inspects the creators from PostgreSQL, per schemas, not LDAP directory. A creator is a role with LOGIN option and CREATE privilege on a schema. You can manually set the target owner of a grant to any managed roles.

ldap2pg does not configure privileges on __all__ schemas. You are supposed to use global scope instead. If you want to grant/revoke default privilege per schema, you must reference schema default.

The following example configures default privileges for alice to allow bob to SELECT on future tables created by alice.

privileges:
  reading:
  - default: global
    type: SELECT
    on: TABLES
  owning:
  - type: CREATE
    on: SCHEMAS

rules:
- roles:
    names:
    - alice
    - bob
    options: LOGIN
- grant:
    privilege: owning
    role: alice
- grant:
    privilege: reading
    role: bob

PostgreSQL has hard-wire global default privileges. If a role does not have global default privileges configured, PostgreSQL assume some defaults. By default, PostgreSQL just grant privileges on owner. You can see them once you modify the default privileges. PostgreSQL will copy the hard-wired values along your granted privileges.

If you don’t explicitly re-grant these privileges in ldap2pg.yml, ldap2pg will revoke these hard-wired privileges. Actually, an owner of table don’t need to be granted SELECT on its own tables. Thus, the hard-wired defaults are useless. You can let ldap2pg purge these useless defaults.

A privilege profile is a list of reference to a privilege type in an ACL. In ldap2pg, an ACL is a set of query to inspect, grant and revoke privilege on a class of objects. The inspect query expands aclitem PostgreSQL type to list all grants from system catalog. Privilege profile can include another profile.

Builtin privilege profile starts and ends with __. ldap2pg disables privilege profile starting with _. Thus you have to include builtin privileges profile in another profile to enable them. If two profiles reference the same privilege, ldap2pg will inspect it once.

privileges:
  ro:
  - __connect__
  - __usage_on_schemas__
  - __select_on_tables__

  rw:
  - ro
  - __insert__
  - __update_on_tables__

  ddl:
  - rw
  - __all_on_schemas__
  - __all_on_tables__

rules:
- grant:
    privilege: ddl
    database: mydb
    role: admins

Builtin profile’s name follows the following loose convention:

This page does not document the SQL standard and the meaning of each SQL privileges. You will find the documentation of SQL privileges in GRANT and ALTER DEFAULT PRIVILEGES.

Here is the list of builtin ACL.

For effective privileges:

ALL ... IN SCHEMA ACL inspects whether a privilege is granted to only a subset of objects. This is a partial grant. A partial grant is either revoked if unwanted or regranted if expected.

ACL for default privileges:

Theses ACL must be referenced with global set to either schema or global.

You can reference these ACL using privileges:on parameter in YAML. Like this:

privileges:
  myprofile:
  - type: SELECT
    on: ALL TABLES IN SCHEMA

You cannot (yet) configure custom ACL.

Here is the list of predefined privileges:

Here is the list of predefined default privileges. Default privilege profile references both global and schema defaults.

ldap2pg does NOT configure PostgreSQL for you. You should carefully read Section 20.10 for this point. Having PostgreSQL properly configured before writing ldap2pg.yaml is a good start. Here is the steps to setup PostgreSQL with LDAP in the best order:

Once you have LDAP authentication configured in PostgreSQL cluster, you can move to automate role creation from the LDAP directory using ldap2pg:

The first step is to search your LDAP server with ldapsearch(1), the CLI tool from OpenLDAP. Like this:

$ ldapsearch -H ldaps://ldap.ldap2pg.docker -U testsasl -W
Enter LDAP Password:
SASL/DIGEST-MD5 authentication started
SASL username: testsasl
SASL SSF: 128
SASL data security layer installed.
# extended LDIF
#
# LDAPv3
...
# search result
search: 4
result: 0 Success

# numResponses: 16
# numEntries: 15
$

Now save the settings in ldaprc:

LDAPURI ldaps://ldap.ldap2pg.docker
LDAPSASL_AUTHCID testsasl

And in environment: LDAPPASSWORD=secret

Next, update your ldapsearch(1) to properly match role entries in LDAP server:

$ ldapsearch -H ldaps://ldap.ldap2pg.docker -U testsasl -W -b cn=dba,ou=groups,dc=ldap,dc=ldap2pg,dc=docker '' member
...
# dba, groups, ldap.ldap2pg.docker
dn: cn=dba,ou=groups,dc=ldap,dc=ldap2pg,dc=docker
member: cn=Alan,ou=people,dc=ldap,dc=ldap2pg,dc=docker
member: cn=albert,ou=people,dc=ldap,dc=ldap2pg,dc=docker
member: cn=ALICE,ou=people,dc=ldap,dc=ldap2pg,dc=docker

# search result
search: 4
result: 0 Success

...
$

Now translate the query in ldap2pg.yaml and associate a role mapping to produce roles from each values of each entries returned by the LDAP search:

- ldapsearch:
    base: cn=dba,ou=groups,dc=ldap,dc=ldap2pg,dc=docker
  role:
    name: '{member.cn}'
    options: LOGIN SUPERUSER

Test it:

$ ldap2pg
...
Querying LDAP cn=dba,ou=groups,dc=ldap,dc=ldap2pg,dc=docker...
Would create alan.
Would create albert.
Would update options of alice.
...
Comparison complete.
$

Read further on how to control role creation from LDAP entry in Section H.1.5. Once you’re satisfied with the comparison output, go real with --real.

ldap2pg supports LDAP High Availability out of the box just like any openldap client. Use a space separated list of URI to tells all servers.

$ LDAPURI="ldaps://ldap1 ldaps://ldap2" ldap2pg

See [ldap.conf(5)] for further details.

Since Postgres provide a CREATEROLE role option, you can manage roles without superuser privileges. Security-wise, it’s a good idea to manage roles without super privileges.

ldap2pg supports this case. However, you must be careful about the limitations. Let’s call the non-super role creating other roles creator.

If ever you want to clean all roles in a PostgreSQL cluster, ldap2pg could be helpful. You must explicitly define an empty rules.

$ echo '{version: 6, rules: []}' | ldap2pg --config -
...
Empty synchronization map. All roles will be dropped!
...

In this example, default blacklist applies. ldap2pg never drop its connection role.

Already familiar with Docker and willing to save the setup time? You’re at the right place.

To run the container simply use the command:

$ docker run --rm dalibo/ldap2pg --help

The Docker image of ldap2pg use the same configuration options as explained in the Section H.1.4 and Section H.1.5 sections. You can mount the ldap2pg.yml configuration file.

$ docker run --rm -v ${PWD}/ldap2pg.yml:/workspace/ldap2pg.yml dalibo/ldap2pg

You can also export some environmnent variables with the -e option:

$ docker run --rm -v ${PWD}/ldap2pg.yml:/workspace/ldap2pg.yml -e PGDSN=postgres://postgres@localhost:5432/ -e LDAPURI=ldaps://localhost -e LDAPBINDDN=cn=you,dc=entreprise,dc=fr -e LDAPPASSWORD=pasglop dalibo/ldap2pg

Make sure your container can resolve the hostname your pointing to. If you use some internal name resolution be sure to add the –dns= option to your command pointing to your internal DNS server. More info

Project repository ships a docker-compose.yml file to launch an Samba Directory and a PostgreSQL instances.

$ docker compose pull
...
Status: Downloaded newer image for postgres:16-alpine
$ docker compose up -d
Creating network "ldap2pg_default" with the default driver
Creating ldap2pg_postgres_1 ...
Creating ldap2pg_samba_1 ...
Creating ldap2pg_postgres_1
Creating ldap2pg_samba_1 ... done

It’s up to you to define how to access Postgres and LDAP containers from your host: either use DNS resolution or a docker-compose.override.yml to expose port on your host. Provided docker-compose.yml comes with postgres.ldap2pg.docker and samba.ldap2pg.docker dnsdock aliases.

Setup your environment with regular PG* envvars so that psql can just connect to your PostgreSQL instance. Check with a simple psql invocation.

$ export PGHOST=postgres.ldap2pg.docker PGUSER=postgres PGPASSWORD=postgres
$ psql -c 'SELECT version()';

Do the same to setup libldap2 with LDAP* envvars. A ldaprc is provided setting up BINDDN and BASE. ldap2pg supports LDAPPASSWORD to set password from env. Check it with ldapsearch:

$ export LDAPURI=ldaps://samba.ldap2pg.docker LDAPPASSWORD=1Ntegral
$ ldapsearch -vxw $LDAPPASSWORD -s base cn
ldap_initialize( <DEFAULT> )
filter: (objectclass=*)
requesting: cn
# extended LDIF
#
# LDAPv3
# base <cn=users,dc=bridoulou,dc=fr> (default) with scope baseObject
# filter: (objectclass=*)
# requesting: cn
#

# Users, bridoulou.fr
dn: CN=Users,DC=bridoulou,DC=fr
cn: Users

# search result
search: 2
result: 0 Success

# numResponses: 2
# numEntries: 1
$

# contents docker-compose.override.yml
version: '3'

services:
  samba:
    ports:
      # HOST:CONTAINER
      - 389:389
      - 636:636

  postgres:
    ports:
      - 5432:5432

$ go run ./cmd/ldap2pg
09:54:27 INFO   Starting ldap2pg                                 version=v6.0-alpha5 runtime=go1.20.3 commit=<none>
09:54:27 WARN   Running a prerelease! Use at your own risks!
09:54:27 INFO   Using YAML configuration file.                   path=./ldap2pg.yml
...
09:54:27 INFO   Nothing to do.                                   elapsed=78.470278ms mempeak=1.2MiB postgres=0s queries=0 ldap=486.921µs searches=1
$

ldap2pg project comes with three cases for testing:

test/fixtures/ holds fixtures for Samba and PostgreSQL. Default development environment loads nominal and extra fixtures. By default, big case is not loaded. Func tests use nominal and extra fixtures. See below for big case.

test/fixtures/postgres/reset.sh resets PostgreSQL state. You can also use make reset-postgres to recreate PostgreSQL container from scratch.

Unit tests strictly have no I/O. Run unit tests as usual go tests.

$ go test ./...
?       github.com/dalibo/ldap2pg/cmd/ldap2pg   [no test files]
?       github.com/dalibo/ldap2pg/cmd/render-doc        [no test files]
ok      github.com/dalibo/ldap2pg/cmd/mon-dojo  0.002s
ok      github.com/dalibo/ldap2pg/internal      0.003s
ok      github.com/dalibo/ldap2pg/internal/config       0.007s
ok      github.com/dalibo/ldap2pg/internal/inspect      0.005s
ok      github.com/dalibo/ldap2pg/internal/ldap 0.005s
ok      github.com/dalibo/ldap2pg/internal/lists        0.005s
?       github.com/dalibo/ldap2pg/internal/postgres     [no test files]
ok      github.com/dalibo/ldap2pg/internal/perf 0.004s
ok      github.com/dalibo/ldap2pg/internal/privilege    0.003s
?       github.com/dalibo/ldap2pg/internal/role [no test files]
ok      github.com/dalibo/ldap2pg/internal/pyfmt        0.004s
ok      github.com/dalibo/ldap2pg/internal/tree 0.002s
ok      github.com/dalibo/ldap2pg/internal/wanted       0.003s
$

test/ directory is a [pytest] project with functionnal tests. Functionnal tests tend to validate ldap2pg in real world : no mocks.

Func tests requires Python 3.6. Create a virtualenv to isolate ldap2pg dev Python dependencies. Install dev dependencies with pip install -Ur test/requirements.txt.

$ pip install -Ur test/requirements.txt
...
Successfully installed iniconfig-2.0.0 packaging-23.1 pluggy-1.3.0 pytest-7.4.2 sh-1.14.1
$

You can run func tests right from you development environment:

$ pip install -Ur test/requirements.txt
...
$ pytest test/
...
ldap2pg: /home/bersace/src/dalibo/ldap2pg/test/ldap2pg.sh
...
test/test_nominal.py::test_re_revoke PASSED                                  [ 90%]
test/test_nominal.py::test_nothing_to_do PASSED                              [100%]

=============================== 11 passed in 14.90s ================================
$

CI executes func tests in CentOS 6 and 7 and RockyLinux 8 and 9.

Tests are written with the great pytest and sh projects. conftest.py provides various specific fixtures. The most important is that Postgres database is reset between each Python module. pytests executes Func tests in definition order. If a test modifies Postgres, the following tests will have this modification kept until the end of the module. This allows to split a big scenario in severals steps without loosing context and CPU cycle.

Two main pytest fixtures are very useful when testing: psql and ldap. These little helpers provide fastpath to frequent inspection of Postgres database on LDAP base with sh.py-style API.

You can execute tests just like in CI with the following commands:

$ goreleaser build --clean --snapshot --single-target
$ COMPOSE_FILE=docker-compose.yml:test/docker-compose.yml docker compose up --exit-code-from=test

To stress ldap2pg on big setup, use make big. This will feed directory with a lot of users and groups, several databases with a lot of schemas, etc. Synchronize this setup with:

$ test/genperfconfig.sh | PGDATABASE=big0 go run ./cmd/ldap2pg -c -

Building documentation requires Python 3.7. mkdocs is in charge of building the documentation. To edit the doc, install docs/requirements.txt and run mkdocs serve at the toplevel directory. See mkdocs documentation for further information.

$ pip install -r docs/requirements.txt
...
Successfully installed babel-2.12.1 certifi-2023.7.22 charset-normalizer-3.2.0 click-8.1.7 colorama-0.4.6 ghp-import-2.1.0 idna-3.4 jinja2-3.1.2 markdown-3.5 m...