diff --git a/.gitignore b/.gitignore index f93d27b70..7db9747b8 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,7 @@ *.jar *.swp *.bak +*.ent *.versionsBackup dependency-reduced-pom.xml asm-9.7.jar diff --git a/Configure.pl b/Configure.pl index 6166ee4ce..68a1bdf97 100755 --- a/Configure.pl +++ b/Configure.pl @@ -415,7 +415,12 @@ sub search_maven_artifact { } print "Select number [0-" . $#docs . "]: "; my $choice = ; + unless (defined $choice) { + warn "No input received (not running interactively?). Defaulting to [0].\n"; + $choice = 0; + } chomp $choice; + $choice = 0 unless $choice =~ /^\d+$/ && $choice <= $#docs; return $docs[$choice]{id}; } @@ -510,12 +515,16 @@ sub score_jdbc_relevance { my $score = 0; # Higher score for JDBC indicators - $score += 5 if $doc->{g} =~ /jdbc/i; - $score += 5 if $doc->{a} =~ /jdbc/i; - $score += 3 if $doc->{g} =~ /database|mysql|postgresql|oracle|sqlserver/i; - $score += 3 if $doc->{a} =~ /database|mysql|postgresql|oracle|sqlserver/i; - $score += 2 if $doc->{latestVersion} =~ /jdbc/i; - $score += 4 if $doc->{c} =~ /Driver$/; + my $g = $doc->{g} // ''; + my $a = $doc->{a} // ''; + my $v = $doc->{latestVersion} // ''; + my $c = $doc->{c} // ''; + $score += 5 if $g =~ /jdbc/i; + $score += 5 if $a =~ /jdbc/i; + $score += 3 if $g =~ /database|mysql|postgresql|oracle|sqlserver/i; + $score += 3 if $a =~ /database|mysql|postgresql|oracle|sqlserver/i; + $score += 2 if $v =~ /jdbc/i; + $score += 4 if $c =~ /Driver$/; # Boost score based on download count $score += log($doc->{downloadCount} || 1); diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index b01a4256b..3dbb1f6cf 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -110,15 +110,12 @@ sudo dpkg -r perlonjava ```bash ./jperl -E 'print "Hello World"' ./jperl myscript.pl -CLASSPATH="jdbc-drivers/h2-2.2.224.jar" ./jperl myscript.pl ``` **Windows:** ```bash jperl -E "print 'Hello World'" jperl myscript.pl -set CLASSPATH=jdbc-drivers\h2-2.2.224.jar -jperl myscript.pl ``` ### Common Options @@ -132,18 +129,23 @@ jperl myscript.pl 1. Using Configure.pl: ```bash -./Configure.pl --search mysql-connector-java +./jperl Configure.pl --search mysql-connector-java ``` 2. Using Java classpath (shown in platform-specific examples above) ### Database Connection Example + +SQLite is bundled with PerlOnJava — no additional installation needed: + ```perl use DBI; -my $dbh = DBI->connect("jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1"); -$dbh->do("CREATE TABLE test (id INT, name VARCHAR(50))"); +my $dbh = DBI->connect("dbi:SQLite:dbname=:memory:", "", ""); +$dbh->do("CREATE TABLE test (id INTEGER PRIMARY KEY, name TEXT)"); ``` +For other databases, add JDBC drivers via CLASSPATH or Configure.pl (see below). + See [Database Access Guide](../guides/database-access.md) for detailed connection examples and supported databases. ## Build Notes @@ -165,33 +167,37 @@ See [Database Access Guide](../guides/database-access.md) for detailed connectio The `Configure.pl` script manages configuration settings and dependencies for PerlOnJava. +> **Tip:** Using `./jperl` to run Configure.pl is recommended because it includes +> built-in HTTPS support. System Perl may require additional modules +> (`IO::Socket::SSL`, `Net::SSLeay`) for the Maven Central search to work. + ### Common Tasks **View current configuration:** ```bash -./Configure.pl +./jperl Configure.pl ``` **Add JDBC driver (search):** ```bash -./Configure.pl --search mysql +./jperl Configure.pl --search mysql make # Rebuild to include driver ``` **Add JDBC driver (direct):** ```bash -./Configure.pl --direct com.h2database:h2:2.2.224 +./jperl Configure.pl --direct com.mysql:mysql-connector-j:8.2.0 make # Rebuild to include driver ``` **Update configuration:** ```bash -./Configure.pl -D perlVersion=v5.42.0 +./jperl Configure.pl -D perlVersion=v5.42.0 ``` **Upgrade all dependencies:** ```bash -./Configure.pl --upgrade +./jperl Configure.pl --upgrade ``` ### Available Options diff --git a/docs/guides/database-access.md b/docs/guides/database-access.md index ca0de9dd6..b435e4f4c 100644 --- a/docs/guides/database-access.md +++ b/docs/guides/database-access.md @@ -4,16 +4,18 @@ This guide explains how to use databases with PerlOnJava through the DBI module ## Quick Start +SQLite is bundled with PerlOnJava — no additional installation needed: + ```perl use DBI; -my $dbh = DBI->connect("jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1"); -$dbh->do("CREATE TABLE users (id INT, name VARCHAR(50))"); +my $dbh = DBI->connect("dbi:SQLite:dbname=:memory:", "", ""); +$dbh->do("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)"); ``` ## Adding JDBC Drivers -JDBC Database drivers can be added in two ways: +SQLite works out of the box. For other databases, JDBC drivers can be added in two ways: 1. Using Configure.pl: - The Configure script updates the build configuration to install the JDBC database drivers in the PerlOnJava jar file @@ -22,8 +24,8 @@ JDBC Database drivers can be added in two ways: Examples: ```bash -./Configure.pl --search mysql-connector-java -./Configure.pl --search aws-mysql-jdbc +./jperl Configure.pl --search mysql-connector-java +./jperl Configure.pl --search aws-mysql-jdbc ``` Then build with the drivers included: @@ -39,29 +41,33 @@ gradle clean build Unix/Linux/Mac: ```bash - CLASSPATH="jdbc-drivers/h2-2.2.224.jar" ./jperl myscript.pl + CLASSPATH="jdbc-drivers/mysql-connector-j-8.2.0.jar" ./jperl myscript.pl ``` Windows: ```bash - set CLASSPATH=jdbc-drivers\h2-2.2.224.jar + set CLASSPATH=jdbc-drivers\mysql-connector-j-8.2.0.jar jperl myscript.pl ``` Calling java directly with the classpath is also possible: ```bash - java --enable-native-access=ALL-UNNAMED -cp "jdbc-drivers/h2-2.2.224.jar:target/perlonjava-5.42.0.jar" org.perlonjava.app.cli.Main myscript.pl + java --enable-native-access=ALL-UNNAMED -cp "jdbc-drivers/mysql-connector-j-8.2.0.jar:target/perlonjava-5.42.0.jar" org.perlonjava.app.cli.Main myscript.pl ``` ## Database Connection Examples -### H2 Database +### SQLite (bundled) ```perl -# In-memory database -my $dbh = DBI->connect("jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1"); +# In-memory database (Perl DBI DSN format) +my $dbh = DBI->connect("dbi:SQLite:dbname=:memory:", "", ""); # File-based database -my $dbh = DBI->connect("jdbc:h2:file:/path/to/database"); +my $dbh = DBI->connect("dbi:SQLite:dbname=/path/to/database.db", "", ""); + +# JDBC URL format also works +my $dbh = DBI->connect("jdbc:sqlite::memory:"); +my $dbh = DBI->connect("jdbc:sqlite:/path/to/database.db"); ``` ### MySQL @@ -82,11 +88,6 @@ my $dbh = DBI->connect( ); ``` -### SQLite -```perl -my $dbh = DBI->connect("jdbc:sqlite:/path/to/database.db"); -``` - ### BigQuery ```perl my $dbh = DBI->connect( diff --git a/docs/reference/configure.md b/docs/reference/configure.md index c16513677..cd4a40eae 100644 --- a/docs/reference/configure.md +++ b/docs/reference/configure.md @@ -5,13 +5,18 @@ The `Configure.pl` script manages configuration settings and dependencies for Pe ## Synopsis ```bash -./Configure.pl [options] -./Configure.pl -D key=value -./Configure.pl --search keyword -./Configure.pl --direct group:artifact:version -./Configure.pl --upgrade +./jperl Configure.pl [options] +./jperl Configure.pl -D key=value +./jperl Configure.pl --search keyword +./jperl Configure.pl --direct group:artifact:version +./jperl Configure.pl --upgrade ``` +> **Tip:** `Configure.pl` can be run with either `./jperl` or `perl`. Using `./jperl` is +> recommended because it includes built-in HTTPS support, while system Perl may +> require additional modules (`IO::Socket::SSL`, `Net::SSLeay`) for the Maven +> Central search to work. + ## Options ### Help and Information @@ -20,7 +25,7 @@ The `Configure.pl` script manages configuration settings and dependencies for Pe - Show help message and usage instructions ```bash -./Configure.pl --help +./jperl Configure.pl --help ``` ### Configuration Management @@ -32,9 +37,9 @@ The `Configure.pl` script manages configuration settings and dependencies for Pe - Boolean/numeric values are used as-is ```bash -./Configure.pl -D perlVersion=v5.40.0 -./Configure.pl -D jarVersion=3.0.1 -./Configure.pl -D strict_mode=true -D enable_optimizations=false +./jperl Configure.pl -D perlVersion=v5.40.0 +./jperl Configure.pl -D jarVersion=3.0.1 +./jperl Configure.pl -D strict_mode=true -D enable_optimizations=false ``` **Special behavior for `jarVersion`:** @@ -43,7 +48,7 @@ The `Configure.pl` script manages configuration settings and dependencies for Pe **View current configuration:** ```bash -./Configure.pl +./jperl Configure.pl ``` ### Dependency Management @@ -55,15 +60,15 @@ The `Configure.pl` script manages configuration settings and dependencies for Pe ```bash # Search by keyword -./Configure.pl --search h2 -./Configure.pl --search mysql +./jperl Configure.pl --search mysql +./jperl Configure.pl --search postgresql # Search by driver class name -./Configure.pl --search org.h2.Driver -./Configure.pl --search com.mysql.cj.jdbc.Driver +./jperl Configure.pl --search com.mysql.cj.jdbc.Driver +./jperl Configure.pl --search org.postgresql.Driver # Search by group:artifact -./Configure.pl --search org.postgresql:postgresql +./jperl Configure.pl --search org.postgresql:postgresql ``` **Search behavior:** @@ -79,9 +84,8 @@ The `Configure.pl` script manages configuration settings and dependencies for Pe - Format must be: `group:artifact:version` ```bash -./Configure.pl --direct com.h2database:h2:2.2.224 -./Configure.pl --direct org.postgresql:postgresql:42.7.1 -./Configure.pl --direct com.mysql:mysql-connector-j:8.2.0 +./jperl Configure.pl --direct com.mysql:mysql-connector-j:8.2.0 +./jperl Configure.pl --direct org.postgresql:postgresql:42.7.1 ``` **`--verbose`** @@ -91,7 +95,7 @@ The `Configure.pl` script manages configuration settings and dependencies for Pe - Useful for troubleshooting search issues ```bash -./Configure.pl --search h2 --verbose +./jperl Configure.pl --search mysql --verbose ``` ### Dependency Upgrades @@ -103,7 +107,7 @@ The `Configure.pl` script manages configuration settings and dependencies for Pe - Uses `./gradlew versionCatalogUpdate` for Gradle ```bash -./Configure.pl --upgrade +./jperl Configure.pl --upgrade ``` **Requirements:** @@ -118,12 +122,12 @@ The `Configure.pl` script manages configuration settings and dependencies for Pe 1. Search for the driver: ```bash -./Configure.pl --search mysql-connector-java +./jperl Configure.pl --search mysql-connector-java ``` 2. Or use direct coordinates if you know them: ```bash -./Configure.pl --direct com.mysql:mysql-connector-j:8.2.0 +./jperl Configure.pl --direct com.mysql:mysql-connector-j:8.2.0 ``` 3. Rebuild the project to include the driver: @@ -139,10 +143,10 @@ Instead of bundling drivers, you can load them at runtime: ```bash # Download driver manually -wget https://repo1.maven.org/maven2/com/h2database/h2/2.2.224/h2-2.2.224.jar +wget https://repo1.maven.org/maven2/com/mysql/mysql-connector-j/8.2.0/mysql-connector-j-8.2.0.jar # Use with CLASSPATH -CLASSPATH=/path/to/h2-2.2.224.jar ./jperl script.pl +CLASSPATH=/path/to/mysql-connector-j-8.2.0.jar ./jperl script.pl ``` ## How It Works @@ -191,7 +195,7 @@ For `jarVersion` updates, also: ### View Current Configuration ```bash -./Configure.pl +./jperl Configure.pl ``` Output: @@ -206,14 +210,14 @@ strict_mode = true ### Update Configuration ```bash -./Configure.pl -D perlVersion=v5.42.0 -D jarVersion=3.1.0 +./jperl Configure.pl -D perlVersion=v5.42.0 -D jarVersion=3.1.0 ``` ### Search and Add JDBC Driver ```bash # Search for PostgreSQL driver -./Configure.pl --search postgresql +./jperl Configure.pl --search postgresql # Output shows: # Multiple matches found: @@ -233,8 +237,8 @@ make ### Add Driver with Direct Coordinates ```bash -# Add H2 database driver -./Configure.pl --direct com.h2database:h2:2.2.224 +# Add MySQL database driver +./jperl Configure.pl --direct com.mysql:mysql-connector-j:8.2.0 # Rebuild make @@ -243,7 +247,7 @@ make ### Upgrade All Dependencies ```bash -./Configure.pl --upgrade +./jperl Configure.pl --upgrade ``` Output: @@ -261,11 +265,11 @@ Gradle dependencies updated successfully. ```bash # Option 1: Search and select -./Configure.pl --search mysql +./jperl Configure.pl --search mysql make # Option 2: Direct coordinates -./Configure.pl --direct com.mysql:mysql-connector-j:8.2.0 +./jperl Configure.pl --direct com.mysql:mysql-connector-j:8.2.0 make # Option 3: Manual CLASSPATH (no rebuild needed) @@ -275,7 +279,7 @@ CLASSPATH=/path/to/mysql-connector.jar ./jperl script.pl ### Updating Project Version ```bash -./Configure.pl -D jarVersion=4.0.0 +./jperl Configure.pl -D jarVersion=4.0.0 # This updates Configuration.java and all references to perlonjava-*.jar ``` @@ -283,21 +287,21 @@ CLASSPATH=/path/to/mysql-connector.jar ./jperl script.pl ```bash # Search by database name -./Configure.pl --search postgresql --verbose +./jperl Configure.pl --search postgresql --verbose # Search by driver class -./Configure.pl --search org.postgresql.Driver --verbose +./jperl Configure.pl --search org.postgresql.Driver --verbose ``` ## Troubleshooting ### Search Returns No Results -**Problem**: `./Configure.pl --search keyword` finds nothing +**Problem**: `./jperl Configure.pl --search keyword` finds nothing **Solutions**: - Try broader keywords: `mysql` instead of `mysql-connector-java-8.2.0` -- Search by driver class: `./Configure.pl --search com.mysql.cj.jdbc.Driver` +- Search by driver class: `./jperl Configure.pl --search com.mysql.cj.jdbc.Driver` - Use `--verbose` to see search URL and results - Use `--direct` if you know the exact coordinates @@ -307,7 +311,7 @@ CLASSPATH=/path/to/mysql-connector.jar ./jperl script.pl **Solution**: You must rebuild after adding dependencies: ```bash -./Configure.pl --direct group:artifact:version +./jperl Configure.pl --direct group:artifact:version make # This downloads and bundles the dependency ``` diff --git a/examples/dbi.pl b/examples/dbi.pl index 9b7aaac02..f19552ac1 100644 --- a/examples/dbi.pl +++ b/examples/dbi.pl @@ -1,13 +1,9 @@ -# misc/snippets/dbi.pl +# examples/dbi.pl # -# Install h2 driver: -# curl https://repo1.maven.org/maven2/com/h2database/h2/2.2.224/h2-2.2.224.jar --output h2-2.2.224.jar +# SQLite is bundled with PerlOnJava - no additional installation needed. # # Run using: -# java -cp "h2-2.2.224.jar:target/perlonjava-5.42.0.jar" org.perlonjava.app.cli.Main examples/dbi.pl -# -# or using: -# CLASSPATH=h2-2.2.224.jar ./jperl examples/dbi.pl +# ./jperl examples/dbi.pl # use strict; @@ -16,18 +12,18 @@ use Data::Dumper; use feature 'say'; -# Connect to H2 database +# Connect to SQLite in-memory database (bundled, no extra driver needed) my $dbh = DBI->connect( - "jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1", # In-memory H2 database - "sa", # Default H2 username - "", # Empty password + "dbi:SQLite:dbname=:memory:", + "", # No username needed + "", # No password needed { RaiseError => 1 } ); # Create a test table $dbh->do("CREATE TABLE users ( - id INTEGER AUTO_INCREMENT PRIMARY KEY, - name VARCHAR(100), + id INTEGER PRIMARY KEY AUTOINCREMENT, + name TEXT, age INTEGER )"); @@ -82,7 +78,7 @@ # Fetch as hash refs with specific column names $sth->execute(20); -my $named_cols = $sth->fetchall_arrayref({ NAME => 1, AGE => 1 }); +my $named_cols = $sth->fetchall_arrayref({ name => 1, age => 1 }); say "\nNamed columns only:"; print Dumper $named_cols; @@ -106,9 +102,9 @@ # Complex query with joins and hash slice (assuming we add a new table) $dbh->do("CREATE TABLE orders ( - order_id INTEGER AUTO_INCREMENT PRIMARY KEY, + order_id INTEGER PRIMARY KEY AUTOINCREMENT, user_id INTEGER, - amount DECIMAL(10,2), + amount REAL, FOREIGN KEY (user_id) REFERENCES users(id) )"); @@ -136,7 +132,7 @@ # Add a new column that allows NULL -$dbh->do("ALTER TABLE users ADD COLUMN last_login TIMESTAMP NULL"); +$dbh->do("ALTER TABLE users ADD COLUMN last_login TEXT"); # Insert rows with NULL values $dbh->do("INSERT INTO users (name, age, last_login) VALUES (?, ?, ?)", @@ -199,7 +195,7 @@ print Dumper $nested; # Access nested data example -say "\nAccessing nested data:"; +say "\nAccessing nested data:"; for my $user_id (sort keys %$nested) { say "User $user_id orders:"; for my $order_id (sort keys %{$nested->{$user_id}}) { @@ -211,4 +207,3 @@ $sth->finish; $dbh->disconnect; -