Class: JSS::DBConnection

Inherits:
Object
  • Object
show all
Includes:
Singleton
Defined in:
lib/jss-api/db_connection.rb,
lib/jss-api.rb

Overview

A mysql connection to the JSS database.

This is a singleton class, only one can exist at a time, and it is created, but not connected, automatically when the module loads.

Use it via the JSS::DB_CNX constant (for connection metadata) and the JSS::DB_CNX.db attribute (which contains the actual mysql query interface) for making queries

Direct MySQL access is minimal and discouraged, since it bypasses the API, and can be very dangerous. However, it’s necessary to overcome some limitations of the API or to access custom tables.

While a database connction isn’t required for most things, warnings will be sent to stderr when functionality is limited due to a lack of a database connection i.e. when JSS::DB_CNX.connected? == false

To make a connection with credentials, just call the #connect method thus:

JSS::DB_CNX.connect :server => 'server.company.com', :user => "user", :pw => "pw"

Other options include:

:db_name => which database to connect to, defaults to 'jamfsoftware'
:port => tcp port for connection to server, defaults to the standard mysql port.
:connect_timeout => seconds to wait before giving up on connection, defaults to 120
:read_timeout => seconds to wait before giving up on recieving data, defaults to 120
:write_timeout => seconds to wait before giving up on sending data, defaults to 120
:timeout => sets all three timeouts to the same value, defaults to 120

Calling JSS::DB_CNX.connect again will re-use any values not provided. but will create a new connection.

Constant Summary collapse

DEFAULT_DB_NAME =

The name of the JSS database on the mysql server

"jamfsoftware"
DFT_TIMEOUT =

give the connection a 120 second timeout, for really slow net connections (like… from airplanes)

120
DFT_SOCKET = 
'/var/mysql/mysql.sock'
SQL_DATE_FORMAT =

the strftime format for reading/writing dates in the db

"%Y-%m-%d %H:%M:%S"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ DBConnection

Returns a new instance of DBConnection.



104
105
106
107
108
 
# File 'lib/jss-api/db_connection.rb', line 104

def initialize ()
  require 'mysql'
  @mysql = Mysql.init
  @connected = false
end

Instance Attribute Details

#connect_timeout ⇒ Object (readonly)

Returns the value of attribute connect_timeout.



98
99
100
 
# File 'lib/jss-api/db_connection.rb', line 98

def connect_timeout
  @connect_timeout
end

#connected ⇒ Object (readonly) Also known as: connected?

Returns the value of attribute connected.



101
102
103
 
# File 'lib/jss-api/db_connection.rb', line 101

def connected
  @connected
end

#db_name ⇒ Object (readonly)

Returns the value of attribute db_name.



97
98
99
 
# File 'lib/jss-api/db_connection.rb', line 97

def db_name
  @db_name
end

#port ⇒ Object (readonly)

Returns the value of attribute port.



94
95
96
 
# File 'lib/jss-api/db_connection.rb', line 94

def port
  @port
end

#read_timeout ⇒ Object (readonly)

Returns the value of attribute read_timeout.



99
100
101
 
# File 'lib/jss-api/db_connection.rb', line 99

def read_timeout
  @read_timeout
end

#server ⇒ Object (readonly)

Returns the value of attribute server.



93
94
95
 
# File 'lib/jss-api/db_connection.rb', line 93

def server
  @server
end

#socket ⇒ Object (readonly)

Returns the value of attribute socket.



95
96
97
 
# File 'lib/jss-api/db_connection.rb', line 95

def socket
  @socket
end

#user ⇒ Object (readonly)

Returns the value of attribute user.



96
97
98
 
# File 'lib/jss-api/db_connection.rb', line 96

def user
  @user
end

#write_timeout ⇒ Object (readonly)

Returns the value of attribute write_timeout.



100
101
102
 
# File 'lib/jss-api/db_connection.rb', line 100

def write_timeout
  @write_timeout
end

Instance Method Details

#connect(args = {}) ⇒ true

Connect to the JSS MySQL database.

Parameters:

  • args (Hash) (defaults to: {}) —

    the keyed arguments for connection.

Options Hash (args):

  • :server (String) —

    Required, the hostname of the JSS API server

  • :port (Integer) —

    the port number to connect with, defaults to the default Mysql TCP port

  • :socket (String, Pathname) —

    when the server is ‘localhost’, the path to the connection socket.

  • :db_name (String) —

    the name of the database to use, defaults to ‘jamfsoftware’

  • :user (String) —

    Required, the mysql user to connect as

  • :pw (String, Symbol) —

    Required, the password for that user, or :prompt, or :stdin If :prompt, the user is promted on the commandline to enter the password for the :user. If :stdin#, the password is read from a line of std in represented by the digit at #, so :stdin3 reads the passwd from the third line of standard input. defaults to line 2, if no digit is supplied. see JSS.stdin

  • :connect_timeout (Integer) —

    the number of seconds to wait for an initial response, defaults to 120

  • :read_timeout (Integer) —

    the number of seconds before read-request times out, defaults to 120

  • :write_timeout (Integer) —

    the number of seconds before write-request times out, defaults to 120

  • :timeout (Integer) —

    used for any of the timeouts that aren’t explicitly set.

Returns:

  • (true) —

    the connection was successfully made.

Raises:



141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
 
# File 'lib/jss-api/db_connection.rb', line 141

def connect(args = {})

  # settings from config if they aren't in the args
  args[:server] ||= JSS::CONFIG.db_server_name
  args[:port] ||= JSS::CONFIG.db_server_port
  args[:socket] ||= JSS::CONFIG.db_server_socket
  args[:db_name] ||= JSS::CONFIG.db_name
  args[:user] ||= JSS::CONFIG.db_username
  args[:connect_timeout] ||= JSS::CONFIG.db_connect_timeout
  args[:read_timeout] ||= JSS::CONFIG.db_read_timeout
  args[:write_timeout] ||= JSS::CONFIG.db_write_timeout

  ### if one timeout was given, use it for all three
  args[:connect_timeout] ||= args[:timeout]
  args[:read_timeout] ||= args[:timeout]
  args[:write_timeout] ||= args[:timeout]

  ### if these weren't given, use the defaults
  args[:connect_timeout] ||= DFT_TIMEOUT
  args[:read_timeout] ||= DFT_TIMEOUT
  args[:write_timeout] ||= DFT_TIMEOUT
  args[:port] ||= Mysql::MYSQL_TCP_PORT
  args[:socket] ||= DFT_SOCKET
  args[:db_name] ||= DEFAULT_DB_NAME

  begin
    @mysql.close if connected?
  rescue Mysql::ClientError::ServerGoneError
    @connected = false
  end

  @server = args[:server]
  @port = args[:port]
  @socket = args[:socket]
  @mysql_name = args[:db_name]
  @user = args[:user]
  @connect_timeout = args[:connect_timeout]
  @read_timeout = args[:read_timeout]
  @write_timeout = args[:write_timeout]

  # make sure we have a user
  raise JSS::MissingDataError, "No JSS user specified, or listed in configuration." unless args[:user]

  # passwd from prompt, stdin, or args?
  raise JSS::MissingDataError, "Missing :pw (or :prompt/:stdin) for user '#{@user}'" unless args[:pw]

  @pw = if args[:pw] == :prompt
    JSS.prompt_for_password "Enter the password for the MySQL user #{@user}@#{args[:server]}:"
  elsif  args[:pw].is_a?(Symbol) and args[:pw].to_s.start_with?('stdin')
    args[:pw].to_s =~ /^stdin(\d+)$/
    line = $1
    line ||= 2
    JSS.stdin line
  else
    args[:pw]
  end



  @mysql = Mysql.init

  @mysql.options Mysql::OPT_CONNECT_TIMEOUT, @connect_timeout
  @mysql.options Mysql::OPT_READ_TIMEOUT, @read_timeout
  @mysql.options Mysql::OPT_WRITE_TIMEOUT, @write_timeout

  @mysql.connect @server, @user , @pw , @mysql_name, @port, @socket

  @connected = true
end

#db ⇒ Mysql

Returns The mysql database connection itself.

Returns:

  • (Mysql) —

    The mysql database connection itself

Raises:



214
215
216
217
 
# File 'lib/jss-api/db_connection.rb', line 214

def db
  raise JSS::InvalidConnectionError, "No database connection. Please use JSS::DB_CNX.connect" unless JSS::DB_CNX.connected?
  @mysql
end

#disconnect ⇒ Object

close the connection to the database it’ll have to be re-connected before using again



223
224
225
226
227
 
# File 'lib/jss-api/db_connection.rb', line 223

def disconnect
  @mysql.close if connected?
  @connected = false
  nil
end