Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
OpenXPKI::Server::DataUser:ContributednPerl:Server::Database::Role::Driver(3)

Name
       OpenXPKI::Server::Database::Role::Driver	- Moose	role that every
       database	driver has to consume

Synopsis
	   package OpenXPKI::Server::Database::Driver::MyDB2;
	   use Moose;
	   with	'OpenXPKI::Server::Database::Role::SequenceSupport';
	   with	'OpenXPKI::Server::Database::Role::MergeEmulation';
	   with	'OpenXPKI::Server::Database::Role::Driver';

	   # required by OpenXPKI::Server::Database::Role::Driver
	   sub dbi_driver { 'DB2' }	      #	DBI compliant driver name
	   sub dbi_dsn {		      #	DSN string including all parameters.
	       my $self	= shift;
	       return sprintf("dbi:%s:dbname=%s",
		   $self->dbi_driver,
		   $self->name,
	       );
	   }
	   sub dbi_connect_params { {} }      #	Additional parameters for DBI's	connect()
	   sub sqlam_params { {		      #	Parameters for SQL::Abstract::More
	       limit_offset => 'FetchFirst',
	   } }

	   # required by OpenXPKI::Server::Database::Role::SequenceSupport
	   sub nextval_query {		      #	SQL query to retrieve next sequence value
	       my ($self, $seq)	= @_;
	       return "VALUES NEXTVAL FOR $seq";
	   }

	   __PACKAGE__->meta->make_immutable;

       Then e.g. in your database.yaml:

	   main:
	       type: MyDB2
	       ...

       The above code is actually the current driver for IBM DB2 databases.

Description
       This Moose role must be consumed	by every OpenXPKI database driver. It
       defines some standard attributes	which represent	database connection
       parameters of the same name (not	all are	required for every DBMS).
       Furthermore it requires the consuming class to implement	certain
       methods.

   Writing an own driver
       If you have a DBMS that is not yet supported by OpenXPKI	you can	write
       and use a new driver without changing existing code. The	only
       requirement is that there is a DBI driver for your DBMS (look for it on
       MetaCPAN
       <https://metacpan.org/search?q=DBD%3A%3A&search_type=modules>).

       To connect OpenXPKI to your (not	yet supported) DBMS follow these
       steps:

       1. Write	a driver class in the "OpenXPKI::Server::Database::Driver::*"
       namespace that consumes the following Moose roles:
	   o   OpenXPKI::Server::Database::Role::SequenceSupport if your DBMS
	       has native support for sequences,

	   o   OpenXPKI::Server::Database::Role::SequenceEmulation otherwise.

	   o   OpenXPKI::Server::Database::Role::MergeSupport if your DBMS has
	       native support for some form of an SQL MERGE query (="REPLACE"
	       = "UPSERT" = "INSERT or UPDATE"),

	   o   OpenXPKI::Server::Database::Role::MergeEmulation	otherwise.

	   o   OpenXPKI::Server::Database::Role::Driver

	   ... and implement the methods that these roles require.

       2. Reference your driver	class by it's driver name (the last part after
       *::Driver::, case sensitive) in your configuration file.
       3. Submit your code to the OpenXPKI team	:)

Attributes
       o   name	- Database name	(Str, required)

       o   namespace - Schema/namespace	that will be added as table prefix in
	   all queries.	Could e.g. be used to store multiple OpenXPKI
	   installations in one	database (Str, optional)

       o   host	- Database host: IP or hostname	(Str, optional)

       o   port	- Database TCP port (Int, optional)

       o   user	- Database username (Str, optional)

       o   passwd - Database password (Str, optional)

Methods
       Please note that	the following methods are implemented in the driver
       class that consumes this	Moose role.

   dbi_driver
       Returns the DBI compliant case sensitive	driver name (Str).

   dbi_dsn
       Returns the DSN that is passed to "connect" in DBI (Str).

   dbi_connect_params
       Returns optional	parameters that	are passed to "connect"	in DBI
       (HashRef).

   dbi_on_connect_do
       Returns optional	commands to be executed	after connecting to the
       database	(ArrayRef or Str).

   sqlam_params
       Returns optional	parameters that	are passed to "new" in
       SQL::Abstract::More (HashRef).

   next_id
       Returns the next	insert id, i.e.	the value of the given sequence	(Int).

       Parameters:

       o   $dbi	- OpenXPKI database handler ("OpenXPKI::Server::Database",
	   required)

       o   $seq	- SQL sequence whose next value	shall be returned (Str,
	   required)

   merge_query
       Builds a	MERGE query (or	emulates it by either an INSERT	or an UPDATE
       query) and returns a OpenXPKI::Server::Database::Query object which
       contains	SQL string and bind parameters.

       Parameters:

       o   $dbi	- the OpenXPKI::Server::Database instance

       o   $into - Table name including	schema (if applicable) (Str, required)

       o   $set	- Columns that are always set (INSERT or UPDATE). Hash with
	   column name / value pairs.

       o   $set_once - Columns that are	only set on INSERT (additional to
	   those in the	"where"	parameter. Hash	with column name / value
	   pairs.

       o   $where - WHERE clause specification that must contain the PRIMARY
	   KEY columns and only	allows "AND" and "equal" operators: "<{	col1
	   =" val1, col2 => val2 }>> (HashRef)

perl v5.24.1			  2OpenXPKI::Server::Database::Role::Driver(3)

Name | Synopsis | Description | Attributes | Methods

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=OpenXPKI::Server::Database::Role::Driver&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help