"use strict";(self.webpackChunkdocusaurus=self.webpackChunkdocusaurus||[]).push([[468],{8350:(e,s,r)=>{r.r(s),r.d(s,{assets:()=>l,contentTitle:()=>c,default:()=>x,frontMatter:()=>i,metadata:()=>n,toc:()=>a});const n=JSON.parse('{"id":"classes/instance","title":"Instance","description":"Handles connection data and serves as the gateway for performing queries.","source":"@site/docs/classes/instance.md","sourceDirName":"classes","slug":"/classes/instance","permalink":"/awSQL/classes/instance","draft":false,"unlisted":false,"tags":[],"version":"current","sidebarPosition":2,"frontMatter":{"sidebar_position":2},"sidebar":"defaultSidebar","previous":{"title":"awSQL","permalink":"/awSQL/classes/awsql"},"next":{"title":"Select","permalink":"/awSQL/classes/select"}}');var t=r(4848),d=r(8453);const i={sidebar_position:2},c="Instance",l={},a=[{value:"Methods",id:"methods",level:2},{value:"connect()",id:"connect",level:3},{value:"destroy()",id:"destroy",level:3},{value:"queryRaw()",id:"queryraw",level:3},{value:"getDatabases()",id:"getdatabases",level:3},{value:"selectDatabase()",id:"selectdatabase",level:3},{value:"getTables()",id:"gettables",level:3},{value:"Query Builders",id:"query-builders",level:3},{value:"Database &amp; Table Management",id:"database--table-management",level:3},{value:"Structure Management",id:"structure-management",level:3},{value:"Utility Methods",id:"utility-methods",level:3}];function h(e){const s={a:"a",admonition:"admonition",code:"code",em:"em",h1:"h1",h2:"h2",h3:"h3",header:"header",hr:"hr",li:"li",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,d.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(s.header,{children:(0,t.jsx)(s.h1,{id:"instance",children:"Instance"})}),"\n",(0,t.jsx)(s.p,{children:"Handles connection data and serves as the gateway for performing queries."}),"\n",(0,t.jsxs)(s.p,{children:["Instances can be managed globally via ",(0,t.jsx)(s.a,{href:"../classes/awsql",children:"awSQL"}),"."]}),"\n",(0,t.jsx)(s.hr,{}),"\n",(0,t.jsx)(s.h2,{id:"methods",children:"Methods"}),"\n",(0,t.jsx)(s.hr,{}),"\n",(0,t.jsx)(s.h3,{id:"connect",children:"connect()"}),"\n",(0,t.jsxs)(s.p,{children:[(0,t.jsx)(s.code,{children:"Promise"})," \u2192 () \u2192 ",(0,t.jsx)(s.strong,{children:"String"})]}),"\n",(0,t.jsx)(s.p,{children:"Establishes a connection to the database."}),"\n",(0,t.jsx)(s.admonition,{title:"Possible Errors",type:"warning",children:(0,t.jsx)(s.p,{children:"Throws an error if the connection fails."})}),"\n",(0,t.jsx)(s.p,{children:(0,t.jsx)(s.strong,{children:"Returns"})}),"\n",(0,t.jsxs)(s.p,{children:["\u2192 ",(0,t.jsx)(s.strong,{children:"String"})," - Connection confirmation in the format: ",(0,t.jsx)(s.code,{children:'"Connected to host with user user"'})]}),"\n",(0,t.jsx)(s.hr,{}),"\n",(0,t.jsx)(s.h3,{id:"destroy",children:"destroy()"}),"\n",(0,t.jsxs)(s.p,{children:["\u2192 () \u2192 ",(0,t.jsx)(s.strong,{children:"true"})]}),"\n",(0,t.jsx)(s.p,{children:"Destroys the connection and releases resources."}),"\n",(0,t.jsx)(s.p,{children:(0,t.jsx)(s.strong,{children:"Returns"})}),"\n",(0,t.jsxs)(s.p,{children:["\u2192 ",(0,t.jsx)(s.strong,{children:"true"})," - Always returns ",(0,t.jsx)(s.code,{children:"true"})," unless an error occurs."]}),"\n",(0,t.jsx)(s.hr,{}),"\n",(0,t.jsx)(s.h3,{id:"queryraw",children:"queryRaw()"}),"\n",(0,t.jsxs)(s.p,{children:[(0,t.jsx)(s.code,{children:"async"})," \u2192 (",(0,t.jsx)(s.code,{children:"queryString"})," = ",(0,t.jsx)(s.strong,{children:"String"}),", ",(0,t.jsx)(s.code,{children:"values"}),"? = ",(0,t.jsx)(s.strong,{children:"Array"}),"<",(0,t.jsx)(s.strong,{children:"any"}),">) \u2192 ",(0,t.jsx)(s.strong,{children:"any"})]}),"\n",(0,t.jsx)(s.p,{children:"Executes a raw SQL query."}),"\n",(0,t.jsx)(s.admonition,{title:"Security Tip",type:"tip",children:(0,t.jsxs)(s.p,{children:["Use ",(0,t.jsx)(s.code,{children:"?"})," placeholders and pass values seperately to prevent SQL injection."]})}),"\n",(0,t.jsx)(s.p,{children:(0,t.jsx)(s.strong,{children:"Parameters"})}),"\n",(0,t.jsxs)(s.table,{children:[(0,t.jsx)(s.thead,{children:(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.th,{children:"Parameter"}),(0,t.jsx)(s.th,{children:"Type"}),(0,t.jsx)(s.th,{children:"Description"})]})}),(0,t.jsxs)(s.tbody,{children:[(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"queryString"})}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.strong,{children:"String"})}),(0,t.jsx)(s.td,{children:"SQL query to execute."})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"values"})}),(0,t.jsxs)(s.td,{children:[(0,t.jsx)(s.strong,{children:"Array"}),"<",(0,t.jsx)(s.strong,{children:"any"}),">"]}),(0,t.jsxs)(s.td,{children:["Values for placeholders (",(0,t.jsx)(s.code,{children:"?"}),"), in left-to-right order."]})]})]})]}),"\n",(0,t.jsx)(s.p,{children:(0,t.jsx)(s.strong,{children:"Returns"})}),"\n",(0,t.jsxs)(s.p,{children:["\u2192 ",(0,t.jsx)(s.strong,{children:"any"})," - Query Result"]}),"\n",(0,t.jsx)(s.hr,{}),"\n",(0,t.jsx)(s.h3,{id:"getdatabases",children:"getDatabases()"}),"\n",(0,t.jsxs)(s.p,{children:[(0,t.jsx)(s.code,{children:"async"})," \u2192 (",(0,t.jsx)(s.code,{children:"excludeSchema"}),"? = ",(0,t.jsx)(s.strong,{children:"Boolean"}),") \u2192 ",(0,t.jsx)(s.strong,{children:"Array"}),"<",(0,t.jsx)(s.strong,{children:"String"}),">"]}),"\n",(0,t.jsx)(s.p,{children:"Retrieves a list of databases accessible to the user."}),"\n",(0,t.jsx)(s.p,{children:(0,t.jsx)(s.strong,{children:"Parameters"})}),"\n",(0,t.jsxs)(s.table,{children:[(0,t.jsx)(s.thead,{children:(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.th,{children:"Parameter"}),(0,t.jsx)(s.th,{children:"Type"}),(0,t.jsx)(s.th,{children:"Description"})]})}),(0,t.jsx)(s.tbody,{children:(0,t.jsxs)(s.tr,{children:[(0,t.jsxs)(s.td,{children:[(0,t.jsx)(s.code,{children:"excludeSchema"})," ",(0,t.jsx)(s.strong,{children:"option"})]}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.strong,{children:"Boolean"})}),(0,t.jsxs)(s.td,{children:["Excludes ",(0,t.jsx)(s.code,{children:"information_schema"})," if ",(0,t.jsx)(s.code,{children:"true"})]})]})})]}),"\n",(0,t.jsx)(s.p,{children:(0,t.jsx)(s.strong,{children:"Returns"})}),"\n",(0,t.jsxs)(s.p,{children:["\u2192 ",(0,t.jsx)(s.strong,{children:"Array"}),"<",(0,t.jsx)(s.strong,{children:"String"}),"> - List of database names."]}),"\n",(0,t.jsx)(s.p,{children:(0,t.jsx)(s.strong,{children:"Example"})}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-js",metastring:"showLineNumbers",children:"const databases = await instance.getDatabases();\r\nconsole.log(databases); // ['awSQL_dev','information_schema']\n"})}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-js",metastring:"title=\"Excluding default database 'information_schema'\" showLineNumbers",children:"const databasesWithoutSchema = await instance.getDatabases(true);\r\nconsole.log(databasesWithoutSchema); // ['awSQL_dev']\n"})}),"\n",(0,t.jsx)(s.hr,{}),"\n",(0,t.jsx)(s.h3,{id:"selectdatabase",children:"selectDatabase()"}),"\n",(0,t.jsxs)(s.p,{children:["\u2192 (",(0,t.jsx)(s.code,{children:"name"})," = ",(0,t.jsx)(s.strong,{children:"String"}),") \u2192 ",(0,t.jsx)(s.code,{children:"this"})]}),"\n",(0,t.jsx)(s.p,{children:"Sets a default database for future queries."}),"\n",(0,t.jsx)(s.p,{children:(0,t.jsx)(s.strong,{children:"Parameters"})}),"\n",(0,t.jsxs)(s.table,{children:[(0,t.jsx)(s.thead,{children:(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.th,{children:"Parameter"}),(0,t.jsx)(s.th,{children:"Type"}),(0,t.jsx)(s.th,{children:"Description"})]})}),(0,t.jsx)(s.tbody,{children:(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"name"})}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.strong,{children:"String"})}),(0,t.jsx)(s.td,{children:"The database to select"})]})})]}),"\n",(0,t.jsx)(s.p,{children:(0,t.jsx)(s.strong,{children:"Returns"})}),"\n",(0,t.jsxs)(s.p,{children:["\u2192 ",(0,t.jsx)(s.code,{children:"this"})]}),"\n",(0,t.jsx)(s.hr,{}),"\n",(0,t.jsx)(s.h3,{id:"gettables",children:"getTables()"}),"\n",(0,t.jsxs)(s.p,{children:["\u2192 (",(0,t.jsx)(s.code,{children:"database"}),"? = ",(0,t.jsx)(s.strong,{children:"String"}),") \u2192 ",(0,t.jsx)(s.strong,{children:"Array"}),"<",(0,t.jsx)(s.strong,{children:"String"}),">"]}),"\n",(0,t.jsx)(s.p,{children:"Retrieves a list of tables in the selected database."}),"\n",(0,t.jsx)(s.admonition,{title:"Possible Errors",type:"warning",children:(0,t.jsxs)(s.p,{children:["Requires ",(0,t.jsx)(s.code,{children:"options.multipleStatements"})," set to ",(0,t.jsx)(s.code,{children:"true"})," at instance creation."]})}),"\n",(0,t.jsx)(s.p,{children:(0,t.jsx)(s.strong,{children:"Returns"})}),"\n",(0,t.jsxs)(s.p,{children:["\u2192 ",(0,t.jsx)(s.strong,{children:"Array"}),"<",(0,t.jsx)(s.strong,{children:"String"}),">"]}),"\n",(0,t.jsx)(s.p,{children:(0,t.jsx)(s.strong,{children:"Example Usage"})}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-js",metastring:"showLineNumbers",children:'const tables = await instance.getTables("awSQL_dev");\r\nconsole.log(tables);\n'})}),"\n",(0,t.jsx)(s.pre,{children:(0,t.jsx)(s.code,{className:"language-json",metastring:'title="Result" showLineNumbers',children:"[\r\n  'Categories',\r\n  'Customers',\r\n  'Employees',\r\n  'OrderDetails',\r\n  'Orders',\r\n  'Products',\r\n  'Shippers',\r\n  'Suppliers'\r\n]\n"})}),"\n",(0,t.jsx)(s.hr,{}),"\n",(0,t.jsx)(s.h3,{id:"query-builders",children:"Query Builders"}),"\n",(0,t.jsx)(s.p,{children:"These methods return specialized query objects that allow for structured queries:"}),"\n",(0,t.jsxs)(s.table,{children:[(0,t.jsx)(s.thead,{children:(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.th,{children:"Method"}),(0,t.jsx)(s.th,{children:"Description"}),(0,t.jsx)(s.th,{children:"Returns"})]})}),(0,t.jsxs)(s.tbody,{children:[(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:".select(from, ...columns?)"})}),(0,t.jsxs)(s.td,{children:["Prepare a ",(0,t.jsx)(s.code,{children:"SELECT"})," query."]}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.a,{href:"./select",children:"Select"})})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:".insert(into)"})}),(0,t.jsxs)(s.td,{children:["Prepare an ",(0,t.jsx)(s.code,{children:"INSERT"})," query."]}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.a,{href:"./insert",children:"Insert"})})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:".delete(from)"})}),(0,t.jsxs)(s.td,{children:["Prepare a ",(0,t.jsx)(s.code,{children:"DELETE"})," query."]}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.a,{href:"./delete",children:"Delete"})})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:".update(table)"})}),(0,t.jsxs)(s.td,{children:["Prepare an ",(0,t.jsx)(s.code,{children:"UPDATE"})," query."]}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.a,{href:"./update",children:"Update"})})]})]})]}),"\n",(0,t.jsx)(s.hr,{}),"\n",(0,t.jsx)(s.h3,{id:"database--table-management",children:"Database & Table Management"}),"\n",(0,t.jsxs)(s.table,{children:[(0,t.jsx)(s.thead,{children:(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.th,{children:"Method"}),(0,t.jsx)(s.th,{children:"Description"}),(0,t.jsx)(s.th,{children:"Returns"})]})}),(0,t.jsxs)(s.tbody,{children:[(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:".dropDatabase(database)"})}),(0,t.jsxs)(s.td,{children:["Deletes an entire database (",(0,t.jsx)(s.em,{children:"requires admin privileges"}),")."]}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.a,{href:"../typedefs/okpacket",children:"OkPacket"})})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:".dropTable(table)"})}),(0,t.jsxs)(s.td,{children:["Deletes a table (",(0,t.jsx)(s.em,{children:"default database must be set"}),")."]}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.a,{href:"../typedefs/okpacket",children:"OkPacket"})})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:".createDatabase(name)"})}),(0,t.jsxs)(s.td,{children:["Creates a new database (",(0,t.jsx)(s.em,{children:"fails if it already exists"}),")."]}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.a,{href:"../typedefs/okpacket",children:"OkPacket"})})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:".createTable(name)"})}),(0,t.jsx)(s.td,{children:"Prepares a new table creation query."}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.a,{href:"./create-table",children:"CreateTable"})})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:".alterTable(name)"})}),(0,t.jsx)(s.td,{children:"Prepares a table modification query."}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.a,{href:"./alter-table",children:"AlterTable"})})]})]})]}),"\n",(0,t.jsx)(s.admonition,{title:"Potential Errors",type:"danger",children:(0,t.jsxs)(s.ul,{children:["\n",(0,t.jsxs)(s.li,{children:["Creating a database requires ",(0,t.jsx)(s.strong,{children:"admin privileges"}),"."]}),"\n",(0,t.jsxs)(s.li,{children:["Dropping a table reqeuires ",(0,t.jsx)(s.strong,{children:"a default database to be selected"}),"."]}),"\n"]})}),"\n",(0,t.jsx)(s.hr,{}),"\n",(0,t.jsx)(s.h3,{id:"structure-management",children:"Structure Management"}),"\n",(0,t.jsxs)(s.table,{children:[(0,t.jsx)(s.thead,{children:(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.th,{children:"Method"}),(0,t.jsx)(s.th,{children:"Description"}),(0,t.jsx)(s.th,{children:"Returns"})]})}),(0,t.jsxs)(s.tbody,{children:[(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:".createStructure()"})}),(0,t.jsx)(s.td,{children:"Creates a structure object."}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.a,{href:"./structure",children:"Structure"})})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:".getStructure(table, database?)"})}),(0,t.jsx)(s.td,{children:"Retrieves the structure of a table."}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.a,{href:"./structure",children:"Structure"})})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:".checkStructure(table, desiredStructure, database?)"})}),(0,t.jsx)(s.td,{children:"Compares a table's structure with the expected one."}),(0,t.jsxs)(s.td,{children:[(0,t.jsx)(s.code,{children:"{ errors: [], passed: [] }"})," ",(0,t.jsx)("br",{}),"\u2705 If errors.length === 0, the structure is correct."]})]})]})]}),"\n",(0,t.jsx)(s.hr,{}),"\n",(0,t.jsx)(s.h3,{id:"utility-methods",children:"Utility Methods"}),"\n",(0,t.jsxs)(s.table,{children:[(0,t.jsx)(s.thead,{children:(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.th,{children:"Method"}),(0,t.jsx)(s.th,{children:"Description"}),(0,t.jsx)(s.th,{children:"Returns"})]})}),(0,t.jsxs)(s.tbody,{children:[(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:".total(table)"})}),(0,t.jsxs)(s.td,{children:["Counts total rows in a table. (",(0,t.jsx)(s.em,{children:"Requires a default database"}),")."]}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"Number"})})]}),(0,t.jsxs)(s.tr,{children:[(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:".isConnected()"})}),(0,t.jsx)(s.td,{children:"Checks if the instance is connected."}),(0,t.jsx)(s.td,{children:(0,t.jsx)(s.code,{children:"Boolean"})})]})]})]}),"\n",(0,t.jsx)(s.hr,{})]})}function x(e={}){const{wrapper:s}={...(0,d.R)(),...e.components};return s?(0,t.jsx)(s,{...e,children:(0,t.jsx)(h,{...e})}):h(e)}},8453:(e,s,r)=>{r.d(s,{R:()=>i,x:()=>c});var n=r(6540);const t={},d=n.createContext(t);function i(e){const s=n.useContext(d);return n.useMemo((function(){return"function"==typeof e?e(s):{...s,...e}}),[s,e])}function c(e){let s;return s=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:i(e.components),n.createElement(d.Provider,{value:s},e.children)}}}]);