Dancer...tabase(3pm)

💖 Dancer::Plugin::Auth::Extensible::Database 💖

okay bestie, so this is a page from User Contributed Perl Documentation, and it's all about Dancer::Plugin::Auth::Extensible::Database, the plugin you call when you want your app to ~authenticate via a database~ ✨

---

🌸 NAME 🌸

Dancer::Plugin::Auth::Extensible::Database — authenticate via a database. that's it, that's the whole vibe. you give it a database, it tells you if someone's allowed in 💅

---

✨ DESCRIPTION ✨

so this class? it's an authentication provider, and its whole job is to authenticate users against a database. it does that by using Dancer::Plugin::Database to actually get at the database 🫶

and for the password situation — Crypt::SaltedHash is what handles the hashed passwords, securely. because bestie. you would not want to store plain text passwords, right?? 😭 (and if your answer to that is genuinely yes, please reconsider. you really do not want to do that, especially when doing things right is literally so easy!!) 🚫

for how to set up a database connection properly, go peek at Dancer::Plugin::Database; and for how to configure this auth provider with your database details, scroll down to the "CONFIGURATION" section below 👇

also, for how to actually use the authentication framework — including how to pick a more useful authentication provider — check Dancer::Plugin::Auth::Extensible 💖

---

🎀 CONFIGURATION 🎀

this provider tries to use sensible defaults, so honestly? if your database tables look anything like the ones in the "SUGGESTED SCHEMA" section below, you might not need to configure much at all. slay.

the most basic configuration ever — assuming defaults for all options, and defining a single authentication realm named 'users':

plugins:
    Auth::Extensible:
        realms:
            users:
                provider: 'Database'

but like, you'd still need to have given Dancer::Plugin::Database suitable database connection details, obviously. see the docs for that plugin for the full rundown, but it could be as simple as, e.g.:

plugins:
    Auth::Extensible:
        realms:
            users:
                provider: 'Database'
    Database:
        driver: 'SQLite'
        database: 'test.sqlite'

and here's a full example showing every single option, no cap:

plugins:
    Auth::Extensible:
        realms:
            users:
                provider: 'Database'
                # optionally set DB connection name to use (see named
                # connections in Dancer::Plugin::Database docs)
                db_connection_name: 'foo'

                # Optionally disable roles support, if you only want to check
                # for successful logins but don't need to use role-based access:
                disable_roles: 1

                # optionally specify names of tables if they're not the defaults
                # (defaults are 'users', 'roles' and 'user_roles')
                users_table: 'users'
                roles_table: 'roles'
                user_roles_table: 'user_roles'

                # optionally set the column names (see the SUGGESTED SCHEMA
                # section below for the default names; if you use them, they'll
                # Just Work)
                users_id_column: 'id'
                users_username_column: 'username'
                users_password_column: 'password'
                roles_id_column: 'id'
                roles_role_column: 'role'
                user_roles_user_id_column: 'user_id'
                user_roles_role_id_column: 'roles_id'

and for how to configure multiple authentication realms, the main Dancer::Plugin::Auth::Extensible documentation has you covered 💜

---

🦋 SUGGESTED SCHEMA 🦋

if you use a schema similar to the examples down here, you should need, like, minimal configuration to get this authentication provider working for you. it just works ✨

the examples given here should be MySQL-compatible; you should only need minimal changes to use them with other database engines.

🌈 users table

you'll need a table to store user accounts in, of course. a suggestion is something like:

CREATE TABLE users (
    id       INTEGER     AUTO_INCREMENT PRIMARY KEY,
    username VARCHAR(32) NOT NULL       UNIQUE KEY,
    password VARCHAR(40) NOT NULL
);

you will quite likely want other fields to store e.g. the user's name, email address, etc; all columns from the users table will be returned by the "logged_in_user" keyword for your convenience. cute, right? 💖

🌈 roles table

you'll need a table to store a list of available roles in (unless you're not using roles — in which case, disable role support (see the "CONFIGURATION" section)).

CREATE TABLE roles (
    id    INTEGER     AUTO_INCREMENT PRIMARY KEY,
    role  VARCHAR(32) NOT NULL
);

🌈 user_roles table

finally, (unless you've disabled role support) you'll need a table to store user <-> role mappings (i.e. one row for every role a user has; so adding extra roles to a user consists of adding a new role to this table). it's entirely up to you whether you use an "id" column in this table; you probably shouldn't need it.

CREATE TABLE user_roles (
    user_id  INTEGER  NOT NULL,
    role_id  INTEGER  NOT NULL,
    UNIQUE KEY user_role (user_id, role_id)
);

if you're using InnoDB tables rather than the default MyISAM, you could add a foreign key constraint for better data integrity; see the MySQL documentation for details, but a table definition using foreign keys could look like:

CREATE TABLE user_roles (
    user_id  INTEGER, FOREIGN KEY (user_id) REFERENCES users (id),
    role_id  INTEGER, FOREIGN_KEY (role_id) REFERENCES roles (id),
    UNIQUE KEY user_role (user_id, role_id)
) ENGINE=InnoDB;

⚠️ heads up bestie — that's FOREIGN_KEY on the role_id line, exactly as written. don't go "fixing" it, just copy it as-is, iykyk 🙈

---

and that's the whole page!! this one was documented for perl v5.36.0, dated 2023-01-05 — so like, it's a little vintage, but it still eats 💅 mwah, go authenticate something, ily 🫶