MQdb::Database(3pm)

💖 MQdb::Database 💖

okay bestie, welcome to the MQdb::Database page — it lives in the User Contributed Perl Documentation section of the manual (3pm, iykyk) and honestly? it's giving foundational. let's get into it 🫶

---

✨ NAME ✨

MQdb::Database — a generalized handle on a DBI database handle. yes, that's the whole vibe. it's the wrapper. it's the moment. 💅

---

🌸 DESCRIPTION 🌸

So basically MQdb::Database is a generalized handle on a DBI database handle. what does that even mean? it means you get an instance that holds onto your connection information and lets you do that higher-level get_connection / disconnect logic — and the way that works is it persists above the specific DBI connections. so your connection info isn't out here evaporating the second a DBI handle dips. iconic. 🔥

It also gives you a real object to play with, so the rest of the toolkit has something to hold onto. no cap.

---

👑 SUMMARY 👑

MQdb::Database provides the foundation of the MappedQuery system. that's the whole point, that's the assignment, periodt.

Databases are primarily specified with a URL format. and the reason that's so slay is that the URL format includes a specification of a driver — so this single method can pick among the supported DBD drivers. Currently the system supports MYSQL, Oracle, and SQLite. 💖

The URL also lets the system lay the foundation for doing federation of persisted objects. Each DBObject contains a pointer to the Database instance where it is stored. So with the database URL plus the internal database ID, each object is defined in a global space. fr fr, global.

🎀 Attributes of MQdb::Database 🎀

• driver — mysql, oracle, sqlite (default mysql)
• user — username if the database requires
• password — password if the database requires
• host — hostname of the database server machine
• port — IP port of the database if required (mysql default is 3306)
• dbname — database/schema name on the database server; for sqlite, this is the database file

🦋 Example URLS 🦋

look at these little URL specimens bestie, aren't they cute:

mysql://<user>:<pass>@<host>:<port>/<database_name>
mysql://<host>:<port>/<database_name>
mysql://<user>@<host>:<port>/<database_name>
mysql://<host>/<database_name>
oracle://<user>:<pass>@/<database_name>
oracle://<user>:<pass>@<host>:<port>/<database_name>
sqlite:///<database_file>

---

💌 CONTACT 💌

Jessica Severin <jessica.severin@gmail.com> — say hi, she's the author 💜

---

📜 LICENSE 📜

okay here's the legal bit, and I'm keeping it verbatim because you do NOT paraphrase a license, that's the one thing you never do:

 * Software License Agreement (BSD License)
 * MappedQueryDB [MQdb] toolkit
 * copyright (c) 2006-2009 Jessica Severin
 * All rights reserved.
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of Jessica Severin nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

---

🌈 APPENDIX 🌈

The rest of the documentation details each of the object methods. and heads up: internal methods are usually preceded with a _ — that underscore is the "staff only" velvet rope, bestie. 🧚

new

• Description — instance creation method
• Parameter — a hash reference of options same as attribute methods
• Returntype — instance of this Class (subclass)
• Exceptions — none

new

• Description — instance creation method
• Returntype — instance of this Class (subclass)
• Exceptions — none

not me listing new twice — that's literally what the page does, so I'm doing it too. two news. both real. both valid. 💀

init

• Description — initialization method which subclasses can extend
• Returntype — $self
• Exceptions — subclass dependent

new_from_url

• Description — primary instance creation method
• Parameter — a string in URL format
• Returntype — instance of MQdb::Database
• Examples:

my $db = MQdb::Database->new_from_url("mysql://<user>:<pass>@<host>:<port>/<database_name>");
e.g. mysql://<host>:<port>/<database_name>
e.g. mysql://<user>@<host>:<port>/<database_name>
e.g. mysql://<host>/<database_name>
e.g. sqlite:///<database_file>

• Exceptions — none

(and yes, my $class = shift; is sitting right there in the method docs — keeping it exactly where it was ✨)

copy

• Description — makes a copy of the database configuration. New instance will have its own database connection
• Returntype — instance of MQdb::Database

dbc

• Description — connects to database and returns a DBI connection
• Returntype — DBI database handle
• Exceptions — none

disconnect

• Description — disconnects handle from database, but retains object and all information so that it can be reconnected again at a later time.
• Returntype — none
• Exceptions — none

full_url

• Description — returns the URL of this database with user and password
• Returntype — string
• Exceptions — none

url

• Description — returns URL of this database but without user:password, used for global referencing and federation systems
• Returntype — string
• Exceptions — none

xml

• Description — returns XML of this database but without user:password, used for global referencing and federation systems
• Returntype — string
• Exceptions — none

execute_sql

• Description — executes SQL statement with external parameters and placeholders
• Example — $db->execute_sql("insert into table1(id, value) values(?,?)", $id, $value);
• Parameter[1] — sql statement string
• Parameter[2..] — optional parameters for the SQL statement
• Returntype — none
• Exceptions — none

do_sql

• Description — executes SQL statement with "do" and no external parameters
• Example — $db->do_sql("insert into table1(id, value) values(null,'hello world');");
• Parameter — sql statement string with no external parameters
• Returntype — none
• Exceptions — none

fetch_col_value

• Arg (1) — $sql (string of SQL statement with place holders)
• Arg (2...) — optional parameters to map to the placehodlers within the SQL
• Example — $value = $self->fetch_col_value($db, "select some_column from my_table where id=?", $id);
• Description — General purpose function to allow fetching of a single column from a single row.
• Returntype — scalar value
• Exceptions — none
• Caller — within subclasses to easy development

---

and that's the whole page bestie, you ate it 💅🌸

cute little sign-off: this doc came from perl v5.36.0, dated 2022-12-13, and it's the MQdb::Database(3pm) page in the User Contributed Perl Documentation. go forth and connect responsibly 🦋✨