Release 1.1 User's Guide and Reference
1. NuoDB API DataSource Reference Page...................................................................... 6 2. NuoDB Online Documentation v1.1........................................................................... 7 2.1 Overview........................................................................................... 8 2.1.1 About the NuoDB Architecture...................................................................... 10 2.1.2 Client Connections............................................................................... 12 2.1.3 System Requirements and Support.................................................................. 13 2.2 Installing NuoDB..................................................................................... 15 2.2.1 Linux Installation................................................................................ 16 2.2.2 Mac OS X Installation............................................................................ 18 2.2.3 Windows Installation............................................................................. 19 2.2.4 Installing a New License.......................................................................... 21 2.2.5 Uninstalling NuoDB.............................................................................. 23 2.3 Getting Started...................................................................................... 24 2.3.1 QuickStart..................................................................................... 25 2.3.1.1 Run the QuickStart.......................................................................... 26 2.3.1.1.1 Console > Explorer QS................................................................. 31 2.3.1.2 Execute SQL Commands.................................................................... 33 2.3.1.3 Web Console with the QuickStart.............................................................. 36 2.3.1.4 Copy of Execute SQL Commands.............................................................. 39 2.3.2 Using Command Line to Get Started................................................................. 45 2.3.2.1 Linux Command Line Usage.................................................................. 46 2.3.2.2 Windows Command Line Usage............................................................... 49 2.3.3 Developing with NuoDB........................................................................... 51 2.3.3.1 C++ with NuoDB Getting Started............................................................. 52 2.3.3.2 Java Hibernate with NuoDB Getting Started..................................................... 53 2.3.3.3 Java with NuoDB Getting Started............................................................. 55 2.3.3.4 JRuby with NuoDB Getting Started............................................................ 57 2.3.3.5 Sample Client Programs..................................................................... 60 2.3.4 Migrating Databases to NuoDB..................................................................... 61 2.4 APIs and Drivers..................................................................................... 62 2.4.1 NuoDB Drivers.................................................................................. 63 2.4.1.1 Available NuoDB Drivers..................................................................... 64 2.4.1.2 NuoDB Drivers on GitHub.................................................................... 66 2.4.1.3 JDBC Connections.......................................................................... 68 2.4.1.3.1 JDBC Connection Properties............................................................. 71 2.4.1.4 ODBC Connections......................................................................... 72 2.4.1.4.1 Example: Using ODBC and Microsoft Excel to Read a NuoDB Database........................... 73 2.4.1.4.2 Example: Using ODBC and Open Office Calc to Read a NuoDB Database......................... 77 2.4.1.5 NuoDB ADO.NET Driver..................................................................... 81 2.4.1.6 NuoDB PHP PDO Driver..................................................................... 88 2.4.1.7 NuoDB Zend Framework Adapter.............................................................. 90 2.4.2 APIs.......................................................................................... 91 2.4.2.1 C++ API Reference......................................................................... 92 2.4.2.2 JDBC API Reference........................................................................ 96 2.4.2.3 JDBC API Requirements..................................................................... 97 2.4.2.4 JDBC API Sample.......................................................................... 98 2.4.3 Understanding Client Connections.................................................................. 104 2.4.4 Programming................................................................................... 105 2.4.4.1 C++ with NuoDB........................................................................... 106 2.4.4.2 Java With NuoDB........................................................................... 107 2.5 Tools and Utilities.................................................................................... 108 2.5.1 Tools......................................................................................... 109 2.5.1.1 NuoDB Loader............................................................................. 110 2.5.1.2 NuoDB Manager........................................................................... 115 2.5.1.3 NuoDB Migrator............................................................................ 127 2.5.1.3.1 NuoDB Migration...................................................................... 129 2.5.1.3.2 Usage Examples for NuoDB............................................................. 131 2.5.1.3.3 MSSQL Migration...................................................................... 133 2.5.1.3.4 MySQL Migration...................................................................... 134 2.5.1.3.5 Oracle Migration....................................................................... 136
2.5.1.3.6 PostgreSQL Migration.................................................................. 138 2.5.1.3.7 Commands........................................................................... 140 2.5.1.4 NuoDB SQL CLI............................................................................ 147 2.5.1.4.1 nuosql Command...................................................................... 150 2.5.1.4.2 Batch Processing from the Command Line.................................................. 152 2.5.1.4.3 Selecting from the DUAL Table........................................................... 154 2.5.1.4.4 Metadata............................................................................ 155 2.5.1.4.5 Troubleshooting the NuoDB SQL Client.................................................... 156 2.5.1.5 NuoDB Web Console........................................................................ 157 2.5.1.5.1 Start the NuoDB Web Console........................................................... 163 2.5.1.5.2 Start a Database Using the Web Console................................................... 165 2.5.1.5.3 Specify Alert Settings................................................................... 169 2.5.1.5.4 webapp.properties..................................................................... 170 2.5.1.5.5 Storefront Demo....................................................................... 172 2.5.2 3rd Party Utilities................................................................................ 185 2.5.2.1 DbVisualizer for NuoDB JDBC Driver........................................................... 186 2.5.2.2 OLD_DbVisualizer for NuoDB JDBC Driver....................................................... 188 2.5.2.3 SQL Workbench/J.......................................................................... 191 2.5.2.4 SQuirreL Universal SQL..................................................................... 192 2.6 SQL Reference...................................................................................... 193 2.6.1 Summary of SQL Supported by NuoDB.............................................................. 194 2.6.2 SQL Reference Pages............................................................................ 202 2.6.2.1 ALTER DOMAIN........................................................................... 204 2.6.2.2 ALTER SEQUENCE........................................................................ 206 2.6.2.3 ALTER TABLE............................................................................. 207 2.6.2.4 ALTER TRIGGER.......................................................................... 208 2.6.2.5 ALTER USER............................................................................. 210 2.6.2.6 AUTOCOMMIT............................................................................ 211 2.6.2.7 COMMIT................................................................................. 213 2.6.2.8 CREATE DATABASE....................................................................... 214 2.6.2.9 CREATE DOMAIN.......................................................................... 215 2.6.2.10 CREATE INDEX.......................................................................... 217 2.6.2.11 CREATE PROCEDURE.................................................................... 218 2.6.2.12 CREATE ROLE........................................................................... 219 2.6.2.13 CREATE SCHEMA........................................................................ 220 2.6.2.14 CREATE SEQUENCE...................................................................... 221 2.6.2.15 CREATE TABLE.......................................................................... 222 2.6.2.16 CREATE TRIGGER........................................................................ 225 2.6.2.17 CREATE USER........................................................................... 227 2.6.2.18 CREATE VIEW........................................................................... 228 2.6.2.19 DELETE................................................................................. 230 2.6.2.20 DROP DATABASE........................................................................ 231 2.6.2.21 DROP DOMAIN........................................................................... 232 2.6.2.22 DROP INDEX............................................................................. 233 2.6.2.23 DROP PROCEDURE....................................................................... 234 2.6.2.24 DROP ROLE............................................................................. 235 2.6.2.25 DROP SCHEMA.......................................................................... 236 2.6.2.26 DROP SEQUENCE........................................................................ 238 2.6.2.27 DROP TABLE............................................................................ 239 2.6.2.28 DROP TRIGGER.......................................................................... 240 2.6.2.29 DROP USER............................................................................. 241 2.6.2.30 DROP VIEW............................................................................. 242 2.6.2.31 EXPLAIN................................................................................ 244 2.6.2.32 GRANT................................................................................. 246 2.6.2.33 INSERT................................................................................. 248 2.6.2.34 RELEASE............................................................................... 250 2.6.2.35 REPLACE............................................................................... 251 2.6.2.36 REVOKE................................................................................ 254 2.6.2.37 ROLLBACK.............................................................................. 255 2.6.2.38 SAVEPOINT............................................................................. 257
2.6.2.39 SELECT................................................................................. 260 2.6.2.40 SET.................................................................................... 266 2.6.2.41 SHOW.................................................................................. 268 2.6.2.42 START TRANSACTION.................................................................... 271 2.6.2.43 TRUNCATE TABLE........................................................................ 273 2.6.2.44 UPDATE................................................................................ 274 2.6.2.45 UPGRADE............................................................................... 275 2.6.2.46 USE.................................................................................... 277 2.6.3 SQL Language Elements and Transactions........................................................... 279 2.6.3.1 Datatypes Supported by NuoDB............................................................... 280 2.6.3.1.1 NuoDB Extensions..................................................................... 281 2.6.3.1.2 Standard SQL Datatype Keywords Supported................................................ 282 2.6.3.1.3 String Types.......................................................................... 285 2.6.3.1.4 Date, Time, and TimeStamp Conversions................................................... 286 2.6.3.1.5 Numeric Types........................................................................ 287 2.6.3.1.6 Datatypes [old] <HIDDEN>.............................................................. 290 2.6.3.2 Domains.................................................................................. 293 2.6.3.3 Operators and Operations.................................................................... 294 2.6.3.3.1 Logical Operators...................................................................... 295 2.6.3.3.2 Comparison Operators.................................................................. 296 2.6.3.3.3 Numeric Operations.................................................................... 304 2.6.3.4 Functions................................................................................. 307 2.6.3.4.1 CHAR_LENGTH Function............................................................... 309 2.6.3.4.2 SUBSTR Function..................................................................... 310 2.6.3.4.3 String Concatenation................................................................... 311 2.6.3.4.4 Date and Time Functions................................................................ 312 2.6.3.5 Expressions............................................................................... 315 2.6.3.5.1 Value Expressions..................................................................... 316 2.6.3.5.2 Conditional Expressions................................................................. 317 2.6.3.6 Object Privileges........................................................................... 318 2.6.3.7 Transactions and Isolation Levels.............................................................. 319 2.6.3.7.1 Relationship to java.sql Levels............................................................ 322 2.6.3.8 Internationalization and Localization............................................................ 323 2.6.3.9 Migration Notes............................................................................ 324 2.6.3.9.1 Distinction between a schema and a database............................................... 325 2.6.3.10 Compliance with SQL Standard............................................................... 326 2.6.3.11 Summary of SQL in NuoDB.................................................................. 333 2.6.4 Working With Triggers............................................................................ 341 2.6.5 SQL.......................................................................................... 344 2.7 Administration and Deployment.......................................................................... 346 2.7.1 Administration Tools............................................................................. 347 2.7.1.1 nuoagent................................................................................. 348 2.7.1.1.1 Commands to Start and Stop NuoDB Brokers and Agents...................................... 350 2.7.1.1.2 Starting and Stopping NuoDB Agents/Brokers, Web Console and Tray Monitor...................... 352 2.7.1.2 nuodb.................................................................................... 354 2.7.1.3 default.properties........................................................................... 358 2.7.2 Provisioning NuoDB.............................................................................. 363 2.7.2.1 Domain Administrators....................................................................... 364 2.7.2.2 Data Durability in NuoDB..................................................................... 365 2.7.2.3 Configuration Scenarios...................................................................... 367 2.7.2.3.1 Single Host Configuration............................................................... 368 2.7.2.3.2 Multiple Host Configuration.............................................................. 370 2.7.2.3.3 Amazon AWS......................................................................... 377 2.7.2.3.4 Multiple Data Centers and Cloud Regions................................................... 380 2.7.2.3.5 Automate Configuration Scenarios........................................................ 383 2.7.2.3.6 Using Amazon Web Services (AWS) Components............................................ 384 2.7.2.3.7 Microsoft Azure....................................................................... 395 2.7.2.4 Deployment Guidelines...................................................................... 399 2.7.2.4.1 Memory Management.................................................................. 400 2.7.2.4.2 High Availability (HA)................................................................... 401
2.7.2.4.3 Redundancy and Failover............................................................... 403 2.7.2.4.4 Hadoop Distributed File System (HDFS).................................................... 404 2.7.3 Troubleshooting NuoDB.......................................................................... 405 2.7.4 How To Scale Out a NuoDB Database............................................................... 408 2.7.5 Setup a Pilot Project on Multiple Hosts............................................................... 410 2.8 Glossary........................................................................................... 411 2.9 Release Notes....................................................................................... 413 2.9.1 Bug Fixes and Improvements...................................................................... 414 2.9.2 Known Bugs and Limitations....................................................................... 418 2.10 Acknowledgements.................................................................................. 421 2.11 Documentation Download............................................................................. 424
NuoDB API DataSource Reference Page JDBC API NuoDB Company Website Copyright 2013 NuoDB, Inc. All rights reserved SPACER
NuoDB Online Documentation v1.1 Welcome to the NuoDB Documentation! Installation and Getting Started Installing NuoDB Getting Started Overview SQL Materials SQL Reference SQL Language Elements and Transactions Programming and Administration APIs and Drivers Tools and Utilities Administration Tools
Overview A NuoDB system is designed for the configuration, deployment, and management of one or more databases on a cloud. From a conceptual point of view, a NuoDB system has three layers: a Management Layer, an SQL Layer, and a Data Layer. Each NuoDB database is associated with multiple processes running in each of these layers. Management Layer NuoDB Broker is a process that manages access to transaction engines and storage managers, independent of any particular database in the NuoDB system. By default, when you start a broker, the broker defines a NuoDB domain. NuoDB Agent is a process that manages NuoDB processes running on a particular computer. It starts and stops the NuoDB servers and communicates with a broker about the state of the system. NuoDB Manager is a text-based tool that you can use interactively or non-interactively to administer all aspects of NuoDB. NuoDB Web Console is a web based GUI administration tool running by default on; http:/ /localhost:8080 NuoDB System Tray is a GUI tool running on MAC OSX and Windows used to more easily launch the NuoDB Console, QuickStart Wizard and SQL Prompt. NuoDB Loader is a tool for importing and exporting data. SQL Layer NuoDB Transaction Engine provides access to a single database. It handles requests from clients, caches data, and coordinates transactions. There may be any number of transaction engines running on a single machine or across a cluster. Data Layer NuoDB Storage Manager is a process that provides durability of the data that it handles (for example by writing to disk). There may be any number of storage managers running on a single machine or across a cluster. Each storage manager is associated with exactly one database. Transaction engines and storage managers send asynchronous messages to each other while the system is running, in order to maintain copies of the current database. NuoDB Domain Lastly, a NuoDB Domain is a collection of NuoDB hosts that have been provisioned to work together to support one or more NuoDB databases. By default, when you start a broker, the broker defines a NuoDB domain. On most platforms the NuoDB installer will automatically start a broker when the OS starts. The following drawing is a conceptual illustration of the components that comprise a NuoDB system.
NuoDB Company Website Copyright 2013 NuoDB, Inc. All rights reserved SPACER
About the NuoDB Architecture Atomic Architecture, Latency and Storage Management NuoDB uses a unique architecture to achieve high performance, elasticity, scalability, and ACID compliance. Overview How does NuoDB handle the case of two transactions, running on parts of a database that are separated by a long-latency network, where each transaction can run and commit before either transaction can determine the existence of the other? How do storage managers that ensure durability also maintain consistency with each other and with the current state of the database? The NuoDB architecture makes it possible for transaction engines to maintain a copy of a database in memory, and for storage managers to stay synchronized with each other and with the transaction engines. All elements of a NuoDB database (data, indexes, metadata, and transaction state) are maintained in objects called atoms, which are of various types. The transaction manager atom (TMA) tracks the start events and commit events of all transactions in the system. Instances of the TMA receive and send messages to and from other TMAs, and to and from TEs and SMs. Each TE and each SM has a TMA instance. Transactions A NuoDB client application starts a transaction by recording a start event on a TE, which is referred to as the local TE. Similarly, when the transaction completes, the TE records a transaction end event. All TEs record all start and end events, making it possible for all transactions to be visible across the database. All TEs for a particular database communicate with each other by means of batched, asynchronous messages; messages about transaction state changes require no acknowledgement. When two transactions are operating independently (for example, inserting values into different tables) they do not communicate at all. How Conflicts Are Resolved Conflicts can occur on specific pieces of data, such as trying to update to the same record, or inserting the same values into unique indexes. If multiple copies of an atom are in circulation, and there is a conflict, a single instance of the atom is designated as the atom chairman. The atom chairman acts as referee and resolves the conflict of operations on data. The steps in this kind of conflict resolution are as follows: The local records or index atom instance sends a change request to the records or index atom chairman. The chairman receives change requests and determines if there is a conflict. During this communication process, each change is stalled. Consequently the transaction thread stalls until the atom chairman responds. If the change does not conflict with concurrent changes the transaction proceeds. Commit Protocol NuoDB database administrators can set a minimum level of durability for a database, and application developers can require a higher level of durability for specific applications. The commit protocol is specified as a command line option. The remote commit with journaling protocol guarantees that at least one SM has copies of all of a transaction's changes before the transaction commits. The following list describes the steps in a commit process: 1. 2. 3. 4. The transaction issues a commit request to the TE it is connected to (which is the local TE). The local TE sends a pre-commit message to the TMAs on SMs. The SMs receive the pre-commit message and each one: Flushes its replication message journal, using direct I/O Sends a "CommitACK" message to the TMA on the local TE. The TMA on the local TE: Receives at least one "CommitACK" message Sends a "committed" message to all other TMAs Tells its TE that it can respond to the transaction saying its commit succeeded. Because the commit sequence is critical to performance, the messages are not batched, but sent immediately. This sequence guarantees that all changes made by the committed transaction are on durable storage in at least one place. If all the SMs serving the database fail simultaneously, applying the journaled replication message to the archived atoms restores all changes made by transactions that had committed before the catastrophe. Applications or databases with higher durability requirements can require a commit
protocol, which requires receiving "commit received" messages from two SMs. NuoDB Company Website Copyright 2013 NuoDB, Inc. All rights reserved SPACER
Client Connections The following illustration shows a simple NuoDB database system and a client that wants to connect to it. The steps in the process shown in this conceptual illustration are as follows: 1. An application that seeks to connect to the database calls to the broker on Host A. 2. 3. Because the Broker communicates with all Agents in the Domain it knows which Transaction Engines are available and determines the best transaction engine for the application. The broker communicates back to the client that it should connect to the Transaction Engine on Host B. Once the Application knows which Host and Transaction Engine to communicate with, it will no longer communicate with the Broker. The client connects to the Transaction Engine on Host B. About Client Connections and Transaction Engines NuoDB distributes new requests for transactions from a client application to existing transaction engines that are connected to the client application. There is no mechanism for redistributing existing connections when a new transaction engine starts. You must explicitly establish a new connection from the client application and send it to the newly started transaction engine. If you add a transaction engine process while client applications are connected to transaction engines that are already running, and you want to have the same number of connections, and you want to balance the connections among all transaction engines, you must explicitly disconnect the existing client connections and reconnect clients to all transaction engines after you start the new transaction engine. NuoDB Company Website Copyright 2013 NuoDB, Inc. All rights reserved SPACER
System Requirements and Support NuoDB runs on Linux, Mac OS X, and Windows, and requires the Java SDK. Supported Operating Systems Ubuntu 11.10 and 12.x RHEL 5.9 and 6.x Linux (x64) SuSe Linux Enterprise Server 11 sp2 opensuse 12.x Amazon Basic EC2 MAC OS X 10.7.x or later (x64) Windows (x64) 7 or later note: Client support only for x32 Additional Software Requirements NuoDB requires Java 1.6 or later, and has been tested using the following software: Oracle Java 1.6 MAC JDK 1.6 Open JDK 1.6 On Windows (x64), Java must also be (x64). 3rd Party Software NuoDB will install Jetty as the embedded web server for NuoConsole:\ Jetty 8.1 Minimum Recommended Hardware CPU Memory Dual Core x86_64, 1.6GHz 4 GB Unsupported Software NuoDB does not support g++ on Windows NuoDB Ruby drivers have not been tested on Windows NuoDB Go driver is not supported NuoDB Perl driver is not supported
NuoDB Company Website Copyright 2013 NuoDB, Inc. All rights reserved SPACER
Installing NuoDB NuoDB is supported on and provides installation packages multiple operating systems. Please select your platform of choice below for further details. System Requirements and Support Linux Installation Mac OS X Installation Windows Installation Installing a New License Bug Fixes and Improvements Known Bugs and Limitations NuoDB Company Website Copyright 2013 NuoDB, Inc. All rights reserved SPACER
Linux Installation To install and add new users you must have write access to the /opt directory. RPM Installation Run the RedHat Package Manager (RPM) using the NuoDB package $ rpm --install nuodb-1.1.linux.x64.rpm Installation Details Installation Directory Path Variable /opt/nuodb /opt/nuodb/bin NuoDB Broker Running Using options from the default.properties file Web Console Running http://localhost:8080 License 2 Hosts DEB Installation Run the Debian package utility, dpkg: dpkg --i nuodb-1.1.linux.x64.deb Installation Details Installation Directory Path Variable /opt/nuodb /opt/nuodb/bin NuoDB Broker Running Using options from the default.properties file Web Console Running http://localhost:8080 License 2 Hosts TAR.GZ Installation Copy the compressed file and expand it to the install directory you wish to use: $ sudo cp nuodb-1.1.linux.x64.tar.gz /opt/ $ sudo tar -zxvf /opt/nuodb-1.1.linux.x64.tar.gz Configure your environment variable. Add $NUODB_ROOT /nuodb/bin to the PATH, where $NUODB_ROOT is where you installed the product.
$ export PATH=$PATH:/opt/nuodb/bin Optionally, use init.d scripts to start NuoDB processes. NuoDB provides a sample init.d script. To experiment with the NuoDB SQL client and a sample NuoDB database see the QuickStart. You can also get started just by using the command line: see Linux Command Line Usage. Installation Details Installation Directory Path Variable No Default Set during Installation No Default must be set manually NuoDB Broker Not Running Must be started manually Web Console Not Running Must be started manually http://localhost:8080 License 2 Hosts NuoDB Company Website Copyright 2013 NuoDB, Inc. All rights reserved SPACER
Mac OS X Installation To install NuoDB you must have write access to the /opt directory. Wizard Installation NuoDB can be installed by double-clicking the.pkg file and walking through the installation prompts. Once the installation is complete, the QuickStart Wizard will appear. The OS X Gatekeeper feature may cause an "Unidentified Developer" error to be thrown when downloading or installing apps that were not purchased via the Mac App Store. If you experience this behavior use the following to resolve the error: 1. Goto: System Preferences > Security and Privacy > General 2. Select the "Anywhere" radio button for "Allow applications downloaded from:" Command Line Installation The Command Line installation of NuoDB allows you bypass the installation Wizard and install using all of the default options. Please note that the QuickStart Wizard will appear once the Command Line installation is complete. $ sudo installer -pkg ~/Downloads/nuodb-1.1.macosx.x64.pkg -target / Installation Details The following are the default installation details, regardless of the installation method (Wizard or Command Line). Installation Directory Path Variable /opt/nuodb /opt/nuodb/bin NuoDB Broker Running Using options from the default.properties file Web Console Running http://localhost:8080 Default License 2 Hosts Post Installation Once the installation is complete you will be prompted to run the QuickStart Wizard which will introduce you to the elements of the NuoDB Architecture and automatically start a test database. You can choose to cancel the QuickStart Wizard, and in that case we would suggest that you review the Linux Command Line Usage for examples of how to start a database manually. NuoDB Company Website Copyright 2013 NuoDB, Inc. All rights reserved SPACER
Windows Installation Prerequisites Write permissions. To install NuoDB you must have write access to the C:\Program Files directory..net Framework v4 or later must be installed, or the NuoDB ADO.NET driver, which is part of the NuoDB install package, will not install. To verify you have it, look for it in the list of installed programs in Control Panel (Start > Control Panel > Programs > Programs and Features). If it's not installed, download and install.net Framework v4 before installing NuoDB. Important Previous versions of NuoDB 64-bit installations are automatically upgraded as part of the NuoDB v1.1 installation process. 32-bit installations however are not, and require the user to first uninstall the previous version before installing NuoDB v1.1. Wizard Installation NuoDB can be installed by double-clicking the.exe file and walking through the installation prompts. Once the installation is complete, the QuickStart Wizard launches. When you install NuoDB on Windows you may see a User Account Settings dialog indicating that the installer is about to make changes to the computer. Our installer is a signed as NuoDB, Inc. Silent Installer The silent installer suppresses all interactive dialog prompts and installs NuoDB to the default locations noted below. Command > nuodb-1.1.windows.x64.exe /S The installer does several things beyond unpacking the software, including: Sets up the proper registry entries for the NuoDB ODBC driver Checks that a valid version of Java is installed Installs and starts a broker as a Windows Service. Installation Details The following are the default installation details, regardless of the installation method (Wizard or Silent Install). Installation Directory Path Variable c:\program Files\nuodb c:\program Files\nuodb\bin NuoDB Broker Running Using options from the default.properties file Web Console Running http://localhost:8080 Default License 2 Hosts
Post Installation Once the installation is complete you will be prompted to run the QuickStart Wizard which will introduce you to the elements of the NuoDB Architecture and automatically start a test database. You can choose to cancel the QuickStart Wizard, and in that case we would suggest that you review the Windows Command Line Usage for examples of how to start a database manually. NuoDB Company Website Copyright 2013 NuoDB, Inc. All rights reserved SPACER
Installing a New License The Free License is limited to a domain of two hosts only. The following instruction will walk you through obtaining and installing a new license. Obtain a new license License Type Cost Notes Developer Free Requires online registration at the NuoDB WebSite Allows for unlimited hosts Not supported for production environments. Professional Priced Requires a purchase by contacting the Nuo DB Sales Organization Supported for production environments Regardless of how you obtain your new license, you will receive an email with your new license file as an attachment. Installation Steps Before you Begin You must have a Broker running to successfully install your new license. The following instruction assumes you are using default domain and password as defined in the etc/default.properties file. Save your License The license needs to be saved to and installed on the host running the Broker, only. There is no need to install the license to any other host in your NuoDB Domain. Start the Broker # By default, the NuoDB installation will automatically start a broker and domain for you unless you installed using the TAR.GZ files. UNIX $ java -jar /opt/nuodb/jar/nuoagent.jar & Windows > start java -jar "c:\program Files\nuodb\jar\nuoagent.jar" Start nuodbmanager
# Always use the nuodbmanager utility when administering your domain and database from the command line. UNIX $ java -jar /opt/nuodb/jar/nuodbmanager.jar --broker localhost --password bird Windows > java -jar "c:\program Files\nuodb\jar\nuodbmanager" --broker localhost --password bird Install your new license # The following command is for all platforms nuodb [domain] > apply domain license licensefile /path/to/your/license_file.txt Verify your new license # The following command is for all platforms nuodb [domain] > show domain license NuoDB Company Website Copyright 2013 NuoDB, Inc. All rights reserved SPACER
Uninstalling NuoDB To unistall NuoDB: Windows 7 Control Panel 1. 2. Navigate to Start > Control Panel > Programs > Uninstall a program Select NuoDB from the list of installed programs and click Unistall/Change. The NuodDB Uninstall dialog opens. 3. Click Uninstall to uninstall NuoDB. Windows Command Line Interface 1. Open a CMD window (Start > Run > cmd). Run the following commands: > cd C:\Program Files\NuoDB\ > uninstall nuodb-sh Linux/Mac OSX 1. Open a Terminal and run the following commands: $ cd /opt/nuodb $ sudo sh uninstall-nuodb.sh $ Password: $ This will uninstall NuoDB and remove ALL associated files and preferences. $ Do you wish to proceed with the uninstall? (Y/n): y $ Uninstalling NuoDB... $ NuoDB successfully uninstalled. NuoDB Company Website Copyright 2013 NuoDB, Inc. All rights reserved SPACER
Getting Started Get started with NuoDB by running a NuoDB startup script that creates a sample database for you to explore, or by creating your own database. Run a sample client that shows how to connect an application to a NuoDB database. QuickStart Using Command Line To Get Started Developing with NuoDB NuoDB Company Website Copyright 2013 NuoDB, Inc. All rights reserved SPACER
QuickStart Get started with NuoDB by running a NuoDB startup script that creates a domain, a database, and a sample schema. The script starts NuoDB Console and the NuoDB SQL client, so you can use NuoDB with a small sample project. Run the QuickStart Execute SQL Commands Use NuoDB Web Console to Explore the Domain NuoDB Company Website Copyright 2013 NuoDB, Inc. All rights reserved SPACER
Run the QuickStart Procedure to get the product up and running with a sample NuoDB database. The Quickstart runs as a part of the installation however, these instructions will guide you after the product is installed. This task is part of the NuoDB QuickStart, which offers an introduction to the basic features of NuoDB. Run the QuickStart Wizard Windows and Mac OS X Wizard 1. From the NuoDB System Tray select NuoDB Console. The NuoDB Console opens in a browser tab. Note Currently, there is no system tray available for Linux installations. To run the QuickStart manually on a Linux install, see Command-Line instructions in the next section 2. On the Console > Home tab, click Start QuickStart. 3. Leave the Domain Settings and Database Settings unchanged, and click Create Database to start a storage manager (SM), start a transaction engine (TM), create a schema, and import sample data into the database. The QuickStart database is created.
4. Once the database is created, click the Admin or Explorer link to login to the domain containing the database. 5. The Domain Login dialog appears. Accept the default Domain name and password credentials (domain, bird) and click Log in.
The Explorer link opens to the Console Explorer tab, showing the test database in the Data Hierarchy tree. Click here to expand... The Admin link opens to the Console Admin tab showing Domain Overview of the domain you are logged into. Click here to expand...
Run the QuickStart Command-Line The quickstart can also be executed form the command line. Running from the command line accomplishes the same steps as the visual quickstart and provides you with a SQL prompt for further exploring. LINUX/MAC $ /opt/nuodb/run-quickstart WINDOWS > c:\program Files\NuoDB\run-quickstart.cmd QuickStart Tasks On all platforms, running the Quickstart accomplishes the following: Configures your system path. Creates a domain (which is named domain) using the settings in the default.properties file. The initial administrator (with a user name of domain) has an initial password (bird), and a second domain administrator user is quickstart with a password of quickstart. Starts a NuoDB database, named test, with its storage repository in WINDOWS: \tmp\test_archive LINUX/MAC: /tmp/test_archive Creates sample schema (hockey). Creates a sample database (test). Imports data to the sample database from: WINDOWS: %\nuodb\samples\quickstart\bruins.csv LINUX/MAC: $/nuodb/samples/quickstart/bruins.csv Starts the NuoDB SQL client (nuosql), with user name and password of dba and goalie, respectively. Starts NuoDB Console as a process. By default it starts on http://localhost:8080. After the script finishes: Take a look at the remaining tasks in the Quick Start documentation to discover how you can experiment with the NuoDB SQL client, NuoDB Manager and NuoDB Console.
To understand the role of various NuoDB system components, look at the Overview topic. Other topics explain how to start a pilot project of your own, how to set up and administer a system on the cloud, and connect a client to NuoDB. NuoDB Company Website Copyright 2013 NuoDB, Inc. All rights reserved SPACER
Console > Explorer QS 1. Double-click the database. The Database Login dialog launches with the default username and password (dba, goalie). 2. If not already present, enter the username and password, and click Login. You are now logged into database as DBA. 3. To run a query against the database, click New. A tabbed New Query window opens. 4. Write a SQL query and click Execute Query. Note Unless the schema is selected in the Database Hierarchy, fully qualified table names must be used in SQL Explorer
4. queries, e.g., hockey.teams or system.connections. This is because the SQL Explorer uses the USE statement internally in the Database Hierarchy, and therefore its use in the Query window can produce SQL processing conflicts. Selecting a schema in the Database Hierarchy implements USE for your query. The query executes. NuoDB Company Website Copyright 2013 NuoDB, Inc. All rights reserved SPACER
Execute SQL Commands Start NuoSQL from the Command-Line To launch nuosql from the command line, open a terminal or command line window and cd to: Linux/Mac opt/nuodb/bin Windows C:\Program Files\nuodb\bin Then issue the following command. nuosql <DatabaseName>@<HostName> --user <UserName> --password <Password> Linux/Mac Example... Linux/Mac Command $ nuosql test@localhost --user dba --password goalie Linux/Mac Result Execute your SQL Commands Windows Example... Windows Command > cd "c:\program Files\nuodb\bin" > nuosql.exe test@localhost --user dba --password goalie Windows Result
Execute your SQL Commands Executing SQL Commands Once NuoSQL is started you can execute SQL commands as you normally would. More information regarding the NuoDB SQL Syntax can be found here and here. In the window where the SQL session is running issue the following command: SQL> SHOW TABLES; Tables in schema HOCKEY MASTER SCORING TEAMS MASTER, SCORING and TEAMS are the sample tables created when you execute the QuickStart. To see what is in the table, run the following: SQL> SELECT * FROM teams ORDER BY name; YEAR TMID CONFID DIVID RANK PLAYOFF G W L T OTL NAME ----- ----- ------- ------ ----- -------- -- -- -- -- ---- ------------------------------------- 1916 TOB 0 0 4 0 14 7 7 0 0 228th Battalion 1972 ALB 0 WW 5 0 78 38 37 3 0 Alberta Oilers 2010 AND WC PC 2 CQF 82 47 30 0 5 Anaheim Ducks <ETC> Type help to show a list of the NuoDB SQL client commands.
SQL> help ALTER DOMAIN ALTER SEQUENCE ALTER TABLE ALTER TRIGGER ALTER USER <ETC> Change definition of a domain (not yet implemented) Change definition of a sequence Change definition of a table Change definition of a trigger Change definition of a user Exit the NuoDB SQL client by typing quit at the SQL prompt: SQL> quit NuoDB Company Website Copyright 2013 NuoDB, Inc. All rights reserved SPACER
Web Console with the QuickStart Use NuoDB Web Console to view, analyze, and manage a domain. This example uses the domain created by running the Quick Start. Connect to the Web Console By default the NuoDB Web Console runs on port 8080 and the install packages will configure the Web Console to automatically run in the background. The examples shown here are based on the database that is created as a part of the QuickStart. If you have not run the QuickStart please see Run the QuickStart for information. 1. 2. Open a browser and go to: http://localhost:8080/console.html. Login using the following: a. b. Username: quickstart Password: quickstart Domain Overview The default view of the domain, will provide you with access to manage the domain and database resources. Select your Domain to install a new license. Select Database to Add/Remove databases from your Domain. Select Host to manage individual NuoDB processes.
View the Database View the current Test database by selecting database link. The Databases page will view information such as; Status of the database Transactions per second Number of Client Connections CPU and Memory usage Click the name of the database to view more details about the database processes and status. View Database Acitivity Regardless of the database view you are in there will always be a graphical Activity view in the Web Console window.
View Host Information To view information about the individual hosts in your domain, you must select host from the Domain Overview. Next Select the individual host you want to work with to view detailed information. NuoDB Company Website Copyright 2013 NuoDB, Inc. All rights reserved SPACER
Copy of Execute SQL Commands NuoDB is bundled with both a browser based and text based analysis and management tools for your NuoDB database. Launch SQL Explorer 1. Launch the following from your browser: http://localhost:8080/explorer.html 2. Login to your Domain. Note: this example uses the domain credentials for the QuickStart domain (quickstart / quickstart) 3. Select your database from the Database Hierarchy and supply your database level credentials. Note: this example uses the domain credentials for the QuickStart domain (dba / goalie) 4. Select "New" from the Database Hierarchy pane, to open a Query Tab and enter your SQL commands. 5. Go To Sample SQL Commands... Launch NuoSQL from the System Tray NuoSQL is the command line interface to the NuoDB SQL interface. Use the instruction below that matches your OS. OSX Tutorial... Select NuoDB SQL Prompt from the System Tray menu.
A Terminal window will open with the SQL> prompt. Sample SQL Commands... By default using the System Tray to launch the NuoDB SQL Prompt will attempt to connect to the test database that is created when the QuickStart is executed. If this database is not running you will receive an error similar to: Connection Failed: no NuoDB nodes are available for database "test@localhost" If you receive this error, simply run the QuickStart to start the database. Windows Tutorial... Select NuoDB SQL Prompt from the System Tray menu.
A CMD window will open with the SQL> prompt Sample SQL Commands... By default using the System Tray to launch the NuoDB SQL Prompt will attempt to connect to the test database that is created when the QuickStart is executed. If this database is not running you will receive an error similar to: Connection Failed: no NuoDB nodes are available for database "test@localhost" If you receive this error, simply run the QuickStart to start the database. Currently, the Linux installation of NuoDB does not have a System Tray integration. On Linux, you must launch NuoSQL from the command line (below). Start NuoSQL from the Command-Line You can also start NuoSQL directly from the command-line. NuoSQL Syntax
nuosql <DatabaseName>@<HostName> --user <UserName> --password <Password> Unix Example... Unix Command $ nuosql test@localhost --user dba --password goalie Unix Result Execute your SQL Commands Windows Example... Windows Command > cd "c:\program Files\nuodb\bin" > nuosql.exe test@localhost --user dba --password goalie Windows Result
Execute your SQL Commands Executing SQL Commands Once NuoSQL is started you can execute SQL commands as you normally would. More information regarding the NuoDB SQL Syntax can be found here and here. In the window where the SQL session is running issue the following command: SQL> SHOW TABLES; Tables in schema HOCKEY MASTER SCORING TEAMS MASTER, SCORING and TEAMS are the sample tables created when you execute the QuickStart. To see what is in the table, run the following: SQL> SELECT * FROM teams ORDER BY name; YEAR TMID CONFID DIVID RANK PLAYOFF G W L T OTL NAME ----- ----- ------- ------ ----- -------- -- -- -- -- ---- ------------------------------------- 1916 TOB 0 0 4 0 14 7 7 0 0 228th Battalion 1972 ALB 0 WW 5 0 78 38 37 3 0 Alberta Oilers 2010 AND WC PC 2 CQF 82 47 30 0 5 Anaheim Ducks <ETC> Type help to show a list of the NuoDB SQL client commands. SQL> help ALTER DOMAIN ALTER SEQUENCE ALTER TABLE ALTER TRIGGER ALTER USER <ETC> Change definition of a domain (not yet implemented) Change definition of a sequence Change definition of a table Change definition of a trigger Change definition of a user Exit the NuoDB SQL client by typing quit at the SQL prompt: SQL> quit